How to migrate your setenv settings for Confluence 7.12 and later
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
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.
- Java heap size - these are the most commonly updated java options.
- 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.
- 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.
- 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:
- Open your current
<install-directory>/bin/setenv.sh
file. - Copy all lines that begin with
CATALINA_OPTS=
to a temporary file. You'll use this to cross reference your properties. - Open the new
setenv.sh
file. - Work through each property one by one.
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}"
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 theReservedCodeCacheSize
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}"
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}"
Generally there is no need to change the required properties. However, there is a known issue with garbage collection when using Java 11 - CONFSERVER-61415Getting 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}"
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:
- Open your current
<install-directory>/bin/setenv.bat
file. - Copy all lines that begin with
set CATALINA_OPTS=
to a temporary file. You'll use this to cross reference your properties. - Open the new
setenv.bat
file. - Work through each property one by one.
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%
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 theReservedCodeCacheSize
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%
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%"
Generally there is no need to change the required properties. However, there is a known issue with garbage collection when using Java 11 - CONFSERVER-61415Getting 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%
Save the file, and keep it ready for when the time comes to apply your customizations during the upgrade.