Purpose

In Confluence 7.12 we reformatted and added some commentary to the setenv.sh and setenv.bat file to make it easier for you to locate and manage commonly modified Java options and system properties. We also added some recommended values for large instances. 

Rather than copying over your existing setenv.sh or setenv.bat file, we strongly recommend following the process outlined on this page to incorporate your previous configuration into the new file. This will make it easier for you to manage your particular configurations in future. 

Structure of the setenv file

The new file layout is designed to make it easy for you to manage your customizations, and easily differentiate between your custom properties, and those that are required.  

1. Java heap size - these are the most commonly updated java options. 
2. Recommended properties for large instances - we provide some recommended values for large organisations. If you're a large organisation, you can uncomment these properties, then comment out the properties for small organisations. 
3. Additional Confluence system properties - this is where to put properties specific to your site, so they're easy to see and update. You can also add a comment to indicate why the property has been added, to help admins in the future. 
4. Required properties - these are java options and system properties that you should not change, unless directed to do so by our support team. 

Once you've migrated your customizations to the new file format, next time you upgrade, you'll find the process much easier. You'll be able to simply copy over the properties under 'Additional system properties', and change any values of our recommended properties. You won't need to sort through every property to see if it has changed. 

Solution

Migrate your existing setenv.sh customizations in Linux

You can complete this process before beginning your production upgrade.

To migrate your current setenv.sh properties to the new file:

1. Open your current <install-directory>/bin/setenv.sh file.
2. Copy all lines that begin with CATALINA_OPTS= to a temporary file. You'll use this to cross reference your properties. 
3. Open the new setenv.sh file. 
4. Work through each property one by one. 

   1. For properties that are already set in the new file, either keep our recommended value, or update the value.
      In this example we've increased the heap memory. 

      # Set the Java heap size
      CATALINA_OPTS="-Xms4096m -Xmx4096m ${CATALINA_OPTS}"

   2. For properties that are commented out, remove the # to uncomment the property and either keep our recommended value, or update the value.
      In this example we have commented out the ReservedCodeCacheSize recommended for small organizations, in favour of the properties recommended for large organizations. 

      # Default values for small to medium size instances
      # CATALINA_OPTS="-XX:ReservedCodeCacheSize=256m ${CATALINA_OPTS}"
      
      # Recommended values for medium to large, and enterprise size instances
      # Comment out the default values in the block above, then uncomment the values below
      # To learn more about the impact of disabling the upgrade recovery file see:
      # https://confluence.atlassian.com/x/ShtwPg
      CATALINA_OPTS="-XX:ReservedCodeCacheSize=384m ${CATALINA_OPTS}"
      CATALINA_OPTS="-XX:+PrintTenuringDistribution ${CATALINA_OPTS}"
      CATALINA_OPTS="-XX:+PrintGCDetails -XX:+PrintGCTimeStamps ${CATALINA_OPTS}"
      CATALINA_OPTS="-Dconfluence.upgrade.recovery.file.enabled=false ${CATALINA_OPTS}"

   3. For properties that don't appear in the file, add them under the Additional Confluence system properties section.
      In this example we've added two properties to change the behaviour of personal access tokens. 

      # Additional Confluence system properties
      # For a list of properties recognized by Confluence see:
      # https://confluence.atlassian.com/display/DOC/Recognized+System+Properties
      # We recommend you include a support ticket ID and/or note to help track the reason for change
      # For example:
      # CSP-123456 - Added example JVM option to help explain this section
      #CATALINA_OPTS="-Dexample.property=true ${CATALINA_OPTS}"
      
      CATALINA_OPTS="-Datlassian.pats.max.tokens.per.user=5 ${CATALINA_OPTS}"
      CATALINA_OPTS="-Datlassian.pats.max.tokens.expiry.days=90 ${CATALINA_OPTS}"

   4. Generally there is no need to change the required properties. However, there is a known issue with garbage collection when using Java 11  CONFSERVER-61415 - Getting issue details... STATUS .
      In this example we have commented out a single line, which is the workaround outlined in the issue.

      CATALINA_OPTS="-Xlog:gc+age=debug:file=$LOGBASEABS/logs/gc-`date +%F_%H-%M-%S`.log::filecount=5,filesize=2M ${CATALINA_OPTS}"
      #CATALINA_OPTS="-Xloggc:$LOGBASEABS/logs/gc-`date +%F_%H-%M-%S`.log -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=2M ${CATALINA_OPTS}"
      CATALINA_OPTS="-Djava.awt.headless=true ${CATALINA_OPTS}"

