--- title: Install the Java agent on app servers and JVM frameworks source: https://docs.newrelic.com/docs/apm/agents/java-agent/installation/java-agent-installation-app-servers --- This page covers the standard installation path for the New Relic Java agent on any supported app server or JVM-based framework. Follow these steps to download the agent, configure it, and verify that data is flowing to New Relic. ## Compatibility and requirements [#requirements] ### Supported - Java 8, 11, 17, 21, 24, 25, and 26 _(Java 7 supported on agent v6.5.4 and earlier only)_ - JVM-based languages: Java, Scala, Kotlin, and Clojure - App servers and frameworks: Tomcat, Spring Boot, JBoss/WildFly, Glassfish, Jetty, WebLogic, WebSphere, Grails, ColdFusion, Solr, Play, Resin, Tanuki Wrapper, and Geronimo — see [compatibility and requirements](https://docs.newrelic.com/docs/apm/agents/java-agent/getting-started/compatibility-requirements-java-agent) for supported version ranges - Any JVM process that accepts a `-javaagent` argument ### Not supported - Running alongside other APM agents — the Java agent cannot guarantee correct behavior when another APM agent is active in the same JVM ### You need - A New Relic account and license key - A JVM with SHA-2 (256-bit) SSL support - Permission to edit your app server's startup scripts or JVM configuration - Permission to create a directory to hold the agent files ## Install [#install] ### Download the Java agent [#install-step-1] Download `newrelic-java.zip` using one of these methods: #### curl ````bash curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip unzip newrelic-java.zip ``` ```` #### PowerShell ````powershell Invoke-WebRequest -Uri https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip -OutFile newrelic-java.zip Expand-Archive -Path newrelic-java.zip -DestinationPath . ``` ```` #### Web Download `newrelic-java.zip` from the [Java agent release notes](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes/) page. After unzipping, the `newrelic/` directory contains the agent jar (`newrelic.jar`) and configuration file (`newrelic.yml`) that you'll configure in the next steps. ### Place the agent files [#install-step-2] Create a permanent directory and move the agent files into it: ````bash mkdir -p /opt/newrelic mv newrelic/* /opt/newrelic/ ``` We recommend `/opt/newrelic` on Linux/macOS or `C:\opt\newrelic` on Windows. Make sure `newrelic.jar` is **not** on your application classpath or in any directory listed in `java.endorsed.dirs`. ```` ### Pass the `-javaagent` argument [#install-step-3] Add the `-javaagent` flag to your app server's JVM startup configuration, pointing to the full path of `newrelic.jar`. The method differs per server — expand the one that matches your environment: **Tomcat** Choose the method for your Tomcat setup: #### setenv.sh (Linux/macOS) Create `CATALINA_BASE/bin/setenv.sh` if it doesn't exist, then add: ````bash export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/newrelic/newrelic.jar" ``` ```` #### setenv.bat (Windows) Create `CATALINA_BASE/bin/setenv.bat` if it doesn't exist, then add: ````batch SET "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:C:\opt\newrelic\newrelic.jar" ``` ```` #### Windows service 1. Select **Start > Apache Tomcat X.Y.Z > Configure Tomcat > Java**. 2. In the **Java Options** text box, enter the argument. Use forward slashes `/` for the path separator. For Tomcat 6, add a line break after the `-javaagent` argument. ``` -javaagent:/opt/newrelic/newrelic.jar ``` 3. Select **Apply**, then restart Tomcat. #### Apache Commons Daemon The version of Apache Commons Daemon (jsvc) bundled with Tomcat 6 does not support the `-javaagent` argument. A build from the trunk source supports it via the `-X` prefix. See the [Apache bug report](https://issues.apache.org/jira/browse/DAEMON-84) and [Apache Commons source repository](https://commons.apache.org/svninfo.html). **Spring Boot** Add the `-javaagent` argument before the `-jar` argument on the command line: ````bash java -javaagent:/opt/newrelic/newrelic.jar -jar /path/to/your-application.jar ``` ```` **JBoss / WildFly** #### Domain mode (JBoss 6.x EAP and 7.0 AS+) Edit `domain/configuration/domain.xml` and add the `-javaagent` option to your server group's JVM options: ````xml ``` A [JBoss bug in 7.0.2.Final and 7.1.0.Alpha1](https://issues.jboss.org/browse/AS7-1868) prevents JVM options from being set in `domain.xml`. Upgrade your JBoss app server if you encounter this. ```` #### Standalone mode | Platform | Instructions | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Unix/macOS — JBoss 6.x EAP or 7.0.x AS+ | At the bottom of `bin/standalone.conf`, add: `JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar"` | | Windows — JBoss 6.x EAP or 7.0.x AS+ | In `bin/standalone.bat`, before `set JBOSS_ENDORSED_DIRS`, add: `set "JAVA_OPTS=-javaagent:C:\opt\newrelic\newrelic.jar %JAVA_OPTS%"` | | Unix/macOS — JBoss 6.x or earlier | At the bottom of `bin/run.conf`, add: `JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar"` | | Windows — JBoss 6.x or earlier | In `bin/run.bat`, before `set JBOSS_CLASSPATH`, add: `set "JAVA_OPTS=-javaagent:C:\opt\newrelic\newrelic.jar %JAVA_OPTS%"` | **WildFly (standalone)** > #### 💡 TIP > > WildFly 11 or higher requires [additional install steps](https://docs.newrelic.com/docs/apm/agents/java-agent/additional-installation/wildfly-version-11-installation-java). #### Domain mode Edit `domain/configuration/domain.xml` and add the `-javaagent` option to your server group's JVM options: ````xml ``` ```` #### Standalone mode | Platform | Instructions | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Unix/macOS | At the bottom of `bin/standalone.conf`, add: `JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar"` | | Windows | In `bin/standalone.bat`, after `rem Setup JBoss specific properties`, add: `set "JAVA_OPTS=-javaagent:C:\opt\newrelic\newrelic.jar %JAVA_OPTS%"` | **Glassfish** 1. From the Glassfish admin console, select **Application Server > JVM Settings > JVM Options**. 2. Select **Add JVM Option** and add: ``` -javaagent:/opt/newrelic/newrelic.jar ``` 3. Save and restart Glassfish. _If Glassfish doesn't start, the `-javaagent` path may be incorrect. You can also set JVM arguments by editing `domain.xml` directly._ > #### ⚠️ IMPORTANT > > A bug in Glassfish 2.1 prevents classes on the bootstrap class loader from using the Java logging API. This is fixed in 2.1.1 and higher. **Jetty** #### jetty.sh Edit `JAVA_OPTIONS` in your `jetty.sh` script: ````bash export JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/opt/newrelic/newrelic.jar" ``` ```` #### start.ini Add to your `start.ini` config file: ```` -javaagent:/opt/newrelic/newrelic.jar ``` ```` **WebLogic** #### Linux/macOS admin servers 1. Edit `startWebLogic.sh` in the domain's `bin/` directory. 2. Near the beginning of the file, add: ```bash export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/opt/newrelic/newrelic.jar" ``` #### Windows admin servers 1. Edit `startWebLogic.bat` in the domain's `bin/` directory. 2. Near the beginning of the file, add: ```batch set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:"C:\opt\newrelic\newrelic.jar" ``` #### Managed server instances For administration server instances, use the Linux/macOS or Windows instructions above — you cannot configure administration server instances through the admin console. For managed server instances, use the admin console: 1. Navigate to **Environments > Servers > (select a server) > Server Start > Arguments**. 2. Add: ``` -javaagent:/opt/newrelic/newrelic.jar ``` 3. Save and restart the server instance. **WebSphere** #### WebSphere (via admin console) 1. From the admin console, select **Servers > Application servers > (select a server) > Configuration > Service Infrastructure > Java and Process Management**. 2. Select **Process Definition > Additional Properties**, then select **Java Virtual Machine**. 3. In the **Generic JVM arguments** field, add: ``` -javaagent:/opt/newrelic/newrelic.jar ``` 4. Select **Apply**, then **Save**. 5. Restart your server. For more information, see [collecting WebSphere PMI metrics](https://docs.newrelic.com/docs/apm/agents/java-agent/features/jvm-metrics-page#default-pmi). #### WebSphere Community Add the agent to `JAVA_OPTS` when running the startup command: ````bash export JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar" && startup ``` ```` #### WebSphere Liberty Profile 1. Edit `${server.config.dir}/jvm.options`. 2. Add: ``` -javaagent:/opt/newrelic/newrelic.jar ``` 3. Restart your server. **Grails** #### run-app ````bash grails -noreloading -javaagent:/opt/newrelic/newrelic.jar run-app ``` ```` #### run-war In `grails-app/conf/BuildConfig.groovy`, add or edit: ````groovy grails.tomcat.jvmArgs = ["-javaagent:/opt/newrelic/newrelic.jar"] ``` ```` **ColdFusion** 1. Start your ColdFusion server and open the ColdFusion admin console. 2. From the left menu, select **SERVER SETTINGS > Java and JVM**. 3. If using the agent API, specify the path to `newrelic-api.jar` in the **ColdFusion Class Path** field. 4. In the **JVM Arguments** field, add: ``` -javaagent:/opt/newrelic/newrelic.jar ``` 5. Select **Submit Changes**, then restart ColdFusion. **Solr** #### Standalone Solr 5.x+ Add the `-javaagent` property to `bin/solr.in.sh`: ````bash SOLR_OPTS="$SOLR_OPTS -javaagent:/opt/newrelic/newrelic.jar" ``` ```` #### Standalone Solr 4.x or lower Add the `-javaagent` before `start.jar`: ````bash java -javaagent:/opt/newrelic/newrelic.jar -jar start.jar ``` ```` #### App server Solr When running Solr inside an application server, follow the instructions for that app server (see the other entries in this list). Also ensure JMX is enabled. If Solr data doesn't appear in APM, see [troubleshooting procedures for Solr data](https://docs.newrelic.com/docs/apm/agents/java-agent/troubleshooting/java-solr-troubleshooting). **Play Framework** #### Play 1.2.4 ````bash play run your_app_name -javaagent:/opt/newrelic/newrelic.jar ``` ```` #### Play 2.0 1. Start with an unzipped distribution containing the `start` script: ```bash play clean dist && unzip dist/*.zip ``` 2. Start with the `-javaagent` argument: ```bash cd unzipped/folder; chmod a+x start; ./start -javaagent:/opt/newrelic/newrelic.jar ``` #### Play 2.2 1. Start with an unzipped distribution: ```bash play clean dist && unzip target/directory/universal/*.zip ``` 2. Use the `-J-javaagent` prefix: ```bash cd unzipped/folder; ./bin/scriptname -J-javaagent:/opt/newrelic/newrelic.jar ``` #### Play 2.3, 2.4, 2.5 1. Start with an unzipped distribution: ```bash activator clean dist && unzip target/directory/universal/*.zip ``` 2. Use the `-J-javaagent` prefix: ```bash cd unzipped/folder; ./bin/scriptname -J-javaagent:/opt/newrelic/newrelic.jar ``` 3. If you use Typesafe Activator with Play 2.4, also add to `build.sbt`: ```scala javaOptions ++= Seq("-javaagent:/opt/newrelic/newrelic.jar") ``` **Resin** #### Resin with Java 8 Add to the `` section in `conf/resin.conf` or `conf/resin.xml`: ````xml -javaagent:/opt/newrelic/newrelic.jar ``` ```` #### Resin with Java 9+ The Java 9 module system can cause `NoClassDefFoundError: java/sql/SQLException` if `-javaagent` is added to `conf/resin.conf` or `conf/resin.xml`. Use one of these alternatives instead: **Option 1** — Command line: ````bash java -javaagent:/opt/newrelic/newrelic.jar -jar lib/resin.jar start ``` **Option 2** — Edit `bin/resin.sh`, modifying: ```bash exec $JAVA_EXE -javaagent:/opt/newrelic/newrelic.jar -jar lib/resin.jar $@ ``` Then start Resin with `./bin/resin.sh start`. ```` **Tanuki Wrapper (Java Service Wrapper)** In `wrapper.conf`, add a new `wrapper.java.additional` option. Replace `XXX` with an unused number in the file: ````properties wrapper.java.additional.XXX=-javaagent:/opt/newrelic/newrelic.jar ``` On Linux, no quotation marks are needed around the path. This may vary on other operating systems. ```` **Geronimo** Pass the agent jar in `JAVA_OPTS` when running the Geronimo startup command: ````bash export JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar" && geronimo run ``` ```` ## Configure [#configure] Edit `newrelic/newrelic.yml` and set these two required values: ```yaml license_key: 'YOUR_LICENSE_KEY' app_name: 'My Application' ``` The agent reads `newrelic.yml` from the same directory as `newrelic.jar` at startup. You can also override any setting using Java system properties (e.g. `-Dnewrelic.config.license_key=YOUR_KEY`) or environment variables. When using the config file, restrict permissions to read/write for the owner of the application server process only: ```bash chmod 600 /opt/newrelic/newrelic.yml ``` See [Java agent configuration](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file) for all available options. ## Verify your install [#verify] Restart your application server. Send at least two requests, then wait 2–3 minutes and your app appears in [APM & services](https://one.newrelic.com/nr1-core?filters=%28domain%20IN%20%28%27APM%27%2C%20%27EXT%27%29%20AND%20type%20IN%20%28%27APPLICATION%27%2C%20%27SERVICE%27%29%29). If no data appears after five minutes, see [No data appears (Java)](https://docs.newrelic.com/docs/apm/agents/java-agent/troubleshooting/no-data-appears-java). ## Related articles [#related-articles] - [Java agent configuration](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file) - [Compatibility and requirements](https://docs.newrelic.com/docs/apm/agents/java-agent/getting-started/compatibility-requirements-java-agent) - [Install in Docker](https://docs.newrelic.com/docs/apm/agents/java-agent/additional-installation/install-new-relic-java-agent-docker) - [Install with Maven](https://docs.newrelic.com/docs/apm/agents/java-agent/installation/java-agent-installation-maven) - [Install with Gradle](https://docs.newrelic.com/docs/apm/agents/java-agent/installation/java-agent-installation-gradle) - [Update the Java agent](https://docs.newrelic.com/docs/apm/agents/java-agent/installation/update-java-agent)