5. Save the file, and keep it ready for when the time comes to apply your customizations during the upgrade. 

Migrate your existing setenv.bat customizations in Windows

You can complete this process before beginning your production upgrade.

To migrate your current setenv.bat properties to the new file:

1. Open your current <install-directory>/bin/setenv.bat file.
2. Copy all lines that begin with set CATALINA_OPTS= to a temporary file. You'll use this to cross reference your properties. 
3. Open the new setenv.bat file. 
4. Work through each property one by one. 

   1. For properties that are already set in the new file, either keep our recommended value, or update the value.
      In this example we've increased the heap memory. 

      :: Set the Java heap size
      set CATALINA_OPTS=-Xms4096m -Xmx4096m %CATALINA_OPTS%

   2. For properties that are commented out, remove the :: to uncomment the property and either keep our recommended value, or update the value.
      In this example we have commented out the ReservedCodeCacheSize recommended for small organizations, in favour of the properties recommended for large organizations. 

      :: Default values for small to medium size instances
      ::set CATALINA_OPTS=-XX:ReservedCodeCacheSize=256m %CATALINA_OPTS%
      
      :: Recommended values for medium to large, and enterprise size instances
      :: Comment out the default values in the block above, then uncomment the values below
      :: To learn more about the impact of disabling the upgrade recovery file see:
      :: https://confluence.atlassian.com/x/ShtwPg
      set CATALINA_OPTS=-XX:ReservedCodeCacheSize=384m %CATALINA_OPTS%
      set CATALINA_OPTS=-XX:+PrintTenuringDistribution %CATALINA_OPTS%
      set CATALINA_OPTS=-XX:+PrintGCDetails -XX:+PrintGCTimeStamps %CATALINA_OPTS%
      set CATALINA_OPTS=-Dconfluence.upgrade.recovery.file.enabled=false %CATALINA_OPTS%

   3. For properties that don't appear in the file, add them under the Additional Confluence system properties section.
      In this example we've added two properties to change the behaviour of personal access tokens. 

      :: Additional Confluence system properties
      :: For a list of properties recognized by Confluence see:
      :: https://confluence.atlassian.com/display/DOC/Recognized+System+Properties
      :: We recommend you include a support ticket ID and/or note to help track the reason for change
      :: For example:
      :: CSP-123456 - Added example JVM option to help explain this section
      ::set CATALINA_OPTS="-Dexample.property=true %CATALINA_OPTS%"
      
      set CATALINA_OPTS="-Datlassian.pats.max.tokens.per.user=5 %CATALINA_OPTS%"
      set CATALINA_OPTS="-Datlassian.pats.max.tokens.expiry.days=90 %CATALINA_OPTS%"

   4. Generally there is no need to change the required properties. However, there is a known issue with garbage collection when using Java 11  CONFSERVER-61415 - Getting issue details... STATUS .
      In this example we have commented out a single line, which is the workaround outlined in the issue.

      set CATALINA_OPTS=-Xlog:gc+age=debug:file="%atlassian_logsdir%\gc-%atlassian_timestamp%.log"::filecount=5,filesize=2M %CATALINA_OPTS%
      ::set CATALINA_OPTS=-Xloggc:"%atlassian_logsdir%\gc-%atlassian_timestamp%.log" -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=2M %CATALINA_OPTS%
      set CATALINA_OPTS=-Djava.awt.headless=true %CATALINA_OPTS%

5. Save the file, and keep it ready for when the time comes to apply your customizations during the upgrade.