Documentation for Confluence 6.

15
Confluence 6.15 Documentation 2

Contents
Confluence administrator's guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Getting Started as Confluence Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Manage Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Add and Invite Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Delete or Disable Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Restore Passwords To Recover Admin User Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Edit User Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Change a Username . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Managing Site-Wide Permissions and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Confluence Groups for Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Adding or Removing Users in Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Global Permissions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Setting Up Public Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Configuring User Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Configuring the Internal Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Connecting to an LDAP Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Configuring the LDAP Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Configuring an SSL Connection to Active Directory . . . . . . . . . . . . . . . . . . . . . . . . 50
Connecting to an Internal Directory with LDAP Authentication . . . . . . . . . . . . . . . . . . 60
Connecting to Crowd or Jira for User Management . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Reverting from Crowd or Jira applications to Internal User Management . . . . . . . 74
Managing Multiple Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Managing Nested Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Synchronizing Data from External Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Diagrams of Possible Configurations for User Management . . . . . . . . . . . . . . . . . . . . 86
User Management Limitations and Recommendations . . . . . . . . . . . . . . . . . . . . . . . . 92
Requesting Support for External User Management . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Disabling the Built-In User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
SAML SSO for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Managing System and Marketplace Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Writing User Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
User Macro Template Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Customizing your Confluence Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Changing the Look and Feel of Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Customizing the Confluence Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Changing the Site Logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Customizing Color Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Styling Confluence with CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Basic Styling Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Styling Fonts in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Working with Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Applying a Theme to a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Creating a Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Customizing Site and Space Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Upgrading Customized Site and Space Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Working With Decorator Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Custom Decorator Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Customizing a Specific Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Customizing the Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Modify Confluence Interface Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Customizing Email Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Changing the Default Behavior and Content in Confluence . . . . . . . . . . . . . . . . . . . . . . . 132
Administering Site Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Importing Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Changing the Site Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Choosing a Default Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 3

Configuring the Administrator Contact Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Configuring the Site Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Customizing Default Space Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Editing the Site Welcome Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Integrating Confluence with Other Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Linking to Another Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Configuring Workbox Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Integrating Jira and Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Registering External Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Configuring the Office Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Managing your Confluence License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Managing Confluence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Database JDBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Database Setup for Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Configuring an Oracle Datasource in Apache Tomcat . . . . . . . . . . . . . . . . . . . . . . 163
Database Setup for PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Configuring a PostgreSQL Datasource in Apache Tomcat . . . . . . . . . . . . . . . . . . 165
Database Setup for SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Configuring a SQL Server Datasource in Apache Tomcat . . . . . . . . . . . . . . . . . . . 168
Database Setup For MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Configuring a MySQL Datasource in Apache Tomcat . . . . . . . . . . . . . . . . . . . . . . 173
Embedded H2 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Migrating to Another Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Configuring Database Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Configuring database query timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Surviving Database Connection Closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Configuring a datasource connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Site Backup and Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Production Backup Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Configuring Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
User Submitted Backup & Restore Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Manually Backing Up the Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Restoring a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Restoring a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Restoring a Test Instance from Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Restoring Data from other Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Retrieving File Attachments from a Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Troubleshooting failed XML site backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Troubleshooting XML backups that fail on restore . . . . . . . . . . . . . . . . . . . . . . . . . 206
Import a space from Confluence Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Attachment Storage Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Configuring Attachment Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Hierarchical File System Attachment Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Confluence Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Finding Unused Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Data Import and Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Import a Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Audit log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Configuring Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Viewing System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Live Monitoring Using the JMX Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Tracking Customizations Made to your Confluence Installation . . . . . . . . . . . . . . . . . 229
View Space Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Viewing Site Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Viewing System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Configuring the Server Base URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Configuring the Confluence Search and Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Configuring Indexing Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Configuring Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Content Index Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Enabling OpenSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 4

Rebuilding the Ancestor Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Setting Up Confluence to Index External Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Setting Up an External Search Tool to Index Confluence . . . . . . . . . . . . . . . . . . . . . . 240
Configuring Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Configuring a Server for Outgoing Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Setting Up a Mail Session for the Confluence Distribution . . . . . . . . . . . . . . . . . . . . . 242
Configuring the Recommended Updates Email Notification . . . . . . . . . . . . . . . . . . . . 243
The Mail Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Configuring Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Troubleshooting Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
"€" Euro character not displaying properly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
MySQL 3.x Character Encoding Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Other Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Configuring a WebDAV client for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Configuring HTTP Timeout Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Configuring Number Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Configuring Shortcut Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Configuring Time and Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Enabling the Remote API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Enabling Threaded Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Installing a Language Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Installing Patched Class Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Configuring System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Recognized System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Working with Confluence Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Configuring Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
log4j Logging Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Troubleshooting SQL Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Scheduled Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Configuring the Whitelist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Configuring the Time Interval at which Drafts are Saved . . . . . . . . . . . . . . . . . . . . . . . . . 297
Configuring Confluence Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Confluence Security Overview and Advisories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Proxy and HTTPS setup for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Configuring Web Proxy Support for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Connecting to LDAP or Jira applications or Other Services via SSL . . . . . . . . . . . . . . 302
Using Apache with mod_proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Running Confluence behind NGINX with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Running Confluence Over SSL or HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Using Apache to limit access to the Confluence administration interface . . . . . . . . . . 321
Using Apache with mod_jk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Using mod_rewrite to Modify Confluence URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Configuring Secure Administrator Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Confluence Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Using Fail2Ban to limit login attempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Securing Confluence with Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Trackback and External Referrers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Best Practices for Configuring Confluence Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Hiding the People Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Configuring Captcha for Spam Prevention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Hiding External Links From Search Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Configuring Captcha for Failed Logins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Configuring XSRF Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
User Email Visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Anonymous Access to Remote API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Configuring RSS Feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Preventing and Cleaning Up Spam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Configuring a Confluence Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Confluence Home and other important directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Application Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Managing Application Server Memory Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Starting Confluence Automatically on System Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 5

Start Confluence Automatically on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Start Confluence Automatically on Windows as a Service . . . . . . . . . . . . . . . . . . . . . 351
Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Cache Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Cache Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Memory Usage and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Requesting Performance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Access Log Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Compressing an HTTP Response within Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Garbage Collector Performance Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Troubleshooting Slow Performance Using Page Request Profiling . . . . . . . . . . . . . . . . . 367
Identifying Slow Performing Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Confluence Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Data Collection Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Administering Collaborative Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Possible Confluence and Synchrony Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Configuring Synchrony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Set up a Synchrony cluster for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . 383
Migrate from a standalone Synchrony cluster to managed Synchrony . . . . . . . . . . . . . . . 390
Troubleshooting Collaborative Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Using read-only mode for site maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Administering the Atlassian Companion App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Confluence installation and upgrade guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Server Hardware Requirements Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Running Confluence in a Virtualized Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Confluence Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Installing Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Installing a Confluence trial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Installing Confluence on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Installing Confluence on Windows from Zip File . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Uninstalling Confluence from Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Installing Confluence on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Installing Confluence on Linux from Archive File . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Uninstalling Confluence from Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Unattended installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Change listen port for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Start and Stop Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Installing Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Moving to Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Upgrading Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Adding and Removing Data Center Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Change Node Discovery from Multicast to TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Running Confluence Data Center in AWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Getting started with Confluence Data Center on Azure . . . . . . . . . . . . . . . . . . . . . . . . 453
Administering Confluence Data Center on Azure . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Moving from Data Center to Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Installing Java for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Setting the JAVA_HOME Variable in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Change the Java vendor or version Confluence uses . . . . . . . . . . . . . . . . . . . . . . . . . 465
Creating a Dedicated User Account on the Operating System to Run Confluence . . . . . 468
Confluence Setup Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Configuring Jira Integration in the Setup Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Upgrading Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
Upgrading Beyond Current Licensed Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Confluence Post-Upgrade Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Migration from Wiki Markup to XHTML-Based Storage Format . . . . . . . . . . . . . . . . . . . . 486
Migration of Templates from Wiki Markup to XHTML-Based Storage Format . . . . . . . . . 490
Upgrading Confluence Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Create a staging environment for upgrading Confluence . . . . . . . . . . . . . . . . . . . . . . . . . 497
Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
End of Support Announcements for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 6

Supported Platforms FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523

Migrating Confluence Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
From Confluence Evaluation through to Production Installation . . . . . . . . . . . . . . . . . . . . 525
Migrate from Confluence Server to Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Cloud Migration Assistant for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Migrate from Confluence Cloud to Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Confluence Data Center Technical Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Administer your Data Center search index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
External Process Pool for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Document conversion for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
PDF export in Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Restricted Functions in Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
Confluence Data Center Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
Confluence Data Center disaster recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Data Center Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
Troubleshooting a Data Center cluster outage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
Confluence Server and Data Center feature comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
Getting Started with Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 7

Confluence administrator's guide

About the Confluence administrator's guide
This guide covers features and functions that are only available to administrators.
For information on creating and administering spaces, See Spaces.
This guide assumes that you are using the Confluence default theme. If your Confluence site has been
customized the header may look different, and menu items appear in different locations to the examples
given in this guide.
Getting Started as Confluence Administrator
Downloads
Manage Users
Add and Invite Users
Delete or Disable Users Download the Confluence documentation
Restore Passwords To Recover Admin in PDF format.
User Rights
Edit User Details
Change a Username Other resources
Managing Site-Wide Permissions and
Groups Confluence installation and upgrade guide
Configuring User Directories
SAML SSO for Confluence Data Confluence Knowledge Base
Center
Atlassian Answers
Managing System and Marketplace Apps
Writing User Macros
User Macro Template Syntax
Customizing your Confluence Site
Changing the Look and Feel of
Confluence
Changing the Default Behavior and
Content in Confluence
Integrating Confluence with Other
Applications
Linking to Another Application
Configuring Workbox Notifications
Integrating Jira and Confluence
Registering External Gadgets
Configuring the Office Connector
Managing your Confluence License
Managing Confluence Data
Database Configuration
Site Backup and Restore
Attachment Storage Configuration
Confluence Data Model
Finding Unused Spaces
Data Import and Export
Import a Text File
Audit log
Configuring Confluence
Viewing System Information
Configuring the Server Base URL
Configuring the Confluence Search
and Index
Configuring Mail
Configuring Character Encoding
Other Settings
Configuring System Properties
Working with Confluence Logs
Scheduled Jobs
Configuring the Whitelist

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 8

Configuring the Time Interval at which

Drafts are Saved
Configuring Confluence Security
Confluence Security Overview and
Advisories
Proxy and HTTPS setup for
Confluence
Configuring Secure Administrator
Sessions
Confluence Cookies
Using Fail2Ban to limit login attempts
Securing Confluence with Apache
Trackback and External Referrers
Best Practices for Configuring
Confluence Security
Hiding the People Directory
Configuring Captcha for Spam
Prevention
Hiding External Links From Search
Engines
Configuring Captcha for Failed Logins
Configuring XSRF Protection
User Email Visibility
Anonymous Access to Remote API
Configuring RSS Feeds
Preventing and Cleaning Up Spam
Configuring a Confluence Environment
Confluence Home and other important
directories
Application Server Configuration
Starting Confluence Automatically on
System Startup
Performance Tuning
Cache Performance Tuning
Memory Usage and Requirements
Requesting Performance Support
Compressing an HTTP Response
within Confluence
Garbage Collector Performance Issues
Troubleshooting Slow Performance
Using Page Request Profiling
Confluence Diagnostics
Data Collection Policy
Administering Collaborative Editing
Possible Confluence and Synchrony
Configurations
Configuring Synchrony
Set up a Synchrony cluster for
Confluence Data Center
Migrate from a standalone Synchrony
cluster to managed Synchrony
Troubleshooting Collaborative Editing
Using read-only mode for site maintenance
Administering the Atlassian Companion App

Getting Started as Confluence Administrator

If you're just starting out as Confluence
administrator, this page is for you. You'll find this
page useful if your Confluence site is brand new, or
if you're learning to administer an existing site.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 9

Confluence is a Java-based web application. For the

supported environments, there's an installer that will On this page:
set up an application server and copy the application Quick access to admin functions
files to the designated directories on your server via search
machine. If you prefer, you can install Confluence How to administer and configure
from a zip file. See the Confluence Installation Guide Confluence
for details. Getting started on a new
Confluence site
Getting to know an existing
Confluence site

Diagram: a Confluence installation

Quick access to admin functions via search

Start typing what you want to do into the Confluence search box at top right of the screen. The matching
admin functions will appear with a cog icon at the top of the search results.
Screenshot: searching for admin options

Even faster via /: Press / on your keyboard, then continue typing the action you want.
Notes about finding admin functions via search:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 10

Pressing / puts your cursor in the search field.

System admin, Confluence admin, and space admin options may appear in the search results.
Confluence permissions determine the admin options that appear in search results. You'll only see the
options you're allowed to perform.

How to administer and configure Confluence

After installing Confluence, you will perform the initial configuration via a web interface called the Confluence
Setup Wizard.Introducing the Confluence Administration Console: From this point onwards, many of the
admin functions are available from the Confluence Administration Console, which is part of the Confluence
web interface. If you have administrative permissions, you'll have access to the Confluence Administration
Console via your web browser, using the standard Confluence URL for your site.
To access the Confluence Administration Console:
1. Open your Confluence URL in your web browser.
2. Choose

> General Configuration in the header.

For further configuration options, you can edit the XML and properties files that are part of your
Confluence installation directory. To get started, take a look at the Confluence Home and other important
directories. The Confluence administration guide will lead you through tasks such as configuring the log files
and configuring system properties.

Getting started on a new Confluence site

Is this a new Confluence site? Here are some things to get started with:
Decide whether you want to allow public (anonymous) access to your site.See Setting Up Public
Access.
Add a space and some content. See Create a Space then Pages and blogs.
Invite some users to your site. See Add and Invite Users.
Decide whether you will manage your users in Confluence or hook up an external LDAP directory. See
Configuring User Directories.
Make sure you have set up an email server. The above task list will include this step, but it is worth
mentioning it here again. Email notifications are an important part of collaborating on Confluence. See
Configuring a Server for Outgoing Mail.
Now you can continue getting to know your site, as described in the next section.

Getting to know an existing Confluence site

Has the site been around a while, but you're new to Confluence administration? Take a look at these topics:
Understand the Confluence permission scheme. See Permissions and restrictions.
Get to know the power of Marketplace apps (also known as add-ons or plugins), for extending and
customizing your Confluence site. See Managing System and Marketplace Apps.
Investigate more ways of customizing Confluence. See Customizing your Confluence Site.

Manage Users
A Confluence user is a person who can read or
update a Confluence site. You can choose whether
your Confluence site is accessible to anonymous
users (people who have not logged in) or only to
logged-in users. See Setting Up Public Access.

Managing 500+ users across Atlassian

products?
Find out how easy, scalable and effective it

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 11

can be with Crowd! On this page:

See centralized user management.
Confluence user management
Authentication
Seraph
Confluence user management
XML-RPC and SOAP
You can add users to Confluence, and then assign authentication
them permissions that determine their access to the Password authentication
content and administrative functions in your SAML single sign-on
Confluence site. You can also collect users into Related pages:
groups, and assign the permissions to groups for
easier management. See the following topics: Configuring Confluence Security

Add and Invite Users

Delete or Disable Users
Managing Site-Wide Permissions and Groups
By default, Confluence stores its users and groups in the Confluence database. This is called the internal
directory. You can choose to connect Confluence to an external userbase instead, such as Microsoft Active
Directory or another LDAP server. You can also use Atlassian Crowd and Jira applications as directory
managers. When you add a user or group to Confluence, it will be added to the external directory too, based
on your configuration options. See Configuring User Directories.

Authentication

Seraph

Almost all authentication in Confluence (and Jira applications) is performed through Seraph, Atlassian's open
source web authentication framework. The goal of Seraph is to provide a simple, extensible authentication
system that we can use on any application server.
Seraph is implemented as a servlet filter. Its sole job is, given a web request, to associate that request with a
particular user (or no user if the request is anonymous). It supports several methods of authentication,
including HTTP Basic Authentication, form-based authentication, and looking up credentials already stored in
the user's session.
Seraph itself performs no user management functions. It merely checks the credentials of the incoming
request and delegates any user management functions (looking up a user, checking a user's password) to
Confluence's user management system.
If you want to integrate Confluence with your own single sign-on (SSO) infrastructure, you would do so by
installing Atlassian Crowd or by writing a custom Seraph authenticator. See our developer documentation on
HTTP authentication with Seraph.

XML-RPC and SOAP authentication

Normally, requests for Confluence's XML-RPC and SOAP APIs (deprecated) will include an authentication
token as the first argument. With this method of authentication, XML-RPC and SOAP authentication requests
are checked directly against the user management framework, and tokens are assigned directly by the
remote API subsystem. These requests do not pass through Seraph authenticators.
However, if the token argument is blank, Seraph will be used as a fallback authentication method for remote
API requests. So, to use a custom Seraph authenticator with XML-RPC or SOAP requests, ensure that you
pass an empty string as the authentication token to remote API methods.

Password authentication

By default, password authentication is delegated from Seraph to the user management system. This is not
necessary, however. Single sign-on systems may have no password authentication at all, and get all the
necessary credentials from the SSO provider.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 12

SAML single sign-on

If you have a Confluence Data Center license you can connect Confluence to your SAML 2.0 identity
provider for authentication and single sign-on.
See SAML SSO for Confluence Data Center for more information.

Add and Invite Users

There are a number of ways to add users to Confluence: On this page:
Allow user
By user signup: If user signup is enabled on your Confluence site,
signup
people can add themselves as users of the site.
Manage us
Via an invitation link: You can invite people to sign up by sending
er
them an invitation link. You can copy and paste the link, or prompt
signup noti
Confluence to send the link in an email message.
fications
By adding users manually: If you have Administrator or System Invite
Administrator permission, you can manually add new users. people to
Via an external user directory: See Configuring User Directories. sign up
You may also be interested in information about allowing anonymous users Reset the
access to your site. Anonymous users don't count against your Confluence invitation
license totals. link
Add users
manually
Allow user signup Notes

If you enable user signup, a 'Sign Up' option will appear on the Confluence Related pages:
screens. The option will be on the login screen, and also in the header on
Manage
public sites. People can choose the option to create their own usernames on
Users
Confluence.
Setting Up
Public
Access
Configurin
g a Server
for
Outgoing
Mail

You can restrict the signup to people whose email addresses are within a given domain or domains. This is
useful if you want to ensure that only people within your organization can add their own usernames.
You will still be able to add or invite users manually, whether user signup is enabled or not.
You need Confluence Administrator or System Administrator permissions to change the signup options.
To set the user signup options:
1. Choose

> User management

2. Select the User Signup Options tab
3. Choose Allow people to sign up to create their account
4. Choose one of the following options:
Restricted by domain(s) – Note: You need to set up a mail server for Confluence before you
can configure domain restricted signup. When you choose this option, you'll see a text box.
Enter one or more domains, separated by commas. People will only be able to sign up if their
email address belongs to one of the domains specified here. Confluence will send the person
an email message, asking them to click a link to confirm their email address.
For example: mydomain.com, mydomain.net
No restrictions – Anyone will be able to sign up to Confluence. Confluence will not send any
email message requesting confirmation.
5. Choose Notify administrators by email when an account is created if you want Confluence to send
an email message to all administrators (people with Confluence Administrator or System Administrator

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
5. 6.15 Documentation 13

permissions) every time someone signs up to Confluence

Manage user signup notifications

By default, Confluence will send an email notification to all Confluence administrators whenever someone
signs up to your Confluence site. The administrators (people with Confluence Administrator or System
Administrator permissions) will receive this message when someone signs up either by clicking the 'Sign Up'
link or by clicking the invitation URL sent by an administrator.
To disable this notification:
1. Choose

> User management

2. Select the User Signup Options tab
3. Remove the tick from Notify administrators by email when an account is created
4. Choose Save
Screenshot: User signup options

Invite people to sign up

You can invite new users to the site by sending them a signup URL, called an 'invitation link'. You can copy
the invitation link and paste it onto a page or into an email message, or you can prompt Confluence to send
an email message containing the same link.
The option to send invitations is independent of the signup options. You can send invitations if signup is open
to all, restricted by domain, or disabled entirely. Even if signup is restricted or disabled, a person who has
received an invitation will be able to sign up.
When someone visits the invitation link in a browser, a Confluence signup screen will appear.
To invite people to sign up:

1.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 14

1. Choose

> User management

2. Select the Invite Users tab
3. Do either of the following:
Copy the Invitation Link and paste it into an email message, or onto a page on your intranet,
for example
Alternatively, prompt Confluence to send an email message for you:
a. Enter one or more email addresses in the field labeled Email To
Separate the addresses with commas. For example: [email protected],
[email protected]
b. Change the Message if you want to
c. Choose Send

Reset the invitation link

The invitation link includes a security token, like this:

http://confluence.example.com/signup.action?token=d513a04456312c47

This security token is a shared token – individual invitations don't have unique tokens. Anyone who obtains
this token will be able to sign up to Confluence.
You can change the token at any time, by choosing Reset. The previous invitation link will then become
unusable.
Screenshot: Inviting users

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 15

Add users manually

To add a new user:

1. Choose

> User management

2. Select the Add Users tab
3. Enter the user's details
4. Choose whether Confluence should send an email message informing the person of their new
username
The email message will contain a link that the person can use to reset their password.
5. Choose Create
Screenshot: Adding users

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 16

Notes

Multiple directories – You can define multiple user directories in Confluence, so that Confluence
looks in more than one place for its users and groups. For example, you could use the default
Confluence internal directory and connect to an LDAP directory server. In that case, you can define
the directory order to determine where Confluence looks first when processing users and groups.
Here is a summary of how the directory order affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
See Managing Multiple Directories.

Email server required for domain restricted signup and for invitations – You need to set up a mai
l server for Confluence, before you can configure domain restricted signup or send email invitations to
users.
Are the user management options not visible? If you have external user management turned on,
internal user management is disabled. To configure external user management, go to

> General Configuration> Security Configuration. See Disabling the Built-In User Management.
Avoid hash, slash and question characters in usernames - there is a known issue where users
with #, ? or / in their username cannot create spaces. See
CONFSERVER-43494 CONFSERVER-13479
GATHERING IMPACT and GATHERING IMPACT for
more information.

Delete or Disable Users

When someone leaves your organisation, or no longer needs to use On this page:
Confluence, you can either disable their user account, unsync it from any

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 17

external directories, or delete it entirely. Delete,

disable, or
unsync?
Disable a
user
account
Unsync a
user
account

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 18

Delete a
user
account
Del
ete
from
an
inter
nal
Con
flue
nce
dire
ctor
y or
read
/writ
e
exte
rnal
dire
ctor
y
Del
ete
from
a
read
-onl
y
exte
rnal
dire
ctor
y, or
mult
iple
exte
rnal
dire
ctori
es
How
dele
ted
user
s
app
ear
to
othe
r
peo
ple
Only
remove
access to
Confluenc
e

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 19

Limitations
when
deleting a
user
account
Fre
e
text
is
not
ano
nym
ised
Dat
a
stor
ed
in
Syn
chro
ny
is
not
dele
ted
Per
son
al
spa
ces
are
not
dele
ted
Wor
kbo
x
notif
icati
ons
don'
t
disa
ppe
ar
imm
edia
tely
Dat
a
stor
ed
by
third
-par
ty
app
s is
not
dele
ted

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 20

Related pages:
Manage
Users
Configurin
g User
Directories

Managing 500+ users across Atlassian products?

Find out how easy, scalable and effective it can be with Crowd!
See centralized user management.

Delete, disable, or unsync?

It's useful to understand the difference between disabling a user account, unsyncing it from an external
directory, and permanently deleting it from Confluence.
In most situations disabling or unsyncing a user account is the appropriate way to prevent a user from
accessing Confluence, for example when someone leaves your organisation. However, if you do need to
remove someone's name and personal details, you can permanently delete their user account.
When an user account is disabled:
The user won't be able to log in.
The user won't be included in your license count.
People won't be able to see the user in the People directory, mention them, or select their
name/username as a search filter.
Their full name will still appear on any spaces or content they created.
They will be listed in User Management admin screens.
Their account can be re-enabled (this will restore the connection to their content).
Any content they created will be maintained.
When a user account is unsynced from all external directories:
The user won't be able to log in.
The user won't be included in your license count.
People won't be able to see the user in the People directory, mention them, or select their
name/username as a search filter.
Their username will appear on any spaces or content they have created.
They will only be listed on the Unsynced from Directory tab of the User Management admin screens.
Their account will be restored if they are resynced with Confluence.
Any content they created will be maintained.
When a user account is deleted:
The user won't be able to log in.
The user won't be included in your license count.
People won't be able to see the user in the People directory, mention them, or select their
name/username as a search filter.
An anonymised alias will appear on any spaces or content they have created.
They won't be listed in User Management admin screens.
Their account is deleted and anonymised permanently, and can't be restored.
Any content they created will be maintained.

Disable a user account

How you disable a user account depends on whether you manage users in the internal Confluence directory,
or in an external user directory (for example Jira, Crowd, Active Directory).
You need the Confluence Administrator global permission to do this.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 21

To disable a user account:

1. Go to

> User management.

2. Search for the user you want to disable.
3. Choose Disable.
If there is no Disable option, it is likely that Confluence has a read-only connection to an external directory. If
this happens, you'll need to remove the user's access to Confluence in your external directory. This might be
done by disabling the user in that directory, or changing their group membership so they are not synced to
Confluence. They will be treated as an unsynced user in Confluence after your next directory sync.

Unsync a user account

You unsync a user account by excluding it from the accounts to be synchronized with Confluence in your
external directory. See Synchronizing Data from External Directories to learn more about how directory sync
works.
To view users who have previously been synchronized with Confluence, but were not present in the last
directory sync, go to

> User management > Unsynced from Directory.

It's important to note that user accounts can be unsynced intentionally, or because of a problem with your
external directory. Don't assume all unsynced user accounts are to be deleted.

Delete a user account

Deleting a user is permanent, so cannot be undone. If you're trying to reduce your license count, or only
need to remove a someone's access to Confluence, you should disable their account instead.
How you delete a user account depends on whether you manage users in:
an internal directory, or a single read/write external directory (such as Jira, Crowd, or Active Directory)
multiple external directories, or a single read-only external directory (such as Jira, Crowd, or Active
Directory).
The delete process can take several minutes, depending on the amount of content the person had created. It
can also flood your index queue, as it reindexes all pages the user contributed to, so you may want to
perform this task at a time that won't impact other users.
You need the Confluence Administrator global permission to do this.

Delete from an internal Confluence directory or read/write external directory

To permanently delete a user stored in the internal Confluence directory, or a single external directory that
has a read/write connection to Confluence:
1. Go to

> User management.

2. Search for the user you want to delete.
3. Choose Delete.
4. Wait for confirmation that the delete process is complete. This can take a few minutes.
The user account will be deleted from Confluence, and their name replaced with an anonymised alias. This
can't be undone.

Delete from a read-only external directory, or multiple external directories

Deleting a user stored in a read-only external directory or in multiple external directories, is a two-step
process. You need to remove them from all external directories and perform a directory resync before they

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 22

can be deleted from Confluence.

To permanently delete a user stored in multiple external directories, or an external directory that has a
read-only connection to Confluence:
1. In your external directory, remove the user. If the user exists in multiple directories, remove them from
each one.
2. In Confluence, go to

> User management > Unsynced from directory.

3. Search for the username of the person you want to delete.
If the user doesn't appear, wait for Confluence to sync your external directory (or trigger a re-sync if
you usually do this manually). See Synchronizing Data from External Directories.
4. Choose Delete.
5. Wait for confirmation that the delete process is complete. This can take a few minutes.
The user account will be deleted from Confluence, and their name replaced with an anonymised alias. This
can't be undone.

How deleted users appear to other people

Once a user account has been deleted their identity will be anonymised throughout Confluence in places like
the page byline, mentions, comments, and page history.
full names be replaced with an alias like 'user-38782'
usernames will be replaced with the user key (a long string of characters).
their profile picture will be replaced with a default image.
The alias and user key stays the same throughout the site. This means people can see that pages and
comments were made by the same person, but not know the identity of that person.

Only remove access to Confluence

If you want to remove someone's access to Confluence, but retain their user account (or you can't disable
their account for some reason), you can do this by changing their group membership.
1. Create a group, for example no-confluence-access
2. Go to

> General Configuration> Global Permissions.

3. Make sure the no-confluence-access group doesn't have Can Use Confluence permission.
4. Change the user's group membership so they are only a member of the no-confluence-access gr
oup.
If you don't manage groups in Confluence (for example group membership is always synced from your
external directory), the same principles apply, but you'll need to change the user's membership in your
external directory.
Remember that permissions are additive, so just being a member of a group without Confluence access is
not enough. To ensure the user can't log in to Confluence they must not be a member of ANY group that has
the Can Use Confluence global permission (in any user directory).

Limitations when deleting a user account

The ability to delete and anonymize a user account was added in Confluence 6.13.
For earlier Confluence versions there's a workaround you can use to permanently delete a user
account via the database. See Right to erasure in Confluence Server and Data Center.
You can also head to Confluence Server and Data Center GDPR support guides to read more about
Confluence and GDPR generally.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 23

There are some situations where personal information may still be stored in Confluence after you have
deleted a user account, and the delete process does not remove any actual content, for example if someone
has typed the user's name in plain text on a page, or if it is contained in an attached file.

Free text is not anonymised

Deleting a user does not delete any Confluence content (such as pages, files, or comments). This means
that any references to a person's full name, user name, or other personal information that were entered as
free text will remain after the user account is deleted. Text entered in the link text of a link or mention are also
considered free text (for example if you mention someone on a page and change the mention link text to use
just their first name, or a nickname).
Links to the deleted user's personal space (which contains their username in the URL) will also remain after
their personal space has been deleted, if the links were inserted as a web link or free text.
We suggest searching for the deleted person's name and username to see if there is any residual content left
behind.
There are also a couple of known issues that will require manual cleanup:
When multiple people are mentioned on a task, only the first (the assignee) is replaced with the
anonymised alias. This is due to an existing bug where subsequent mentions aren't indexed.
If the user to be deleted is listed on the All Updates tab on the dashboard at the point they are deleted,
their updated items will appear twice, once with their anonymised alias and once with their username.
They will drop off the All Updates tab as new updates occur, but their username will still be listed in the
search index. A full site reindex will resolve this issue.

Data stored in Synchrony is not deleted

If you have collaborative editing enabled, every keystroke in the editor is stored by Synchrony in the
Confluence database. This means that any references to a person's full name, user name, or other personal
information typed in the editor will remain in the Synchrony tables in the database.
See How to reduce the size of Synchrony tables to find out how to remove all data from these tables.

Personal spaces are not deleted

When you delete a user, their personal space is not automatically deleted, as it may contain content owned
by your organization. This means that:
their username will still be visible in the space URL
their name may still be visible in the space title or homepage title
We recommend moving any pages or blogs that you want to keep to a new space, and then deleting the
personal space entirely. Any links to the personal space will be updated with the new space key
automatically when the pages are moved, unless they have been added as a web link or free text.

Workbox notifications don't disappear immediately

The deleted user's full name will still appear in any existing workbox notifications. For example if the deleted
user had shared a page with another user, the notification will still appear in that user's workbox for up to 28
days. See Workbox Notifications for more information about how long a workbox notification is accessible
before it is automatically deleted.

Data stored by third-party apps is not deleted

When you delete a user, we replace the person's full name and username with an anonymous alias in all the
places we know about, such as mentions, page history, and in macros.
If you have installed apps from the Marketplace, there is a chance that these apps are storing data in their
own tables in the Confluence database. Refer to the documentation for your app to find out the best way to
remove this data.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 24

Restore Passwords To Recover Admin User Rights

If you're unable to log in to Confluence as an administrator (for example, On this page:
you've lost the administrator password) you can start Confluence in recovery Use
mode to recover your admin user rights. recovery
mode to
If you know the admin username, and it has a valid email address, you can
restore
reset the password using the forgot password link on the log in screen. We'll
access
send a link to your admin email account to reset your password.
As an administrator, you may find yourself locked out of Confluence because:
You've imported a site from Cloud, and it does not contain a system administrator account.
You've forgotten the password to the administrator account, and don't have access to the email
address associated with it.
You're using an external directory or Jira for user management, have disabled the built in user
management, and your external directory is not currently available.
You need to make a change to the configuration of an external user directory in Confluence while that
directory is not available.
In any of these situations you can use recovery mode to restore administrator access to Confluence.

Using Confluence 6.5.0 or earlier? You'll need to use the database method to recover your admin
user rights. See the earlier documentation.

Use recovery mode to restore access

Recovery mode works by creating a virtual user directory with a temporary admin account. You set the
password for this admin account when applying the system property. Users can continue to log in and
access Confluence while it is in recovery mode.
To recover administrator user rights:
1. Stop Confluence.
2. Edit <installation-directory>/bin/setenv.sh or setenv.bat and add the following
system property, replacing <your-password> with a unique, temporary password.

-Datlassian.recovery.password=<your-password>

See Configuring System Properties for more information on using system properties.
3. Start Confluence manually (don't start Confluence as a service).
4. Log in to Confluence with the username recovery_admin and the temporary password you specified
in the system property.
5. Reset the password for your existing admin account, or create a new account and add it to the
appropriate administrator group.
6. Confirm that you can successfully log in with your new account.
7. Stop Confluence.
8. Edit <installation-directory>/bin/setenv.sh or setenv.bat and remove the system
property.
9. Restart Confluence using your usual method (manually or by starting the service).
Good to know:
Remove the system property as soon as you have restored admin access.
Don't leave Confluence in recovery mode, or use the recovery_admin account as a regular
administrator account.
Your temporary password should be a unique. Don't use an existing password or the one you intend to
use for your admin account.

Edit User Details

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 25

You can view and edit the details of Confluence users, including their name, On this page:
password, email address, group membership, and ability to access
Confluence. Edit a
user's
details
Edit a user's details Reset login
count
1. Choose
Related pages:
> User management Delete or
2. Do either of the following: Disable
Choose Show all users to list everyone in the Users
'confluence-users' or 'users' group Adding or
Removing
Enter a username, full name or email address in the Find User
Users in
field and hit Search
Groups
Add and
If you're already viewing someone's profile, choose Ad Invite
minister User in the sidebar. Users

2. Select the user you want to manage

Now you'll see the person's current details and links allowing you to edit them.
View Profile — View the user's profile.
Edit Groups — Add or remove this user from a group.
Edit Details — Change details such as the user's name, email address, contact details and team or
department information. In some instances you may be able to change usernames as well. See Chang
e a Username for information.
Delete Profile Picture - remove current and all previous profile pictures uploaded by the user.
Set Password — Edit the user's password details.
Disable — You can disable (i.e. deactivate) access for a user who no longer needs access to
Confluence.
Delete — You can permanently delete a user, and replace their full name and username with an
anonymous alias.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 26

Reset login count

Confluence records the number of failed logins attempts made against each user account. When the login
attempts exceed a preset number, the user is prompted to authenticate using CAPTCHA until they
successfully log in.
If the user you're administering has any failed login attempts, you can manually set the failed login count for a
user back to zero by clicking Reset Failed Login Count.

Multiple user directories

You can define multiple user directories in Confluence, so that Confluence looks in more than one
place for its users and groups. For example, you could use the default Confluence internal directory
and connect to an LDAP directory server. In that case, you can define the directory order to
determine where Confluence looks first when processing users and groups.
Here is a summary of how the directory order affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
See Managing Multiple Directories.

Change a Username
As a Confluence administrator, you can change a user's username. This On this page:
could be for any reason, but might happen when someone changes their
name, for example. Confluenc
e-manage
Each active users must have a unique username, so no two active users d users
can have the same username. You can, however, assign the username of a Users
disabled user to another active user. managed
in an
The procedure for changing a username depends on where you manage
external
your users. See Configuring User Directories for more info.
directory
Notes

Confluence-managed users

If you manage your users in the Confluence internal directory, you can rename your user in Confluence.
You'll need Confluence Administrator permissions to change a username.
To change a username:
1. Choose

> User management

2. Search for the user or choose Show all users
3. Select the user you'd like to edit and choose Edit Details
4. Enter the new username and choose Submit
That person will need to use their new username to log in to Confluence from now on. The new username
will also be reflected throughout Confluence, including in @mentions.

Users managed in an external directory

If you don't manage your users in the Confluence internal directory, you may still be able to change
someone's username. Confluence can't update external users, but it will detect changes in usernames
coming from some external directories.
The following table shows the instances where you may be able to change a username in your external

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 27

directory and have the change detected in Confluence.

User directory Where to rename the user

Internal directory with LDAP Rename the user in the LDAP directory, Confluence will detect the
authentication renamed user.
Note: you must have 'Copy User on Login' enabled. See Copying Users
on Login for more information.

Jira 6.1 or later Rename the user in Jira, Confluence will automatically detect the
renamed user.

Atlassian Crowd 2.7 or later Rename the user in Crowd, Confluence will automatically detect the
renamed user.

LDAP Rename the user in your LDAP directory, Confluence will automatically
detect the renamed user.

Notes

Some important things to note about changing usernames:

Mentions and page history – Any user mentions in current pages will automatically reflect the user's
new username, but any mentions in page versions created prior to Confluence 5.3 will include the
user's old username.
Personal Spaces – If a Confluence Administrator renames a user who has a personal space, the
space key for that space will remain as the original username. For example, if jsmith's username is
changed to jbrown, their personal space key will remain ~jsmith.

Managing Site-Wide Permissions and Groups

Permissions determine what people can do on your
Confluence site. Confluence recognizes permissions Related pages:
at site level and at space level, as well as page-level Confluence Security Overview and
restrictions. Advisories
You can create groups and allocate people to them, Global Permissions Overview
so that you can assign permissions to a number of
people at once. It's quicker to give a group access to
Confluence than giving every member access
individually.
You can also set the access levels for anonymous
users or deny access to unlicensed users from
linked applications, such as Jira Service Desk.

Managing 500+ users across Atlassian

products?
Find out how easy, scalable and effective it
can be with Crowd!
See centralized user management.

Confluence Groups for Administrators

Grouping users in Confluence is a great way to cut down the work required
when managing permissions and restrictions. Once you have a group of
users, you can assign that group a set of global permissions. For example, if
you don't want that group of users to be able to create spaces, you can
revoke the 'Create Space(s)' permission.
Other users can also take advantage of Confluence groups. Space admins c
an assign a set of space permissions to a group rather than to each

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 28

individual user, and other users with the 'Add/Delete Restrictions' space On this page:
permission can add and remove page restrictions for groups.
Special
groups
Special groups Anonymou
s users
There are two special default groups in Confluence: Add or
1. confluence-administrators: This is a group of 'super-users' who can delete
access the Confluence administration screens ('administration groups
console') and perform site-wide administration. Members of this group Confluenc
can also see all spaces and pages in the Confluence site. Any user e
who is a member of this group has site-wide administration powers, Administra
regardless of any other setting. The settings on the global tor
permissions screen do not affect the powers allowed to members of permission
this group. vs
2. confluence-users: This is the default group for all new users. confluence
Permissions you assign to this group will be assigned to all newly -admin
created users. group
compariso
n
Notes
Related pages:
Manage
Users
Global
Permission
s Overview

The Confluence administrator global permission and the confluence-administrators group are not
related. Going by the names, you would think they are the same thing, but they are not. Granting a user or a
group Confluence administrator global permission provides access to a sub-set of administrative functions.
Granting membership to the confluence-administrators group gives complete access to all functions
and content.
View the comparison table.

Anonymous users

All users who don't log in when they access Confluence are considered 'anonymous'. You can grant
anonymous users the 'Use Confluence' permission via the Global Permissions screen if you need to. This will
allow non-registered users to access pages and spaces in Confluence. A space administrator can further
control anonymous access per space via the space permissions.

Add or delete groups

To add a new group:

1. Choose the cog icon

, then choose General Configuration

2. Choose Groups in the left-hand panel
3. Choose Add Group
4. Enter a name for your group and choose Save
You're now ready to start adding users to the group.
To delete a group:
1. Choose the cog icon

, then choose General Configuration

2.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 29

2. Choose Groups in the left-hand panel

You will see a list of all existing groups along with links to remove them.
3. Choose Delete next to the group you want to remove

Confluence Administrator permission vs confluence-admin group comparison

Granting the Confluence Administrator permission to someone allows them access to many, but not
all, options in the administration console (

> General configuration). Expand the comparison table to view the options available to people granted the
Confluence Administrator permission, and to those in the confluence-admin group.
Click to view the comparison table

Administration option Confluence Admin confluence-administrators

permission group

CONFIGURATION

General Configuration

Further Configuration

Manage Referrers

Languages

Shortcut Links

Global Templates and

Blueprints

Import Templates

Mail Servers

Recommended Updates Email

User Macros

In-app Notifications

HipChat Integration

Attachment Storage

Spam Prevention

PDF Export Language Support

Configure Code Macro

WebDAV Configuration

Office Connector

ATLASSIAN MARKETPLACE

Find new apps

Manage apps

USERS & SECURITY

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 30

Users

Groups

Security Configuration

Global Permissions

Space Permissions

User Directories

Whitelist

LOOK AND FEEL

Themes

Color Scheme

Layouts

Stylesheet

Site Logo and Favicon

PDF Layout

PDF Stylesheet

Default Space Logo

Custom HTML

ADMINISTRATION

System Information

Backup & Restore

Content Indexing

Mail Queue

Cache Management

Scheduled Jobs

License Details

Logging and Profiling

Thread Dump

Application Links

Application Navigator

Analytics

Import from Another Wiki

Atlassian Support Tools

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 31

Clustering

Notes

Multiple user directories: You can define multiple user directories in Confluence, so that Confluence
looks in more than one place for its users and groups. For example, you could use the default
Confluence internal directory and connect to an LDAP directory server. In that case, you can define
the directory order to determine where Confluence looks first when processing users and groups.
Here is a summary of how the directory order affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
See Managing Multiple Directories.

Adding or Removing Users in Groups

If you are a Confluence Administrator, you can add On this page:
users and groups, and assign users to groups, in
order to determine their permissions. Add and remove members via
group management
This page tells you how to add a user to a group or Edit group membership via user
remove a user from a group. For an overview of management
users and groups, please refer to Confluence
Groups and Manage Users. Related pages:

You can edit group membership in two places: Manage Users

Global Permissions Overview
From the group management screen
From the user management screen for a
particular user
If you're using Confluence Cloud head to Groups
and product access to find out how to do this in your
site.

Add and remove members via group management

This is the recommended method. It allows you to manage the group membership for a number of users at
the same time.
To add members to a group:
1. Choose the cog icon

, then choose General Configuration

2. Choose Groups in the left-hand panel
3. Choose the group to which you want to add users
4. Choose Add Members
5. Type the username(s) of the people you want to add to the group
If you want to add more than one member, separate the usernames with commas
You can also search for and select users by choosing the search icon
6. Choose Add to add the member(s) to the group
To remove members from a group:
1. Choose the cog icon

, then choose General Configuration

2. Choose Groups in the left-hand panel
3. Choose the group from which you want to remove the user
4.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 32

4. Choose the Delete user from group icon next to the user whose group membership you want to
remove

Screenshot: Adding members

Edit group membership via user management

You can update a user's group membership from the user management screen. This functionality allows you
to update one user at a time.
To add a user to a group or remove a user from a group:
1. Go to the user management screen for the user concerned. There are two ways to do this:
Either,
Go to the user's Profile and choose Administer User on the user's profile screen.
Or, Choose the cog icon

, then choose General Configuration

a. Choose Users in the left-hand panel
b. Choose Show all users, or search for a specific user by entering all or part of their
username, full name or email address
c. Choose the username you want to edit
2. Choose Edit Groups
3. Select the group(s) for this user
To remove a user from a group, remove the tick mark in the relevant check box.
Screenshot: Editing a user's groups

You can define multiple user directories in Confluence, so that Confluence looks in more than one
place for its users and groups. For example, you could use the default Confluence internal directory
and connect to an LDAP directory server. In that case, you can define the directory order to
determine where Confluence looks first when processing users and groups.
Here is a summary of how the directory order affects the processing:
The order of the directories is the order in which they will be searched for users and groups.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 33

Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
See Managing Multiple Directories.

Managing 500+ users across Atlassian products?

Find out how easy, scalable and effective it can be with Crowd!
See centralized user management.

Global Permissions Overview

Global Permissions determine the actions which a On this page:
user is allowed to perform in Confluence at a site
level. To assign global permissions to a user or Overview of global permissions
group you need Confluence Administrator or greater Comparing the System
permissions. Administrator permission with the
Confluence Administrator
The first system administrator is created in the setup permission
wizard when Confluence is first set up. This user has Comparing the
the system administrator global permission and is a confluence-administrators group
member of the confluence-administrators gr with the administrator permissions
oup. Updating global permissions
Revoking access for unlicensed
The default confluence-administrators gr users from Jira Service Desk
oup is a special, super-user group. Learn more. Error messages you may see

Overview of global permissions

The following global permissions can be applied to groups and individuals.

Global Description
Permission

Can Use This is the most basic permission that allows users to access the site.
Users with this permission count towards the number of users allowed by your license.

Attach Files This allows the user to upload files to be stored in their user profile.
to User
Profile This feature was made obsolete by the introduction of personal spaces in Confluence
2.2. Hence, this permission is no longer relevant. Attachments can be accessed from a
user profile view (for example, an image within the 'About Me' field of a profile view) by
attaching these files to a page within that user's personal space and referencing them
using appropriate wiki markup code.

Personal This permission allows the user to create a personal space.

Space

Create This permission allows users to create new spaces within your Confluence site. When a
Space(s) space is created, the creator automatically has the 'Admin' permission for that space and
can perform space-wide administrative functions.

Confluence This permission allows users to access the 'Administration Console' that controls
Administrator site-wide administrative functions. Users with this permission can perform most, but not
all, of the Confluence administrative functions. See the comparison of 'System
Administrator' and 'Confluence Administrator' below.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 34

System This permission allows users to access the 'Administration Console' that controls
Administrator site-wide administrative functions. Users with this permission can perform all the
Confluence administrative functions, including the ones which the 'Confluence
Administrator' permission does not allow. See the comparison of 'System Administrator'
and 'Confluence Administrator' below. Refer also to the note about the
'confluence-administrators' group below.

Comparing the System Administrator permission with the Confluence Administrator permission

Confluence recognizes two levels of administrator:

System Administrator – Users with this permission can perform all the Confluence administrative
functions, including the ones which the 'Confluence Administrator' permission does not allow.
Confluence Administrator – Users with this permission can perform most, but not all, of the
Confluence administrative functions.
The two-tier administration is useful when you want to delegate some administrator privileges to project
managers or team leaders. You can give 'Confluence Administrator' permission to users who should be able
to perform most administrative functions, but should not be able to perform functions that can compromise
the security of the Confluence system.
The following functions are granted to the 'System Administrator' permission but excluded from the
'Confluence Administrator' permission:

Administration Excluded from Confluence Administrator permission

Screen

General The following functionality is disallowed:

Configuration
Server Base URL
Public Signup
Connection Timeouts

Further The following functionality is disallowed:

Configuration
Remote API plugin

Security The following functionality is disallowed:

Configuration
External user management
Append wildcards to user and group searches
Enable Custom Stylesheets for Spaces
Show system information on the 500 page
Maximum RSS Items
XSRF Protection

Plugins The following functionality is disallowed:

Upgrade
Install
Confluence Upgrade Check

Daily Backup This function is disallowed entirely.

Admin

Mail Servers This function is disallowed entirely.

User Macros This function is disallowed entirely.

Attachment This function is disallowed entirely.

Storage

Layouts This function is disallowed entirely.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 35

Custom HTML This function is disallowed entirely.

Backup & This function is disallowed entirely.

Restore

Logging and This function is disallowed entirely.

Profiling

Cluster This function is disallowed entirely.

Configuration

Scheduled This function is disallowed entirely.

Jobs

Application People with the 'Confluence Administrator' permission can add, modify and remove
Links application links and project links. For example, they can link Confluence to Jira.
However, Confluence administrators can configure only OAuth authentication for
application links.

Office This function is disallowed entirely.

Connector
configuration

Comparing the confluence-administrators group with the administrator permissions

The default confluence-administrators group is a special, 'super-user' group that gets permissions
above and beyond the Confluence administrator and system administrator global permissions. Members of
this group can perform site-wide administration functions, and also see the content of all pages and spaces in
the Confluence site, regardless of space permissions or page restrictions.
Restricted pages and blog posts are not visible to members of the confluence-administrators group in
the dashboard, blog roll, search and most macros, but will be visible in the following places:
In the sidebar (visible with Page Tree navigation, but not visible with Child Pages navigation)
Pages index page
Reorder pages screen
Page tree macro
Content by user macro
Quicknav
Members of this group can also see restricted pages and blog posts if they have the page URL.
Members of this group can't edit pages by default however. They would need to grant themselves space
permissions, or add themselves to the page restrictions in order to edit.
Granting a user the system administrator and Confluence administrator global permissions does not allow
that user to automatically see all spaces in your site, or see restricted pages. These permissions only give
access to administration tools. Be aware, however, that users with system administrator global permission
could add themselves to the confluence-administrators group.

You can't change the global permissions granted to the confluence-administrators group. If you don't
want your admins to be able to see all spaces and restricted pages, you can create a new group, and grant
that group the Confluence administrator and system administrator global permissions.
The Confluence administrator global permission and the confluence-administrators group are not
related. Going by the names, you would think they are the same thing, but they are not. Granting a user or a
group Confluence administrator global permission provides access to a sub-set of administrative functions.
Granting membership to the confluence-administrators group gives complete access to all functions
and content.

Updating global permissions

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 36

To view the global permissions for a group or user:

1. Choose the cog icon

, then choose General Configuration

2. Choose Global Permissions in the left-hand panel. The 'View Global Permissions' screen appears.
Add or edit group and user permissions as follows:
To add permissions for a group:
1. First add the group to Confluence, if you have not already done so.
2. Choose Edit Permissions. The 'Edit Global Permissions' screen appears.
3. Enter the group name in the Grant browse permission to box in the 'Groups' section. You can
search for the group name.
4. Choose Add.
5. The group will appear in the list and you can now edit its permissions.
To add permissions for a specific user:
(Consider adding the user to a group and then assigning the permissions to the group, as described above,
instead of assigning permissions to the specific user.)
1. First add the user to Confluence, if you have not already done so.
2. Choose Edit Permissions. The 'Edit Global Permissions' screen appears.
3. Enter the username in the Grant browse permission to box in the 'Individual Users' section. You can
search for the username.
4. Choose Add.
5. The username will appear in the list and you can now edit its permissions.
To add or edit the permissions for a user or group:
1. Select, or clear, the check box under the relevant permission in the row for the relevant user/group. A
selected check box indicates that the permission is granted.
2. To allow anonymous access to your Confluence site, select the 'Use Confluence' and 'View User
Profile' options in the 'Anonymous Access' section.
3. Choose Save All to save your changes.
Screenshot: Editing global permissions

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 37

Revoking access for unlicensed users from Jira Service Desk

If you're using Confluence as a knowledge base for Jira Service Desk, you can choose to allow all active
users and customers (that is logged in users who do not have a Confluence license) to view pages in specific
spaces. This permission can only be turned on via Jira Service Desk.
To revoke access for unlicensed users:
1. Go to

> General Configuration > Global Permissions.

2. Choose Edit Permissions
3. Deselect the 'Can Use' permission under Unlicensed Access.
Unlicensed users will no longer be able to access pages in your Confluence site. This can only be re-enabled
via Jira Service Desk.
You can also choose to revoke access for individual spaces from the Space Permissions screen in each
space.
Screenshot: Unlicensed access section of the Global Permissions page.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 38

This section only appears on the Global Permissions page in Confluence if you have linked a space to your
Service Desk project (as a Knowledge base), and chosen to allow all active users and customers to access
without a Confluence license. See Serving customers with a knowledge base in the Service Desk
documentation for more info.

Error messages you may see

Confluence will let you know if there is a problem with some permissions. In rare situations, you may see the
following error messages below a permission:
'User/Group not found' - This message may appear if your LDAP repository is unavailable, or if the
user/group has been deleted after the permission was created.
'Case incorrect. Correct case is: xxxxxx' - This message may appear if the upper/lower case in the
permission does not match the case of the username or group name. If you see a number of
occurrences of this message, you should consider running the routine supplied to fix the problem.

Setting Up Public Access

You can enable anonymous access (also known as On this page:
public access) to your Confluence site by granting
the 'Use Confluence' permission to 'anonymous' Enabling anonymous access to
users. An 'anonymous' user is someone who has not the site
logged in to the Confluence site. The 'Use Disabling anonymous access to
Confluence' permission is also called 'can use'. the site
Granting public access to a space
This user category gives you an easy way to Notes
administer users who have not logged into the site.
Permissions assigned to this category apply to all Related pages:
anonymous users of the site. Configuring Captcha for Spam
Prevention
Enabling anonymous access to the site Add and Invite Users
Global Permissions Overview
If you want to make your site visible to everyone,
including people who have not logged in, you must
enable anonymous access at site level.
To enable anonymous access to your site:
1. Choose the cog icon

, then choose General Configuration

2. Choose Global Permissions in the left-hand panel.
3. Choose Edit Permissions.
4. In the 'Anonymous Access' section, select the can use check box to enable anonymous access to the
content on your site.
5. If you want to allow anonymous users to see user profiles, select the check box in the View User
Profiles section.
Note: You must grant the 'can use' permission as well, if you want to grant the 'View User Profiles'
permission.
6. Choose Save All.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 39

Disabling anonymous access to the site

To disable anonymous access to your site, deselect the can use check box, then choose Save All. People
will not be able to see the content on the site until they have logged in.

Granting public access to a space

To enable public access to a Confluence space, you must grant the following permissions to anonymous
users:
The site-wide 'can use' permission, as described above.
The relevant space permissions. If you want a space to be publicly accessible, the anonymous user
must have at least the 'View Space' permission. To set space permissions, choose Browse > Space
Admin > Permissions.

Notes

You can't grant Space Admin or Restrict permissions to anonymous users.

You can allow people to sign up for usernames themselves, and choose other options for user signup
and invitations. See Add and Invite Users.

Configuring User Directories

A user directory is a place where you store On this page:
information about users and groups. User
information includes the person's full name, Configuring User Directories in
username, password, email address and other Confluence
personal information. Group information includes the Connecting to a Directory
name of the group, the users that belong to the Updating Directories
group, and possibly groups that belong to other
Related pages:
groups.
Add and Invite Users
The internal directory stores user and group
Managing Site-Wide Permissions
information in the Confluence database. You can
and Groups
also connect to external user directories, and to
Atlassian Crowd and Jira applications as directory
managers.

Managing 500+ users across Atlassian products?

Find out how easy, scalable and effective it can be with Crowd!
See centralized user management.

Configuring User Directories in Confluence

To configure your Confluence user directories:

1. Choose the cog icon

, then choose General Configuration

2. Click 'User Directories' in the left-hand panel.

Connecting to a Directory

You can add the following types of directory servers and directory managers:
Confluence's internal directory. See Configuring the Internal Directory.
Microsoft Active Directory. See Connecting to an LDAP Directory.
Various other LDAP directory servers. See Connecting to an LDAP Directory.
An LDAP directory for delegated authentication. See Connecting to an Internal Directory with LDAP
Authentication.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 40

Atlassian Crowd or Jira 4.3 or later. See Connecting to Crowd or Jira for User Management.
You can add as many external user directories as you need. Note that you can define the order of the
directories. This determines which directory Confluence will search first, when looking for user and group
information. See Managing Multiple Directories.

Updating Directories

Limitations when Editing Directories

You cannot edit, disable or remove the directory your user belongs to. This precaution is designed to prevent
administrators from locking themselves out of the application by changing the directory configuration in a way
that prevents them logging in or removes their administration permissions.
This limitation applies to all directory types. For example:
You cannot disable the internal directory if your user is an internal user.
You cannot disable or remove an LDAP or a Crowd directory if your user comes from that directory.
In some situations, reordering the directories will change the directory that the current user comes from, if a
user with the same username happens to exist in both. This behavior can be used in some cases to create a
copy of the existing configuration, move it to the top, then remove the old one. Note, however, that duplicate
usernames are not a supported configuration.
You cannot remove the internal directory. This precaution aligns with the recommendation below that you
always keep an administrator account active in the internal directory.

Recommendations

The recommended way to edit directory configurations is to log in as an internal user when making changes
to external directory configuration.
We recommend that you keep either an administrator or system administrator user active in your internal
directory for troubleshooting problems with your user directories.

Enabling, Disabling and Removing Directories

You can enable or disable a directory at any time. If you disable a directory, your configuration details will
remain but the application will not recognize the users and groups in that directory.
You have to disable a directory before you can remove it. Removing a directory will remove the details from
the database.

Screenshot above: Configuring user directories

Configuring the Internal Directory

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 41

The internal directory stores user and group On this page:

information in the Confluence database.
Overview
Diagram of Possible Configuration
Overview
Related pages:
The internal directory is enabled by default at
Configuring User Directories
installation. When you create the first administrator
How to Reenable the Internal
during the setup procedure, that administrator's
Directory (Knowledge base article)
username and other details are stored in the internal
directory.
If needed, you can configure one or more additional
user directories. This is useful if you want to grant
access to users and groups that are stored in a
corporate directory or other directory server.

Diagram of Possible Configuration

Diagram above: Confluence using its internal directory for user management.

Connecting to an LDAP Directory

You can connect your Confluence application to an
LDAP directory for authentication, user and group
management.

Managing 500+ users across Atlassian

products?
Find out how easy, scalable and effective it
can be with Crowd!
See centralized user management.

Overview

An LDAP directory is a collection of data about users

and groups. LDAP (Lightweight Directory Access
Protocol) is an Internet protocol that web

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 42

applications can use to look up information about On this page:

those users and groups from the LDAP server.
Overview
We provide built-in connectors for the most popular Connecting to an LDAP Directory
LDAP directory servers: in Confluence
Server Settings
Microsoft Active Directory
Schema Settings
Apache Directory Server (ApacheDS)
Permission Settings
Apple Open Directory
Adding Users to Groups
Fedora Directory Server
Automatically
Novell eDirectory
Advanced Settings
OpenDS
User Schema Settings
OpenLDAP
Group Schema Settings
OpenLDAP Using Posix Schema
Membership Schema Settings
Posix Schema for LDAP
Diagrams of Some Possible
Sun Directory Server Enterprise Edition
Configurations
(DSEE)
A generic LDAP directory server Related pages:
When to use this option: Connecting to an LDAP Configuring User Directories
directory server is useful if your users and groups
are stored in a corporate directory. When configuring
the directory, you can choose to make it read only,
read only with local groups, or read/write. If you
choose read/write, any changes made to user and
group information in the application will also update
the LDAP directory.

Connecting to an LDAP Directory in Confluence

To connect Confluence to an LDAP directory:

1. Choose the cog icon

, then choose General Configuration

2. Click User Directories in the left-hand panel.
3. Add a directory and select one of these types:
Microsoft Active Directory – This option provides a quick way to select AD, because it is the
most popular LDAP directory type.
LDAP – You will be able to choose a specific LDAP directory type on the next screen.
4. Enter the values for the settings, as described below.
5. Save the directory settings.
6. Define the directory order by clicking the blue up- and down-arrows next to each directory on the
'User Directories' screen. Here is a summary of how the directory order affects the processing:
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
The order of the directories is the order in which they will be searched for users and groups (by
default Confluence aggregates group membership from all directories, so the order does not
impact membership itself).
For details see Managing Multiple Directories.

Server Settings

Setting Description

Name Enter a meaningful name to help you identify the LDAP directory server. Examples:
Example Company Staff Directory
Example Company Corporate LDAP

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 43

Directory Select the type of LDAP directory that you will connect to. If you are adding a new LDAP
Type connection, the value you select here will determine the default values for many of the
options on the rest of screen. Examples:
Microsoft Active Directory
OpenDS
And more.

Hostname The host name of your directory server. Examples:

ad.example.com
ldap.example.com
opends.example.com

Port The port on which your directory server is listening. Examples:

389
10389
636 (for example, for SSL)

Use SSL Check this if the connection to the directory server is an SSL (Secure Sockets Layer)
connection. Note that you will need to configure an SSL certificate in order to use this
setting.

Username The distinguished name of the user that the application will use when connecting to the
directory server. Examples:
cn=administrator,cn=users,dc=ad,dc=example,dc=com
cn=user,dc=domain,dc=name
[email protected]

By default, all users can read the uSNChanged attribute; however, only
administrators or users with relevant permissions can access the Deleted Objects
container. The specific privileges required by the user to connect to LDAP are
"Bind" and "Read" (user info, group info, group membership, update sequence
number, deleted objects), which the user can obtain by being a member of the
Active Directory's built-in administrators group.
Note that the incremental sync will fail silently if the Active Directory is accessed by
a user without these privileges. This has been reported as CWD-3093.

Password The password of the user specified above.

Note: Connecting to an LDAP server requires that this application log in to the server with
the username and password configured here. As a result, this password cannot be one-way
hashed - it must be recoverable in the context of this application. The password is currently
stored in the database in plain text without obfuscation. To guarantee its security, you need
to ensure that other processes do not have OS-level read permissions for this application's
database or configuration files.

Schema Settings

Setting Description

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 44

Base DN The root distinguished name (DN) to use when running queries against the directory server.
Examples:
o=example,c=com
cn=users,dc=ad,dc=example,dc=com
For Microsoft Active Directory, specify the base DN in the following format: dc=domain
1,dc=local. You will need to replace the domain1 and local for your specific
configuration. Microsoft Server provides a tool called ldp.exe which is useful for finding
out and configuring the the LDAP structure of your server.

Additional This value is used in addition to the base DN when searching and loading users. If no value
User DN is supplied, the subtree search will start from the base DN. Example:
ou=Users

Additional This value is used in addition to the base DN when searching and loading groups. If no
Group value is supplied, the subtree search will start from the base DN. Example:
DN
ou=Groups

If no value is supplied for Additional User DN or Additional Group DN this will cause the subtree
search to start from the base DN and, in case of huge directory structure, could cause performance
issues for login and operations that rely on login to be performed.

Permission Settings

Note: You can only assign LDAP users to local groups when 'External Management User Management' is
not selected.

Setting Description

Read Only LDAP users, groups and memberships are retrieved from your directory server and can
only be modified via your directory server. You cannot modify LDAP users, groups or
memberships via the application administration screens.

Read LDAP users, groups and memberships are retrieved from your directory server and can
Only, with only be modified via your directory server. You cannot modify LDAP users, groups or
Local memberships via the application administration screens. However, you can add groups to
Groups the internal directory and add LDAP users to those groups.
Note for Confluence users: Users from LDAP are added to groups maintained in
Confluence's internal directory the first time they log in. This is only done once per user.
There is a known issue with Read Only, with Local Groups in Confluence that may apply to
you. See
CONFSERVER-28621 - User Loses all Local Group Memberships If LDAP Sync is Unable to find
the User, but the User appears again in subsequent syncs CLOSED

Read/Write LDAP users, groups and memberships are retrieved from your directory server. When you
modify a user, group or membership via the application administration screens, the
changes will be applied directly to your LDAP directory server. Please ensure that the
LDAP user specified for the application has modification permissions on your LDAP
directory server.

Adding Users to Groups Automatically

Setting Description

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 45

Default Option available in Confluence 3.5 and later, and JIRA 4.3.3 and later. This field appears
Group if you select the 'Read Only, with Local Groups' permission. If you would like users to be
Memberships automatically added to a group or groups, enter the group name(s) here. To specify
more than one group, separate the group names with commas.
In Confluence 3.5 to Confluence 3.5.1: Each time a user logs in, their group
memberships will be checked. If the user does not belong to the specified group(s), their
username will be added to the group(s). If a group does not yet exist, it will be added
locally.
In Confluence 3.5.2 and later, and JIRA 4.3.3 and later: The first time a user logs in,
their group memberships will be checked. If the user does not belong to the specified
group(s), their username will be added to the group(s). If a group does not yet exist, it
will be added locally. On subsequent logins, the username will not be added
automatically to any groups. This change in behavior allows users to be removed from
automatically-added groups. In Confluence 3.5 and 3.5.1, they would be re-added upon
next login.

Please note that there is no validation of the group names. If you mis-type the group
name, authorization failures will result – users will not be able to access the applications
or functionality based on the intended group name.

Examples:
confluence-users
confluence-users,jira-administrators,jira-core-users

Advanced Settings

Setting Description

Enable Nested Enable or disable support for nested groups. Some directory servers allow you to
Groups define a group as a member of another group. Groups in such a structure are called n
ested groups. Nested groups simplify permissions by allowing sub-groups to inherit
permissions from a parent group.

Manage User If true, you can activate and deactivate users in Crowd independent of their status in
Status Locally the directory server.

Filter out If true, user accounts marked as expired in ActiveDirectory will be automatically
expired users removed. For cached directories, the removal of a user will occur during the first
synchronization after the account's expiration date.
Note: This is available in Embedded Crowd 2.0.0 and above, but not available in the
2.0.0 m04 release.

Use Paged Enable or disable the use of the LDAP control extension for simple paging of search
Results results. If paging is enabled, the search will retrieve sets of data rather than all of the
search results at once. Enter the desired page size – that is, the maximum number of
search results to be returned per page when paged results are enabled. The default is
1000 results.

Follow Choose whether to allow the directory server to redirect requests to other servers.
Referrals This option uses the node referral (JNDI lookup java.naming.referral)
configuration setting. It is generally needed for Active Directory servers configured
without proper DNS, to prevent a 'javax.naming.PartialResultException: Unprocessed
Continuation Reference(s)' error.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 46

Naive DN If your directory server will always return a consistent string representation of a DN,
Matching you can enable naive DN matching. Using naive DN matching will result in a
significant performance improvement, so we recommend enabling it where possible.

This setting determines how your application will compare DNs to determine if they
are equal.
If this checkbox is selected, the application will do a direct, case-insensitive, string
comparison. This is the default and recommended setting for Active Directory,
because Active Directory guarantees the format of DNs.
If this checkbox is not selected, the application will parse the DN and then check
the parsed version.

Enable Enable incremental synchronization if you only want changes since the last
Incremental synchronization to be queried when synchronizing a directory.
Synchronization
Please be aware that when using this option, the user account configured for
synchronization must have read access to:
The uSNChanged attribute of all users and groups in the directory that need to be
synchronized.
The objects and attributes in the Active Directory deleted objects container.
If at least one of these conditions is not met, you may end up with users who are
added to (or deleted from) the Active Directory not being respectively added (or
deleted) in the application.
This setting is only available if the directory type is set to "Microsoft Active Directory".

Synchronization Synchronization is the process by which the application updates its internal store of
Interval user data to agree with the data on the directory server. The application will send a
(minutes) request to your directory server every x minutes, where 'x' is the number specified
here. The default value is 60 minutes.

Read Timeout The time, in seconds, to wait for a response to be received. If there is no response
(seconds) within the specified time period, the read attempt will be aborted. A value of 0 (zero)
means there is no limit. The default value is 120 seconds.

Search Timeout The time, in seconds, to wait for a response from a search operation. A value of 0
(seconds) (zero) means there is no limit. The default value is 60 seconds.

Connection This setting affects two actions. The default value is 0.

Timeout
(seconds) The time to wait when getting a connection from the connection pool. A value of 0
(zero) means there is no limit, so wait indefinitely.
The time, in seconds, to wait when opening new server connections. A value of 0
(zero) means that the TCP network timeout will be used, which may be several
minutes.

User Schema Settings

Setting Description

User This is the name of the class used for the LDAP user object. Example:
Object
Class user

User The filter to use when searching user objects. Example:

Object
Filter (&(objectCategory=Person)(sAMAccountName=*))
More examples can be found in our knowledge base. See How to write LDAP search filters.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 47

User The attribute field to use when loading the username. Examples:
Name
Attribute cn
sAMAccountName

NB: In Active Directory, the 'sAMAccountName' is the 'User Logon Name (pre-Windows
2000)' field. The User Logon Name field is referenced by 'cn'.

User The RDN (relative distinguished name) to use when loading the username. The DN for each
Name LDAP entry is composed of two parts: the RDN and the location within the LDAP directory
RDN where the record resides. The RDN is the portion of your DN that is not related to the
Attribute directory tree structure. Example:
cn

User First The attribute field to use when loading the user's first name. Example:
Name
Attribute givenName

User Last The attribute field to use when loading the user's last name. Example:
Name
Attribute sn

User The attribute field to use when loading the user's full name. Example:
Display
Name displayName
Attribute

User The attribute field to use when loading the user's email address. Example:
Email
Attribute mail

User The attribute field to use when loading a user's password. Example:
Password
Attribute unicodePwd

User The attribute used as a unique immutable identifier for user objects. This is used to track
Unique I username changes and is optional. If this attribute is not set (or is set to an invalid value),
D user renames will not be detected — they will be interpreted as a user deletion then a new
Attribute user addition.
This should normally point to a UUID value. Standards-compliant LDAP servers will
implement this as 'entryUUID' according to RFC 4530. This setting exists because it is
known under different names on some servers, e.g. 'objectGUID' in Microsoft Active
Directory.

Group Schema Settings

Setting Description

Group Object Class This is the name of the class used for the LDAP group object. Examples:
groupOfUniqueNames
group

Group Object Filter The filter to use when searching group objects. Example:
(&(objectClass=group)(cn=*))

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 48

Group Name Attribute The attribute field to use when loading the group's name. Example:
cn

Group Description Attribute The attribute field to use when loading the group's description. Example:
description

Membership Schema Settings

Setting Description

Group Members Attribute The attribute field to use when loading the group's members. Example:
member

User Membership Attribute The attribute field to use when loading the user's groups. Example:
memberOf

Use the User Membership Check this if your directory server supports the group membership attribute
Attribute, when finding the on the user. (By default, this is the 'memberOf' attribute.)
user's group membership
If this checkbox is selected, your application will use the group
membership attribute on the user when retrieving the list of groups
to which a given user belongs. This will result in a more efficient
retrieval.
If this checkbox is not selected, your application will use the members
attribute on the group ('member' by default) for the search.
If the Enable Nested Groups checkbox is seleced, your application
will ignore the Use the User Membership Attribute option and will
use the members attribute on the group for the search.

Use the User Membership Check this if your directory server supports the user membership attribute
Attribute, when finding the on the group. (By default, this is the 'member' attribute.)
members of a group
If this checkbox is selected, your application will use the group
membership attribute on the user when retrieving the members of a
given group. This will result in a more efficient search.
If this checkbox is not selected, your application will use the members
attribute on the group ('member' by default) for the search.

Diagrams of Some Possible Configurations

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 49

Diagram above: Confluence connecting to an LDAP directory.

Diagram above: Confluence connecting to an LDAP directory with permissions set to read only and local
groups.

Configuring the LDAP Connection Pool

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 50

When connection pooling is enabled, the LDAP Related pages:

directory server maintains a pool of connections and
assigns them as needed. When a connection is Connecting to an LDAP Directory
closed, the directory server returns the connection to Configuring User Directories
the pool for future use. This can improve
performance significantly.

To configure your LDAP connection pool:

1. Choose the cog icon

, then choose General Configuration

2. Click 'User Directories' in the left-hand panel.
3. Click 'LDAP Connection Pool Configuration' in the 'Additional Configuration' section.

Setting Description Default

Value

Initial Pool The number of LDAP connections created when initially connecting to the 1
Size pool.

Preferred The optimal pool size. LDAP will remove idle connections when the number of 10
Pool Size connections grows larger than this value. A value of 0 (zero) means that there
is no preferred size, so the number of idle connections is unlimited.

Maximum The maximum number of connections. When the number of connections 0

Pool Size reaches this value, LDAP will refuse further connections. As a result, requests
made by an application to the LDAP directory server will be blocked. A value
of 0 (zero) means that the number of connections is unlimited.

Pool Timeout The length of time, in seconds, that a connection may remain idle before 30
(seconds) being removed from the pool. When the application is finished with a pooled
connection, the connection is marked as idle, waiting to be reused. A value of
0 (zero) means that the idle time is unlimited, so connections will never be
timed out.

Pool Protocol Only these protocol types will be allowed to connect to the LDAP directory plain
server. If you want to allow multiple protocols, enter the values separated by a ssl
space. Valid values are: (Both
plain
plain
and ssl)
ssl

Pool Only these authentication types will be allowed to connect to the LDAP simple
Authentication directory server. If you want to allow multiple authentication types, enter the
values separated by a space. See RFC 2829 for details of LDAP
authentication methods. Valid values are:
none
simple
DIGEST-MD5

Notes:
The connection pool settings are system wide and will be used to create a new connection pool for
every configured LDAP directory server.
You must restart your application server for these settings to take effect.

Configuring an SSL Connection to Active Directory

If you want to configure a read/write connection with
Microsoft Active Directory, you will need to install an
SSL certificate, generated by your Active Directory

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 51

server, onto your Confluence server and then install On this page:
the certificate into your JVM keystore.
Prerequisites
Step 1. Install the Active Directory
Certificate Services
Step 2. Obtain the Server
Certificate
Step 3. Import the Server
Certificate
Related pages:
Connecting to an LDAP Directory
Configuring User Directories

There's a Confluence SSL plugin that facilitates this process.

Updating user, group, and membership details in Active Directory requires that your Atlassian application be
running in a JVM that trusts the AD server. To do this, we generate a certificate on the Active Directory
server, then import it into Java's keystore.

Prerequisites

To generate a certificate, you need the following components installed on the Windows Domain Controller to
which you're connecting.

Required Component Description

Internet Information Services This is required before you can install Windows Certificate Services.
(IIS)

Windows Certificate Services This installs a certification authority (CA) which is used to issue
certificates. Step 1, below, explains this process.

Windows 2000 Service Pack Required if you are using Windows 2000
2

Windows 2000 High Required if you are using Windows 2000. Provides the highest available
Encryption Pack (128-bit) encryption level (128-bit).

Step 1. Install the Active Directory Certificate Services

If Certificate Services are already installed, skip to step 2, below. The screenshots below are from Server
2008, but the process is similar for Server 2000 and 2003.
1. Log in to your Active Directory server as an administrator.
2. Click Start, point to Administrative Tools, and then click Server Manager.
3. In the Roles Summary section, click Add Roles.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 52

4. On the Select Server Roles page, select the Active Directory Certificate Services check box. Click
Next twice.

5. On the Select Role Services page, select the Certification Authority check box, and then click Next
.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 5. 6.15 Documentation
Confluence 53

6. On the Specify Setup Type page, click Enterprise, and then click Next.

7. On the Specify CA Type page, click Root CA, and then click Next.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
7. 6.15 Documentation 54

8. On the Set Up Private Key and Configure Cryptography for CA pages, you can configure optional
configuration settings, including cryptographic service providers. However, the default values should
be fine. Click Next twice.

9.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 55

9. In the Common name for this CA box, type the common name of the CA, and then click Next.

10. On the Set Validity Period page, accept the default values or specify other storage locations for the
certificate database and the certificate database log, and then click Next.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 56

11. After verifying the information on the Confirm Installation Selections page, click Install.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 57

12. Review the information on the results screen to verify that the installation was successful.

Step 2. Obtain the Server Certificate

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 58

The steps above describe how to install the certification authority (CA) on your Microsoft Active Directory
server. Next, you will need to add the Microsoft Active Directory server's SSL certificate to the list of accepted
certificates used by the JDK that runs your application server.
The Active Directory certificate is automatically generated and placed in root of the C:\ drive, matching a file
format similar to the tree structure of your Active Directory server. For example: c:\ad2008.ad01.atlass
ian.com_ad01.crt.

You can also export the certificate by executing this command on the Active Directory server:

certutil -ca.cert client.crt

You might still fail to be authenticated using the certificate file above. In this case, Microsoft's LDAP over SSL
(LDAPS) Certificate page might help. Note that you need to:

1. Choose "No, do not export the private key" in step-10 of Exporting the LDAPS Certificate and
Importing for use with AD DS section
2. Choose "DER encoded binary X.509 (.CER)" in step-11 of Exporting the LDAPS Certificate and
Importing for use with AD DS section. This file will be used in the following step.

Step 3. Import the Server Certificate

For an application server to trust your directory's certificate, the certificate must be imported into your Java
runtime environment. The JDK stores trusted certificates in a file called a keystore. The default keystore file
is called cacerts and it lives in the jre\lib\security sub-directory of your Java installation.

In the following examples, we use server-certificate.crt to represent the certificate file exported by
your directory server. You will need to alter the instructions below to match the name actually generated.
Once the certificate has been imported as per the below instructions, you will need to restart the application
to pick up the changes.

Windows

1. Navigate to the directory in which Java is installed. It's probably called something like C:\Program
Files\Java\jdk1.5.0_12.

cd /d C:\Program Files\Java\jdk1.5.0_12

2. Run the command below, where server-certificate.crt is the name of the file from your
directory server:

keytool -importcert -keystore .\jre\lib\security\cacerts -file

server-certificate.crt

3. keytool will prompt you for a password. The default keystore password is changeit.
4. When prompted Trust this certificate? [no]: enter yes to confirm the key import:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 59

Enter keystore password: changeit

Owner: CN=ad01, C=US
Issuer: CN=ad01, C=US
Serial number: 15563d6677a4e9e4582d8a84be683f9
Valid from: Tue Aug 21 01:10:46 ACT 2007 until: Tue Aug 21
01:13:59 ACT 2012
Certificate fingerprints:
MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE
SHA1:
73:73:4E:A6:A0:D1:4E:F4:F3:CD:CE:BE:96:80:35:D2:B4:7C:79:C1
Trust this certificate? [no]: yes
Certificate was added to keystore

You may now change 'URL' to use LDAP over SSL (i.e. ldaps://<HOSTNAME>:636/) and use the 'Secure
SSL' option when connecting your application to your directory server.

UNIX

1. Navigate to the directory in which the Java used by JIRA is installed. If the default JAVA installation is
used, then it would be

cd $JAVA_HOME

2. Run the command below, where server-certificate.crt is the name of the file from your
directory server:

sudo keytool -importcert -keystore ./jre/lib/security/cacerts

-file server-certificate.crt

3. keytool will prompt you for a password. The default keystore password is changeit.
4. When prompted Trust this certificate? [no]: enter yes to confirm the key import:

Password:
Enter keystore password: changeit
Owner: CN=ad01, C=US
Issuer: CN=ad01, C=US
Serial number: 15563d6677a4e9e4582d8a84be683f9
Valid from: Tue Aug 21 01:10:46 ACT 2007 until: Tue Aug 21
01:13:59 ACT 2012
Certificate fingerprints:
MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE
SHA1:
73:73:4E:A6:A0:D1:4E:F4:F3:CD:CE:BE:96:80:35:D2:B4:7C:79:C1
Trust this certificate? [no]: yes
Certificate was added to keystore

You may now change 'URL' to use LDAP over SSL (i.e. ldaps://<HOSTNAME>:636/) and use the 'Secure
SSL' option when connecting your application to your directory server.

Mac OS X

1. Navigate to the directory in which Java is installed. This is usually

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 60
1.

cd /Library/Java/Home

2. Run the command below, where server-certificate.crt is the name of the file from your
directory server:

sudo keytool -importcert -keystore ./jre/lib/security/cacerts

-file server-certificate.crt

3. keytool will prompt you for a password. The default keystore password is changeit.
4. When prompted Trust this certificate? [no]: enter yes to confirm the key import:

Password:
Enter keystore password: changeit
Owner: CN=ad01, C=US
Issuer: CN=ad01, C=US
Serial number: 15563d6677a4e9e4582d8a84be683f9
Valid from: Tue Aug 21 01:10:46 ACT 2007 until: Tue Aug 21
01:13:59 ACT 2012
Certificate fingerprints:
MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE
SHA1:
73:73:4E:A6:A0:D1:4E:F4:F3:CD:CE:BE:96:80:35:D2:B4:7C:79:C1
Trust this certificate? [no]: yes
Certificate was added to keystore

You may now change 'URL' to use LDAP over SSL (i.e. ldaps://<HOSTNAME>:636/) and use the 'Secure
SSL' option when connecting your application to your directory server.

Connecting to an Internal Directory with LDAP Authentication

You can connect your Confluence application to an On this page:
LDAP directory for delegated authentication. This
means that Confluence will have an internal Overview
directory that uses LDAP for authentication only. Connecting Confluence to an
There is an option to create users in the internal Internal Directory with LDAP
directory automatically when they attempt to log in, Authentication
as described in the settings section. Server Settings
Copying Users on Login
Schema Settings
Overview Advanced Settings
User Schema Settings
An internal directory with LDAP authentication offers Group Schema Settings
the features of an internal directory while allowing Membership Schema Settings
you to store and check users' passwords in LDAP Diagrams of Possible
only. Note that the 'internal directory with LDAP Configurations
authentication' is separate from the default 'internal
directory'. On LDAP, all that the application does is Related pages:
to check the password. The LDAP connection is
read only. Every user in the internal directory with Configuring User Directories
LDAP authentication must map to a user on LDAP,
otherwise they cannot log in.
When to use this option: Choose this option if you
want to set up a user and group configuration within
your application that suits your needs, while

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 61

checking your users' passwords against the

corporate LDAP directory. This option also helps to
avoid the performance issues that may result from
downloading large numbers of groups from LDAP.

Connecting Confluence to an Internal Directory with LDAP Authentication

To connect to an internal directory but check logins via LDAP:

1. Choose the cog icon

, then choose General Configuration

2. Click 'User Directories' in the left-hand panel.
3. Add a directory and select type 'Internal with LDAP Authentication'.
4. Enter the values for the settings, as described below.
5. Save the directory settings.
6. If you want LDAP users to be used in place of existing internal users, move the 'Internal with LDAP
Authentication' directory to the top of the list. You can define the directory order by clicking the blue
up- and down-arrows next to each directory on the 'User Directories' screen. Here is a summary of
how the directory order affects the processing:
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
The order of the directories is the order in which they will be searched for users and groups (by
default Confluence aggregates group membership from all directories, so the order does not
impact membership itself).
For details see Managing Multiple Directories.
7. Add your users and groups in Confluence. See Add and Invite Users and Managing Site-Wide
Permissions and Groups .

Server Settings

Setting Description

Name A descriptive name that will help you to identify the directory. Examples:
Internal directory with LDAP Authentication
Corporate LDAP for Authentication Only

Directory Select the type of LDAP directory that you will connect to. If you are adding a new LDAP
Type connection, the value you select here will determine the default values for some of the
options on the rest of screen. Examples:
Microsoft Active Directory
OpenDS
And more.

Hostname The host name of your directory server. Examples:

ad.example.com
ldap.example.com
opends.example.com

Port The port on which your directory server is listening. Examples:

389
10389
636 (for example, for SSL)

Use SSL Check this box if the connection to the directory server is an SSL (Secure Sockets Layer)
connection. Note that you will need to configure an SSL certificate in order to use this
setting.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 62

Username The distinguished name of the user that the application will use when connecting to the
directory server. Examples:
cn=administrator,cn=users,dc=ad,dc=example,dc=com
cn=user,dc=domain,dc=name
[email protected]

Password The password of the user specified above.

Copying Users on Login

Setting Description

Copy User This option affects what will happen when a user attempts to log in. If this box is
on Login checked, the user will be created automatically in the internal directory that is using
LDAP for authentication when the user first logs in and their details will be synchronized
on each subsequent log in. If this box is not checked, the user's login will fail if the user
wasn't already manually created in the directory.

If you check this box the following additional fields will appear on the screen, which are
described in more detail below:
Default Group Memberships
Synchronize Group Memberships
User Schema Settings (described in a separate section below)

Update User Whenever your users authenticate to the application, their attributes will be automatically
attributes on updated from the LDAP server into the application. After you select this option, you won't
Login be able to modify or delete your users directly in the application.
If you need to modify a user, do it on the LDAP server; it will be updated in the
application after authenticating.
If you need to delete a user, do it on the LDAP server, but also in the application. If
you delete the user only on the LDAP server, it will be rejected from logging in to the
application, but it won't be set as inactive, which will affect your license. You'll need
to disable the Update User attributes on Login option to delete the user, and then
enable it again.

Default This field appears if you check the Copy User on Login box. If you would like users to
Group be automatically added to a group or groups, enter the group name(s) here. To specify
Memberships more than one group, separate the group names with commas. Each time a user logs in,
their group memberships will be checked. If the user does not belong to the specified
group(s), their username will be added to the group(s). If a group does not yet exist, it
will be added to the internal directory that is using LDAP for authentication.

Please note that there is no validation of the group names. If you mis-type the group
name, authorization failures will result – users will not be able to access the applications
or functionality based on the intended group name.

Examples:
confluence-users
bamboo-users,jira-administrators,jira-core-users

Synchronize This field appears if you select the Copy User on Login checkbox. If this box is checke
Group d, group memberships specified on your LDAP server will be synchronized with the
Memberships internal directory each time the user logs in.

If you check this box the following additional fields will appear on the screen, both
described in more detail below:
Group Schema Settings (described in a separate section below)
Membership Schema Settings (described in a separate section below)

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 63

Note: 'Copy Users on Login' must be enabled if you want to be able to change usernames.

Schema Settings

Setting Description

Base The root distinguished name (DN) to use when running queries against the directory server.
DN Examples:
o=example,c=com
cn=users,dc=ad,dc=example,dc=com
For Microsoft Active Directory, specify the base DN in the following format: dc=domain1,
dc=local. You will need to replace the domain1 and local for your specific
configuration. Microsoft Server provides a tool called ldp.exe which is useful for finding
out and configuring the the LDAP structure of your server.

User The attribute field to use when loading the username. Examples:
Name
Attribute cn
sAMAccountName

Advanced Settings

Setting Description

Enable Enable or disable support for nested groups. Some directory servers allow you to define a
Nested group as a member of another group. Groups in such a structure are called nested groups.
Groups Nested groups simplify permissions by allowing sub-groups to inherit permissions from a
parent group.

Use Enable or disable the use of the LDAP control extension for simple paging of search results.
Paged If paging is enabled, the search will retrieve sets of data rather than all of the search results
Results at once. Enter the desired page size – that is, the maximum number of search results to be
returned per page when paged results are enabled. The default is 1000 results.

Follow Choose whether to allow the directory server to redirect requests to other servers. This
Referrals option uses the node referral (JNDI lookup java.naming.referral) configuration setting.
It is generally needed for Active Directory servers configured without proper DNS, to prevent
a 'javax.naming.PartialResultException: Unprocessed Continuation Reference(s)' error.

User Schema Settings

Note: this section is only visible when Copy User on Login is enabled.

Setting Description

Additional This value is used in addition to the base DN when searching and loading users. If no value
User DN is supplied, the subtree search will start from the base DN. Example:
ou=Users

User This is the name of the class used for the LDAP user object. Example:
Object
Class user

User The filter to use when searching user objects. Example:

Object
Filter (&(objectCategory=Person)(sAMAccountName=*))

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 64

User The RDN (relative distinguished name) to use when loading the username. The DN for each
Name LDAP entry is composed of two parts: the RDN and the location within the LDAP directory
RDN where the record resides. The RDN is the portion of your DN that is not related to the
Attribute directory tree structure. Example:
cn

User First The attribute field to use when loading the user's first name. Example:
Name
Attribute givenName

User Last The attribute field to use when loading the user's last name. Example:
Name
Attribute sn

User The attribute field to use when loading the user's full name. Example:
Display
Name displayName
Attribute

User The attribute field to use when loading the user's email address. Example:
Email
Attribute mail

Group Schema Settings

Note: this section is only visible when both Copy User on Login and Synchronize Group Memberships ar
e enabled.

Setting Description

Additional This value is used in addition to the base DN when searching and loading groups. If no
Group DN value is supplied, the subtree search will start from the base DN. Example:
ou=Groups

Group Object This is the name of the class used for the LDAP group object. Examples:
Class
groupOfUniqueNames
group

Group Object The filter to use when searching group objects. Example:
Filter
(objectCategory=Group)

Group Name The attribute field to use when loading the group's name. Example:
Attribute
cn

Group The attribute field to use when loading the group's description. Example:
Description
Attribute description

Membership Schema Settings

Note: this section is only visible when both Copy User on Login and Synchronize Group Memberships ar
e enabled.

Setting Description

Group Members Attribute The attribute field to use when loading the group's members. Example:
member

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 65

User Membership Attribute The attribute field to use when loading the user's groups. Example:
memberOf

Use the User Membership Check this box if your directory server supports the group membership
Attribute, when finding the attribute on the user. (By default, this is the 'memberOf' attribute.)
user's group membership
If this box is checked, your application will use the group
membership attribute on the user when retrieving the members of
a given group. This will result in a more efficient retrieval.
If this box is not checked, your application will use the members
attribute on the group ('member' by default) for the search.

Diagrams of Possible Configurations

Diagram above: Confluence connecting to an LDAP directory for authentication only.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 66

Diagram above: Confluence connecting to an LDAP directory for authentication only, with each user
synchronized with the internal directory that is using LDAP authentication when they log in to Confluence.

Connecting to Crowd or Jira for User Management

You can connect your Confluence application to On this page:
Atlassian Crowd or to a Jira application (version 4.3
or later) for management of users and groups, and Connecting Confluence to Crowd
for authentication. for User Management
Connecting Confluence to Jira
applications for User Management
Connecting Confluence to Crowd for User Diagrams of Some Possible
Management Configurations
Troubleshooting
Atlassian Crowd is an application security framework
that handles authentication and authorization for Related pages:
your web-based applications. With Crowd you can Configuring User Directories
integrate multiple web applications and user
directories, with support for single sign-on (SSO)
and centralized identity management. The Crowd
Administration Console provides a web interface for
managing directories, users and their permissions.
See the Administration Guide.
When to use this option: Connect to Crowd if you
want to use the full Crowd functionality to manage
your directories, users and groups. You can connect
your Crowd server to a number of directories of all
types that Crowd supports, including custom
directory connectors.

Managing 500+ users across Atlassian products?

Find out how easy, scalable and effective it can be with Crowd!

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 67

See centralized user management.

To connect Confluence to Crowd:

1. Go to your Crowd Administration Console and define the Confluence application to Crowd. See the
Crowd documentation: Adding an Application.
2. Choose the cog icon

, then choose General Configuration

3. Click 'User Directories' in the left-hand panel.
4. Add a directory and select type 'Atlassian Crowd'. Enter the settings as described below.
5. Save the directory settings.
6. Define the directory order by clicking the blue up- and down-arrows next to each directory on the ' Us
er Directories' screen. Here is a summary of how the directory order affects the processing:
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
The order of the directories is the order in which they will be searched for users and groups (by
default Confluence aggregates group membership from all directories, so the order does not
impact membership itself).
For details see Managing Multiple Directories.
7. If required, configure Confluence to use Crowd for single sign-on (SSO) too. See the Crowd
documentation: Integrating Crowd with Atlassian Confluence.

Crowd Settings in Confluence

Setting Description

Name A meaningful name that will help you to identify this Crowd server amongst your list of
directory servers. Examples:
Crowd Server
Example Company Crowd

Server The web address of your Crowd console server. Examples:

URL
http://www.example.com:8095/crowd/
http://crowd.example.com

Application The name of your application, as recognized by your Crowd server. Note that you will need
Name to define the application in Crowd too, using the Crowd administration Console. See the
Crowd documentation on adding an application.

Application The password which the application will use when it authenticates against the Crowd
Password framework as a client. This must be the same as the password you have registered in
Crowd for this application. See the Crowd documentation on adding an application.

Note: There is a known issue where the password is not saved in some instances
CONFSERVER-33979 - New JIRA/Crowd password not saved after test
GATHERING IMPACT when
configuring Confluence to use Jira/Crowd as a external user directory.

Crowd Permissions

Setting Description

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 68

Read Only The users, groups and memberships in this directory are retrieved from Crowd and can
only be modified via Crowd. You cannot modify Crowd users, groups or memberships via
the application administration screens.

Read/Write The users, groups and memberships in this directory are retrieved from Crowd. When you
modify a user, group or membership via the application administration screens, the
changes will be applied directly to Crowd. Please ensure that the application has
modification permissions for the relevant directories in Crowd. See the Crowd
documentation: Specifying an Application's Directory Permissions.

Advanced Crowd Settings

Setting Description

Enable Nested Enable or disable support for nested groups. Before enabling nested groups, please
Groups check to see if the user directory or directories in Crowd support nested groups. When
nested groups are enabled, you can define a group as a member of another group. If
you are using groups to manage permissions, you can create nested groups to allow
inheritance of permissions from one group to its sub-groups.

Enable Enable or disable incremental synchronization. Only changes since the last
Incremental synchronization will be retrieved when synchronizing a directory. Note that full
Synchronization synchronization is always executed when restarting Fisheye.

Synchronization Synchronization is the process by which the application updates its internal store of
Interval user data to agree with the data on the directory server. The application will send a
(minutes) request to your directory server every x minutes, where 'x' is the number specified
here. The default value is 60 minutes.

Connecting Confluence to Jira applications for User Management

Note that the license tiers for your Jira application and Confluence do not need to match to use this
feature. For example, you can manage a Confluence 50 user license with Jira Software, even if Jira
Software only has a 25 user license.

Subject to certain limitations, you can connect a number of Atlassian applications to a single JIRA application
for centralized user management.
When to use this option: You can connect to a server running JIRA 4.3 or later, JIRA Software 7.0 or later,
JIRA Core 7.0 or later, or JIRA Service Desk 3.0 or later. Choose this option as an alternative to Atlassian
Crowd, for simple configurations with a limited number of users.
To connect Confluence to a Jira application:
1. In your Jira application go to

> User Management > Jira User Server.

(For Jira 6.4 and earlier go to your Jira administration screen then Users > Jira User Server)
Click Add Application.
Enter the application name and password that Confluence will use when accessing Jira.
Enter the IP address or addresses of your Confluence server. Valid values are:
A full IP address, e.g. 192.168.10.12.
A wildcard IP range, using CIDR notation, e.g. 192.168.10.1/16. For more
information, see the introduction to CIDR notation on Wikipedia and RFC 4632.
Save the new application.
2. Set up the Jira user directory in Confluence:
Choose the cog icon

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 2.
Confluence 6.15 Documentation 69

, then choose General Configuration

Click 'User Directories' in the left-hand panel.
Add a directory and select type 'Atlassian Jira'.
Enter the settings as described below. When asked for the application name and password,
enter the values that you defined for your Confluence application in the settings on Jira.
Save the directory settings.
Don't change the directory order until you have done the next step or you may accidentally
lock yourself out of the Confluence admin console.

3. In order to use Confluence, users must be a member of the confluence-users group or have
Confluence 'can use' permission. Follow these steps to configure your Confluence groups in your JIRA
application:
a. Add the confluence-users and confluence-administrators groups in your JIRA
application.
b. Add your own username as a member of both of the above groups.
c. Choose one of the following methods to give your existing JIRA users access to Confluence:
Option 1: In your JIRA application, find the groups that the relevant users belong to. Add
the groups as members of one or both of the above Confluence groups.
Option 2: Log in to Confluence using your JIRA account and go to the Confluence Admi
nistration Console. Click 'Global Permissions' and assign the 'can use' permission to
the relevant JIRA groups.
4. In Confluence you can now define the directory order by clicking the blue up- and down-arrows next
to each directory on the 'User Directories' screen. Here is a summary of how the directory order
affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
For details see Managing Multiple Directories.

Ensure that you have added Confluence URL into Jira Whitelist in Jira Administration >>
System >> Security >> Whitelist. For example: https://confluence.atlassian.com/ or refer to
this guide: Configuring the whitelist.

Jira Settings in Confluence

Setting Description

Name A meaningful name that will help you to identify this Jira server in the list of directory
servers. Examples:
Jira Service Desk Server
My Company Jira

Server The web address of your Jira server. Examples:

URL
http://www.example.com:8080
http://jira.example.com

Application The name used by your application when accessing the Jira server that acts as user
Name manager. Note that you will also need to define your application to that Jira server, via the '
Other Applications' option in the 'Users, Groups & Roles' section of the 'Administration'
menu.

Application The password used by your application when accessing the Jira server that acts as user
Password manager.

Jira Permissions

Setting Description

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 70

Read Only The users, groups and memberships in this directory are retrieved from the Jira server that
is acting as user manager. They can only be modified via that JIRA server.

Read/Write The users, groups and memberships in this directory are retrieved from the Jira server that
is acting as user manager. When you modify a user, group or membership via the
application administration screens, the changes will be applied directly to Jira.

Advanced Jira Settings

Setting Description

Enable Nested Enable or disable support for nested groups. Before enabling nested groups, please
Groups check to see if nested groups are enabled on the JIRA server that is acting as user
manager. When nested groups are enabled, you can define a group as a member of
another group. If you are using groups to manage permissions, you can create nested
groups to allow inheritance of permissions from one group to its sub-groups.

Synchronization Synchronization is the process by which the application updates its internal store of
Interval user data to agree with the data on the directory server. The application will send a
(minutes) request to your directory server every x minutes, where 'x' is the number specified
here. The default value is 60 minutes.

Diagrams of Some Possible Configurations

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 71

Diagram above: Confluence, JIRA and other applications connecting to Crowd for user management.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 72

Diagram above: Confluence connecting to JIRA for user management.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 73

Diagram above: Confluence connecting to JIRA for user management, with JIRA in turn connecting to LDAP.

Troubleshooting

Below are some error messages you may encounter. If you run into problems, you should turn on WARN
logging for the relevant class. See Configuring Logging.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 74

Error Message Cause

error.jirabaseurl.connection.refused Connection refused. This may be because:

Check if an instance of
Jira is running on the Jira url is incorrect
given url Jira instance is not running on
the specified url.
Jira instance running on the
specified url is not 4.3 or later.

error.applicationlink.connection.refused Failed to establish Unable to create an application

application link between link between Jira and Confluence.
Jira server and This may be because:
Confluence server.
Confluence or Jira url is
incorrect
the instance is not running on
the specified url
credentials are incorrect.
Refer to the Confluence log files
for further troubleshooting
information.

error.jirabaseurl.not.valid This is not a valid url for A runtime exception has occured.
a Jira application. Refer to the Confluence log files
for further troubleshooting
information.

Reverting from Crowd or Jira applications to Internal User Management

If your Confluence site currently uses Crowd or a On this page:
Jira application for user management, you can revert Option 1 – Manually Recreate
to internal user management as described below. If Users and Groups in Confluence
your Confluence instance has only a few users, it is Option 2 – Transfer Crowd/Jira
easier to recreate the users and groups in application Users and Groups to
Confluence manually. If you have a large number of the Confluence Database
users and groups, it is more efficient to migrate the
relevant users and groups into the Confluence
Internal directory.

Both options provided below will reset the

affected users' passwords. When done, be
sure to notify them to use the 'Reset My
Password' link on the Confluence log in
page before they attempt to log in.

Option 1 – Manually Recreate Users and Groups in Confluence

Use this option if you have only a few users and groups.
1. Log in to Confluence as a Confluence system administrator.
2. Go to the user directories administration screen and move the internal directory to the top of the list of
directories, by clicking the arrows in the 'Order' column.
3. Make sure that you have at least one user from the internal directory in each of the confluence-us
ers and confluence-administrators groups.
4. Make sure that you have a username in the internal directory with Confluence system administrator
permissions.
If you do not have such a user, add a new one now, and log out of Confluence.
Log back in as the user you just added, and go back to the user directories administration
screen.
5. Disable the 'Atlassian Crowd' directory.
6.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 75

6. Manually add the required users and groups in Confluence. They will be added to the internal
directory, because you have moved it to the top of the list of directories.
If you have assigned Confluence permissions to a group which exists in your Jira application,
you must create a group in Confluence with the same name.
If a user who exists in your Jira application has created content or has had permissions
assigned to them in Confluence, you must also create that user in Confluence.
7. Add the users to the required groups.

Option 2 – Transfer Crowd/Jira application Users and Groups to the Confluence Database

This method is not officially supported. The Atlassian Support team won't be able to assist you with
this process.
We strongly recommend trying this in a test environment, and then making a full backup of your
database before deciding to deploy the change in your production environment.

Use this option to migrate External Application (Crowd or Jira applications) users into the Confluence
database. You need a knowledge of SQL to perform this task.
The SQL commands given below are tailored for MySQL. If you are using a database other than MySQL,
you will need to modify the SQL to work in your database.

Step 1. Create Backups

Creating backups is the only way to restore your data if something goes wrong.
1. From Confluence, create a full XML site backup including attachments.
2. Stop Confluence.
3. Make a backup copy of the Confluence home and installation directories.
4. Repeat the above steps for your External Application.
5. From your MySQL administration tool, create a database backup for the Crowd/Jira application and
Confluence databases.

Step 2. Replace Confluence User Management

Use the SQL below to move groups and users from your External Application to Confluence by transferring
table content. The SQL provided is specific to MySQL and must be modifed for other databases.

Find the IDs for your Directories

1. Run the following command and take note of the resulting number. It will be referenced throughout the
following instructions as <Confluence Internal ID>.

select id from cwd_directory where directory_name='Confluence

Internal Directory';

2. From the User Directories administration page, find the name of the directory who's users/groups you
want to move. Run the following command and take note of the resulting number. It will be referenced
throughout the following instructions as <External Application ID>.

select id from cwd_directory where directory_name='<External

Directory Name>';

Find and remove duplicate users who belong to the same group in multiple directories

To make sure you don't introduce duplicates in the next step, when you move groups to Confluence, use the
following SQL query to locate any users that belong to a group with the same name in both your external
directory and internal Confluence directory.
1. Run the following command to find any users with the same name, that belong to the same group
across different directories:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 76
1.

SELECT count(*), a.user_name, c.group_name from cwd_user a

join cwd_membership b on b.child_user_id = a.id
join cwd_group c on c.id = b.parent_id group by 2,3 having
count(*)>1

Make a note of each of the usernames and groups returned. You'll need this in the next step.
2. In your external directory, remove the users from their respective groups. Their membership will still
be retained in the Confluence internal directory.
3. Run the SQL query above again. Once it returns no results, you can move to the next step.

Move Groups to Confluence

1. It is possible that you have several groups in your Internal Directory that have the same name as
groups in your External Application. To find these, run:

select distinct a.id, a.directory_id, a.group_name,

d.directory_name from cwd_group a join cwd_group b on
a.group_name=b.group_name join cwd_directory d on
d.id=a.directory_id where a.directory_id != b.directory_id;

a. If you have results from the previous query, for each of the group names that have duplicates,
find the id for the group in the Confluence Internal Directory (<internal group id>) and the
External Application (<external group id>). Run the following:

update cwd_group_attribute set group_id=<internal group

id>, directory_id=<Confluence Internal Id> where
group_id=<external group id>;
update cwd_membership set child_group_id=<internal group
id> where child_group_id=<external group id>;
update cwd_membership set parent_id=<internal group id>
where parent_id=<external group id>;
delete from cwd_group where id=<external group id>;

2. Move all the groups in the External Application to the Confluence Internal Directory.

update cwd_group set directory_id=<Confluence Internal ID> where

directory_id=<External Application ID>;

Move Users to Confluence

1. It is possible that you have several users in your Internal Directory that have the same name as users
in your External Application. To find these, run:

select distinct a.id, a.directory_id, a.user_name,

d.directory_name from cwd_user a join cwd_user b on
a.user_name=b.user_name join cwd_directory d on
d.id=a.directory_id where a.directory_id != b.directory_id;

a. If you have results from the previous query, for each of the user names that have duplicates,
find the id for the user in the Confluence Internal Directory (<internal user id>) and the External

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation
a. 77

Application (<external user id>). Run the following:

update cwd_membership set child_user_id=<internal user id>

where child_user_id=<external user id>;
update cwd_user_credential_record set user_id=<internal
user id> where user_id=<external user id>;
update cwd_user_attribute set user_id=<internal user id>,
directory_id=<Confluence Internal ID> where
user_id=<external user id>;
delete from cwd_user where id=<external user id>;

2. Move all the users in the External Application to the Confluence Internal Directory.

update cwd_user set directory_id=<Confluence Internal ID> where

directory_id=<External Application ID>;

Delete the External Application directory

1. You need to change the order of your directories so that the Internal directory is at the top, and active.
a. If you have only two directories - the Internal and the External Application directory you are
deleting, then do the following:

update cwd_app_dir_mapping set list_index = 0 where

directory_id = <Confluence Internal ID>;

b. If you have more than two directories, you need to rearrange them so the Internal Directory is at
the top (list_index 0) and the External Application directory you are deleting is at the bottom.
List the directories and their order using

select d.id, d.directory_name, m.list_index from

cwd_directory d join cwd_app_dir_mapping m on
d.id=m.directory_id order by m.list_index;

Change the list indexes so that they are in the order you want. Directory order can be
rearranged using

update cwd_app_dir_mapping set list_index = <position>

where directory_id = <directory id>;

c. Check that the internal directory is enabled.

List the internal directory. An enabled directory will have its 'active' column set to 'T'

select id, directory_name, active from cwd_directory

where id = <Internal Directory id>;

If the internal directory is not active, activate it by

update cwd_directory set active = 'T' where id =

<Internal Directory id>;

2.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 78

2. When the directories are ordered correctly, delete the External Application directory from the directory
order:

delete from cwd_app_dir_operation where app_dir_mapping_id =

(select id from cwd_app_dir_mapping where directory_id =
<External Application ID>);
delete from cwd_app_dir_mapping where directory_id = <External
Application ID>;

3. The External Application directory is referenced in several other tables in the database. You need to
remove the remaining references to it:

delete from cwd_directory_attribute where directory_id=<External

Application ID>;
delete from cwd_directory_operation where directory_id=<External
Application ID>;

4. All references to the External Directory should now have been removed. Delete the directory using:

delete from cwd_directory where id = <External Application ID>;

Reset passwords

All users who were in the External Directory you deleted, including admins, will be unable to log in. Their
passwords need to be reset by choosing the 'Forgot your password?' link on the login page. Alternatively,
use the instructions at Restore Passwords To Recover Admin User Rights to reset the administrator
password, then set the users' passwords for them via the Manage Users page in the administration screen.

Managing Multiple Directories

This page describes what happens when you have On this page:
defined more than one user directory in Confluence. Overview
For example, you may have an internal directory and Configuring the Directory Order
you may also connect to an LDAP directory server Effect of Directory Order
and/or other types of user directories. When you Login
connect to a new directory server, you also need to Permissions
define the directory order. Updating Users and groups
Avoid duplicate usernames across directories. If
you are connecting to more than one user directory,
we recommend that you ensure the usernames are
unique to one directory. For example, we do not
recommend that you have a user jsmith in both
'Directory1' and 'Directory2'. The reason is the
potential for confusion, especially if you swap the
order of the directories. Changing the directory order
can change the user that a given username refers
to.

Managing 500+ users across Atlassian

products?
Find out how easy, scalable and effective it
can be with Crowd!
See centralized user management.

Overview

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 79

Here is a summary of how the directory order affects the processing:

The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.

Configuring the Directory Order

You can change the order of your directories as defined to Confluence. Select 'User Directories' from the
Confluence Administration Console and click the blue up- and down-arrows next to each directory.

Notes:
Please read the rest of this page to understand what effect the directory order will have on
authentication (login) and permissions in Confluence, and what happens when you update users and
groups in Confluence.
Before you move an external directory above Confluence's internal directory, make sure you (and your
admin users) are members of a group called confluence-administrators in your external
directory or you may accidentally lock yourself out of the Confluence admin console.

Effect of Directory Order

This section summarizes the effect the order of the directories will have on login and permissions, and on the
updating of users and groups.

Login

The directory order is significant during the authentication of the user, in cases where the same user exists in
multiple directories. When a user attempts to log in, the application will search the directories in the order
specified, and will use the credentials (password) of the first occurrence of the user to validate the login
attempt.

Permissions

Aggregating membership (default)

The directory order is not significant when granting the user permissions based on group membership as
Confluence uses an aggregating membership scheme by default. If the same username exists in more than
one directory, the application will aggregate (combine) group membership from all directories where the
username appears.
Example:
You have connected two directories: The Customers directory and the Partners directory.
The Customers directory is first in the directory order.
A username jsmith exists in both the Customers directory and the Partners directory.
The user jsmith is a member of group G1 in the Customers directory and group G2 in the Partners
directory.
The user jsmith will have permissions based on membership of both G1 and G2 regardless of the
directory order.
For administrators upgrading to Confluence 5.7 or later:
How group memberships are determined for users that belong to multiple user directories (such as LDAP,
Active Directory, Crowd) changed in Confluence 5.7. Group memberships are now aggregated from all direct
ories, not the first one the user appears in. In most cases, this change will have no impact as users generally
only exist in one directory, or their memberships are correctly synchronized between user directories. In
some rare cases, where group memberships are out of synch, the change may lead to users gaining

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 80

permissions to view spaces and pages (if they are a member a group in a user directory that was previously
being ignored by Confluence).
Here's an example scenario...
This is Issac. Something went wrong a while ago, so he's got the same username in two user
directories, but belongs to different groups.

Right now, the user directories in his organization's Confluence site look like this:

and Issac's group memberships in each directory looks like this:

The 'Dev Team' page is restricted to the developers group.

In Confluence 5.6 and earlier, Issac couldn't see this page as we determined his group
membership from Active Directory - because it's the first directory in the list it had the highest
priority.
In Confluence 5.7 and beyond, Issac will see the page because we determine his group
membership from all directories, not just the highest one.
To Confluence his group membership looks like this:

This means after the 5.7 upgrade he can see any pages and spaces that are restricted to the 'developers'
group.

Non-aggregating membership

It is possible to use the REST API to tell Confluence to use a non-aggregating membership scheme as
follows:
Turning on non-aggregating membership...
The REST resource supported JSON and XML. You'll need to be a system administrator and logged in to
do this.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 81

# To GET the current setting

curl -H 'Accept: application/json' -u <username>
<base-url>/rest/crowd/latest/application

# To PUT the setting

curl -H 'Content-type: application/json' -X PUT -d
'{"membershipAggregationEnabled":false}' -u <username>
<base-url>/rest/crowd/latest/application

If you've chosen non-aggregating membership, the directory order is significant. If the same username exists
in more than one directory, the application will look for group membership only in the first directory where the
username appears, based on the directory order.
Example:
You have connected two directories: The Customers directory and the Partners directory.
The Customers directory is first in the directory order.
A username jsmith exists in both the Customers directory and the Partners directory.
The user jsmith is a member of group G1 in the Customers directory and group G2 in the Partners
directory.
The user jsmith will have permissions based on membership of G1 only, not G2.

Updating Users and groups

If you update a user or group via the application's administration screens, the update will be made in the first
directory where the application has write permissions.
Example 1:
You have connected two directories: The Customers directory and the Partners directory.
The application has permission to update both directories.
The Customers directory is first in the directory order.
A username jsmith exists in both the Customers directory and the Partners directory.
You update the email address of user jsmith via the application's administration screens.
The email address will be updated in the Customers directory only, not the Partners directory.
Example 2:
You have connected two directories: A read/write LDAP directory and the internal directory.
The LDAP directory is first in the directory order.
All new users will be added to the LDAP directory. It is not possible to add a new user to the internal
directory.

Managing Nested Groups

Some directory servers allow you to define a group
as a member of another group. Groups in such a
structure are called nested groups. Nested groups
simplify permissions by allowing sub-groups to
inherit permissions from a parent group.
This page describes how Confluence handles
nested groups that exist in one or more of your
directory servers.

Enabling Nested Groups

You can enable or disable support for nested groups

on each directory individually. Go to the 'User
Directories' section of the Confluence

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 82

Administration Console, edit the directory and select On this page:

'Enable Nested Groups'. See Configuring User
Directories. Enabling Nested Groups
Effect of Nested Groups
Notes: Login
Permissions
Before enabling nested groups for a specific
Viewing lists of group
directory type in Confluence, please make
members
sure that your directory server supports
Adding and updating group
nested groups.
membership
Please read the rest of this page to
Examples
understand what effect nested groups will
Example 1: User is member
have on authentication (login) and
of sub-group
permissions in Confluence, and what
Example 2: Sub-groups as
happens when you update users and groups
members of the
in Confluence.
jira-developers group
You can't edit the directory you are currently
Notes
logged in via. This means that in most cases
you need to log in with an administrator Related pages:
account stored in the internal directory.
Configuring User Directories

Effect of Nested Groups

This section explains how nested groups affect logging in, permissions, and viewing and updating users and
groups.

Login

When a user logs in, they can access the application if they belong to an authorized group or any of its
sub-groups.

Permissions

The user can access a function if they belong to a group that has the necessary permissions, or if they
belong to any of its sub-groups.

Viewing lists of group members

If you ask to view the members of a group, you will see all users who are members of the group and all users
belonging its sub-groups, consolidated into one list. We call this a flattened list.
You can't view or edit the nested groups themselves, or see that one group is a member of another group.

Adding and updating group membership

If you add a user to a group, the user is added to the named group and not to any other groups.
If you try to remove a user from a flattened list, the following will happen:
If the user is a member of the top group in the hierarchy of groups in the flattened list, the user is
removed from the top group.
Otherwise, you see an error message stating that the user is not a direct member of the group.

Examples

Example 1: User is member of sub-group

Imagine the following two groups exist in your directory server:

staff
marketing

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 83

Memberships:
The marketing group is a member of the staff group.
User jsmith is a member of marketing.
You will see that jsmith is a member of both marketing and staff. You will not see that the two groups are
nested. If you assign permissions to the staff group, then jsmith will get those permissions.

Example 2: Sub-groups as members of the jira-developers group

In an LDAP directory server, we have the groups engineering-group and techwriters-group. We want to
grant both groups developer-level access to the JIRA. We will have a group called jira-developers that has
developer-level access.
Add a group called jira-developers.
Add the engineering-group as a sub-group of jira-developers.
Add the techwriters-group as a sub-group of jira-developers.
Group memberships are now:
jira-developers — sub-groups: engineering-group, techwriters-group
engineering-group — sub-groups: dev-a, dev-b; users: pblack
dev-a — users: jsmith, sbrown
dev-b — users: jsmith, dblue
techwriters-group — users: rgreen
When the JIRA application requests a list of users in the jira-developers group, it receives the following list:
pblack
jsmith
sbrown
dblue
rgreen

Diagram: Sub-groups as members of the jira-developers group

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 84

Notes

Possible impact on performance. Enabling nested groups may result in slower user searches.
Definition of nested groups in LDAP. In an LDAP directory, a nested group is a child group entry
whose DN (Distinguished Name) is referenced by an attribute contained within a parent group entry.
For example, a parent group Group One might have an objectClass=group attribute and one or
more member=DN attributes, where the DN can be that of a user or that of a group elsewhere in the
LDAP tree:

member=CN=John Smith,OU=Users,OU=OrgUnitA,DC=sub,DC=domain
member=CN=Group
Two,OU=OrgUnitBGroups,OU=OrgUnitB,DC=sub,DC=domain

Synchronizing Data from External Directories

For certain directory types, Confluence stores a
cache of directory information (users and groups) in
the application database, to ensure fast recurrent
access to user and group data. A synchronization
task runs periodically to update the internal cache
with changes from the external directory.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 85

On this page:
Affected Directory Types
How it Works
Finding the Time Taken to
Synchronize
Manually Synchronizing the Cache
Configuring the Synchronization
Interval
Unsynced users
Related pages:
Configuring User Directories

Affected Directory Types

Data caching and synchronization apply to the following user directory types:
LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to re
ad only.
LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to re
ad only, with local groups.
LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to re
ad/write.
Atlassian Crowd.
Atlassian JIRA.
Data caching and synchronization do not occur for the following user directory types:
Internal Directory with LDAP Authentication.
Internal Directory.

How it Works

Here is a summary of the caching functionality:

The caches are held in the application database.
When you connect a new external user directory to the application, a synchronization task will start
running in the background to copy all the required users, groups and membership information from the
external directory to the application database. This task may take a while to complete, depending on
the size and complexity of your user base.
Note that a user will not be able to log in until the synchronization task has copied that user's details
into the cache.
A periodic synchronization task will run to update the database with any changes made to the external
directory. The default synchronization interval, or polling interval, is one hour (60 minutes). You can
change the synchronization interval on the directory configuration screen.
You can manually synchronize the cache if necessary.
If the external directory permissions are set to read/write: Whenever an update is made to the users,
groups or membership information via the application, the update will also be applied to the cache and
the external directory immediately.
All authentication happens via calls to the external directory. When caching information from an
external directory, the application database does not store user passwords.
All other queries run against the internal cache.

Finding the Time Taken to Synchronize

The 'User Directories' screen shows information about the last synchronization operation, including the
length of time it took.

Manually Synchronizing the Cache

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 86

You can manually synchronize the cache by clicking 'Synchronize' on the 'User Directories' screen. If a
synchronization operation is already in progress, you cannot start another until the first has finished.
Screen snippet: User directories, showing information about synchronization

Configuring the Synchronization Interval

Note: The option to configure the synchronization interval for Crowd and Jira directories is available in Confl
uence 3.5.3 and later. Earlier versions of Confluence allow you to configure the interval for LDAP directories
only.
You can set the 'Synchronization Interval' on the directory configuration screen. The synchronization
interval is the period of time to wait between requests for updates from the directory server.
The length you choose for your synchronization interval depends on:
The length of time you can tolerate stale data.
The amount of load you want to put on the application and the directory server.
The size of your user base.
If you synchronize more frequently, then your data will be more up to date. The downside of synchronizing
more frequently is that you may overload your server with requests.
If you are not sure what to do, we recommend that you start with an interval of 60 minutes (this is the default
setting) and reduce the value incrementally. You will need to experiment with your setup.

Unsynced users

To view users who have previously been synchronized with Confluence, but were not present in the last
directory sync, go to

> User management > Unsynced from Directory.

Users may appear in the Unsynced from Directory tab be due to a problem with your last sync, or because
the user has been intentionally removed from the external directory (for example because they've left your
organisation).
If a user who has created content is removed from an external directory, and a new account is created with
the same username, that username will be associated with the original user's content. This is intentional, to
ensure that if a directory sync problem occurs, users are correctly re-associated with their own content.
If the user was intentionally unsynced, administrators can choose to:
Leave the unsynced account as it is. The person's username will appear on any content or comments
they've created.
Delete the account from the Unsynced from Directory tab, which then replaces the username with an
anonymous alias. This final deletion step is usually only required if you've received a formal erasure
request.
See Delete or Disable Users for more information. Don't assume that because a user appears in the
unsynced users list, that they are to be deleted from Confluence.
You may see a user in the Unsynced from Directory tab with the username 'exporter'. This account is used
when creating the demonstration space when you first install Confluence, and can be included when
importing a Cloud site. You can safely ignore this unsynced account.

Diagrams of Possible Configurations for User Management

The aim of these diagrams is to help people

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 87

understand each directory type at a glance. We have On this page:

kept the diagrams simple and conceptual, with just
enough information to be correct. Confluence Internal Directory
Confluence with Read/Write
Some things that we do not attempt to show: Connection to LDAP
Confluence with Read-Only
In most cases, we do not attempt to show that
Connection to LDAP, with Local
you can have multiple directory types mapped
Groups
to Confluence at the same time. We illustrate
Confluence Internal Directory with
that fact in just the first two LDAP diagrams.
LDAP Authentication
We have not included a diagram for
Confluence with LDAP
Confluence's legacy connection to Jira
Authentication, Copy Users on
database.
First Login
We do not attempt to show all of the possible
Confluence Connecting to Jira
configurations and layered connections that
Confluence Connecting to Jira and
are available now that you can use Jira as a
Jira Connecting to LDAP
directory manager.
Confluence and Jira Connecting to
Crowd

Related pages:

Configuring User Directories

Confluence Internal Directory

Diagram above: Confluence using its internal directory for user management.

Confluence with Read/Write Connection to LDAP

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 88

Diagram above: Confluence connecting to an LDAP directory.

Confluence with Read-Only Connection to LDAP, with Local Groups

Diagram above: Confluence connecting to an LDAP directory with permissions set to read only and local

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 89

groups.

Confluence Internal Directory with LDAP Authentication

Diagram above: Confluence connecting to an LDAP directory for authentication only.

Confluence with LDAP Authentication, Copy Users on First Login

Diagram above: Confluence connecting to an LDAP directory for authentication only, with each user
synchronized with the internal directory that is using LDAP authentication when they log in to Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 90

Confluence Connecting to Jira

Diagram above: Confluence connecting to JIRA for user management.

Confluence Connecting to Jira and Jira Connecting to LDAP

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 91

Diagram above: Confluence connecting to JIRA for user management, with JIRA in turn connecting to LDAP.

Confluence and Jira Connecting to Crowd

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 92

Diagram above: Confluence, JIRA and other applications connecting to Crowd for user management.

User Management Limitations and Recommendations

This page describes the optimal configurations and
limitations that apply to user management in
Confluence.

General Recommendations

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 93

Avoid duplicate usernames across directories. If On this page:

you are connecting to more than one user directory,
we recommend that you ensure the usernames are General Recommendations
unique to one directory. For example, we do not Recommendations for Connecting
recommend that you have a user jsmith in both to LDAP
'Directory1' and 'Directory2'. The reason is the Optimal Number of Users
potential for confusion, especially if you swap the and Groups in your LDAP
order of the directories. Changing the directory order Directory
can change the user that a given username refers Redundant LDAP is Not
to. Supported
Specific Notes for
Be careful when deleting users in remote Connecting to Active
directories. Directory
Recommendations for Connecting
If you are connecting to an LDAP directory, a Crowd to Jira for User Management
directory or a Jira directory, please take care when Single Sign-On Across
deleting users from the remote directory. If you Multiple Applications is Not
delete a user that is associated with data in Supported
Confluence, this will cause problems in Confluence. Custom Application
If a user who has created content is deleted from an Connectors are Not
external directory, and an account is then re-created Supported
with the same username, it will automatically be Custom Directories are Not
re-associated with that content. This is intentional, Supported
so that if a directory sync problem occurs, users are Load on your JIRA instance
correctly re-associated with their content. JIRA Cloud applications not
supported
Avoid hash, slash and question characters in Recommendations
usernames
Related pages:
There is a known issue where users with #, ? or / in
their username cannot create spaces. See Connecting to an LDAP Directory
Connecting to Crowd or Jira for
CONFSERVER-43494
GATHERING IMPACT and User Management
CONFSERVER-13479 Configuring User Directories
GATHERING IMPACT for
more information.

Recommendations for Connecting to LDAP

Please consider the following limitations and recommendations when connecting to an LDAP user directory.

Optimal Number of Users and Groups in your LDAP Directory

The connection to your LDAP directory provides powerful and flexible support for connecting to, configuring
and managing LDAP directory servers. To achieve optimal performance, a background synchronization task
loads the required users and groups from the LDAP server into the application's database, and periodically
fetches updates from the LDAP server to keep the data in step. The amount of time needed to copy the users
and groups rises with the number of users, groups, and group memberships. For that reason, we
recommended a maximum number of users and groups as described below.
This recommendation affects connections to LDAP directories:
Microsoft Active Directory
All other LDAP directory servers
The following LDAP configurations are not affected:
Internal directories with LDAP authentication
LDAP directories configured for 'Authentication Only, Copy User On First Login'
Please choose one of the following solutions, depending on the number of users, groups and memberships
in your LDAP directory.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 94

Your environment Recommendation

Up to 10 000 (ten thousand) Choose the 'LDAP' or 'Microsoft Active Directory' directory type.
users, 1000 (one thousand) You can make use of the full synchronization option. Your application's
groups, and 20 (twenty) groups database will contain all the users and groups that are in your LDAP
per user server.

More than the above Use LDAP filters to reduce the number of users and groups visible to
the synchronization task.

Our Test Results

We performed internal testing of synchronization with an AD server on our local network consisting of 10 000
users, 1000 groups and 200 000 memberships.
We found that the initial synchronization took about 5 minutes. Subsequent synchronizations with 100
modifications on the AD server took a couple of seconds to complete.
Please keep in mind that a number of factors come into play when trying to tune the performance of the
synchronization process, including:
Size of userbase. Use LDAP filters to keep this to the minimum that suits your requirements.
Type of LDAP server. We currently support change detection in AD, so subsequent synchronizations
are much faster for AD than for other LDAP servers.
Network topology. The further away your LDAP server is from your application server, the more
latent LDAP queries will be.
Database performance. As the synchronization process caches data in the database, the
performance of your database will affect the performance of the synchronization.
JVM heap size. If your heap size is too small for your userbase, you may experience heavy garbage
collection during the synchronization process which could in turn slow down the synchronization.

Redundant LDAP is Not Supported

The LDAP connections do not support the configuration of two or more LDAP servers for redundancy
(automated failover if one of the servers goes down).

Specific Notes for Connecting to Active Directory

When the application synchronizes with Active Directory (AD), the synchronization task requests only the
changes from the LDAP server rather than the entire user base. This optimizes the synchronization process
and gives much faster performance on the second and subsequent requests.
On the other hand, this synchronization method results in a few limitations:
1. Externally moving objects out of scope or renaming objects causes problems in AD. If you
move objects out of scope in AD, this will result in an inconsistent cache. We recommend that you do
not use the external LDAP directory interface to move objects out of the scope of the sub-tree, as
defined on the application's directory configuration screen. If you do need to make structural changes
to your LDAP directory, manually synchronize the directory cache after you have made the changes to
ensure cache consistency.
2. Synchronizing between AD servers is not supported. Microsoft Active Directory does not replicate
the uSNChanged attribute across instances. For that reason, we do not support connecting to different
AD servers for synchronization. (You can of course define multiple different directories, each pointing
to its own respective AD server.)
3. Synchronizing with AD servers behind a load balancer is not supported. As with synchronizing
between two different AD servers, Microsoft Active Directory does not replicate the uSNChanged
attribute across instances. For that reason, we do not support connecting to different AD servers even
when they are load balanced. You will need to select one server (preferably one that is local) to
synchronize with instead of using the load balancer.
4. You must restart the application after restoring AD from backup. On restoring from backup of an
AD server, the uSNChanged timestamps are reverted to the backup time. To avoid the resulting
confusion, you will need to flush the directory cache after a Active Directory restore operation.
5. Obtaining AD object deletions requires administrator access. Active Directory stores deleted
objects in a special container called cn=Deleted Objects. By default, to access this container you need

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
5. 6.15 Documentation 95

to connect as an administrator and so, for the synchronization task to be aware of deletions, you must
use administrator credentials. Alternatively, it is possible to change the permissions on the cn=Deleted
Objects container. If you wish to do so, please see this Microsoft KB article.
6. The User DN used to connect to AD must be able to see the uSNChanged attribute. The
synchronization task relies on the uSNChanged attribute to detect changes, and so must be in the
appropriate AD security groups to see this attribute for all LDAP objects in the subtree.

Recommendations for Connecting to Jira for User Management

Please consider the following limitations and recommendations when connecting to a JIRA server for user
management.

Single Sign-On Across Multiple Applications is Not Supported

When you connect to a JIRA application for user management, you will not have single sign-on across the
applications connected in this way. JIRA, when acting as a directory manager, does not support SSO.

Custom Application Connectors are Not Supported

JIRA applications, Confluence, FishEye, Crucible and Bamboo can connect to a JIRA server for user
management. Custom application connectors will need to use the new REST API.

Custom Directories are Not Supported

Earlier versions of JIRA supported OSUser Providers. It was therefore possible write a special provider to
obtain user information from any external user directory. This is no longer the case.

Load on your JIRA instance

If your JIRA instance is already under high load, then using it as a User Server will increase that load.

JIRA Cloud applications not supported

You cannot use JIRA Cloud applications to manage standalone users. Cloud users and users within your
self-hosted Atlassian applications need to be managed separately.

Recommendations

Your environment Recommendation

If all the following are true: Your environment meets the optimal requirements for
using a JIRA application for user management.
Your JIRA application is not under high
load.
You want to share user and group
management across just a few
applications, such as one JIRA Software
server and one Confluence server, or two
JIRA servers.
You do not need single sign-on (SSO)
between your JIRA application and
Confluence, or between two JIRA servers.
You do not have custom application
connectors. Or, if you do have them, you
are happy to convert them to use the new
REST API.
You are happy to shut down all your
servers when you need to upgrade your
JIRA application.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 96

If one or more of the following are true: We recommend that you install Atlassian Crowd for
user management and SSO.
If your JIRA application is already under
high load.
You want to share user and group
management across more than 5
applications.
You need single sign-on (SSO) across
multiple applications.
You have custom applications integrated
via the Crowd SOAP API, and you cannot
convert them to use the new REST API.
You are not happy to shut down all your
servers when you need to upgrade JIRA.

If you are considering creating a custom Please see if one of the following solutions will work
directory connector to define your own storage for you:
for users and groups...
If you have written a custom provider to support a
specific LDAP schema, please check the
supported LDAP schemas to see if you can use
one of them instead.
If you have written a custom provider to support
nested groups, please consider enabling nested
groups in the supported directory connectors
instead.
If you have written a custom provider to connect to
your own database, please consider loading the
data into the application's database instead.
If you need to keep the custom directory
connection, please consider whether Atlassian
Crowd meets your requirements. See the
documentation on Creating a Custom Directory
Connector.

Requesting Support for External User Management

This page gives guidelines on how to request help On this page:
from the Atlassian support team if you are having
problems with external user management. External Troubleshooting the Connection to
user management includes connections to Active your External User Directory
Directory, other LDAP servers, Atlassian Crowd or a Problems During Initial Setup
Jira application for user management. The Complex Authentication or
information on this page is provided in addition to the Performance Problems
more general page on Troubleshooting Problems
Related pages:
and Requesting Technical Support.
Troubleshooting Problems and
The cause of such problems may be:
Requesting Technical Support
The LDAP server is not responding. Configuring User Directories
The application password is incorrectly
configured, causing the LDAP server or other
directory to return an authentication error.
Other LDAP settings are incorrectly
configured.

Troubleshooting the Connection to your External User Directory

The configuration screen for external directories in Confluence has a 'Test Settings' button. This will help
you to diagnose problems with user management in Active Directory and other LDAP servers.
To test your directory connection:
1. Choose the cog icon

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 97
1.

, then choose General Configuration

2. Click 'User Directories' in the left-hand panel.
3. Edit the relevant directory.
4. Click 'Test Settings'.
5. The results of the test will appear at the top of the screen.
Please refer to our knowedge base articles for troubleshooting user management and login issues.
If the above resources do not help, continue below.

Problems During Initial Setup

Raise a support request and include the following information.

Download an LDAP browser to make sure you have the right settings in your LDAP directory.
Atlassian recommends LDAP Studio. Include screenshots of your user and group DNs.
If you can start up Confluence and access the Administration Console, review your directory settings.
See Connecting to an LDAP Directory. Attach screenshots of all your settings.

Complex Authentication or Performance Problems

Raise a support request and include the following information.

Confluence Server

Log in to Confluence and access the Administration Console.

Take a screenshot of the 'System Information' screen, or save the page as HTML.
Take a screenshot of the 'Global Permissions' screen, if people are having problems with logging in.
Go to 'Space Admin' for the relevant space and take a screenshot of the 'Permissions' page, if you
are having problems with space or page permissions.

Confluence Configuration Files

If you have implemented a custom authenticator or in any way modified seraph-config.xml or ser
aph-paths.xml, please provide the modified file.

User Management System

Include the name and version of your LDAP server.

Does your LDAP server use dynamic or static groups?
Review your directory settings. See Connecting to an LDAP Directory. Attach screenshots of all your
settings.

Diagnostics

Enable profiling. See Performance Tuning.

Enable detailed user management logging, by editing confluence/WEB-INF/classes/log4j.pr
operties.
Change this section:

###
# Atlassian User
###
#log4j.logger.com.atlassian.user=DEBUG
#log4j.logger.com.atlassian.confluence.user=DEBUG
#log4j.logger.bucket.user=DEBUG
#log4j.logger.com.atlassian.seraph=DEBUG
#log4j.logger.com.opensymphony.user=DEBUG

Remove the '#' signs at the beginning of the lines, so that it looks like this:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 98

###
# Atlassian User
###
log4j.logger.com.atlassian.user=DEBUG
log4j.logger.com.atlassian.confluence.user=DEBUG
log4j.logger.bucket.user=DEBUG
log4j.logger.com.atlassian.seraph=DEBUG
log4j.logger.com.opensymphony.user=DEBUG

After enabling both the above, please attempt a Confluence LDAP account login and attach a copy of
the log files that are produced when the problem occurs. To do this, locate your install directory, then
zip the full /logs directory into a single file for us to examine.The logs directory is located in your
Confluence Home directory.

Disabling the Built-In User Management

In some circumstances you may want to disable Confluence's built in user management, and delegate all user
management to an external application, such as Jira Software or Jira Service Desk. You can disable internal
user management by turning on Confluence's External User Management setting. You'll need to be a system
administrator to do this.
You might disable Confluence's internal user management:
When Crowd's directory permissions are configured so that Confluence cannot update the Crowd
directories (as a system error will occur when Confluence attempts to write data into Crowd). See Connec
ting to Crowd or Jira for User Management for more information.
If you are using a Jira application for user management. This centralizes all user management in that Jira
app. See Connecting to Crowd or Jira for User Management.
To disable management of users and groups within Confluence:

1. > General Configuration > Security Configuration.

2. Click Edit.
3. Select the External user management checkbox then Save your change.

Note: If you turn on External user management:

You will not be able to add users or groups in Confluence.

You will not be able to edit user details (full name and email) of users in Confluence Internal Directory
You will not be able to use public signup in your site.
The Forgot Password link will not appear on the Confluence login page.
Users will not be able to reset their password in Confluence.
SAML SSO for Confluence Data Center
Security Assertion Markup Language (SAML) is an On this page:
XML-based data format that allows a service to
exchange authorization data with an identity provider Supported Identity Providers
(IdP). The most common use case is allowing a user Set up single sign-on
to sign in to multiple software applications using the Set up SSL/TLS
same authentication details, usually a username and Set up your identity provider
password. This is referred to as single sign-on Configure SAML Authentication in
(SSO). your Atlassian application
Best practices
We provide the functionality for Confluence Data Troubleshooting
Center to connect to your IdP so that you can
provide your users with an SSO experience. This onl
y handles authentication. Application access and
any required authorizations, such as ensuring that
users belong to the appropriate groups/roles and

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 99

have the necessary permissions, should be

configured in the user directory and/or the
application itself.

Supported Identity Providers

SAML single sign-on should work with any identity provider implementing the SAML 2.0 Web Browser SSO
Profile, using the HTTP POST binding.
We currently perform tests with the following identity providers:
Microsoft Active Directory (using ADFS 3.0)
Microsoft Azure Active Directory
OneLogin
Okta
PingIdentity

Set up single sign-on

You'll need to configure your application and your IdP to provide single sign-on for your users.

Set up SSL/TLS
To make sure that SAML authentication is secure and private, you need to set up SSL/TLS in the application.
See Running Confluence Over SSL or HTTPS for more information.
Once set up, you need to make sure that the application's configured base URL is using the HTTPS protocol.
If you want to use a reverse proxy, check out the following guides:
Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http)
Securing your Atlassian applications with Apache using SSL
When using a reverse proxy that terminates SSL/TLS, you need to make sure that the request URL the
application server sees matches the fully-qualified domain name for the reverse proxy. This is usually
achieved by configuring the <Connector> directive with the appropriate proxyName, proxyPort, secure and sc
heme settings. Please check the documentation above for specific examples.

Set up your identity provider

If you want Confluence to provide SSO, you'll need to add it to your IdP. The exact process varies depending
on the IdP, but you'll usually need to:
Define an 'application' in your IdP
Provide some data about the application, including data you can access on your application's Authenti
cation screen
Make sure the NameID attribute of the users in your IdP is set to the username in your Atlassian
application
Give the appropriate users permission to use the application
At the end of the setup process your IdP will provide you with a set of data that you'll need to configure your
Atlassian application.

Configure SAML Authentication in your Atlassian application

To configure SAML authentication in Confluence:

1. Go to

> General Configuration> SAML Authentication.

2. Select SAML single sign-on.
Configure the following settings:

Setting Notes

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 100

Single This value is provided by your IdP, as part of setting up SAML. It's sometimes also
sign-on called 'Entity ID'
issuer
The issuer is the IdP your application will be accepting authentication requests from

Identity This value is provided by your IdP, as part of setting up SAML.

provider
single It defines the URL your users will be redirected when logging in.
sign-on
URL

X.509 This value is provided by your IdP, as part of setting up SAML. This is sometimes
Certificate referred to as a 'Signing certificate'. The key usually starts with '-----BEGIN
CERTIFICATE-----'.
This contains the public key we'll use to verify that all received SAML authentication
requests have been issued by your IdP.

Login This defines how your users can use single-sign on. The options are:
mode
Use SAML as secondary authentication – the default way to log in will be the
standard application login form. You can log in using SAML if you go to your IdP
and select your application, or by using the this URL to log in: BASE-URL/plugin
s/servlet/external-login. We recommended this method so you can test that
everything is configured correctly, and that users can log in using SSO.
Use SAML as primary authentication – in this mode, all browser-based users
will be redirected from the application's login screen to the IdP to log in. It's still
possible to authenticate by:
Basic Auth
Form-based auth via dedicated REST endpoint
Existing Remember Me tokens

You should only enable this mode once you've verified that SAML
authentication is working as expected.

Remember When checked, successful user logins will be remembered in the user's browser.
user logins When browsing to their application, users will be logged in automatically without
having to authenticate again using SAML.
Confluence Data Center uses 'remember me' to enable users to move seamlessly
between nodes. Turning Remember user logins off in this screen can override this
Confluence behaviour and lead to users needing to log in again each time they
move to another node. We recommend keeping Remember user logins enabled.

3. The following information is provided on the Authentication screen, and will be required to configure
your IdP:

Setting name Notes

Assertion Consumer Service This is the URL the IdP will return SAML authentication requests
URL to.

Audience URL (Entity ID) This is the URL the IdP will prepare SAML authentication
requests for.

4. Click Save configuration.

Once you've configured both your application and your IdP, you're ready to start using SSO.

Best practices

SAML authentication requests are only valid for a limited time. You should make sure the clocks on
the server running your application/s and the IdP are synchronised.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 101

If users and groups in your application are configured using User Directories, you'll usually want to use
the same LDAP directory to be the source of users for both your IdP and Atlassian application. Users
need to exist in the user directory before they can log in using SSO.

Troubleshooting

If you make a mistake configuring the SAML authentication, or are unable to log in using your IdP, you
can restore login form authentication by using issuing a DELETE request (using a username and
password for an administrator configured in your user directory):

curl -u admin_user:admin_password -X DELETE

http://base-url/product/rest/authconfig/1.0/saml

If an authentication error occurs, the user will only see basic details about what went wrong. For
security reasons, the details about the underlying problem are not shown. You'll need to check the
application logs to see the cause of the problem.
In some cases you might also experience errors shown by your IdP. For those you will need to use the
support and tools provided by your IdP, rather than Atlassian support.
When using SAML as primary authentication and you have CAPTCHA enabled in the
application, users that use HTTP basic authentication (for example in REST resource calls) may get
locked out if they enter an incorrect password too many times. In these cases, an administrator will
need to reset the user's CAPTCHA in the user list screen.

Managing System and Marketplace Apps

An app is a separately installed component that extends the basic Confluence functionality.
Not to be confused with the Confluence mobile app that users install on their own device, these apps are
installed by a Confluence admin, and act like an extension to Confluence. They are also known 'plugins' or
'add-ons'.
There are two main types of apps:
System apps - these are bundled with Confluence and provide core functionality
User installed apps - these are usually downloaded from The Marketplace and may have been created by
Atlassian or by a third party developer.
For information about developing your own apps for Confluence, see the Confluence Server and Data Center
Developer documentation.

About the Universal Plugin Manager

System and Marketplace apps are managed via the Universal Plugin Manager (known as the UPM). The UPM
can be found in most Atlassian applications, and provides a consistent experience for administering apps. To
visit the UPM, go to

> Manage apps in the Confluence header.

The UPM allows you to:
Discover and install new apps from the Atlassian Marketplace.
Install or remove apps.
Configure app settings.
Enable or disable apps and their component modules.
Confirm app compatibility before upgrading Confluence.
You'll need Confluence Administrator permissions to access the UPM.
See Request Marketplace Apps for information on how users can find and request add-ons.
See the Universal Plugin Manager documentation for more information on using the UPM.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 102

Disable and uninstall apps

You can disable or unsubscribe from user installed apps that are no longer being used on your site. See Disablin
g and enabling apps to find out how to do this.
Once the app is disabled, its features are immediately unavailable. If the app included macros, pages that
contained those macros will show an 'unknown macro' error. To avoid this, you can check which macros are
being used on your site before disabling an app by checking the macro usage statistics.
Go to

> General Configuration > Macro Usage.

Writing User Macros

User macros are useful if you want to create your On this page:
own custom macros. These can be to perform
specific actions, apply custom formatting and much Create a User Macro
more. Edit a user macro
Delete a user macro
User macros are created and managed within Best practices
Confluence itself, you do not need to develop an app Example user macros
(plugin). You will need some coding skills though.
Related Pages:
You'll need System Administrator permissions to
create and manage user macros. User Macro Module (Developer
documentation)

Create a User Macro

To add a new user macro:

1. Go to

> General Configuration > User Macros

2. Choose Create a User Macro
3. Enter the macro details (see table below)
4. Click Add

Macro details Description

field

Macro name This is the name of the macro, as it appears in the code.

Visibility This controls who can see this macro in the macro browser or auto-complete. Options
are:
Visible to all users
Visible only to system administrators
Note that if you select Visible only to system administrators, users will still see the
output of the macro on a page, and the macro placeholder will still be visible when a
user edits a page. It is only hidden in the macro browser and autocomplete.
All macro information is discoverable, including the macro title, description, parameter
names and other metadata. Do not include confidential data anywhere in the
definition of a user macro, even if it is marked as visible only to system
administrators.

Macro Title This is the title that will appear in the macro browser and auto-complete.

Description This is the description that will appear in the macro browser. The macro browser's
search will pick up matches in both the title and description.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 103

Categories Select one or more macro browser categories for your macro to appear in.

Icon URL Enter an absolute URL (for example http://mysite.com/mypath/status.png)

or path relative to the Confluence base URL (for example /images/icons/macrob
rowser/status.png) if you want the macro browser to display an icon for your
macro.

Documentation If you have documentation for your macro, enter the URL here.
URL

Macro Body Specify how Confluence should process the body before passing it to your macro.
Processing
The macro body is the content that is displayed on a Confluence page. If your macro
has a body, any body content that the user enters will be available to the macro in
the $body variable.

Options for processing the macro body include:

No macro body
Select this option if your macro does not have a body.
Escaped
Confluence will add escape characters to the HTML markup in the macro body.
Use this if you want to show actual HTML markup in the rendered page. For
example, if the body is <b>Hello World</b> it will render as <b>Hello
World</b>.
Unrendered
HTML in the body will be processed within the template before being output.
Ensure that HTML is ultimately output by the template.
Rendered
Confluence will recognize HTML in the macro body, and render it appropriately.
For example, if the body is <b>Hello World</b> it will render as Hello World.

Template This is where you write the code that determines what the macro should do.
Use HTML and Confluence-specific XML elements in the macro template.
You can use the Velocity templating language. Here is more information on the
Velocity project.
If your macro has a body, your template can refer to the macro body text by
specifying '$body'.
Each parameter variable you use must have a matching metadata definition. Use
@param to define metadata for your macro parameters.
When using the information passed using parameters, refer to your parameters
as $paramXXX where 'XXX' is the parameter name that you specifed in the @par
am metadata definition.
Use @noparams if your macro does not accept parameters.

See User Macro Template Syntax for more information and examples.

Do you need a plugin instead?

If you want to distribute your user macro as a plugin, please refer to the developer's guide to the Use
r Macro plugin module. If you want to create more complex, programmatic macros in Confluence,
you may need to write a Macro plugin.

Edit a user macro

To edit a user macro:

1. Go to

> General Configuration > User Macros

2. Click Edit next to the relevant macro
3.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 104

3. Update the macro details

4. Click Save

Delete a user macro

To delete a user macro:

1. Go to

> General Configuration > User Macros

2. The currently configured user macros will appear
3. Click Delete next to the relevant macro
Before deleting a user macro, you should search for all occurrences of the macro in pages and blog posts.
Users will see an 'unknown macro' error if you delete a user macro that is still in use on a page.

Best practices

This section contains tips and suggestions for best practices when creating your own user macros.

Add a descriptive header to your macro template

We recommend that you include a short description as a comment at the top of the Template field as shown
below.

## Macro title: My macro name

## Macro has a body: Y or N
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: My Name
## Date created: dd/mm/yyyy
## Confluence version: Version it was developed for
## Installed by: My Name

## Short description of what the macro does

Expose your parameters in the macro browser

The macro browser is the easiest way for users to configure your macro. You can specify the macro
category, link to an icon, define the parameters that the macro browser will use to prompt the user for
information, and more.

Supply default values for macro parameters

As you can't guarantee that a user has supplied parameters, one of the first things to do in the macro is
check that you have received some value if you expect to rely on it later on in the macro code.
In the example below, the macro expects three parameters, and substitutes sensible defaults if they are not
supplied.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 105

#set($spacekey= $paramspacekey)
#set($numthreads= $paramnumthreads)
#set($numchars= $paramnumchars)

## Check for valid space key, otherwise use current

#if (!$spacekey)
#set ($spacekey=$space.key)
#end

## Check for valid number of threads, otherwise use default of 5

#if (!$numthreads)
#set ($numthreads=5)
#end

## Check for valid excerpt size, otherwise use default of 35

#if (!$numchars)
#set ($numchars=35)
#end

Consider security implications

We recommend thoroughly testing your user macro with a number of permission scenarios, such as
restricted pages and space permissions to avoid inadvertently displaying content that a user has no
permission to see. See User Macro Template Syntax for more information.

Example user macros

Hello World
This example demonstrates how to create a user macro that displays the text 'Hello World!' and any text
that the user places in the body of the macro.

Field Value

Macro name helloworld

Visibility Visible to all users in the Macro Browser

Macro Title Hello World

Description Displays "Hello World" and the macro body.

Categories Confluence Content

Icon URL You can leave this field blank

Documentation You can leave this field blank

URL

Macro body Rendered

processing

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 106

Template Enter the code below in the template field - this example will print the text
straight onto the page.

## @noparams
Hello World!
$body

If you wanted the text to appear in a panel you could include the relevant AUI
message class as shown here.

## @noparams
<div class="aui-message closeable">
Hello World!
$body
</div>

Using the 'Hello World' macro on a page

Now you can add the macro to your Confluence page using the Macro Browser, or by typing {hello in the
editor and selecting the macro from the list of suggestions.

The result is:

NoPrint
This example demonstrates how to create a user macro that can contain text that is visible when viewing
a page, but does not print.

Field Value

Macro name noprint

Visibility Visible to all users in the Macro Browser

Macro Title No Print

Description Hides text from printed output.

Categories Confluence Content

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 107

Icon URL You can leave this field blank

Documentation URL You can leave this field blank

Macro body processing Rendered

Template Enter the code below in the template field.

## @noparams
<div class="noprint">$body</div>

Using the 'NoPrint' Macro on a page

Now you can add the macro to your Confluence page using the Macro Browser. Text entered into the
body of the macro placeholder will not be printed, but will appear when the page is viewed online.

Making the PDF export recognize the NoPrint macro

See Advanced PDF Export Customizations.

Color and Size

This example demonstrates how you can pass parameters to your macro. We'll create a font style macro
which has two parameters to allows the user to specify the color and size of the text contained in the
macro body.

Field Value

Macro name stylish

Visibility Visible to all users in the Macro Browser

Macro Title Stylish

Description Applies colour and size to text.

Categories Confluence Content

Icon URL You can leave this field blank

Documentation You can leave this field blank

URL

Macro body Rendered

processing

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 108

Template Enter the code below in the template field. If your macro requires more than one
parameter, you can use variables $param0 to $param9 to represent them.

## @param 0:title=colour|type=string
## @param 1:title=size|type=string
<span style="color: $param0; font-size:
$param1">$body</span>

Alternatively, you can also use explicitly-named parameters in your macro. These
macro parameters will appear as variables with the name $param<x> where <x>
is the name of your parameter.

## @param Colour:title=colour|type=string
## @param Size:title=size|type=string
<span style="color: $paramColour; font-size:
$paramSize">$body</span>

Formatted Panel
This example demonstrates how to write a user macro that creates a panel that is preformatted with
specific colors. It will create a panel that looks like this:

(Title)

Note: The panel's title will be empty if the user does not give a value for the title parameter.

Field Value

Macro name formpanel

Visibility Visible to all users in the Macro Browser

Macro Title Formatted Panel

Description Creates a panel preformatted with specific colors

Categories Formatting

Icon URL You can leave this field blank

Documentation You can leave this field blank

URL

Macro body Escaped

processing

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 109

Template Enter the code below in the template field. See below for a more detailed explanation of the code b

## @param Title:title=Title|type=string|desc=Title
<ac:structured-macro ac:name="panel">
<ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>
<ac:parameter ac:name="borderStyle">solid</ac:parameter>
<ac:parameter ac:name="borderColor">#6699CC</ac:parameter>
<ac:parameter ac:name="borderWidth">2</ac:parameter>
<ac:parameter ac:name="titleColor">#000000</ac:parameter>
<ac:parameter ac:name="title">$!paramTitle</ac:parameter>
<ac:rich-text-body>$body</ac:rich-text-body>
</ac:structured-macro>

Explanation of the code in the macro template

Below is a breakdown of the user macro template code.

Item Description

## @param Title:title=Title|type=string|desc=Title @param defines

the metadata for
your macro
parameters.
@param Title
This parameter is
called "Title".
title=Title

defines the
parameter title that
will appear in the
macro browser as
"Title".
type=string

defines the field

type for the
parameter as a text
field.
desc=Title

defines the
description of the
parameter in the
macro browser.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 110

<ac:structured-macro ac:name="panel"> This calls the

Confluence Panel
macro.
The easiest way to
find out the code
name of a
Confluence macro
by viewing the
Storage Format of a
page containing the
macro. You'll need
Confluence
Administrator
permissions to view
the storage format.

<ac:parameter ac:name="titleBGColor">#ccc</ac:parameter> Sets the

<ac:parameter ac:name="borderStyle">solid</ac:parameter> parameters for the
<ac:parameter ac:name="borderColor">#6699CC</ac:parameter> macro: the
<ac:parameter ac:name="borderWidth">2</ac:parameter> background color,
<ac:parameter ac:name="titleColor">#000000</ac:parameter> border style, border
color, border width
and title color.
To discover the
names of the
parameters for a
Confluence macro,
view the storage
format as described
above.

<ac:parameter ac:name="title">$!paramTitle</ac:parameter> Enters the value

stored in the 'Title'
parameter into the
title section of the
macro.
The ! tells the
macro to leave the
title blank, when
there is no data in
the "Title"
parameter.

<ac:rich-text-body>$body</ac:rich-text-body> Users can enter

data that is stored
in the body of the
macro. This line
enables the macro
to access and store
the body content
passed to your
macro.

</ac:structured-macro> This command

marks the end of
the macro.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 111

Do more with Confluence

Not keen to write your own macro? There are a ton of free and paid macros available in the Atlassian
Marketplace. Here are some of our most popular:
Numbered Headings: Automatically number headings for easy navigation and documentation
HideElements for Confluence: Hide several Confluence page elements - e.g. title, comments,
buttons - with just one click
Composition Tabs & Page Layout: Bring your content to life - tabs, highlights, instant focus,
menus and expandable sections

User Macro Template Syntax

See Writing User Macros for an introduction to On this page:
writing a user macro.
Accessing your macro's body
This page provides information about the code you Using parameters in your user
can enter in a user macro template. macro
Objects available to your macro
Controlling parameter appearance
Accessing your macro's body in the editor placeholder
Use the $body object within your user macro Related pages:
template to access the content passed to your
macro in the macro body. Writing User Macros

The $body object is available if you have specified

that your macro has a body (in other words, if you
have not selected No macro body).
Example: Let's assume your macro is called hello
world.
Enter the following code in your template:

Hello World: $body

A user, when editing a Confluence page, chooses

your macro in the macro browser and then enters
the following in the macro placeholder that is
displayed in the edit view:

From Matthew

The wiki page will display the following:

Hello World: From Matthew

Using parameters in your user macro

You can specify parameters for your macro, so that users can pass it information to determine its behavior on
a Confluence page.

How your macro parameters are used on a Confluence page

When adding a macro to a Confluence page, the macro browser will display an input field for each macro
parameter. The field type is determined by the parameter type you specify.

Defining the parameters

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 112

A parameter definition in the template contains:

@param
The parameter name
A number of attributes (optional).
Format:

## @param MYNAME:title=MY TITLE|type=MY TYPE|desc=MY

DESCRIPTION|required=true|multiple=true|default=MY DEFAULT VALUE

Additional notes:
The order of the parameters in the template determines the order in which the macro browser displays
the parameters.
We recommend that you define the parameters at the top of the template.
There may be additional attributes, depending on the parameter type you specify.
The sections below describe each of the attributes in detail.

Attribute Description Required /

name Recommended
/ Optional

(an A unique name for the parameter. The parameter name is the first Required
unnamed, attribute in the list. The name attribute itself does not have a name. See
first the section on name below.
attribute)

title The parameter title will appear in the macro browser. If you do not Recommended
specify a title, Confluence will use the parameter name.

type The field type for the parameter. See the section on type below. Recommended

desc The parameter description will appear in the macro browser. Optional

required Specifies whether the user must enter information for this parameter. Optional
Defaults to false.

multiple Specifies whether the parameter accepts multiple values. Defaults to Optional
false.

default The default value for the parameter. Optional

Parameter name

The parameter name is the first attribute in the list. The name attribute itself does not have a name.
Example: The following code defines 2 parameters, named 'foo' and 'bar':

## @param foo
## @param bar

Parameter type

The field type for the parameter. If you do not specify a type, the default is string.

Parameter type Description

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 113

boolean Displays a checkbox to the user and passes the value 'true' or 'false' to the macro as a string.

enum Offers a list of values for selection. You can specify the values to appear in a dropdown in the macro
browser. Example of specifying the enum values:

## @param
colour:title=Colour|type=enum|enumValues=Grey,Red,Yellow,Green

Note about i18n: Confluence does not support internationalization of the enum values.The value the
user sees is the one passed to the macro as the parameter value, with the capitalization given. In th
case 'Grey', 'Red', etc.

string A text field. This is the default type. Example with a required field:

## @param
status:title=Status|type=string|required=true|desc=Status to
display

confluence-content Offers a control allowing the user to search for a page or blog post. Example:

## @param
page:title=Page|type=confluence-content|required=true|desc=Select
a page do use

username Search for user.

## @param user:title=Username|type=username|desc=Select username

to display

spacekey Offers a list of spaces for selection. Passes the space key to the macro. Example:

## @param space:title=Space|type=spacekey

date Confluence accepts this type, but currently treats it in the same way as 'string'. Example:

## @param fromDate:title=From Date|type=date|desc=Date to start

from. Format: dd/mm/YYYY

Note about dates: A user can enter a date in any format, you should validate the date format in your
user macro.

int Confluence accepts this type, but treats it in the same way as 'string'. Example with a default value:

## @param numPosts:title=Number of
Posts|type=int|default=15|desc=Number of posts to display

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 114

percentage Confluence accepts this type, but treats it in the same way as 'string'. Example:

## @param pcent:title=Percentage|type=percentage|desc=Number of
posts to display

Using the parameters in your macro code

The parameters are available in your template as $paramfoo, $parambar for parameters named "foo" and
"bar".
Normally, a parameter like $paramfoo that is missing will appear as '$paramfoo' in the output. To display
nothing when a parameter is not set, use an exclamation mark after the dollar sign like this: $!paramfoo

Using no parameters

If your macro does not accept parameters, you should use @noparams in your template.

If the user macro contains no parameters and does not specify @noparams, then the macro browser will
display a free-format text box allowing users to enter undefined parameters. This can be confusing if the
macro does not accept parameters.
Example: Add the following line at the top of your template:

## @noparams

Objects available to your macro

Including the macro body and parameters, the following Confluence objects are available to the macro:

Variable Description Class Reference

$body The body of the macro (if the macro has a body) String

$paramfoo, $paramba Named parameters ("foo", "bar") passed to your String

r, ... $param<name> macro.

$config The BootstrapManager object, useful for retrieving BootstrapManager

Confluence properties.

$renderContext The PageContext object, useful for (among other PageContext

things) checking $renderContext.outputType

$space The Space object that this content object (page, blog Space
post, etc) is located in (if relevant).

$content The current ContentEntity object that this macro is ContentEntityObject

a included in (if available).

Macros can also access objects available in the default Velocity context, as described in the developer
documentation.

Security consideration
When creating a User Macro you should avoid using $content.getChildren() or $content.ge
tDescendants() as these methods will list all pages, regardless of page restrictions or space
permissions. This may lead to page viewers seeing pages that they do not have permission to see.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 115

We also recommend thoroughly testing your user macro with a number of permission scenarios,
such as restricted pages and space permissions.

Controlling parameter appearance in the editor placeholder

You can determine which macro parameters should appear in the placeholder in the Confluence editor.
By default as many parameters as can fit will be displayed in the placeholder, as shown here:

You can control which parameters you want to display here, to ensure the most relevant information is visible
to the author.
For example, the Confluence Warning macro has two parameters, title and icon. We consider title to be the
most interesting parameter, so we have configured the Warning macro to show only the value of the title para
meter.
Let's assume an author adds the Warning macro to a page, and gives it a title of 'The title of the warning'.
The macro configuration leads to a placeholder as shown here:

To configure the macro placeholder for a user macro, you will add attributes to the @param entry in the
template.
For example, if our Warning macro is a user macro, the configuration for the title parameter is as follows:

## @param
title:type=string|option-showNameInPlaceholder=false|option-showValue
InPlaceholder=true

The attribute showNameInPlaceholder specifies that the title parameter's name should not be shown.

The attribute showValueInPlaceholder specifies that the title parameter's value should be shown.

If none of the parameters in a macro include any of the above attributes, then the default behavior is to show
all the parameters that fit in the placeholder: full title and value.
If one or more parameters has either attribute set, then all parameters that do not include the attributes will
default to false (that is, they will not be shown).

Customizing your Confluence Site

This page is an introduction to customizing Confluence at site level. This is of interest to Confluence
administrators – people with System Administrator or Confluence Administrator permissions.
For guidelines on customizations at a personal and space level, see Your User Profile or Customize your Space.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 116

We've documented the customizations under two broad headings:

You can change the appearance of Confluence by customizing the dashboard, adjusting the colors,
adding a site logo, and more. See Changing the Look and Feel of Confluence.
You can determine the default behavior by setting various options, or define the default content that
appears in new spaces, on the dashboard, and in other Confluence locations. See Changing the Default
Behavior and Content in Confluence.

Related pages:
Integrating Confluence with Other Applications
Tracking Customizations Made to your
Confluence Installation
Confluence administrator's guide

Changing the Look and Feel of Confluence

You can change the appearance, or look and feel of Related pages:
Confluence for the whole site (globally) or for
individual spaces. Administering Site Templates

Changes you make to the whole site will also apply Working With Decorator Macros
to all spaces that are inheriting the global look and Customizing a Specific Page
feel. Users with space administrator permissions Upgrading Customized Site and
can further customize the appearance of a Space Layouts
space and override the global look and feel for that
space. See Customize your Space for more.

Ways to customize the look and feel of your site:

Add your own site logo. See Changing the Site Logo.
Change the color scheme of the user interface. See Customizing Color Schemes.
Use themes for advanced layout customization. See Working with Themes.
Change the site or space layouts, which determine how the controls are laid out in the site. This
does not change the actual page layouts, but it does change the way the surrounding controls appear
in the page. See Customizing Site and Space Layouts.

Customizing the Confluence Dashboard

The dashboard is the default landing page for your On this page:
Confluence site. It gives people all the tools they
need to discover pages, resume their work and Editing the site welcome message
quickly jump to their favorite spaces and pages. Using a page as the site landing
page
Advanced customizations
Editing the site welcome message
Related pages:
The site welcome message appears on the right
Save for later
hand side of the dashboard and is the perfect place
Changing the Look and Feel of
to inject some of your organization's personality.
Confluence
See Editing the Site Welcome Message to find out
how to add announcements, useful links, images,
macros and more.
You'll need Confluence administrator permissions to
edit the site welcome message.

Using a page as the site landing page

If you want more control, you can choose to use an ordinary Confluence page as your site landing page,
instead of sending people to the dashboard. See Configuring the Site Home Page to find out more.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 117

Using a page instead of the dashboard can be useful if most people will be reading, rather than creating,
pages in your site. However, for sites where you want to encourage teams to collaborate, the dashboard
provides the best tools for resuming work in progress and keeping up with what is happening in the site.

Advanced customizations

You can further customize the dashboard by editing the global layout file. See Customizing Site and Space
Layouts for more information on how to do this. You'll need some knowledge of Velocity to modify the layout
files.
There are two locations that you can add content to:
Web panels added to atl.dashboard.secondary will appear below the site welcome message.
Web items added to system.dashboard.button will appear next to the Create space and Invite
users button at the top right of the dashboard.
If you modify layouts in Confluence you will need to reapply your modifications each time you upgrade
Confluence. The more dramatic your customizations are, the harder it may be to reapply the changes when
upgrading. See Upgrading Customized Site and Space Layouts to find out what will be involved before
modifying the layouts.

Changing the Site Logo

You can customize the look and feel of your On this page:
Confluence site by changing the logos.
Changing the site logo
You can change: Changing the site icon (favicon)
Changing the default space logo
the site logo
Changing a specific space logo
the default space logo for all spaces
the space logo for individual spaces. Related pages:
Changing the Look and Feel of
Confluence

1. Space logo: appears in the sidebar and on the dashboard.

2. Site logo: always visible, click the logo to go to the dashboard (or site homepage).

Changing the site logo

The Site Logo appears in the header and is visible throughout Confluence. You need Confluence
Administrator permissions to change the site logo.
To change the site logo:
1. Choose the cog icon

, then choose General Configuration

2. Choose Site Logo and Favicon.
3. Choose Browse to upload a new logo.
4. Choose Show Logo Only or Show Logo and Title depending on whether you wish the Site Title to

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 118
4.
display in the header.
5. Choose Save.
Confluence's Auto Look and Feel will detect the colors in your new logo, and change the site color scheme to
match.
If you would prefer to use the default color scheme with your custom logo go to

> General Configuration > Color Scheme > Edit and then choose Reset to revert back to the default
scheme.

1. Site logo: auto look and feel has updated the header colours to complement the logo.
2. Site title: this is the name of your site.

Changing the site icon (favicon)

You can also change the site favicon (the icon that appears in your browser tab). You need Confluence
Administrator permissions to do this.
1. Go to

> General Configuration > Site Logo and Favicon.

2. Locate your image file and choose Upload.
You can upload PNG, GIF, JPEG, or ICO files. For best results images should be square, and at least 48x48
pixels.

Changing the default space logo

The Space Logo appears in the sidebar and as an icon in the Sites Directory. The default space logo applies
to all spaces that do not have a custom space logo applied - see Configure the Sidebar.
You need to be a Confluence Administrator to change the default space logo.
To change the default space logo:
1. Go to

> General Configuration > Default Space Logo.

2. Choose Logo:ON
3. Choose Browse to upload a new logo
4. Choose Upload Logo
5. Choose Save.

Changing a specific space logo

Space Administrators can change the logo for their space. This overrides the default space logo and any cha
nges to the default space logo will not appear in these spaces. See example above - 'Sample Space' has a
custom logo.

See see Configure the Sidebar to find out how to change the logo in a specific space.

Customizing Color Schemes

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 119

Confluence administrators can configure a new color scheme for the site. On this page
The default color scheme for the site will also become the default for all Reset your
spaces within it. color
scheme
To change the site's color scheme:
after
1. Choose the cog icon uploading
a site logo
, then choose General Configuration Related pages:
2. Choose Color Scheme in the left-hand panel
3. Click Edit Changing
4. Enter standard HTML/CSS2 color codes, or use the color-picker the Look
and Feel of
to choose a new color from the palette provided. Confluenc
5. Hit Save e

Any changes you make will immediately be reflected across the Confluence
site.

Reset your color scheme after uploading a site logo

When you upload a site logo, Confluence automatically detects the colors in your logo and customizes the
color scheme for you.
You can change the color scheme as above, or reset your color scheme back to the default (and still keep
your new site logo).
To reset the color scheme:
1. Choose the cog icon

, then choose General Configuration

2. Choose Color Scheme in the left-hand panel
3. Click Edit
4. Hit Reset

Styling Confluence with CSS

This page explains the facility for changing the look and feel of Confluence On this page:
with CSS. Introductio
n
Introduction
Considerat
ions for
Cascading Style Sheets (CSS) are an industry-standard way of styling a Using
web page. The content of a page is rendered with HTML, and its look and Custom
feel is determined by CSS files. You can upload a CSS text file, or simply CSS
type in a stylesheet, and apply it to a space or even a whole Confluence Getting
site. Started
CSS
Note: By default, only system administrators can edit the CSS for a space or Resources
for the site. To allow any user with Space Admin permissions to edit the
CSS for a space, go to
Related pages:
> General Configuration > Security Configuration and select Custom Basic
Stylesheets for Spaces. Styling
Tutorial
Creating CSS styles that work seamlessly across different browsers is a
Styling
delicate task for basic web sites, and reasonably challenging when
Fonts in
customizing web applications like Confluence. It is important to test each
Confluenc
change that you make and ensure it works as expected in all areas of
e
Confluence – for example, on the Confluence dashboard as well as on
regular pages.
In order to get you started, we have compiled this introduction, a basic
styling tutorial.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 120

Considerations for Using Custom CSS

CSS Knowledge is Required

If you are not familiar with CSS, see the links in the CSS Resources section below. You should spend some
time to become confident with Cascading Style Sheets before you start editing your Confluence style sheets.

Security

Custom CSS can be used to inject scripts into a page, opening the risk of cross-site scripting (XSS) attacks.
With this feature enabled, space administrators could upload styles that steal other users' login credentials,
trick their browsers into performing actions on the wiki without their knowledge, or even obtain global
administration privileges. As such, this feature is disabled by default. Confluence administrators should only
enable custom CSS if they are comfortable with the risks listed in this paragraph.

Scaling

Each page needs to scale. Depending on the resolution of the user's screen, the content should render
intelligently. Your designs needs to degrade gracefully. Try resizing each page that exists in Confluence.
There are quite a few pages in the browse-space-section, like drafts, labels, page hierarchy, and so on. Your
style has to work everywhere, not just in the first page you happen to be looking at.

Features Cannot Be Disabled

It is easy to turn off certain links, headers, or even menu items by simply setting their style to 'hidden'. This
can help you to roll out Confluence to users that may not be very Wiki-savvy yet. The simpler the UI, the
easier it may be for them to use. However, please remember that removing the link to a part of the
application does not mean that the functionality is not available. Every user can still change their style from
within their browsers, or access the URL directly. Don't rely on CSS to disable parts of Confluence.

Features Should Not Be Disabled

Users familiar with Confluence will expect to find the same controls that they are accustomed to. Removing
buttons or controls from the interface is not advised as it may frustrate your users and cause them to
circumvent your design by using direct URL access, as mentioned above.

Custom CSS does not apply to Admin screens

Any CSS styling applied to your site will not be applied to the Administration console. This is to ensure
changes to CSS do not prevent administrators from accessing Admin functions in future.

Confluence Version Compatibility

Be aware of any plans to upgrade your Confluence instance. Future versions of Confluence may not be
compatible with your custom CSS — this may cause your CSS to break, requiring maintenance when
Confluence is upgraded. Ask your Confluence administrator for more information.

Test on Different Web Browsers

As a rule you should test your modifications on the various web browsers supported by Confluence.

CSS Customization is Not Supported

As creating custom CSS has potentially limitless possibilities, Atlassian will not support issues that are
caused by or related to CSS customization.

Getting Started

Editing the CSS

To edit a space's CSS style sheets:

1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
2. Choose Stylesheet then Edit.
3. Paste your custom CSS into the text field.

4.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 121

4. Save your changes. The new CSS will be visible on all content pages in the space.
To edit your global CSS stylesheet:
1. Choose

> General Configuration > Stylesheet.

2. Choose Edit.
3. Paste your custom CSS into the text field.
4. Choose Save.
Note:
The new CSS will be visible across all spaces, provided they do not define their own custom
stylesheet and are not using a theme. This CSS will also overwrite all styles defined in custom global
themes.
You may be able to add CSS to your site by choosing Custom HTML in the administration section,
and adding your CSS definitions to the HEAD or BODY of the page. You should only use this option if
you cannot achieve the desired results via the global stylesheet.

Follow the Tutorial

Follow the examples in the Basic Styling Tutorial to get started.

CSS Resources

W3C CSS Standards

Mozilla Developer Network
W3resource.com

Basic Styling Tutorial

This page contains instructions on how to get started with custom CSS On this page:
styling in Confluence. CSS
Editing
CSS Editing Quick-Start Quick-Start
Tutorial:
To edit a space's CSS style sheets: Changing
1. Go to the space and choose Space tools > Look and Feel from the the Header
bottom of the sidebar Backgroun
2. Choose Stylesheet then Edit. d
3. Paste your custom CSS into the text field. CSS
4. Save your changes. The new CSS will be visible on all content pages Editing
in the space. Tips
Notes
Related pages:
Styling
Confluenc
e with CSS

Tutorial: Changing the Header Background

The header is the menu area at the top of a default Confluence page where the Breadcrumb Links, Browse
menu, User menu and the Quick Search box reside. In this example, we are going to change the
background of the header to include a custom graphic.
1. Create a custom graphic. For this example, we created a custom header graphic of 1046 x 61 pixels.
2. Upload the custom graphic to a page in the space that you are customizing.
3. Note the page ID of the page where you uploaded the new graphic. (in this example, the page ID was '
658833839'.
4. Compose your custom CSS for the header. The example below loads the new graphic (called 'header.
png') from a specific page (denoted by page ID ' 658833839') in the same space.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 4.
Confluence 6.15 Documentation 122

#header .aui-header {

background-image:url('../download/attachments/658833839/header.p
ng');
background-repeat: no-repeat;
}

5. Log in as the Space Administrator.

6. Open the Space Admin page.
7. Click Stylesheet.
8. Click Edit to change the code in the text field.
9. Paste your custom CSS into the text field.
10. Click Save and then reload the page (you may have to shift-reload). The background of the header will
change.
11. The custom header will be visible on all content pages in the space. To revert your change, simple
delete the custom code from the 'Stylesheet' page and click Save.

CSS Editing Tips

Begin With a Space Stylesheet
A space stylesheet is a good starting point for CSS customization, as it already includes all of the elements
that can be changed. When you work on the space stylesheet it styles all content pages in the space. Build
and test it at space-level, before considering applying the new stylesheet to your entire site. Once you are
satisfied with your space design, test it thoroughly until you are confident that it has no problems. Then, you
can look into advanced customization of the Confluence CSS such as adjusting the Search page, the
Dashboard and other integral pages.
Use the Right Tools
As the Confluence CSS is reasonably sophisticated, web development applications will help you to
understand how the page styles have been created. In particular, you will need to view the existing source for
the pages you're starting to work on. If you don't already have some, tools such as the following free
applications will allow you to do this.
1. Firebug
Firebug, a plugin for the Firefox web browser, allows you to take a look at the style of each element on your
page. This is very useful to see what styles are currently applied, for example styles applied to the header
only.
2. Web Developer
The Web Developer plugin for Firefox allows you to edit CSS inline and create new page designs.
3. CSS Edit
CSS Edit is a stand-alone CSS editor for Macintosh that extracts all existing styles from a given page and
allows you to overwrite these.
Edit Simple Elements First
Begin by editing simple elements and checking that they work. By making changes, then checking that each
one worked, you can easily isolate any CSS code that is causing problems. Be aware that some page
elements are more suited to customization than others. For example, adding a gradient to the toolbar is less
likely to 'break' the page than changing the page width. Editing reasonably static elements such as
background graphics will render more predictably than designs which attempt to completely change the user
interface or the Javascript-powered drop-down menus (which we don't recommend editing).

Notes

Note: By default, only system administrators can edit the CSS for a space or for the site. To allow any user
with Space Admin permissions to edit the CSS for a space, go to

> General Configuration > Security Configuration and select Custom Stylesheets for Spaces.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 123

Styling Fonts in Confluence

Confluence provides the ability to adjust its visual Related pages:
style via Cascading Style Sheets (CSS). This tutorial
shows you to change the fonts and font sizes of a Basic Styling Tutorial
Confluence page, using a few lines of CSS. Styling Confluence with CSS

Below is the code for the custom font. Copy and

paste it into the Space Stylesheet form within the
Space Administration section.
Changing the fonts

In order to customize the fonts in Confluence, you first need to set the body font to the font you want.
Secondly, you may want to adjust the font size because different fonts have different relative sizes.
The relevant CSS is shown below. It changes Confluence's font from the default of Helvetica/Arial – sans
serif to Times/Times New Roman – serif. To adjust for the fact that Times is a bit smaller than Helvetica, we
increase the font size to 14 pixels. The many styles that 'wiki-content' in their definition are necessary to
change the font size for all the tags in the wiki content.

body {
font-family: Times, "Times New Roman", serif;
font-size: 14px;
}
.wiki-content,
.wiki-content p,
.wiki-content table,
.wiki-content tr,
.wiki-content td,
.wiki-content th,
.wiki-content ol,
.wiki-content ul,
.wiki-content li {
font-size: 14px;
}

Notes

Note: By default, only system administrators can edit the CSS for a space or for the site. To allow any user
with Space Admin permissions to edit the CSS for a space, go to

> General Configuration > Security Configuration and select Custom Stylesheets for Spaces.

Working with Themes

Themes are used to change the appearance of your Confluence site or
spaces. Related pages:

Confluence comes with a single default theme installed, or you can Apply a
download and install other themes from The Atlassian Marketplace. Theme to
a Space
Once a theme is installed it can be applied to the whole site or to individual Applying a
spaces. Theme to
a Site
To see the themes installed in your site: Creating a
1. Go to Theme

> General Configuration > Themes.

2. You'll see a list of all the themes installed in your site.
When a new space is created, whichever theme is applied to the whole site

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 124

will be applied by default to the new space. The space theme can then be
changed by anyone with by anyone with space administrator permissions for
that space.

Note about the Documentation theme

The Documentation theme was available in Confluence 5.9 and earlier.

Many of the Documentation theme features are now available in the
Confluence default theme. Check out Develop Technical Documentation in
Confluence for more information about using Confluence for documentation
using the default theme.

Applying a Theme to a Site

Themes are used to change the appearance of your Confluence site. See W Related pages:
orking with Themes for an overview of how themes apply to your whole site,
and how you can add more themes. To apply a theme across the site: Apply a
Theme to
1. Go to a Space

> General Configuration > Themes.

2. The screen will display all available themes. Choose a theme.
3. Choose Confirm.
All spaces that have the Global look and feel applied as their space theme
will inherit this theme and any customizations you make to it.

Creating a Theme
If you want to create your own theme, you will need Related pages:
to write a Confluence plugin. Please refer to the
following pages in our developer documentation: Applying a Theme to a Site
Apply a Theme to a Space
Get started with plugin development.
Follow the developer's tutorial for writing a
Confluence theme.
Create a theme using the theme plugin
module.

Customizing Site and Space Layouts

You can modify Confluence's look and feel by On this page:
editing layout files (also known as
decorators). Editing these files allows you to change Editing a site decorator file
the look and feel of the whole Confluence site, or Using Velocity macros
just an individual space. Advanced customizations

When you edit a site layout, you'll be modifying the Related pages:
default decorators in every space in your site, except Velocity Template Overview
for those that have already been edited in a space. Basic Introduction to Velocity
See Customize Space Layouts for more information Customizing your Confluence Site
on how to edit the decorators for a single space.
You'll need System Administrator permissions to edit
site layouts.

If you modify layouts in Confluence you will need to reapply your modifications each time you
upgrade Confluence. The more dramatic your customizations are, the harder it may be to reapply the
changes when upgrading. See Upgrading Customized Site and Space Layouts to find out what will
be involved before modifying the layouts.

Confluence is built on top of the open source SiteMesh library, a web-page layout system.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 125

To edit the layout of Confluence, you will need to modify these decorator files. A decorator file is a .vmd file
and is written in Velocity. You can learn more from the Velocity User Guide.

Once you are familiar with Velocity, you can edit the decorator files to personalize the appearance of
Confluence.
The decorator files in Confluence are grouped into the following categories:
Site layouts: These are used to define the controls that surround each page in the site. For example,
the header, footer and dashboard.
Content layouts: These control the appearance of content such as pages and blog posts. They do
not change the way the pages themselves are displayed, but allow you to alter the way the
surrounding comments or attachments are displayed.
Export layouts: These control the appearance of spaces and pages when they are exported to
HTML.

Editing a site decorator file

To edit a site decorator:

1. Go to

> General Configuration > Layouts (under Look and Feel)

2. Click Create Custom next to the decorator .vmd file you want to modify.
3. Make your changes and click Update.
If something goes wrong: Hit Reset Default to revert to the original layouts.

Using Velocity macros

When editing Custom Decorator Templates, there are a number of macros available to define complex or
variable parts of the page such as menus and breadcrumbs. You may insert these macros anywhere in your
templates. More information on Working With Decorator Macros.

Advanced customizations

Overriding Velocity templates

The velocity directory is at the front of Confluence's Velocity template search path. As such, you can
override any of Confluence's Velocity templates by placing an identically named file in the right place. While
we don't recommend you do this unless you know exactly what you're doing, it does give you complete
control over the look of every aspect of Confluence. It also means that you can edit your templates in a
text-editor if you wish, rather than through the web interface.

Caching

Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows
to reload that page from disk. If you are editing the pages on disk, you will either have to turn off velocity's
caching temporarily in WEB-INF/classes/velocity.properties, or restart the server to make your
changes visible.

Location of Velocity files

You will find the Velocity files in your Confluence installation directory. The primary Velocity files are located
in the <CONFLUENCE-INSTALLATION>\confluence\decorators directory. For example, you will find
the following files in that directory: main.vmd, space.vmd, form-aui.vmd, global.vmd, and more.

Finding the layout via the URL

If the layout has changed so extensively as to not be visible, you can browse to the URL directly:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 126

http://<confluence base
url>/admin/resetdecorator.action?decoratorName=decorators/main.vmd

Substitute the base URL and the appropriate .vmd file.

Upgrading Customized Site and Space Layouts

As Confluence evolves, so do the default site and Related pages:
space layouts that drive the rendering of every page.
As new functionality is added or current functionally Customizing Site and Space
is changed, the default layouts are modified to Layouts
support these changes.

If you are using custom layouts based on defaults from a previous Confluence version, you run the
risk of breaking functionality, or worse, missing out on great new features!

Take care on each new release of Confluence to reapply your changes to the new default templates.
To reapply your custom layouts, you need to:
1. Obtain the source of your custom layouts from your current version of Confluence.
2. Reapply your customizations to the new default layouts.

Step 1. Obtain your Custom Layouts

Ideally, you should keep a record of each customization you have applied to each of your Confluence site or
space layouts.
If not, you should be able to find your customizations using the following method. This method extracts all
site- and space-level layouts from your Confluence site as a single output. From this output, you should be
able to identify your customizations.

This method is handy to use if you have:

Many spaces with space layout customizations, or
Do not have an independent record of your site or space layout customizations.

Custom layouts are stored in the DECORATOR table within your Confluence database. You can SELECT for
the source of the layout using SQL like this:

mysql> select SPACEKEY,DECORATORNAME,BODY from DECORATOR;

+----------+---------------------+------+
| SPACEKEY | DECORATORNAME | BODY |
+----------+---------------------+------+
| NULL | decorators/main.vmd | ... |
+----------+---------------------+------+
1 row in set (0.03 sec)

This example was tested on MySQL, but should be applicable to all SQL databases.

Step 2. Reapply your Customizations

When you upgrade Confluence to another major release of Confluence, you will need to manually reapply
any customizations you made to any site-wide or space-specific layouts. Unless otherwise stated, you should
not need to reapply customizations after conducting a minor release upgrade of Confluence.
What are 'major' and 'minor' releases? Major release upgrades are ones where the 1st digit of
Confluence's version number or the 1st digit after the 1st decimal place differ after the upgrade, for example,
when upgrading from Confluence 3.0 to 3.1, or 2.8 to 3.0. Minor release upgrades are ones where the 1st

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 127

digit of Confluence's version number and the 1st digit after the 1st decimal place remain the same after the
upgrade, for example, when upgrading Confluence 3.0 to 3.0.1.
If you have made Confluence site-wide layout customizations:
1. Choose the cog icon

, then choose General Configuration

2. Select Layouts in the left-hand navigation panel. The decorators are grouped under Site, Content an
d Export layouts.
3. Ensure you have all your customizations available (preferably in a form which can be copied and
pasted).
4. Click Reset Default next to the layout whose customizations need to be reapplied.
5. Click Create Custom next to the same layout and reapply your customizations (by copying and
pasting them) into the appropriate locations within the new default layout.
6. Click the Save button.
7. Repeat this procedure from step 4 for each layout whose customizations need to be reapplied.
If you have made space-specific layout customizations:
1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
2. Choose Layout. The decorators are grouped under Site, Content and Export layouts.
3. Ensure you have all your customizations available (preferably in a form which can be copied and
pasted).
4. Click Reset Default next to the layout whose customizations need to be reapplied.
5. Click Create Custom next to the same layout and reapply your customizations (by copying and
pasting them) into the appropriate locations within the new default layout.
6. Click the Save button.
7. Repeat this procedure from step 5 for each layout whose customizations need to be reapplied.

Step 3. Test your Modifications Carefully

Changes may interact unpredictably with future versions of Confluence. When upgrading, you should always
test your custom modifications thoroughly before deploying them on a live site. It's beyond the scope of
Atlassian Support to test and deploy these changes.

Turning Off Caching

Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows
to reload that page from disk. If you are editing the pages on disk, you will either have to turn off Velocity's
caching temporarily in WEB-INF/classes/velocity.properties, or restart the server to make your
changes visible.
The velocity.properties file is available in the confluence-x.x.x.jar file, where x.x.x is the
Confluence version number. The JAR file is located in the WEB-INF/lib directory. If you wish to make
modification to the files in the JAR, we recommend the following steps:
1. Stop Confluence.
2. Make a backup copy of the JAR file.
3. Un-jar the file
4. Locate and edit the appropriate file that you wish to modify.
5. Re-jar the confluence-x.x.x.jar file.
6. Relocate the JAR file to the appropriate directory.
7. Restart Confluence.

Working With Decorator Macros

Decorator Macros are Velocity macros which are used to draw complex or variable parts of the page such as
menus and breadcrumbs when editing Custom decorators. Decorator macros can be inserted anywhere in your
templates.
The macro is called by inserting a string of the form: #macroName("argument1" "argument2" "argument3").There
are no commas between the arguments. Unless otherwise noted, these macros take no arguments.
NOTE: These macros will only work reliably when customizing main.vmd. They may not work in other Velocity

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 128

decorators. Decorator macros will not work inside normal confluence pages.

Macro Usage

#breadcrumbs() Draws the "You are here" breadcrumbs list, like the
one found above the page name in the default
template.

#includePage(pageTitle) Includes a confluence page with the specified title. If

you have 2 or more pages with the same title across
multiple spaces, this macro will include the page
belonging to the space you are currently viewing.

#searchbox() Inserts a search box into the page, like the one to
the far right of the breadcrumbs in the default
template.

#globalnavbar(type) Draws the global navigation bar, as found in the top

right-hand corner of the default template. The
navigation bar can be displayed in two modes:

#globalnavbar("table") Displays the navigation bar in its default mode:

drawn as a table of links with colored backgrounds
and mouse-over effects.

#globalnavbar("text") Displays the navigation bar as series of text links

separated by
|
characters.

#usernavbar() Draws the user-specific navigation-bar. This bar

contains the links to the user's profile and history, or
to the login and signup pages if the user is not
logged in.

#helpicon() Draws the help icon, and link to the Confluence help
page.

#printableicon() On pages where a printable version is available,

draws the printable page icon, linking to the
printable version of the page. Otherwise, draws
nothing

#pagetitle(class) When you are viewing a page in a Confluence

space, draws the name of the space that page is in.
Otherwise, writes the word "CONFLUENCE".The
"class" argument is the CSS class that the title
should be drawn in. Unless you have customized
your Confluence installation's CSS file, you should
call this with "spacenametitle" as the class: #paget
itle("spacenametitle")

#poweredby() Writes out the "Powered by Confluence" and

Confluence version-number boilerplate found at the
bottom of the default template.

#bottomshadow() Draws the fading shadow-effect found at the bottom

of the content area in the default template.

#dashboardlink() Inserts a link to the dashboard page.

Custom Decorator Templates

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 129

About Decorators

Confluence is built on top of the Open Source SiteMesh library, a web-page layout system that provides a
consistent look and feel across a site. SiteMesh works through "decorators" that define a page's layout and
structure, and into which the specific content of the page is placed. If you are interested, you can read more in
the SiteMesh documentation.
What this means for Confluence is that you can customize the look and feel of parts of your Confluence site
through editing decorators, for example:
The "Main" decorator defines the generic header and footer
The "Page" decorator defines how a page is displayed
The "Printable" decorator defines the look and feel of the printable versions of pages.
You can view and edit these decorators from within Confluence. Changes to the decorators will affect all spaces
in that Confluence installation.
The decorator that is used to draw Confluence's administrative pages cannot be edited from within Confluence.
This means that if you make a mistake that renders the rest of the site unuseable, the administrative pages
should still be available for you to fix the template.

Browsing the Default Decorators

At any time, you can browse the default decorators that come packaged with Confluence by following the "View
Default" links on the "Site Layouts" page. The template browser also allows you to view the "#parsed" templates
that are included within the template when it is compiled. While you can't edit these included templates, you will
probably have to copy some or all of them into your custom template as you do your customization.

Editing Custom Decorators

To edit Confluence decorators you will need a good knowledge of HTML, and some understanding of the Velocit
y templating language.
To edit a decorator:
1. Go to Confluence Admin > Layouts.
2. Choose Create Custom beside the decorator you wish to edit.
3. Save your changes.
If you make a mistake or want to undo your changes, choose Reset Default beside the edited decorator.
Alternatively, the custom templates are stored in the DECORATOR table in the database. If you have somehow
managed to render Confluence completely unuseable through editing your templates, delete the relevant entries
from the DECORATOR table.

Macros

Some parts of the page are drawn using Velocity macros, including the navigation bar. The macros you should
know about when editing decorators are described in Working With Decorator Macros.

For Advanced Users

The velocity directory is at the front of Confluence's velocity template search path. As such, you can override
any of Confluence's velocity templates by placing an identically named file in the right place.
While we don't recommend you do this, it does give you complete control over the look of every aspect of
Confluence. It also means that you can edit your templates in a text-editor if you wish, rather than through your
browser.
There are, however, two important caveats:
1. Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it
knows to reload that page from disk. If you are editing the pages on disk, you will either have to turn off
velocity's caching temporarily in WEB-INF/classes/velocity.properties, or restart the server to
make your changes visible.
2. Changes may interact unpredictably with future versions of Confluence. When upgrading, you should
always test your custom modifications thoroughly before deploying them on a live site.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 130

Customizing a Specific Page

If you'd like to change the appearance of a specific page, you can modify the corresponding Velocity template.
Here's how to find out which one:
1. Access the page. Note the name of the action. For example, the "Contact Administrators" page is <baseU
rl>/administrators.action.
2. Browse to <confluence-install>/confluence/WEB-INF/lib/confluence-x.y.jar. Copy the file.
3. Unzip or unjar the file using a standard unzipper or the java jar utility.
4. Open xwork.xml. Search the file for the name of the action corresponding to the page you'd like to modify.
You'll see an entry like:

<action name="administrators"
class="com.atlassian.confluence.user.actions.AdministratorsAction">
<interceptor-ref name="defaultStack"/>
<result name="success"
type="velocity">/administrators.vm</result>
</action>

5. The file to look for is the vm or vmd file. In the above example, it's administrators.vmd. Because there is
no context path (just a / before the name of the file), its in the root of the Confluence webapp. For the
stand-alone, that's <confluence-install>/confluence folder.
6. Modify the file.
For details on how to configure the file, check the Velocity Template Overview.
Customizing the Login Page
This page gets you started on customizing the Confluence login page, to Related pages:
add your own logo or custom text. This will not customize the login process,
just what users sees when they log in. Changing
the Site
Notes: Logo
Velocity
Customizations to the Confluence login page will need to be
Template
reapplied when you upgrade Confluence. Consider this before
Overview
making drastic changes to the layout, and be sure to keep a list of
Customizin
what you have changed for your upgrade process later.
g Site and
Please test your changes on a test Confluence site first.
Space
Only administrators with access to the server where Confluence is running Layouts
can modify the Confluence login page. Changing
the Look
and Feel of
Confluenc
e
Modify
Confluenc
e Interface
Text

To change the login page:

1. Shut down your Confluence server.
2. In the Confluence installation directory, find the file confluence/login.vm.
3. Make a copy of this file as a backup.
4. Edit the file with a text editor to make the required changes. The content contains a mixture of HTML
and Velocity. See Velocity Template Overview (in our developer documentation).
5. Start Confluence and test your changes.
The same process can be applied to modify most of the templates in the Confluence web application. Be
careful to test your changes before applying them to a live site. The templates contain code that is vital for
Confluence to function, and it is easy to accidentally make a change that prevents use of your site.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 131

Modify Confluence Interface Text

All Confluence UI text is contained in a single Java properties file. This file can be modified to change the default
text, and also to translate Confluence into languages other than English.
The UI text file is ConfluenceActionSupport.properties. From your Confluence install directory:

\confluence\WEB-INF\lib\confluence-x.x.x.jar

Replace "x.x.x" with your Confluence version, for example for 4.3.2, it
will be named "confluence-4.3.2.jar".
Within this File, the relevant file to edit is
:\com\atlassian\confluence\core\ConfluenceActionSupport.properties.

Refer to Editing jar files for reference.

The file contains parameters with name=value pairs, in the format:

parameter.name=Parameter value

Parameter names are any text before the '=' character and should never be modified. Any text after the '='
character is the parameter value, which can be modified freely and can also contain variables. An example
involving variables is:

popular.labels=The three most popular labels are {0}, {1} and {2}.

For more information on replacing values, check out Translating ConfluenceActionSupport Content. Note that
plugins store their text internally, so you must modify plugin text individually.

Steps For Modification

1. Stop Confluence
2. Under your install directory, open \confluence\WEB-INF\lib\confluence-x.x.x.jar\com\atl
assian\confluence\core\ConfluenceActionSupport.properties
3. Search for the text you wish to modify, replace it and save the file in <Confluence-Install>\conflu
ence\WEB-INF\classes\com\atlassian\confluence\core. Please create this folder structure, if
it does not exist already.

If you re-bundle the JAR file, rather than re-deploy the class in the WEB-INF\classes directory,
make sure to move the backup JAR file out of the /lib directory, or the backup may be deployed
by mistake.

4. Restart Confluence

Modify Keyboard Shortcuts

Confluence provides a set of keyboard shortcuts. You could customize the shortcuts by making modifications
inside the ConfluenceActionSupport.properties file.

To disable a particular shortcut, you can simply just comment out a respective line of code. One may like
to disable the shortcut to one of the navigation links: View, Edit, Attachments, Info . For instance, to
disable shortcut to Attachmentsone would comment out the following line:

#navlink.attachments.accesskey=a

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 132

To modify an access key, one could simply just change the letter, bearing in mind the fact that the letter
must be unique.
Customizing Email Templates

Customizing the Confluence email templates is not supported. If you do decide to edit the templates
we strongly recommend you use a test instance of Confluence.
Any customizations you make to the Confluence email notification templates will need to be reapplied
after upgrading Confluence.

Email notification templates are contained within the confluence-email-notifications plugin, which is a
system app (plugin) that is installed automatically when you install Confluence.
Only administrators with access to the Confluence installation directory can modify the Confluence email
templates.
Confluence uses Soy templates (also known as Closure templates) for email notifications. You can find out more
in the Google Developer docs or see our developer tutorial which contains a short introduction to using Soy
templates.
To change the email notification templates:
1. In the Confluence web application folder, find the file /confluence/WEB-INF/atlassian-bundled-
plugins/confluence-email-notifications-plugin-x.x.jar
Note: This plugin is independently versioned, the version number will not necessarily match Confluence's
version number.
2. Copy this file to a working location and extract the jar file. Find out more about how to edit files within .jar
archives.
3. Within the jar file, templates are stored in the /templates/ folder. Edit the Soy templates to make your
changes.
4. Zip all the files and change the file extension to .jar (or refer to the guide on editing files within .jar
archives for other methods).
5. Drop the new jar file into the /confluence/WEB-INF/atlassian-bundled-plugins folder
(replacing the original file - you might want to make a copy of the original file for easy roll back) and then
restart your instance.
6. Test your changes carefully before installing the updated plugin in production.
We strongly recommend you use a test instance for editing the templates contained within the plugin. If you are
unable to enable the plugin, check the Confluence logs for information, it may be that there are problems with
your edits to the Soy templates.

RELATED TOPICS

Customizing Site and Space Layouts

Changing the Look and Feel of Confluence
Modify Confluence Interface Text
Changing the Default Behavior and Content in Confluence
Confluence comes with some handy default settings that determine what Related pages:
people see when they first enter the Confluence site, and the default content
that is put into new spaces and other areas of Confluence. Changing
the Look
Confluence administrators can change the settings to customize the and Feel of
behavior and the default content of their Confluence site: Confluenc
e

Administering Site Templates

Importing Templates
Changing the Site Title
Choosing a Default Language
Configuring the Administrator Contact Page
Configuring the Site Home Page
Customizing Default Space Content

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 133

Editing the Site Welcome Message

Administering Site Templates

A template is a predefined page that can be used as a prototype when creating new pages. Templates can be
created by users, or provided by a blueprints. See Page Templates and Blueprints.
Administrators can import templates, to make them available to other people using Confluence. See Importing
Templates.
Confluence also provides 'system templates' which contain default content for the site welcome message (see E
diting the Site Welcome Message) and default space content (see Customizing Default Space Content).
Administrators can also disable templates and blueprints, to stop them appearing in the Create and Create
Space dialogs anywhere in their Confluence site.
To disable a template or blueprint across the entire Confluence site:
Choose the cog icon

, then choose General Configuration

Choose Global Templates and Blueprints.
Choose Disable next to the template, page blueprint or space blueprint you wish to disable.
Administrators can re-enable these templates and blueprints at any time.
Importing Templates
A template is a predefined page that can be used as On this page:
a prototype when creating new pages. Templates
are useful for giving pages a common style or Step 1. Check the template
format. bundles installed on your
Confluence site
You can create your own templates within Step 2. (Optional) Download and
Confluence. See Create a Template. install additional template bundles
from the Atlassian Marketplace
In addition, you can download pre-defined templates
Step 3. Import the templates to
from the Atlassian Marketplace in the form of a
make them available to users
template bundle. Each template bundle contains one
Notes
or more templates, created by Atlassian or third
parties. Here is a summary of the steps required: Related pages:
Download the template bundle from the Pages and blogs
Atlassian Marketplace. Page Templates
Install the template bundle into your
Confluence site.
Make the templates available by importing
them into the site or into an individual space.
You need 'System Administrator' permission to
install template bundles into your Confluence site.
You need 'Confluence Administrator' permission to
manage the existing template bundles on your
Confluence site. See Global Permissions Overview.

Step 1. Check the template bundles installed on your Confluence site

To see the template bundles that are currently available for import on your Confluence site:
1. Log in to Confluence as a System Administrator or Confluence Administrator.
2. Choose the cog icon

, then choose General Configuration

3. Choose Import Templates in the left-hand panel. You will see a list of the template bundles installed
on your Confluence site, and the templates included in each bundle.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 134

Step 2. (Optional) Download and install additional template bundles from the Atlassian Marketplace

Follow the steps below if you want to add more template bundles to your site.
Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's
information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our
guidelines on add-on support.
To upload more templates:
1. Go to the Atlassian Marketplace and download the template bundle that you need. It will be in the form
of a JAR file. Save the JAR file somewhere in your file system.
2. Log in to Confluence as a System Administrator.
3. Go to

> Manage apps

4. Choose Upload app.
5. Browse to find the template bundle that you downloaded, and upload it to Confluence. The template
bundle will appear in the list under 'User-installed apps'.

Step 3. Import the templates to make them available to users

You now have one or more template bundles on your site. The templates are not available until you have
imported them.
To import a template:
1. Log in to Confluence as a System Administrator or Confluence Administrator.
2. Go to

> General Configuration > Import Templates.

You will see the template bundles installed on your Confluence site and the templates included in
each bundle.
Note: You can see a preview of the template by choosing the template name.
3. Select the templates to be imported by ticking the check boxes next to the relevant template names.
4. Choose the import destination for the templates in the Import To dropdown menu. If you want the
templates to be available to only a specific space, choose the name of the space, otherwise choose Gl
obal Templates to make the templates available to all spaces.
5. Choose Import.
Screenshot: Importing a template

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 135

Notes

Building your own template bundles. You can build a template bundle as an app (also known as a
'plugin' or 'add-on') and then upload it to your Confluence site. You can then import the templates from
your custom template bundle, as described above. You will need some programming knowledge to
develop a template bundle. See Creating A Template Bundle.
Duplicate template names. If a template with the same name already exists on import, a duplicate
template of the same name will be created. You will need to check the templates and rename them
manually.
Removing the template. Removing the app that contains a template will not remove the template
from your Confluence site if you have already imported it. You will need to remove the template
manually via the administration console or space administration screen.

Changing the Site Title

The site title appears in your browser's title bar. By default, it is set to 'Confluence'.
To change the title of your Confluence site:
1. Choose the cog icon

, then choose General Configuration

2. Choose 'General Configuration' in the left-hand panel.
3. Choose 'Edit' at the top of the 'Site Configuration' screen.
4. Enter a new title for your site in the input field next to 'Site Title'.
5. Choose 'Save'.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 136

Related pages:
Changing the Site Logo
Editing the Site Welcome Message
Customizing your Confluence Site
Confluence Administrator's Guide

Choosing a Default Language

Administrators can define a default language to be Related pages:
applied to all spaces in your Confluence site. Note
that individual users can select a language Edit Your User Settings
preference for their session. Recognized System Properties
Configuring Indexing Language
Installing a Language Pack
Setting the default language

To change the default language for the Confluence

site:
1. Choose the cog icon

, then choose General Configuration

2. Select 'Languages' in the 'Configuration'
section of the left-hand panel.
3. Choose Edit and select the language you
want to use as the default language for your
Confluence site.

Confluence comes with the following languages installed and ready to use:
eština (eská republika | Czech Republic)
Dansk (Danmark | Denmark)
Deutsch (Deutschland | Germany)
Eesti (Eesti | Estonia)
English (UK)
English (US)
Español (España | Spain)
Français (France)
Íslenska (Ísland | Iceland)
Italiano (Italia | Italy)
Magyar (Magyarország | Hungary)
Nederlands (Nederland | The Netherlands)
Norsk (Norge | Norway)
Polski (Polska | Poland)
Português (Brasil | Brazil)
Român (România | Romania)
Slovenina (Slovenská republika | Slovak Republic)
Suomi (Suomi | Finland)
Svenska (Sverige | Sweden)
( | Russia)
( | China)
( | Japan)
( | Republic of Korea)

Other settings that affect the language

Individual users can choose the language that Confluence will use to display screen text and messages.
Note that the list of supported languages depends on the language packs installed on your Confluence site.
The language used for your session will depend on the settings below, in the following order of priority from
highest to lowest:
The language preference defined in your user profile. Note that you need to be logged in for this

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 137

setting to take effect.

The language that you choose by clicking an option at the bottom of the Confluence login screen.
Confluence stores this value in a cookie. When the cookie expires, the setting will expire too.
The language set in your browser. The browser sends a header with a prioritized list of languages.
Confluence will use the first supported language in that list. Confluence administrators can disable this
option by setting the confluence.browser.language.enabled system property to false.
The default language for your site, as defined by your Confluence site administrator.

Showing User Interface Key Names for Translation

This feature is useful if you are working on creating translations of the Confluence user interface. After
opening the Confluence dashboard, you can add the following action to the end of your Confluence URL:

?i18ntranslate=on

For example http://myconfluencesite.com?i18ntranslate=on

This will cause each element of the user interface to display its special key name. This makes it easier to
find the context for each key within the user interface. You can then search for the key on http://translations.a
tlassian.com where you can enter an appropriate translation for your custom language pack.
The key names are displayed with a 'lightning bolt' graphic. Here's an example from a space sidebar:

To turn off the translation view, add the following to the end of the Confluence URL:

?i18ntranslate=off

Configuring the Administrator Contact Page

The administrator contact page is a form that allows
a user of Confluence to send a message to the On this page:
administrators of their Confluence site. (In this Customizing the Administrator
context, administrators are the members of the Contact Message
default administrators group.) Disabling the Administrator
Contact Form
See the explanation of Confluence Groups for Configuring Spam Prevention
Administrators.
Related pages:
The title of the administrator contact page is 'Contact
Site Administrators'. Typically, Confluence users Configuring Captcha for Spam
may get to this page by clicking a link on an error Prevention
screen such as the '500 error' page.

Customizing the Administrator Contact Message

You can customize the message that is presented to the user on the ' Contact Site Administrators' page.
To edit the administrator contact message:
1. Choose the cog icon

, then choose General Configuration

2. Choose General Configuration in the left-hand panel.
3. Choose Edit at the top of the 'Site Configuration' section.
4.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 138

4. Enter your text in the Custom Contact Administrators Message box. You can enter any text or Con
fluence wiki markup .
5. Choose Save.

The Default Administrator Contact Message

By default, the 'contact administrators message' looks much like the highlighted area in the screenshot
below, starting with 'Please enter information...'.
Screenshot: The default 'Contact Site Administrators' message

To restore the message to its default simply remove the custom message you entered when following the
instructions above, so that the 'Custom Contact Administrators Message' field is empty.

Disabling the Administrator Contact Form

If you prefer to disable the ability for users to send an email message to the site administrators, you can
disable the form portion of this screen. You can only disable the form if you first provide a 'Custom Contact
Administrators Message' as described above.
To enable or disable the administrator contact form:
1. Choose the cog icon

, then choose General Configuration

2. Choose General Configuration in the left-hand panel.
3. Choose Edit at the top of the 'Site Configuration' section.
4. Select on or off for the 'Contact Administrators Form'.
5. Choose Save.

Configuring Spam Prevention

You can configure Confluence to use Captcha to help prevent spam, including the spamming of Confluence
administrators. The administrator contact form is covered by the site-wide Captcha settings as documented
in Configuring Captcha for Spam Prevention.

Configuring the Site Home Page

The dashboard is the default home page for your Related pages:
site, but you can choose to use a space homepage
as the landing page for your site. Editing the Site Welcome
Message
This can be useful if most people will be reading, Changing the Site Title
rather than creating, pages in your site. However, for
sites where you want to encourage teams to Changing the Site Logo
collaborate, the dashboard provides the best tools

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 139

for resuming work in progress and keeping up with

what is happening in the site.
Users can also choose to override the site
homepage and use the dashboard or a different
page as their landing page in their personal settings.

To use a page as your site home page:

1. Go to

> General Configuration > Further Configuration.

2. Choose Edit.
3. Select a space from the Site Homepage dropdown menu.
When users log in or click the site logo, Confluence will go to the home page of the space you choose
here.
4. Choose Save.

Note about permissions

Before changing the site homepage you should check that the default 'confluence-users' or 'users'
groups have permissions to view the space the page was created in, and that the page itself is not
restricted to particular people or groups.
If your site is public, you'll also need to make sure anonymous users have permissions to view the
space, otherwise anonymous users will be directed to the dashboard instead.

Accessing the dashboard with a site homepage set

If you choose to set a page as your site homepage but would like your users to still be able to access the
Confluence dashboard, you can add a link to the Application Navigator.
To add the Confluence Dashboard to the Application Navigator:
1. Go to

> General Configuration > Application Navigator.

2. Enter the name for your link, for example, 'Dashboard'.
3. Enter the URL for your site dashboard, for example, https://yoursite.com/wiki/dashboard.
action.
4. Choose Add.
A link to the dashboard will now appear in the Application Navigator.

Customizing Default Space Content

Confluence Administrators can edit the template that is used to create the
home page for new sites. This default content appears on the home page
when a new space is created. There is a different template for site spaces,
personal spaces and space blueprints.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 140

The default content in the template only appears for new spaces (those that On this page:
are created after you have defined the content). Changes to the template do Edit the
not affect existing home pages. default
home page
Edit the default home page for a blank space for a blank
space
To edit the default (blank) space content template: Reset the
original
1. Choose the cog icon default
content
, then choose General Configuration
2. Choose Global Templates and Blueprints in the left-hand panel. Related pages:
3. Choose Edit next to 'Default Space Content' or 'Default Personal Spaces
Space Content' depending on whether you want to customize the Page
content for new site space or personal space home pages. Templates
4. Enter the content that you want to appear on the home page for new
blank spaces. you can add variables, macros and other content in the
saw way as edited a page template.
5. Choose Save.
The following variables are available to be added to the default space content templates.
$spaceKey - inserts the space key into the site space homepage
$spaceName - inserts the space name into the site space homepage
$userFullName - inserts the user (owner of the personal space) into the personal space homepage
$userEmail - inserts the email address of the user (owner of the personal space) into the personal
space homepage.
Default space templates differ from ordinary page templates in that they do not present the user with a form
to complete, so variables should be limited to those listed in the Variables menu.
Some macros, such as the Table of Contents macro, may not display correctly when you preview the
template as they are designed to work on a page. The macros will display correctly on the home page when
you create a new space. For more information on editing a template, including adding macros see - Adding
Content to a Template.

Reset the original default content

To reset the original default content:

1. Choose the cog icon

, then choose General Configuration

2. Choose Global Templates and Blueprints in the left-hand panel.
3. Choose Reset to default next to the template you wish to reset.
From this point on, all new space home pages will be created with the original default content.

Editing the Site Welcome Message

Give your site's landing page some personality by On this page:
editing the site welcome message.
Hints for using the template editor
The site welcome message appears on the right Allowing other people to edit the
hand side of the dashboard and is perfect for adding site welcome message
announcements, useful links, or a fun photo from
your last office party or team outing. Related pages:

You'll need Confluence administrator permissions to Configuring the Site Home Page
edit the site welcome message. Changing the Site Title
Changing the Site Logo
To edit the site welcome message:
Confluence administrators can either click the Edit li
nk below the site welcome message on the

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 141

dashboard, or:
1. Go to

> General Configuration > Global Templates and Blueprints.

2. Scroll down to the System templates and choose Edit next to Default Welcome Message.
3. Add your content and choose Save.
You can go back to the original welcome message at any time - choose Reset to Default next to the Default
welcome message template.

Screenshot: Default site welcome message

Hints for using the template editor

The site welcome message is a template, not a page, so you'll be using the template editor to make your
changes.
You can add text, links and macros, as you would in any confluence page, but the process for adding files,
including images is a little different.
You can't upload an image or other file into a template directly. First you'll need to upload the file to a page in
your site, then in your template, choose Insert > Files > Search on other pages to embed the file or image.

You can't use template variables in the site welcome message.

Allowing other people to edit the site welcome message

You can allow people who are not Confluence administrators to edit the site welcome message by using the
include Include Page macro to include content from elsewhere in your site, rather than adding content
directly to the template.
To include content from a page in the site welcome message:
1. Create a new page in a space that is visible to all users. It's important that all users can see content in
that space - if a person does not have permissions to view the space where you've created the page,
they won't be able to see the page content on the dashboard.
2. Add some text, images or macros, then save the page.
3. Restrict who can edit the page (this is optional, but useful if you only want to allow some people to

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 142
3.

change the content).

4. Edit the site welcome message template (as described above) and use the Include page macro to
include the contents of your newly created page.
5. Save the template.
People with permission to edit the page will now be able to make changes at any time, and their changes will
be visible on the dashboard as soon as the page is saved.

Integrating Confluence with Other Applications

You can integrate Confluence with other applications using Application Links. The Application Links feature
allows you to link Confluence to applications such as JIRA Software or JIRA Service Desk.
Linking two applications allows you to share information and access one application's functions from within the
other. For example, you can display a list of issues on a Confluence page using the Jira Issues Macro.
Related Topics
Linking to Another Application
Configuring Workbox Notifications
Integrating Jira and Confluence
Registering External Gadgets
Configuring the Office Connector

Linking to Another Application

Application Links (sometimes called "app links") is a bundled app that allows you to set up links, share
information, and provide access to certain resources or functionality across multiple Atlassian products. We
recommend using OAuth authentication for application links because of the greater security inherent with that
protocol. We no longer recommend the Trusted Applications and Basic authentication types.
Linking Confluence to other applications allows you to include information from those applications in pages or
blogs that you create in Confluence. For example, you could link Confluence to Jira Software and display issues
on a Confluence page using the Jira Issues Macro.
1. Go to

> General Configuration > Application links.

The Application Links configuration page appears and lists any links you already have set up.
2. Enter the URL of the application you want to link to, then click Create new link.
If you check The servers have the same set of users... then this link will be configured using
OAuth (with impersonation) authentication.
If you are not an admin on both servers you won't be able to set up a 2-way (reciprocal) application
link. If you want to go ahead and create a 1-way link anyway, clear the I am an administrator on
both instances checkbox.
3. Use the wizard to finish configuring the link. If the application you are linking to does not have the
Application Links plugin, you must supply additional information to set up a link with OAuth authentication.
When you complete the wizard, the Application Links plugin will create the link between your applications using
the most secure authentication method that is supported between the two applications. See the Application Links
User Guide for more information.
The new link will appear on the "Configure Application Links" page, where you can:
Edit the settings of the application link (for example, to change the authentication type of the link) using
the Edit icon.
Specify the default instance if you have multiple links to the same type of application (for example, to
multiple Jira servers) using the Make Primary link. See Making a primary link for links to the same
application type for more information.

Having trouble integrating your Atlassian products with application links?

We've developed a guide to troubleshooting application links, to help you out. Take a look at it if you
need a hand getting around any errors or roadblocks with setting up application links.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 143

Configuring Workbox Notifications

You can view and manage in-app notifications and On this page:
tasks in your Confluence workbox. In addition, you Which notifications are included?
can receive notifications from Jira applications and Configuring the polling intervals
other Confluence servers in your Confluence Including notifications from Jira
workbox. To make this possible, your Confluence Stopping Jira applications from
server must be linked to the other server(s) via appli sending notifications to
cation links. Confluence
Including notifications from
Possible configurations:
another Confluence server
Your Confluence server provides in-app Sending Confluence notifications
notifications and displays them in its own to another Confluence server
workbox. There are two sub-configurations Disabling workbox and in-app
here: notifications in Confluence
This Confluence server is the only
server involved.
Alternatively, this Confluence server
displays its own in-app notifications,
and also displays notifications from Jira
and/or other Confluence servers.
Your Confluence server does not provide or
display in-app notifications.
Your Confluence server sends in-app
notifications to another Confluence server.
Notes:
Workbox includes notifications and tasks: When you enable in-app notifications, personal tasks
are also enabled in the workbox. When you disable in-app notifications, the workbox no longer
appears and personal tasks are therefore not available on this server.

Which notifications are included?

The workbox displays a notification when someone does one of the following in Confluence:
Shares a page or blog post with you.
Mentions you in a page, blog post, comment or task.
Comments on a page or blog post that you are watching.
Likes a page or blog post that you are watching.
The workbox does not show notifications triggered because you are watching a space. Only watches on
pages and blog posts are relevant here.
The notification in your workbox appears as 'read' if you have already viewed the page or blog post.
If your Confluence site is linked to a Jira application, you will also see the following Jira notifications in your
workbox:
Comments on issues that you are watching.
Mentions.
Shares of issues, filters and searches.

Configuring the polling intervals

The polling intervals are used by the Confluence server that displays in-app notifications and tasks in its
workbox.

Option Description

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 144

Active This is the number of seconds that Confluence will wait before checking (polling) for new
polling notifications relevant to the page that the user is currently viewing. This setting applies to the
interval page open in the browser tab that currently has focus. It does not matter whether the user has
the workbox open or not.

Inactive This is the number of seconds that Confluence will wait before checking (polling) for new
polling notifications relevant to all pages that are not currently in focus. These pages may be on the
interval Confluence server that displays the workbox, or on other Confluence or Jira servers that send
their notifications to this server.
This setting defines an upper limit. For inactive pages, Confluence starts with a polling interval
equal to the active polling interval, then gradually increases the interval between polls until it
reaches the limit defined here.

Including notifications from Jira

If your Confluence site is connected to a Jira application, you can include notifications from your Jira
application, for example Jira Software or Jira Service Desk.
To include notifications from a Jira application:
Your Jira application and Confluence must be connected via an application link. See Linking to Another
Application.
1. Choose the cog icon

, then choose General Configuration

2. Choose In-app Notifications in the left-hand panel of the Confluence administration console.
3. Choose displays in-app notifications from other servers.
Your Jira application will appear in the list of linked applications below this option.
People will see Jira notifications in their workbox, as described in Workbox Notifications.
Notes:
Jira sends its notifications to the Confluence server that is configured as the primary application link.
Your Jira server must be running Jira 5.2 or later.
The following system apps must be present and enabled in Jira. The apps are shipped with Jira 5.2
and later:
'Workbox – Common Plugin'
'Workbox – Jira Provider Plugin'
You do not need to configure Jira. The system apps are enabled by default in Jira, and Jira will
automatically send notifications to Confluence.
The application link must use OAuth authentication. If you don't see your Jira application listed, you
will need to edit the application link (in both applications) to change the authentication type.
Confluence can display notifications from more than one server.
Screenshot: This Confluence server displays in-app notifications from itself and from Jira

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 145

Stopping Jira applications from sending notifications to Confluence

You may wish to configure Confluence to display its own notifications in its workbox, but prevent notifications
from Jira applications from appearing in the workbox, even when JIRA applications and Confluence are
linked via application links.
The Jira administration interface does not offer a way of disabling notifications sent to Confluence.
To stop Jira applications from sending notifications to Confluence: Disable the following plugins in Jira.
(See the Universal Plugin Manager guide to disabling plugins.)
'Workbox – Common Plugin'
'Workbox – Jira Provider Plugin'

Including notifications from another Confluence server

Confluence workbox can include notifications from another Confluence server.

Let's assume that you have two Confluence servers, ConfluenceChatty and ConfluenceQuiet. Let's also
assume that you want ConfluenceChatty to display a workbox, and to include notifications from ConfluenceQ
uiet.
To include notifications from other Confluence servers:
1. Connect ConfluenceChatty and ConfluenceQuiet via application links. In ConfluenceChatty:
Choose the cog icon

, then choose General Configuration

Choose Application Links in the left-hand panel.
Set up the link as described in Linking to Another Application.
2. Configure the notification settings in ConfluenceChatty:
Choose In-app Notifications in the left-hand panel of the Confluence administration console.
Choose displays in-app notifications from other servers.
3. Configure the notification settings in ConfluenceQuiet:
Choose In-app Notifications in the left-hand panel of the Confluence administration console.
Choose sends in-app notifications to another server.
Select the Confluence server that will display the workbox – in our example, this is Confluence
Chatty. (The entry for ConfluenceChatty will appear here only if you have already configured Co
nfluenceChatty to display in-app notifications.)

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 146

Notes:
Your Confluence servers must be running Confluence 4.3.3 or later.
Confluence can display notifications from more than one server.
Confluence can send notifications to only one server.
Only one of the linked Confluence servers can display the in-app notifications.
Screenshot: This Confluence server displays in-app notifications from itself, from Jira, and from another
Confluence server

Sending Confluence notifications to another Confluence server

You can configure Confluence to send all notifications to a different Confluence server. In this case, the
current Confluence server will not display the workbox.
To send notifications to another Confluence server: Follow the instructions in our example for Confluenc
eQuiet above.
Screenshot: This Confluence server sends its in-app notifications to another Confluence server

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 147

Disabling workbox and in-app notifications in Confluence

If you choose does not provide in-app notifications:

The Confluence workbox icon will no longer be visible and people will be unable to access their
workboxes on this server.
This Confluence server will no longer send notifications to its workbox, and will not send notifications
to any other Confluence server.

Integrating Jira and Confluence

Jira applications and Confluence complement each On this page:
other. Collect your team's thoughts, plans and
knowledge in Confluence, track your issues in your Installing Jira and Confluence
Jira application, and let the two applications work together
together to help you get your job done. Use Jira and Confluence together
Delegate user management to Jira
Learn more about what you can do with Jira and Connect Jira and Confluence with
Confluence an application link
Here's some ways you can get Jira and Confluence
working together.

Installing Jira and Confluence together

We recommend running Jira and Confluence in separate stand-alone instances behind an Apache Web
Server. The following documentation will guide you through the installation processes:
Installing Confluence
Installing Jira applications
Running Confluence behind Apache
Integrating Jira with Apache
We don't support deploying Confluence and any other application (including Jira) in the same Tomcat
container. See Can Multiple Atlassian Products Be Deployed in a Single Tomcat Container? for more
information.

Use Jira and Confluence together

This is the fun stuff. Check out Use Jira applications and Confluence together to find out about all the
integration points, great time saving features, and to check exactly which Jira application and version you'll
need.

Delegate user management to Jira

If you already have a Jira application you can choose to delegate user management to Jira, and manage all
your users in one place. You can control which Jira groups also have permissions to use Confluence. Your
license tiers for each application do not need to be the same.
See Configuring Jira Integration in the Setup Wizard to delegate user management to Jira when installing
Confluence for the first time.
See Connecting to Crowd or Jira for User Management to delegate user management to Jira for an existing
Confluence site.

Connect Jira and Confluence with an application link

See Linking to Another Application to find out how to connect Confluence to your Jira application using an
application link. This only needs to be done once.
If you delegated user management to Jira as part of Confluence's setup process, an application link to Jira
will be all set up and ready to go.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 148

Having trouble integrating your Atlassian products with application links?

We've developed a guide to troubleshooting application links, to help you out. Take a look at it if you
need a hand getting around any errors or roadblocks with setting up application links.

Registering External Gadgets

You can register gadgets from external sites (such On this page:
as Jira applications), so the gadgets appear in the m
acro browser and people can add them to Setting up a trust relationship with
Confluence pages using the gadget macro. the other application
Subscribing to all of the
There's two ways to register external gadgets: application's gadgets
Registering individual gadgets
Subscribe to all of the external
Removing access to external
application's gadgets: You can add all the
gadgets
gadgets from your Jira application, Bamboo,
FishEye or Crucible site – or from another Related pages:
Confluence site – to your Confluence gadget
directory. People can then pick and choose Configuring the Whitelist
the gadgets to add to their Confluence The big list of Atlassian gadgets
pages. Linking to Another Application
Register the external gadgets one by one:
If you cannot subscribe to an application's
gadgets, you will need to add the gadgets one
by one. This is necessary for applications and
websites that do not support gadget
subscription, and for applications where you
cannot establish a trusted relationship via
Application Links.
Both methods are described below. First, consider
whether you need to set up a trust relationship
between Confluence and the other application.

Setting up a trust relationship with the other application

In addition to registering the external gadgets, we recommend that you set up an OAuth or Trusted
Application relationship between the application that serves the gadget (the service provider) and Confluence
(the consumer). The trust relationship is required for gadgets that access restricted data from the external
web application.
See how to configure OAuth or Trusted Applications Authentication, using Application Links.
If the external web application provides anonymous access to all the data you need in the gadgets, then you
do not need a trust relationship.
For example, if your gadgets will retrieve data from Jira and your Jira server includes projects and issues that
are restricted to logged-in users, then you will need a trust relationship between Confluence and Jira. If you
do not set up the trust relationship, then the gadgets will show only the information that Jira makes visible to
anonymous users.

Subscribing to all of the application's gadgets

You can add all the gadgets from your Jira, Bamboo, FishEye or Crucible site – or from another Confluence
site – to your Confluence gadget directory. People can then pick and choose the gadgets to add to their
Confluence pages.
To subscribe to another site's gadgets:
1. Go to

> General Configuration > External Gadgets

2.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 149

2. Choose the Gadget Feeds tab.

3. Enter the base URL of the application you want to subscribe to, for example, http://example.com
/jira or http://example.com/confluence.
4. Choose Add. Confluence will convert the URL to a gadget feed and place it in the list of 'Added
Gadget Feeds'.

Screenshot: Subscribing to a gadget feed

Registering individual gadgets

If you cannot subscribe to an application's gadgets, you will need to register the gadgets one by one. This is
necessary for applications and websites that do not support gadget subscription, and for applications where
you cannot establish a trusted relationship via Application Links.
First you will need to get the gadget URL and copy it to your clipboard.

Getting a gadget's URL from an Atlassian application

If your application is another Atlassian application:

A gadget's URL points to the gadget's XML specification file. In general, a gadget's URL looks something like
this:

http://example.com/my-gadget-location/my-gadget.xml

If the gadget is supplied by a plugin, the URL will have this format:
http://my-app.my-server.com:port/rest/gadgets/1.0/g/my-plugin.key:my-gadget/my-p
ath/my-gadget.xml
For example:
http://mycompany.com/jira/rest/gadgets/1.0/g/com.atlassian.streams.streams-jira-
plugin:activitystream-gadget/gadgets/activitystream-gadget.xml
To find a gadget's URL in JIRA:
Go to your dashboard by clicking the Dashboards link at the top left of the screen.
Click Add Gadget to see the list of gadgets in the directory.
Find the gadget you want, using one or more of the following tools:
Use the scroll bar on the right to move up and down the list of gadgets.
Select a category in the left-hand panel to display only gadgets in that category.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 150

Start typing a key word for your gadget in the Search textbox. The list of gadgets will change as
you type, showing only gadgets that match your search term.
Right-click the Gadget URL link for that gadget and copy the gadget's URL into your clipboard.
To find a gadget's URL in Confluence:
Choose Help > Confluence Gadgets to see the list of available Confluence gadgets.
Find the gadget you want.
Right-click the Gadget URL link for that gadget and copy the gadget's URL into your clipboard.

Getting a gadget's URL from another application

If the gadget comes from a non-Atlassian web application or web site, please consult the relevant
documentation for that application to get the gadget URL.

Registering the gadget for use in Confluence

Now that you have the gadget's URL, you can register it in Confluence, so that people can add it to their
pages. You need system administrator permissions to register a gadget.
To register the gadget in Confluence:
1. Go to

> General Configuration > External Gadgets

2. Paste your gadget's URL into the Gadget Specification URL field in the 'Add a new Gadget' section.
3. Choose Add. Your gadget will be shown in the list of registered gadgets below and it will also become
available in the macro browser.
Screenshot: Registering external gadgets one by one

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 151

Removing access to external gadgets

To remove a single gadget from Confluence, click the Delete button next to the gadget URL.
If you have subscribed to an application's gadgets, you will need to remove the entire subscription. You
cannot unregister a single gadget. Click the Delete button next to the gadget feed URL.
The gadget(s) will no longer be available in the macro browser, and people will not be able to add them using
the Gadget macro. Any pages that already use the gadget will show a broken gadget link.

Configuring the Office Connector

The Office Connector allows Confluence users to On this page:
view and import content from Microsoft Office and
Open Office files attached to a page. Enabling and disabling the Office
Connector
The Office Connector system app is bundled with Configuring the Office Connector
Confluence, but a System Administrator can enable options
or disable parts of the Office Connector and can
configure options. Related pages:
Office Connector Prerequisites
Office Connector Limitations and
Enabling and disabling the Office Connector Known Issues

If you want to limit access to all or part of the Office

Connector you can disable the system app, or some
modules in the app.
To enable or disable the Office Connector modules:
1. Go to

> Manage apps

2. Choose System from the filter drop down and then search for Office Connector
3. Expand the Office Connector listing. From here you can:
Choose Configure to specify preferences for the Office Connector (this opens the configuration
screen described below)
Click Disable to disable all modules of the app
Expand the modules list to enable or disable selected Office Connector modules.
Note: only some Office Connector modules can be disabled. Modules that are integral to the operation of the
Office Connector cannot be disabled, and do not have an Enable or Disable button. Modules that can be
disabled include the button and provide a brief description of the module.

Configuring the Office Connector options

Users with System Administrator permissions can change the behavior of the Office Connector.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 152

To set the configuration options for the Office Connector:

1. Go to

> General Configuration > Office Connector

2. Set the configuration options as described in the table below.

Option Default Description

Value

Warnings: Disabled If this option is enabled, the user will receive a warning when importing a Word document.
Show a user when they are about to overwrite existing content.
warning
before
allowing a
user to
perform an
import

Advanced Disabled Note: This feature requires a third party app.

Formatting
Options: Use If this option is enabled, a Confluence page created from an imported Word document will u
the footnote from Adaptavist to render any footnotes contained in the document. Note that you will need
macro for Formatting for Confluence app from Adaptavist to get this macro.
Word
footnotes

Allow Disabled If this option is enabled, the Office Connector will use authentication tokens in the URL.
authentication
tokens in the This needs to be enabled to edit Office 2013 documents.
URL path

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 153

Temporary The The {viewfile} macro will cache data temporarily. This option allows you to set the location o
storage for Confluence settings are:
viewfile Home
macro directory. Confluence home directory – The temporary file will be stored in your Confluence Ho
A directory specified in the directories.properties file – You can specify a lo
Office Connector's directories.properties file:
1. Locate the OfficeConnector-x.xx.jar file (where x.xx is the version number)
Home directory and copy it to a temporary location
2. Unzip the JAR file and find the resources/directories.properties file. The
like this:

#Complete the following line to set a custom cache direc

#If resetting to blank, don't delete anything before or
the '='
com.benryan.confluence.word.edit.cacheDir=

3. Edit the last line, adding the path to your required temporary location directly after th
example:
On Windows:

com.benryan.confluence.word.edit.cacheDir=c:\my\path\

On Linux:

com.benryan.confluence.word.edit.cacheDir=/home/myuse

4. Save the file, recreate the JAR and put it back in your Confluence Home directory, o
JAR.

Maximum file 500 This is the maximum size of the cache used by the {viewfile} macro. (See above.)
space for
cache (MB)

Number of 6 This is the maximum number of threads used to convert PowerPoint, Excel files or PDF slid
Conversion this setting to manage Confluence performance, by limiting the number of threads so that th
Queues does not consume too many resources.
Click Manage Queues to view attachments that are still pending conversion.

Managing your Confluence License

Your license entitles you to run Confluence and be
eligible for support and upgrades for a specified
period. It also defines the number of users who are
entitled to use Confluence.
To quickly check the status of your license you can
go to

> General Configuration > Troubleshooting and

support tools.
You'll need need Confluence Administrator or
System Administrator permissions to view and edit
your license.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 154

Viewing your license details On this page:

To view your Confluence license: Viewing your license details

Updating your license
1. Go to Understanding the user count for
your license
> General Configuration. Exceeding your licensed user
2. Choose License Details in the left-hand count
panel. Reducing your user count
Downgrading your license
The License Details page tells you: Finding your Support Entitlement
Number (SEN)

Related pages:
Upgrading Beyond Current
Licensed Period
Confluence installation and
upgrade guide
Confluence administrator's guide

The type of license (for example: Commercial, Academic, Community, or Evaluation).

Number of users you are licensed for, and how many are currently in use.
Your license expiry date, for support and upgrade eligibility.
Your server ID which is generated when you install Confluence for the first time and remains the same
for the life of the installation (including after upgrades or changes to your license).
Your support entitlement number (SEN).

Updating your license

If you change your license (for example to a license with more users), or migrate from Confluence Cloud and
you will need to update your license.
To update your Confluence license:
1. Go to

> General Configuration > License Details

2. Enter your new license in the License field.
3. Choose Save.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 155

If you're using Data Center, you may need to apply the license to each node individually, if it does not
automatically propagate to all nodes.

Understanding the user count for your license

The number of registered users allowed on your Confluence site may be limited, depending on your license
type.
The License Details page will indicate the number of users currently signed up (your registered user count).
It:
includes only users who have the 'can use' global permissions for the Confluence site.
does not include anonymous users, who may access your Confluence site if you have allowed
anonymous access.
does not include deactivated users.

Exceeding your licensed user count

If you exceed the number of users included in your license, your Confluence instance will become read-only,
that means no users will be able to create or edit content until you reduce the number of users.

Reducing your user count

You can reduce your user count by removing or deactivating users who do not require access to
Confluence. See Delete or Disable Users.
If you have connected Confluence to an LDAP directory, you may want configure Confluence to only
synchronize a subset of users from LDAP rather than all users. See How to change the number of users
synchronized from LDAP to Confluence in the Knowledge Base. This can be a complicated process and we
recommend that you only use this method if necessary.

Downgrading your license

If you decide to downgrade your Confluence license to pay for fewer users you need to ensure that the
number of users currently signed up (as shown on the License Details page) is lower that the number
allowed by your new license before your apply the new license.
If you have more users than your new license allows you will need to reduce your user count before applying

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 156

the new license.

Finding your Support Entitlement Number (SEN)

You can find your Support Entitlement Number (SEN) in three places:
In Confluence - go to

> General Configuration > License Details)

At my.atlassian.com
On your Atlassian invoice.
See How to find your Support Entitlement Number (SEN) for more general information about how Atlassian
Support uses this number.

Managing Confluence Data

This page is an overview of recommended techniques for managing the Related pages:
data on your Confluence site. This is of interest to Confluence
administrators – people with System Administrator or Confluence Managing
Administrator permissions. System
and
Database Configuration Marketplac
Site Backup and Restore e Apps
Attachment Storage Configuration Integrating
Confluence Data Model Confluenc
Finding Unused Spaces e with
Data Import and Export Other
Import a Text File Application
Audit log s
Getting
Started as
Confluenc
e
Administra
tor
Confluenc
e
administrat
or's guide

Database Configuration
This document provides information on connecting On this page:
Confluence to an external database. Choosing an external database
About the embedded H2
database
Choosing an external database Database setup
Database drivers
Note: Take time to choose your database wisely.
Database connection methods
The XML backup built into Confluence is not suited
Database troubleshooting
for migration or backup of large data sets. If you
need to migrate later, you may need to use a third Related pages:
party database migration tool.
Database JDBC Drivers
Below is more information on selecting and Supported Platforms
migrating to an external database: Embedded H2 Database
Managing Confluence Data
Migrating to a Different Database
Supported Databases
Database Troubleshooting

About the embedded H2 database

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 157

Your Confluence installation includes an embedded H2 database, to enable you to try Confluence without
setting up an external database. The embedded H2 database is only supported while you are evaluating
Confluence. You must migrate to a supported external database before using Confluence as a production
system.
To find out if you are still using the embedded database, go to

> General Configuration > Troubleshooting and support tools.

Database setup

To find out how to set up your database, see:

Database Setup for Oracle
Database Setup For MySQL
Database Setup for PostgreSQL
Database Setup for SQL Server

Database drivers

You must use a supported database driver. See Database JDBC Drivers for the drivers we support.
If you attempt to use an unsupported or custom JDBC driver (or a driverClassName from an unsupported
or custom driver in your JINDI datasource connection) collaborative editing will fail.

Database connection methods

You can connect Confluence to your database using a JDBC URL or a JNDI datasource.
By default the setup wizard only provides the option to use a JDBC connection, as this is the recommended
connection method.
If you want to use a JNDI datasource, see Configuring a datasource connection for the steps you'll need to
take before you set up Confluence, as the setup wizard will only provide the option to use a datasource if it
detects a datasource in your Tomcat configuration.

Database troubleshooting

For database-related problems see Database Troubleshooting.

If you need more help, check out Troubleshooting Problems and Requesting Technical Support.

Database JDBC Drivers

This page provides the download links for the JDBC drivers for all supported
databases.
Due to licensing constraints, we are not able to bundle MySQL or Oracle
database drivers with Confluence, so you will need to manually download
and install the driver listed below before you can set up Confluence.
If you use PostgreSQL or Microsoft SQL Server, the drivers are bundled
with Confluence, so you're ready to.

Adding your database driver (MySQL and Oracle)

The Confluence setup wizard will stop you at the Database configuration
step if it can't find an appropriate driver for the database you select.
To make your database driver available to Confluence:
1. Stop Confluence.
2. Download and extract the appropriate driver from the list below.

3.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 158

3. Drop the .jar file in your <installation-directory>/confluen On this page:

ce/WEB-INF/lib directory.
Adding
4. Restart Confluence then go to http://localhost:<port> in your
your
browser to continue the setup process.
database
The setup wizard will return to the database configuration step, and you're driver
back on your way. (MySQL
and
Oracle)
Supported drivers
Supported
drivers

Related pages:
Database
Configurati
on
Supported
Platforms

Database Driver JDBC Notes More

bundled? drivers information

PostgreSQL 9.4-1202 We recommend that you use the bundled Database

JDBC 41 JDBC 4 driver. Setup for
driver PostgreSQL
download If you want to use a later driver, you can
download it from the PostgreSQL website. The
JDBC 41 driver will work under the 1.8 JVM.

Microsoft Microsoft We recommend that you use the bundled Type Database
SQL Server JDBC Driver 4 JDBC driver. setup for
for SQL Microsoft
Server If you decide to use a later version, we may SQL Server
download not be able to provide support for any
problems you encounter.

jTDS 1.3.1 This driver is deprecated. New Confluence

driver installations use the Microsoft JDBC Driver for
download SQL Server (above).
If you're upgrading an existing Confluence site
to Confluence 6.4 you should continue to use
the bundled jTDS driver. We'll help you
migrate to the Microsoft driver in a later
release.

MySQL Connector\J Due to licensing constraints, MySQL drivers Database

5.1 driver are not bundled with Confluence. setup for
download MySQL
Confluence is currently tested with the 5.1.42 d
river.
The latest driver (8.x) is not currently
supported.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 159

Oracle JDBC driver Due to licensing constraints, Oracle drivers are Database
downloads not bundled with Confluence. setup for
Oracle
For Oracle 12c (R1 and R2) use the 12.2.0.x
driver (ojdbc8.jar)
We recommend using the thin drivers only.
See the Oracle JDBC driver FAQ.

If you attempt to use an unsupported or custom JDBC driver (or a driverClassName from an unsupported
or custom driver in your JINDI datasource connection) collaborative editing will fail. You must use a
supported driver.

Database Setup for Oracle

This page provides instructions for configuring On this page:
Confluence to use an Oracle database. Before you start
1. Install Oracle
Before you start
2. Create database user
3. Install Confluence
See Supported Platforms to check your 4. Download and install the Oracle
version of Oracle is supported. You may need thin driver
to upgrade your database before installing 5. Enter your database details
Confluence. 6. Test your database connection
If you're switching from another database, Troubleshooting
including the embedded evaluation database, Related pages:
read Migrating to Another Database before
you begin. Database Configuration
Known Issues for Oracle
You'll need an experienced Oracle database Confluence installation and
administrator (DBA) to set up and maintain upgrade guide
your database.
Our support team can assist with
Confluence problems, but are unable to help
you administer your Oracle database.
If you don't have access to an experienced
Oracle DBA, consider using a different supp
orted database.

1. Install Oracle

If you don't already have an operational Oracle server, download and install it now. See the Oracle
documentation for instructions.
When setting up your Oracle server:
Character encoding must be set to AL32UTF8 (this the Oracle equivalent of Unicode UTF-8).

2. Create database user

To create the user and assign its privileges:

1. Use the sqlplus command to access Oracle via the command line

sqlplus user/password <as sysdba|as sysoper>

If you're logging in with the user 'sys' you'll need to include the "as sysdba" or "as sysoper" to

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 160

determine which sys role you want to use.

2. Create a Confluence user (for example confluenceuser), and grant the following only to that user:

create user <user> identified by <password> default tablespace

<tablespace_name> quota unlimited on <tablespace_name>;
grant connect to <user>;
grant resource to <user>;
grant create table to <user>;
grant create sequence to <user>;
grant create trigger to <user>;

It is very important that the user is granted the exact privileges indicated above. Confluence
requires only these privileges so you should grant specific privileges to the user. create table, cr
eate sequence, and create trigger shouldn't be assigned as part of a role.
Do not grant the user the select any table permission. That permission can cause
problems with other schemas.
When you create a user, specify the tablespace for the table objects as shown above.

3. Install Confluence

Check out the Confluence Installation Guide for step-by-step instructions on how to install Confluence on
your operating system.

4. Download and install the Oracle thin driver

Due to licensing restrictions, we're not able to bundle an Oracle driver with Confluence. To make your
database driver available to Confluence:
1. Stop Confluence.
2. Head to Database JDBC Drivers and download the appropriate driver. The driver file will be called
something like ojdbc8.jar
3. Drop the .jar file in your <installation-directory>/confluence/WEB-INF/lib directory.
4. Restart Confluence then go to http://localhost:<port> in your browser to continue the setup
process.

5. Enter your database details

The Confluence setup wizard will guide you through the process of connecting Confluence to your database.

Use a JDBC connection (default)

JDBC is the recommended method for connecting to your database.

The Confluence setup wizard will provide you with two setup options:
Simple - this is the most straightforward way to connect to your database.
By connection string - use this option if you want to specify additional parameters and are
comfortable constructing a database URL.
Depending on the setup type, you'll be prompted for the following information.

Setup type Field Description

Simple Hostname This is the hostname or IP address of your database server.

Simple Port This is the Oracle port. If you didn't change the port when you installed
Oracle, it will default to 1521.

Simple Service This is the service name (of your confluence database.
name

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 161

By Database The database URL is entered in this format:

connection URL jdbc:oracle:thin:@//<HOST>:<PORT>/<SERVICE>
string
<SERVICE> can be either the SID or Service Name. For example: jdbc:o
racle:thin:@//localhost:1521/confluence
By default, we use the new style URL provided by the thin driver. You can
also use the tnsnames style.

Both Username This is the username of your dedicated database user. In the example
above, this is confluenceuser.

Both Password This is the password for your dedicated database user.

Not sure how to find your hostname, port and SID?

To determine the host, port, service name, and/or SID, execute the following command as the user
running Oracle (usually 'Oracle'):

lsnrctl status

Here's an example of the output:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 162

SNRCTL for Linux: Version 11.2.0.2.0 - Beta on 29-JUN-2012 15:20:59

Copyright (c) 1991, 2010, Oracle. All rights reserved.
Connecting to
(DESCRIPTION=(ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC_FOR_XE)))
STATUS of the LISTENER
------------------------
Alias LISTENER
Version TNSLSNR for Linux: Version 11.2.0.2.0 -
Beta
Start Date 06-JUN-2012 08:36:34
Uptime 23 days 6 hr. 44 min. 25 sec
Trace Level off
Security ON: Local OS Authentication
SNMP OFF
Default Service XE
Listener Parameter File
/u01/app/oracle/product/11.2.0/xe/network/admin/listener.ora
Listener Log File
/u01/app/oracle/diag/tnslsnr/<HOSTNAME>/listener/alert/log.xml
Listening Endpoints Summary...
(DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC_FOR_XE)))

(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=<HOSTNAME>)(PORT=1521)))

(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=<HOSTNAME>)(PORT=8080))(P
resentation=HTTP)(Session=RAW))
Services Summary...
Service "PLSExtProc" has 1 instance(s).
Instance "PLSExtProc", status UNKNOWN, has 1 handler(s) for this
service...
Service "XE" has 1 instance(s).
Instance "XE", status READY, has 1 handler(s) for this service...
Service "XEXDB" has 1 instance(s).
Instance "XE", status READY, has 1 handler(s) for this service...
The command completed successfully

The host and port are determined by the line containing PROTOCOL=tcp (the line without Presen
tation=HTTP).
Under Services Summary, each service which has an instance with READY status is a
connectable service. The name following Service is a service name for connecting to the
database name following Instance on the next line.
The SID is the name of the database instance, as defined by the $ORACLE_SID variable when you
have sourced the Oracle environment to your shell.
For example, if you are running Confluence on the same server as the Oracle database, with the above l
snrctl status output, you would use one of the following URLs:

jdbc:oracle:thin:@//localhost:1521/XE
jdbc:oracle:thin:@localhost:1521:XE

The URL can be used in either a direct JDBC connection or a datasource.

See the Oracle JDBC FAQ for more information on Oracle JDBC URLs.

Use a JNDI datasource

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 163

If you want to use a JNDI datasource, see Configuring a datasource connection for the steps you'll need to
take before you set up Confluence, as the setup wizard will only provide the option to use a datasource if it
detects a datasource in your Tomcat configuration.

6. Test your database connection

In the database setup screen, hit the Test connection button to check:
that Confluence can connect to your database server
that the database character encoding is correct
that your database user has appropriate permissions for the database
that your database user has NOT been granted the SELECT ANY TABLE privilege
Once the test is successful, hit Next to continue with the Confluence setup process.

Troubleshooting

If Confluence complains that it is missing a class file, you may have placed the JDBC driver in the
wrong folder.
The following page contains common issues encountered when setting up your Oracle database to
work with Confluence: Known Issues for Oracle.

Configuring an Oracle Datasource in Apache Tomcat

Error rendering macro 'viewport-redirect' : null

Database Setup for PostgreSQL

This page provides instructions for configuring Confluence to use a On this page:
PostgreSQL database.
Before you
start
Before you start 1. Install
PostgreSQ
See Supported Platforms to check your version of PostgreSQL is L
supported. You may need to upgrade your database before installing 2. Create a
Confluence. database
If you're switching from another database, including the embedded user and
evaluation database, read Migrating to Another Database before you database
begin. 3. Install
Confluenc
e
4. Enter
your
database
details
5. Test
your
database
connection
Troublesho
oting
Related pages:
Database
Configurati
on
Known
issues for
PostgreSQ
L

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 164

1. Install PostgreSQL

If you don't already have PostgreSQL installed, download and install it now.
A few tips when installing PostgreSQL:
The password you provide during the installation process is for the 'postgres' account, which is the
database root-level account (the super user). Remember this username and password as you'll need it
each time you log in to the database.
The default port for PostgreSQL is 5432. If you decide to change the default port, make sure it does
not conflict with any other services running on that port.
Choose the locale that best matches your geographic location.
Don't launch Stack Builder at the completion of the installer.

2. Create a database user and database

Once you've installed PostgreSQL:

1. Create a database user, for example confluenceuser.
Your new user must be able to create database objects and must have can login permission.

2. Next, create a database (for example confluence):

Owner is your new database user (for example confluenceuser)
Character encoding must be set to utf8 encoding.
Collation must also be set to utf8. Other collations, such as "C", are known to cause issues
with Confluence.
You can use pgAdmin as an alternative to the command line to complete this step.

3. Install Confluence

Check out the Confluence Installation Guide for step-by-step instructions on how to install Confluence on
your operating system.

4. Enter your database details

The Confluence setup wizard will guide you through the process of connecting Confluence to your database.
Be sure to select "My own database".

Use a JDBC connection (default)

JDBC is the recommended method for connecting to your database.

The Confluence setup wizard will provide you with two setup options:
Simple - this is the most straightforward way to connect to your database.
By connection string - use this option if you want to specify additional parameters and are
comfortable constructing a database URL.
Depending on the setup type, you'll be prompted for the following information.

Setup type Field Description

Simple Hostname This is the hostname or IP address of your database server.

Simple Port This is the PostgreSQL port. If you didn't change the port when you
installed Postgres, it will default to 5432.

Simple Database This is the name of your confluence database. In the example above, this
name is confluence

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 165

By Database The database URL is entered in this format:

connection URL
jdbc:postgresql://<server>:<port>/<database>
string
For example:
jdbc:postgresql://localhost:5432/confluence

If you need to connect to an SSL database, add the ssl=true parameter

in the database URL. For example:
jdbc:postgresql://localhost:5432/confluence?ssl=true

Both Username This is the username of your dedicated database user. In the example
above, this is confluenceuser.

Both Password This is the password for your dedicated database user.

Use a JNDI datasource

If you want to use a JNDI datasource, see Configuring a datasource connection for the steps you'll need to
take before you set up Confluence, as the setup wizard will only provide the option to use a datasource if it
detects a datasource in your Tomcat configuration.

5. Test your database connection

In the database setup screen, hit the Test connection button to check:
that Confluence can connect to your database server
that the database character encoding is correct
that your database user has appropriate permissions for the database
Once the test is successful, hit Next to continue with the Confluence setup process.
If Confluence and PostgreSQL are hosted on different servers, see the PostgreSQL documentation on how
to set up pg_hba.conf to make sure Confluence and PostgreSQL can communicate remotely.

Troubleshooting

If Confluence complains that it is missing a class file, you may have placed the JDBC driver in the
wrong folder.
If you're unable to connect to the database from Confluence and they are on different machines, most
likely you have a firewall in between the two machines or your pg_hba.conf file is misconfigured.
Verify that your firewall is set to allow connections through 5432 or double check your hba
configuration.
The following page contains common issues encountered when setting up your PostgreSQL database
to work with Confluence: Known issues for PostgreSQL.

Configuring a PostgreSQL Datasource in Apache Tomcat

Error rendering macro 'viewport-redirect' : null

Database Setup for SQL Server

This page provides instructions for configuring
Confluence to use a Microsoft SQL Server database.

Before you start

Check the following before you start:

See Supported Platforms to check your
version of SQL Server is supported. You may
need to upgrade your database before
installing Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 166

If you're switching from another database, On this page:

including the embedded evaluation database,
read Migrating to Another Database before Before you start
you begin. 1. Install SQL Server
2. Create a database and
database user
3. Install Confluence
4. Enter your database details
5. Test your database connection
Database driver changes
Troubleshooting
Related pages:
Database Configuration
Known issues for SQL Server
Confluence installation and
upgrade guide

1. Install SQL Server

If you don't already have Microsoft SQL Server installed, download and install it now. See Installation for SQL
Server on MSDN for step-by-step instructions.
Note about authentication modes...
SQL Server allows two types of authentication: SQL Server Authentication and Windows Authentication.
To make sure Confluence will be able to connect to your database you'll need to set your SQL server to
allow Mixed Authentication (both SQL Server and Windows modes). This setup is generally found under
Properties > Security > Server Authentication.

2. Create a database and database user

Once you've installed SQL Server, create a database user and database for Confluence as follows:
1. Using your SQL administrator permissions, create a new database (for example confluence)
2. Set the default collation for the database to SQL_Latin1_General_CP1_CS_AS (case sensitive).

ALTER DATABASE <database-name> COLLATE

SQL_Latin1_General_CP1_CS_AS

If you see a 'database could not be exclusively locked to perform the operation' error, you may need to
prevent other connections by setting the mode to single user for the transaction

ALTER DATABASE <database-name> SET SINGLE_USER WITH ROLLBACK

IMMEDIATE;
<your ALTER DATABASE query>
ALTER DATABASE <database-name> SET MULTI_USER;

3. Check the database isolation level of READ_COMMITTED_SNAPSHOT is ON.

SELECT is_read_committed_snapshot_on FROM

sys.databases WHERE name= 'database-name'

If this query returns 1, then READ_COMMITTED_SNAPSHOT is ON, and you're good to go.

If this query returns 0, READ_COMMITTED_SNAPSHOT option is OFF and you will need to turn it on

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 167

as follows:

ALTER DATABASE <database-name>

SET READ_COMMITTED_SNAPSHOT ON
WITH ROLLBACK IMMEDIATE;

4. Using your SQL administrator permissions, create a new SQL user account for Confluence (for
example, confluenceuser).
5. Give this user full create, read and write permissions for the database tables. Confluence must be able
to create its own schema. Refer to the SQL Server documentation for how to do this.

3. Install Confluence

Check out the Confluence Installation Guide for step-by-step instructions on how to install Confluence on
your operating system.

4. Enter your database details

The Confluence setup wizard will guide you through the process of connecting Confluence to your database.

Use a JDBC connection (default)

JDBC is the recommended method for connecting to your database.

The Confluence setup wizard will provide you with two setup options:
Simple - this is the most straightforward way to connect to your database.
By connection string - use this option if you want to specify additional parameters and are
comfortable constructing a database URL.
Depending on the setup type, you'll be prompted for the following information.

Setup Field Description

type

Simple Hostname This is the hostname or IP address of your database server.

Simple Port This is the SQL Server port. If you didn't change the port when you installed
SQL Server, it will default to 1433.

Simple Database This is the name of your confluence database. In the example above, this is c
name onfluence

Simple Instance To find out your instance name, connect to your database and run one of the
name following:

select @@SERVICENAME;

SELECT SERVERPROPERTY('InstanceName');

If you have a default named instance setup in SQL Server, you won't need to
specify this parameter.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 168

By Database The database URL is entered in this format:

connection URL jdbc:sqlserver://<hostname>:<port>;databaseName=<database>
string
For example:
jdbc:sqlserver://yourserver:1433;databaseName=confluence

Both Username This is the username of your dedicated database user. In the example above,
this is confluenceuser.

Both Password This is the password for your dedicated database user.

Use a JNDI datasource

If you want to use a JNDI datasource, see Configuring a datasource connection for the steps you'll need to
take before you set up Confluence, as the setup wizard will only provide the option to use a datasource if it
detects a datasource in your Tomcat configuration.

5. Test your database connection

In the database setup screen, hit the Test connection button to check:
Confluence can connect to your database server
the database collation and isolation level is correct
your database user has appropriate permissions for the database
Once the test is successful, hit Next to continue with the Confluence setup process.

Database driver changes

In Confluence 6.6 we replaced the open source jTDS driver for Microsoft SQL Server with the official
Microsoft JDBC Driver for SQL Server. You will be automatically migrated to the new driver when you
upgrade to 6.6 or later.
If for some reason the automatic migration fails (for example, if you're using a datasource connection), you'll
need to make this change manually. See Migrate from the jTDS driver to the supported Microsoft SQL Server
driver in Confluence 6.4 or later.

Troubleshooting

If you get the following error message, check you've given the confluenceuser user all the
required database permissions when connecting from localhost.

Could not successfully test your database: : Server connection

failure during transaction. Due to underlying exception:
'java.sql.SQLException: Access denied for user
'confluenceuser'@'localhost' (using password: YES)'

You may need to open additional ports. See this Microsoft KB about the ports required for SQL
Server.
The following page contains common issues encountered when setting up your SQL Server database
to work with Confluence: Known Issues for SQL Server.

Configuring a SQL Server Datasource in Apache Tomcat

Error rendering macro 'viewport-redirect' : null

Database Setup For MySQL

This page provides instructions for configuring
Confluence to use a MySQL database.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 169

Before you start On this page:

Before you start
See Supported Platforms to check your 1. Install MySQL Server
version of MySQL is supported. You may 2. Configure MySQL Server
need to upgrade your database before 3. Create database and database
installing Confluence. user
If you're switching from another database, 4. Install Confluence
including the embedded evaluation database, 5. Download and install the
read Migrating to Another Database before MySQL driver
you begin. 6. Enter your database details
Use a JDBC connection
(default)
Confluence will not work on MySQL variants
Use a JNDI datasource
such as MariaDB (CONFSERVER-29060)
7. Test your database connection
and Percona Server (CONFSERVER-36471
Troubleshooting
)
Related pages:
Database Configuration
Database Troubleshooting for
MySQL
Confluence installation and
upgrade guide

1. Install MySQL Server

If you don't already have MySQL installed, download and install it now. See the MySQL documentation for
step-by-step instructions.

2. Configure MySQL Server

In this step, you will configure your MySQL database server.

Note: If you intend to connect Confluence to an existing MySQL database server, we strongly recommend
that you reconfigure this database server by running through the configuration steps in the MySQL
installation wizard as described below .
To configure MySQL Server:
1. Run the MySQL installation wizard:
a. If you are connecting Confluence to your existing MySQL server, choose Reconfigure
Instance.
b. Choose Advanced Configuration.
c. Choose the type of MySQL Server that best suits your hardware requirements. This will affect
the MySQL Server's usage of memory, disk and CPU resources. Refer to the MySQL
documentation for further information.
d. Choose Transactional Database Only to ensure that your MySQL database will use InnoDB a
s its default storage engine.
You must use the InnoDB storage engine with Confluence. Using the MyISAM storage engine c
an lead to data corruption in Confluence.
e. Set the InnoDB Tablespace settings to your requirements. (The default settings are
acceptable.)
f. Set the approximate number of concurrent connections permitted to suit your Confluence
usage requirements. You can use one of the presets or enter a number manually. Refer to the
MySQL documentation for further information.
g. For the networking options, ensure the Enable TCP/IP Networking and Enable Strict Mode
options are selected (default). Refer to the MySQL documentation on setting the networking an
d server SQL modes for further information.
h. For the MySQL server's default character set, choose Best Support For Multilingualism (in
other words, UTF-8). This will ensure Confluence's support for internationalization. For more
information, see Configuring Database Character Encoding.
i. For the Windows configuration option, choose whether or not to install the MySQL Server as a

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 170
i.
Windows service. If your hardware is going to be used as a dedicated MySQL Server, you may
wish to choose the options to Install As Windows Service (and Launch the MySQL Server
automatically). Refer to the MySQL documentation for further information.
Note: If you choose not to install the MySQL Server as a Windows Service, you will need to
ensure that the database service has been started before running Confluence.
j. Select Modify Security Settings to enter and set your MySQL Server (root) access password.
2. Edit the my.cnf file (my.ini on Windows operating systems) in your MySQL server. Locate the [my
sqld]section in the file, and add or modify the following parameters:
(Refer to MySQL Option Files for detailed instructions on editing my.cnf and my.ini.)
Locate the [mysqld]section in the file, and add or modify the following parameters:
Specify the default character set to be UTF-8:

[mysqld]
...
character-set-server=utf8
collation-server=utf8_bin
...

Set the default storage engine to InnoDB:

[mysqld]
...
default-storage-engine=INNODB
...

Specify the value of max_allowed_packet to be at least 256M:

[mysqld]
...
max_allowed_packet=256M
...

Specify the value of innodb_log_file_size to be at least 2GB:

[mysqld]
...
innodb_log_file_size=2GB
...

Ensure the sql_mode parameter does not specify NO_AUTO_VALUE_ON_ZERO

// remove this if it exists

sql_mode = NO_AUTO_VALUE_ON_ZERO

Ensure that the global transaction isolation level of your Database had been set
to READ-COMMITTED.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 171

[mysqld]
...
transaction-isolation=READ-COMMITTED
...

Check that the binary logging format is configured to use 'row-based' binary logging.

[mysqld]
...
binlog_format=row
...

3. Restart your MySQL server for the changes to take effect:

On Windows, use the Windows Services manager to restart the service.
On Linux:
Run one of the following commands, depending on your setup: '/etc/init.d/mysqld
stop' or '/etc/init.d/mysql stop' or 'service mysqld stop'.
Then run the same command again, replacing 'stop' with 'start'.
On Mac OS X, run 'sudo /Library/StartupItems/MySQLCOM/MySQLCOM restart'.

3. Create database and database user

Once you've installed and configured MySQL, create a database user and database for Confluence as
follows:
1. Run the 'mysql' command as a MySQL super user. The default user is 'root' with a blank password.
2. Create an empty Confluence database schema (for example confluence):

CREATE DATABASE <database-name> CHARACTER SET utf8 COLLATE

utf8_bin;

3. Create a Confluence database user (for example confluenceuser):

GRANT ALL PRIVILEGES ON <database-name>.* TO

'<confluenceuser>'@'localhost' IDENTIFIED BY '<password>';

If Confluence is not running on the same server, replace localhost with the hostname or IP address of
the Confluence server.

4. Install Confluence

Check out the Confluence Installation Guide for step-by-step instructions on how to install Confluence on
your operating system.

5. Download and install the MySQL driver

Due to licensing restrictions, we're not able to bundle the MySQL driver with Confluence. To make your
database driver available to Confluence:
1. Stop Confluence.
2. Head to Database JDBC Drivers and download the appropriate driver. The driver file will be called

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 172
2.

something like mysql-connector-java-5.1.xx-bin.jar

3. Drop the .jar file in your <installation-directory>/confluence/WEB-INF/lib directory.
4. Restart Confluence then go to http://localhost:<port> in your browser to continue the setup
process.

6. Enter your database details

The Confluence setup wizard will guide you through the process of connecting Confluence to your database.

Use a JDBC connection (default)

JDBC is the recommended method for connecting to your database.

The Confluence setup wizard will provide you with two setup options:
Simple - this is the most straightforward way to connect to your database.
By connection string - use this option if you want to specify additional parameters and are
comfortable constructing a database URL.
Depending on the setup type, you'll be prompted for the following information.

Setup type Field Description

Simple Hostname This is the hostname or IP address of your database server.

Simple Port This is the MySQL port. If you didn't change the port when you installed
MySQL, it will default to 3306.

Simple Database This is the name of your confluence database. In the example above, this
name is confluence

By Database The database URL is entered in this format:

connection URL jdbc:mysql://<hostname>:<port>/<database>
string
For example:
jdbc:mysql://localhost:3306/confluence

Both Username This is the username of your dedicated database user. In the example
above, this is confluenceuser.

Both Password This is the password for your dedicated database user.

Use a JNDI datasource

If you want to use a JNDI datasource, see Configuring a datasource connection for the steps you'll need to
take before you set up Confluence, as the setup wizard will only provide the option to use a datasource if it
detects a datasource in your Tomcat configuration.

7. Test your database connection

In the database setup screen, hit the Test connection button to check:
Confluence can connect to your database server
the database character encoding, collation, isolation level and storage engine are correct
your database user has appropriate permissions for the database.
Once the test is successful, hit Next to continue with the Confluence setup process.

Troubleshooting

If Confluence complains that it is missing a class file, you may have placed the JDBC driver in the
wrong folder.
If you get the following error message, verify that you have given the confluenceuser user all the

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 173

required database permissions when connecting from localhost.

Could not successfully test your database: : Server connection

failure during transaction. Due to underlying exception:
'java.sql.SQLException: Access denied for user
'confluenceuser'@'localhost' (using password: YES)'

The following page contains common issues encountered when setting up your MySQL database to
work with Confluence: Database Troubleshooting for MySQL

Configuring a MySQL Datasource in Apache Tomcat

Error rendering macro 'viewport-redirect' : null

Embedded H2 Database
To enable you to try Confluence without setting up On this page:
an external database, your Confluence installation
includes an embedded H2 database. Connect to the embedded H2
database using DB Visualizer
The embedded H2 database is used by default when Connect to the embedded H2
you choose the Trial installation path. database using the H2 console
Migrate to a supported external
database

Related pages:
Confluence Home and other
important directories
Database Configuration

The embedded database files are stored in your Confluence home directory <confluence-home>/databa
se.

The embedded H2 database is only supported while you are evaluating Confluence. You must migrate to a s
upported external database before using Confluence as a production system.
To find out if you are still using the embedded database, go to

> General Configuration > Troubleshooting and support tools.

Connect to the embedded H2 database using DB Visualizer

If you need to make changes directly in the database, and you're using the H2 database, here's how you can
connect to it using DBVisualizer.
DBVisualizer is just one database administration tool. You can use any administration tool that supports
embedded H2 databases. The steps will be similar.
1. Shut down Confluence.
2. Back up your <confluence-home>/database directory.
3. Launch DBVisualizer.
4. Choose Create new database connection and follow the prompts to set up the connection.
The information you'll need is:
Database driver: H2 embedded
Database Userid: sa
Database password: leave this field blank
Database filename:<confluence-home>/database/h2db
leave off the .h2.db file extension.
5. Connect to the database.
Refer to the DBVisualizer documentation for help using DBVisualizer.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 174

Connect to the embedded H2 database using the H2 console

Alternatively you can connect using the browser based H2 console. The easiest way to access the console is
to double click the H2 database jar file at <installation-directory>\confluence\WEB-INF\lib\h
2-x.x.x.jar.

Migrate to a supported external database

If you're using the H2 database, but running Confluence as a production system, you should start planning to
migrate to a supported database as soon as possible.
To migrate to a supported external database:
1. Check Supported Platforms to find out which databases and versions are supported.
2. Head to Migrating to Another Database for a step-by-step guide.

Migrating to Another Database

This document describes how to migrate your
Confluence data from your existing database to
another database. The instructions are designed
primarily for migrating from an evaluation to a
production database.

Large data sets will require third party

database migration tools.

This page covers the following scenarios:

Moving from the embedded, trial database to
a supported external database.
Moving from one external database to
another, for example from Oracle to
PostgreSQL (provided your dataset is not
large)
Upgrading to a new version of the same
external database. Note: you don't need to
migrate your data if you're upgrading the
database in place.

If you are moving your database from one

server to another you can change the JDBC
URL in <confluence-home>/confluenc
e.cfg.xml (if you are using a direct JDBC
connection) or in the definition of your
datasource (if you are connecting via a
datasource).

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 175

On this page:
Limitations of database migration
Database migration
Method one – standard procedure
Step 1: Take note of your
Marketplace apps
Step 2: Back up your data
Step 3: Set up the new
database
Step 4. Install Confluence
(same version number) in a
new location
Step 5. Download and
install the database driver if
necessary
Step 6. Run the Confluence
setup wizard and copy your
data to your new database
Step 7. Re-install your
Marketplace apps
Step 8. Check settings for
new machine
Method two – for installations with
a large volume of attachments
Before you start
Step 1: Take note of your
Marketplace apps
Step 2: Back up your data
Step 3: Set up the new
database
Step 4. Install Confluence
(same version number) in a
new location
Step 5. Download and
install the database driver if
necessary
Step 6. Run the Confluence
setup wizard and copy your
data to your new database
Step 7: Copy your
attachments across
Step 8. Re-install your
Marketplace apps
Step 9. Check settings for
new machine
A note about case sensitivity in
your database
Setting up a new
Confluence instance
Migrating an existing
Confluence instance to a
different database
Troubleshooting
Related pages:
Database Configuration
Confluence Home and other
important directories

Limitations of database migration

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 176

Note: The XML export built into Confluence is not suited for the backup or migration of large data sets. There
are a number of third party tools that may be able to assist you with the data migration. If you would like help
in selecting the right tool, or help with the migration itself, we can put you in touch with one of the Atlassian
Experts.

Database migration

There are two ways you can perform the migration, both described on this page:
1. Method one is the standard procedure.
2. Use method two if the total size of attachments in your installation exceeds 500MB.

Method one – standard procedure

Step 1: Take note of your Marketplace apps

Take note of the apps (also knowns as plugins or add-ons) currently installed and enabled in Confluence, so
that you can reinstate them later. Make a note of the following for each app:
App name and vendor
Version
Enabled or disabled status. This is useful if you have enabled or disabled modules yourself, making
your configuration differ from the default.

Step 2: Back up your data

1. Create an XML backup of your existing data. See Manually Backing Up the Site. Make a note of the
location where you put the XML file. You will need it later to import your Confluence data into your new
database.
2. Stop Confluence.
3. Make a copy of the Confluence Home directory. This is a precautionary measure, to ensure you can
recover your data if it is mistakenly overwritten.
4. If you are using an external database, make a separate backup using the utilities that were installed
with that database. This also is a precautionary measure.

Step 3: Set up the new database

Choose the database setup instructions for your new database, and follow those instructions to do the
following:
Install the database server.
Perform any required configuration of the database server, as instructed.
Add the Confluence database and user. Make a note of the username and password that you define in
this step. You will need them later, when running the Confluence Setup Wizard.

Step 4. Install Confluence (same version number) in a new location

Now you will install Confluence again, with a different home directory path and installation path.
Note: You must use the same version of Confluence as the existing installation. (If you want to upgrade
Confluence, you must do it as a separate step.) For example, if your current site is running Confluence 5.1.2,
your new installation must also be Confluence 5.1.2.
When running the Confluence installer:
Choose Custom Install. (Do not choose to upgrade your existing installation.)
Choose a new destination directory. This is the installation directory for your new Confluence. It
must not be the same as the existing Confluence installation.
Choose a new home directory. This is the data directory for your new Confluence. It must not be the
same as the existing Confluence installation.

Step 5. Download and install the database driver if necessary

Note that Confluence bundles some database drivers, but you'll need to install the driver yourself if it is not
bundled. Follow the database setup instructions for your new database, to download and install the database

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 177

driver if necessary.

Step 6. Run the Confluence setup wizard and copy your data to your new database

When running the Confluence setup wizard:

Enter your license key, as usual.
Choose Production Installation as the installation type.
Choose My own database then select your particular database from the Database type dropdown
menu.
When prompted to choose My own database, then select your new Database type.
Enter your database details. Use test connection to check your database is set up correctly.
On the load content step, choose Restore From Backup. This is where you will import the data from
your XML backup. There are two options for accessing the XML file:
Browse to the location of your XML backup on your network, and choose Upload and Restore.
Alternatively, put the XML file in the Confluence home directory of the new site (<CONFLUENCE
-HOME-DIRECTORY>\restore) then choose Restore. This is the recommended method for
large XML files.
Note: If you choose not to restore during the Confluence setup wizard, you can do the import later. Go to the
Confluence administration console and choose to restore an XML backup. See Site Backup and Restore.

Step 7. Re-install your Marketplace apps

Re-install any apps (also known as plugins or add-ons) that are not bundled with Confluence.
Use the same version of the app as on your old Confluence site.
The data created by the app will already exist in your new Confluence site, because it is included in
the XML backup.

Step 8. Check settings for new machine

If you are moving Confluence to a different machine, you need to check the following settings:
Configure your new base URL. See Configuring the Server Base URL.
Check your application links. See Linking to Another Application.
Update any gadget subscriptions from external sites pointing to this Confluence site. For example, if
your Jira site subscribes to Confluence gadgets, you will need to update your Jira site.
Review any other resources that other systems are consuming from Confluence.

Method two – for installations with a large volume of attachments

Before you start

These instructions only apply to attachments stored in the file system. If you store attachments in the
database see Attachment Storage Configuration to find out how to migrate between different attachment
storage methods.

Step 1: Take note of your Marketplace apps

Take note of the apps (also knowns as plugins or add-ons) currently installed and enabled in Confluence, so
that you can reinstate them later. Make a note of the following for each app:
App name and vendor
Version
Enabled or disabled status. This is useful if you have enabled or disabled modules yourself, making
your configuration differ from the default.

Step 2: Back up your data

1. Create an XML backup of your existing data. See Manually Backing Up the Site. Make a note of the
location where you put the XML file. You will need it later to import your Confluence data into your new
database.
2. Stop Confluence.
3. Make a copy of the attachments directory (<CONFLUENCE-HOME-DIRECTORY>\attachments) in
your Confluence Home directory. You will need it later to copy your Confluence attachments data into

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 178
3.

your new Confluence installation.

4. If you are using an external database, make a separate backup using the utilities that were installed
with that database. This also is a precautionary measure.

Step 3: Set up the new database

Choose the database setup instructions for your new database, and follow those instructions to do the
following:
Install the database server.
Perform any required configuration of the database server, as instructed.
Add the Confluence database and user. Make a note of the username and password that you define in
this step. You will need them later, when running the Confluence Setup Wizard.

Step 4. Install Confluence (same version number) in a new location

Now you will install Confluence again, with a different home directory path and installation path.
Note: You must use the same version of Confluence as the existing installation. (If you want to upgrade
Confluence, you must do it as a separate step.) For example, if your current site is running Confluence 5.1.2,
your new installation must also be Confluence 5.1.2.
When running the Confluence installer:
Choose Custom Install. (Do not choose to upgrade your existing installation.)
Choose a new destination directory. This is the installation directory for your new Confluence. It
must not be the same as the existing Confluence installation.
Choose a new home directory. This is the data directory for your new Confluence. It must not be the
same as the existing Confluence installation.

Step 5. Download and install the database driver if necessary

Note that Confluence bundles some database drivers, but you'll need to install the driver yourself if it is not
bundled. Follow the database setup instructions for your new database, to download and install the database
driver if necessary.

Step 6. Run the Confluence setup wizard and copy your data to your new database

When running the Confluence setup wizard:

Enter your license key, as usual.
Choose Production Installation as the installation type.
Choose My own database then select your particular database from the Database type dropdown
menu.
When prompted to choose My own database, then select your new Database type.
Enter your database details. Use test connection to check your database is set up correctly.
On the load content step, choose Restore From Backup. This is where you will import the data from
your XML backup. There are two options for accessing the XML file:
Browse to the location of your XML backup on your network, and choose Upload and Restore.
Alternatively, put the XML file in the Confluence home directory of the new site (<CONFLUENCE
-HOME-DIRECTORY>\restore) then choose Restore. This is the recommended method for
large XML files.
Note: If you choose not to restore during the Confluence setup wizard, you can do the import later. Go to the
Confluence administration console and choose to restore an XML backup. See Site Backup and Restore.

Step 7: Copy your attachments across

Copy the contents of the attachments directory (<CONFLUENCE-HOME-DIRECTORY>\attachments) from

your old Confluence Home directory to your new Confluence Home directory.

Step 8. Re-install your Marketplace apps

Re-install any apps (also known as plugins or add-ons) that are not bundled with Confluence.
Use the same version of the app as on your old Confluence site.
The data created by the app will already exist in your new Confluence site, because it is included in

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 179

the XML backup.

Step 9. Check settings for new machine

If you are moving Confluence to a different machine, you need to check the following settings:
Configure your new base URL. See Configuring the Server Base URL.
Check your application links. See Linking to Another Application.
Update any gadget subscriptions from external sites pointing to this Confluence site. For example, if
your Jira site subscribes to Confluence gadgets, you will need to update your Jira site.
Review any other resources that other systems are consuming from Confluence.

A note about case sensitivity in your database

'Collation' refers to a set of rules that determine how data is sorted and compared. Case sensitivity is one
aspect of collation. Other aspects include sensitivity to kana (Japanese script) and to width (single versus
double byte characters).

Setting up a new Confluence instance

For new Confluence instances, we recommend using case sensitive collation for your Confluence database.
This is the default collation type used by many database systems.
Note: Even if the database is configured for case sensitive collation, Confluence reduces all usernames to
lower case characters before storing them in the database. For example, this means that 'joebloggs',
'joeBloggs' and 'JoeBloggs' will be treated as the same username.

Migrating an existing Confluence instance to a different database

The default Confluence configuration uses case sensitive database collation. This is typical of databases
created under default conditions. If you are migrating from this type of configuration to a new database, we
recommend that the new database uses case sensitive collation. If you use case insensitive collation, you
may encounter data integrity problems after migration (for example, via an XML import) if data stored within
your original Confluence site required case sensitive distinctions.

Troubleshooting

See our troubleshooting guide if you're unable to restore your XML backup.

Configuring Database Character Encoding

Confluence and your database must be configured On this page:
to use the same character encoding.
New installations
Confluence uses UTF-8 character encoding, so your Existing installations
database will also need to be configured to use
UTF-8 (or the equivalent for your database, for Related pages:
example, AL32UTF8 for Oracle databases).
Troubleshooting Character
Encodings
Configuring Character Encoding
Database Troubleshooting for
MySQL

New installations

When installing Confluence for the first time you will need to consider character encoding:
when creating your database
when connecting to the database via a JDBC connection string or datasource (if you use the simple
setup method in the Confluence setup wizard, we'll take care of this for you).
The Confluence setup wizard will alert you if there is a problem with your character encoding, this will make
sure you don't experience problems down the track. It is much easier to solve problems now, than later when

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 180

you have Confluence data in your database.

The setup guide for each of our supported databases outlines how to configure character encoding correctly
when creating your database:
Database Setup for PostgreSQL
Database Setup For MySQL
Database Setup for SQL Server
Database Setup for Oracle

Existing installations

For existing Confluence sites, where the first version of Confluence installed was 6.4 or earlier, we many not
have checked the collation or character encoding of your database during the initial setup.
If your database is not correctly configured to use UTF-8 character encoding (or the equivalent for your
database, for example AL32UTF8 for Oracle databases):
you may see a health check warning while using Confluence
you may not be able to start Confluence after an upgrade.
If this happens, you'll need to change the character encoding for your existing database. The way you do this
will depend on your database.
Also see Troubleshooting Character Encodings for help diagnosing character encoding problems.
MySQL
See How to Fix the Collation and Character Set of a MySQL Database for details of what you'll need to do to
fix the character encoding in your database. You should also make sure the collation is correct.
Microsoft SQL Server
See How to fix the collation of a Microsoft SQL Server Confluence database for details of what you'll need to
do to fix the character encoding in your database.
PostgreSQL
If you use PostgreSQL, the best option is to recreate your database.
See Database Setup for PostgreSQL for how to create your database using the correct character encoding,
then follow the steps in Migrating to Another Database.
Oracle
If you use Oracle, the best option is to recreate your database.
See Database Setup for Oracle for how to create your database using the correct character encoding, then
follow the steps in Migrating to Another Database.

Configuring database query timeout

If database queries are taking too long to perform, and your application is becoming unresponsive, you can
configure a timeout for database queries. There is no default timeout in Confluence.To configure a database
query timeout, do the following on your test server:
1. Shut down Confluence.
2. Extract databaseSubsystemContext.xml from the confluence-x.x.x.jar that is in confluence/WE
B-INF/lib/, and put a copy in confluence/WEB-INF/classes/.

3. Edit confluence/WEB-INF/classes/databaseSubsystemContext.xml to add the defaultTimeout

property to the "transactionManager" bean:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 181

<bean id="tenantedTransactionManager"
class="org.springframework.orm.hibernate.HibernateTransactionManager"
plugin:available="true">
<property name="sessionFactory" ref="sessionFactory"/>
<property name="defaultTimeout" value="120"/>
</bean>

The timeout is measured in seconds and will forcibly abort queries that take longer than this. In some cases,
these errors are not handled gracefully by Confluence and will result in the user seeing the Confluence error
page.
4. Start Confluence.
Once the timeout is working properly in your test environment, migration the configuration change to Confluence.
You will need to reapply these changes when upgrading Confluence, as the original databaseSubsystemC
ontext.xml file changes from version to version.
Surviving Database Connection Closures

When a database server reboots or a network failure has occurred, all connections in the database connection
pool are broken. To overcome this issue, Confluence would normally need to be restarted.
However, database connections in the database connection pool can be validated by running a simple SQL
query. If a broken database connection is detected in the pool, a new one is created to replace it.
To do this, Confluence can use a validation query for your database connection. This is enabled by default on
new installations (Confluence 6.5 and later), but if you've upgraded from an older Confluence version you can
choose to enable this manually by following the steps below.

Determine the validation query SQL for your database

Different databases have slightly different SQL syntax requirements for their validation query. The validation
query should be as simple as possible, as this is run every time a connection is retrieved from the pool.
The following validation queries are recommended for the following types of databases:

Database Type Validation Query

MySQL select 1

Microsoft SQL Server select 1

Oracle select 1 from dual

PostgreSQL select 1

Enable validation query with a direct JDBC connection

To ensure Confluence validates database connections in the database connection pool:

1. Stop Confluence.
2. Edit the <home-directory>confluence.cfg.xml file.
3. Insert the following property for your particular database.

For PostgreSQL, SQL Server, and MySQL

<property name="hibernate.c3p0.preferredTestQuery">select
1</property>

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 182

For Oracle
<property name="hibernate.c3p0.preferredTestQuery">select 1 from
dual</property>

4. Save confluence.cfg.xml
5. If you're using Confluence 5.10.3 or earlier you'll need to add the following system property with the
validation query for your database.
For example:

-Dc3p0.preferredTestQuery="select 1"

6. Restart Confluence.
You should now be able to recover from a complete loss of all connections in the database connection pool
without the need to restart Confluence.

Enable validation query with a datasource connection

To ensure Confluence validates database connections in the database connection pool:

1. Stop Confluence.
2. Edit the <installation-directory>/conf/server.xml file (or wherever you have configured your
datasource).
3. Find the Resource element for your data source, and add the "validationQuery" parameter as in the
example for PostgreSQL below. Remember to give it the appropriate value for your database type.

server.xml (excerpt)
...
<Resource name="jdbc/confluence" auth="Container"
type="javax.sql.DataSource"
username="postgres"
password="postgres"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://localhost:5432/yourDatabaseName"
maxTotal="60"
maxIdle="20"
validationQuery="select 1" />
...

4. Save conf/server.xml
5. Restart Confluence.
You should now be able to recover from a complete loss of all connections in the database connection pool
without the need to restart Confluence.
Configuring a datasource connection
This guide covers how to configure a JNDI datasource connection to your
database. With this type of connection, Confluence asks the application
server (Tomcat) for your database connection information.
If you'd prefer to use a JDBC connection see the guide for your database:
Database Setup for PostgreSQL
Database Setup for SQL Server
Database Setup For MySQL

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 183

Database Setup for Oracle On this page:

Direct JDBC is the most common way to connect Confluence to your New
database and is the easiest method when it comes time to upgrade Confluenc
Confluence. e
installation
Existing
Confluenc
e
installation
Upgrading
Confluenc
e with a
datasource
Related pages:
Database
JDBC
Drivers

New Confluence installation

The Confluence setup wizard will only provide an option to use a datasource if it detects one in your Tomcat
configuration. If you want to use a datasource, follow the steps below.

1. Stop Confluence
In the Confluence setup wizard, you'll be prompted to choose your database. At this point, you should:
1. Stop Confluence.
2. Back up the following files, in case you need to revert your changes:
<installation-directory>/conf/server.xml
<installation-directory>/confluence/WEB-INF/web.xml
<home-directory>/confluence.cfg.xml

2. Add your database driver

Copy your database driver into the <installation-directory>/lib directory.

Here's where to find the driver for your database:

PostgreSQL: bundled with Confluence at <installation-directory>/confluence/WEB-INF/
lib/postgresql-x.x.x.jar
Microsoft SQL Server: bundled with Confluence at <installation-directory>/confluence/
WEB-INF/lib/mssql-jdbc-x.x.x.x.jar
MySQL: head to Database JDBC Drivers to download the driver
Oracle: head to Database JDBC Drivers to download the driver

3. Configure the datasource in Tomcat

Next, add the datasource configuration to Tomcat.

1. Edit <installation-directory>/conf/server.xml
2. Find the following lines:

<Context path="" docBase="../confluence" debug="0"

reloadable="true">
<!-- Logger is deprecated in Tomcat 5.5. Logging configuration
for Confluence is
specified in confluence/WEB-INF/classes/log4j.properties -->

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 184

3. Insert the following DataSource Resource element for your specific database directly after the lines
above (inside the Context element, directly after the opening <Context.../> line, before Mana
ger).

PostgreSQL...

<Resource name="jdbc/confluence" auth="Container"

type="javax.sql.DataSource"
username="<database-user>"
password="<password>"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://<host>:5432/<database-name>"
maxTotal="60"
maxIdle="20"
validationQuery="select 1"/>

Microsoft SQL Server...

<Resource name="jdbc/confluence" auth="Container"

type="javax.sql.DataSource"
username="<database-user>"
password="<password>"

driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"

url="jdbc:sqlserver://<host>:1433;database=<database-name>"
maxTotal="60"
maxIdle="20"
validationQuery="select 1"/>

If you're using Confluence 6.3 or earlier, you'll need to specify the jTDS driver for SQL Server. See
Configuring a SQL Server Datasource in Apache Tomcat in our 6.3 documentation for a sample
configuration.
MySQL...

<Resource name="jdbc/confluence" auth="Container"

type="javax.sql.DataSource"
username="<database-user>"
password="<password>"
driverClassName="com.mysql.jdbc.Driver"

url="jdbc:mysql://<host>:3306/<database-name>?useUnicode=true&
amp;characterEncoding=utf8"
maxTotal="60"
maxIdle="20"
defaultTransactionIsolation="READ_COMMITTED"
validationQuery="Select 1"/>

Oracle...

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 185

<Resource name="jdbc/confluence" auth="Container"

type="javax.sql.DataSource"
driverClassName="oracle.jdbc.OracleDriver"
url="jdbc:oracle:thin:@<host>:1521:<SID>"
username="<database-user>"
password="<password>"
connectionProperties="SetBigStringTryClob=true"
accessToUnderlyingConnectionAllowed="true"
maxTotal="60"
maxIdle="20"
maxWaitMillis="10000"/>

See how to find your Oracle URL.

Replace <database-user>, <password>, <host> and <database-name> (or <SID> for Oracle)
with details of your own database. You may also need to change the port, if your database server is
not running on the default port.
4. Configure the connection pool and other properties. See the Apache Tomcat 9 Datasource
documentation for more information.

Configurable properties...
Here are the configuration properties for Tomcat's standard data source resource factory (org.ap
ache.tomcat.dbcp.dbcp.BasicDataSourceFactory):

driverClassName - Fully qualified Java class name of the JDBC driver to be used.
maxTotal - The maximum number of active instances that can be allocated from this pool
at the same time.
maxIdle - The maximum number of connections that can sit idle in this pool at the same
time.
maxWaitMillis - The maximum number of milliseconds that the pool will wait (when there
are no available connections) for a connection to be returned before throwing an exception.
password - Database password to be passed to the JDBC driver.
url - Connection URL to be passed to the JDBC driver. (For backwards compatibility, the
property driverName is also recognized.)
user - Database username to be passed to the JDBC driver.
validationQuery - SQL query that can be used by the pool to validate connections
before they are returned to the application. If specified, this query MUST be an SQL
SELECT statement that returns at least one row. When a database server reboots, or there
is a network failure, all the connections in the connection pool are broken and this normally
requires a application server reboot. However, the Commons DBCP (Database Connection
Pool) used by Tomcat can validate connections before issuing them by running a simple
SQL query, and if a broken connection is detected, a new one is created to replace it. To do
this, you will need to set the "validationQuery" option on the database connection pool.
5. If you plan to use collaborative editing, you'll need to make sure:
You're using a supported database driver. Collaborative editing will fail if you're using an
unsupported or custom JDBC driver or driverClassName in your datasource. See Database
JDBC Drivers for the list of drivers we support.
Your database connection pool allows enough connections to support both Confluence and
Synchrony (which defaults to a maximum pool size of 15)
You're using simple username and password authentication for your database.

4. Configure the Confluence web application

Configure Confluence to use this datasource:

1. Edit <CONFLUENCE_INSTALLATION>/confluence/WEB-INF/web.xml.
2. Insert the following element just before </web-app> near the end of the file:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 186

<resource-ref>
<description>Connection Pool</description>
<res-ref-name>jdbc/confluence</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>

5. Restart Confluence and continue setup process

Now that your datasource is configured, you can continue with the setup wizard.
1. Start Confluence.
2. Go to http://localhost:8090 to return to the setup wizard.
3. When prompted choose My own database (datasource).
4. Enter the JNDI name of your datasource, for example,java:comp/env/jdbc/confluence
5. Follow the prompts to finish setting up Confluence.

Existing Confluence installation

If you want to switch from using a direct JDBC connection to a datasource:

Stop Confluence.
Back up the following files, in case you need to revert your changes:
<installation-directory>/conf/server.xml
<installation-directory>/confluence/WEB-INF/web.xml
<home-directory>/confluence.cfg.xml
Follow the steps above for a new installation and copy your driver and add the datasource to the
appropriate files. You can find the details of your current database connection in <home-directory>
/confluence.cfg.xml.
Edit the <home-directory>/confluence.cfg.xml file and remove any line that contains a
property that begins with hibernate.
Insert the following at the start of the <properties> section.
PostgreSQL...

<property name="hibernate.setup"><![CDATA[true]]></property>
<property
name="hibernate.dialect"><![CDATA[net.sf.hibernate.dialect.Pos
tgreSQLDialect]]></property>
<property
name="hibernate.connection.datasource"><![CDATA[java:comp/env/
jdbc/confluence]]></property>

Microsoft SQL Server...

<property name="hibernate.setup"><![CDATA[true]]></property>
<property
name="hibernate.dialect"><![CDATA[net.sf.hibernate.dialect.SQL
ServerIntlDialect]]></property>
<property
name="hibernate.connection.datasource"><![CDATA[java:comp/env/
jdbc/confluence]]></property>

MySQL...

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 187

<property name="hibernate.setup"><![CDATA[true]]></property>
<property
name="hibernate.dialect"><![CDATA[com.atlassian.hibernate.dial
ect.MySQLDialect]]></property>
<property
name="hibernate.connection.datasource"><![CDATA[java:comp/env/
jdbc/confluence]]></property>

Oracle...

<property name="hibernate.setup"><![CDATA[true]]></property>
<property
name="hibernate.dialect"><![CDATA[com.atlassian.confluence.imp
l.hibernate.dialect.OracleDialect]]></property>
<property
name="hibernate.connection.datasource"><![CDATA[java:comp/env/
jdbc/confluence]]></property>

Start Confluence.

Upgrading Confluence with a datasource

If you're upgrading Confluence (manually or using the installer) you will need to:
Stop Confluence (if you have attempted to start it).
Copy your database driver into the <installation-directory>/lib directory.
Edit <installation-directory>/conf/server.xml and add your datasource resource.
Edit <installation-directory>/confluence/WEB-INF/web.xml to configure Confluence to
use this datasource.
If you forget to do these steps, Confluence will not start up after upgrade and you'll see the following error:

HTTP Status 500 - Confluence is vacant, a call to tenanted [public

abstract org.hibernate.Session
org.hibernate.SessionFactory.getCurrentSession() throws
org.hibernate.HibernateException] is not allowed.

Site Backup and Restore

When setting up your Confluence site, it's important to consider how you will back up your data, and restore it, if
things go wrong.

Recommended backup strategy

Having a robust backup strategy for your Confluence site is essential. You should back up your database, install
directory, and home directories (including attachments) on a regular basis, using the database administration
and/or backup tool of your choice.
See Production Backup Strategy for more information.

Scheduled XML backup

Confluence provides a scheduled XML backup option, which backs up your site by performing a full site XML
export each day. This method can be useful for small sites, test sites, or in addition to your database and

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 188

directory backups. We don't recommend you rely solely on this backup method for your production site.
Why XML site export is not suitable for larger sites...
There are a number of reasons why XML site backups are unsuitable for large Confluence sites:
As the number of pages in your site increases, the XML backup takes progressively longer to
complete, and in extreme cases the process of generating the export can cause an outage.
XML backups can consume a lot of disk space rapidly. For example a 1GB Confluence site will create
30GB worth of backups in a month, if unattended.
If the XML export file is very large, restoring your site can take a long time, or may time out.
Marketplace and other user-installed apps are not included in the XML backup. After importing your
backup into a new Confluence site, you will need to re-install all user installed apps.
See Configuring Backups to find out more about the scheduled XML backup, including how to disable this
backup, or change how often this job runs.
If you have a Confluence Data Center license, the scheduled XML backup is disabled by default.

Manual XML backup

You can manually create an XML site backup at any time.

Restoring your site from a backup

In the event do you need to restore your site from a backup, the way you do this depends on your backup
method.
See Restoring Data from other Backups for tips on how to restore Confluence from a database backup.
See Restoring a Site to find out how to import data from an XML site export file into an existing
Confluence site.

Migrate to Confluence Cloud

If you're migrating from Confluence Server to Confluence Cloud, you can use the Cloud Migration
Assistant for Confluence to migrate your content and spaces.

Production Backup Strategy

Although Confluence provides a scheduled XML On this page:
backup, this backup method is only suitable for small
sites, test sites, or in addition to database and Establishing a production system
directory backups. backup solution
Which files need to be backed up?
How do I back up?
Establishing a production system backup solution How do I restore?
Other processes
We recommend establishing a robust database
backup strategy:
Related pages:
Site Backup and Restore

Create a backup or dump of your database using tools provided by your database.
If your database doesn't support online backups, you will need to stop Confluence while you do this.
Create a file system backup of your home directory (both local home and shared home for Data
Center)
Once this is in place, you can disable the daily backup scheduled job.
Having a backup of your database and home directories is more reliable, and easier to restore than a large
XML backup.

Which files need to be backed up?

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 189

Backing up the whole home directory is the safest option, however most files and directories are populated
on startup and can be ignored. At minimum, these files/directories must be backed up:
<conf-home>/confluence.cfg.xml
<conf-home>/attachments (you can exclude extracted text files if space is an issue)
The rest of the directories will be auto-populated on start up. You may also like to backup these directories:
<conf-home>/config – if you have modified your ehcache.xml file.
<conf-home>/index – if your site is large or reindexing takes a long time – this will avoid the need for
a full reindex when restoring.
The location of the home directory is configured on installation and is specified in the confluence.init.p
roperties file. For installation created with the automatic installer the default locations are:

Windows C:\Program Files\Atlassian\Application Data\Confluence

Linux /var/atlassian/application-data/confluence

For Clustered instances only: Backing up the whole shared home directory is the safest option, however
some files and directories are populated at runtime and can be ignored:
<conf-home>/thumbnails
<conf-home>/viewfile.

How do I back up?

The commands to back up your database will vary depending on your database vendor, for example the
command for PostgreSQL is pg_dump dbname > outfile.

You should refer to the documentation for your particular database to find out more.

How do I restore?

Our guide on Migrating Confluence Between Servers has instructions on restoring a backup using this
technique.

Other processes

XML site backups can be used for other processes in Confluence, for example moving servers or switching
to a different database. Using the backup strategy described above will work for those processes too.
Our migrate server procedure– used to set up a test server – can use a SQL dump as well.
The database migration procedure uses the XML backup for small data sets. Large data sets will
require third party database migration tools.
Note: The XML export built into Confluence is not suited for the backup or migration of large data sets. There
are a number of third party tools that may be able to assist you with the data migration. If you would like help
in selecting the right tool, or help with the migration itself, we can put you in touch with one of the Atlassian
Experts.

Configuring Backups
Confluence can automatically back up your data by On this page:
performing a full site export at a scheduled time
each day. Configuring automated backups
Performing manual backups
If you have a Confluence Server license, the Scheduled XML backups in
scheduled XML backup happens every day at Confluence Data Center
2:00am by default.
If you have a Confluence Data Center licens
e, the scheduled backup is disabled, as it is
not suitable for large sites.
The zipped XML backup file will be named 'backup
-yyyy_MM_dd', and stored in the backups directory

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 190

of your Confluence Home directory.

You'll need System Administrator global permissions to make changes to the scheduled XML backups. You
can choose to:
disable the scheduled backup altogether
change the naming convention
include or exclude attachments
schedule the backup at a different time
store the backup files in a different location (disabled by default, find out how to enable it below).

We don't recommend relying on these automatic backups in production sites. You should instead
back up your database, installation directory and home directory manually. See Production Backup
Strategy for more information.

Configuring automated backups

To configure scheduled XML backups:

1. Go to

> General Configuration > Backup administration.

2. Choose Edit to:
Change the backup file name prefix.
Use a different date format (uses the syntax described in simple date format).
Choose whether to include or exclude attachments from backups (attachments are included by
default).
Choose to store backup files in a custom location (this is disabled by default - see Enabling
backup path configuration below).
3. Save your changes.

Enabling Backup Path Configuration

For security reasons, the ability to change the backup file location Backup administration screen is disabled
by default.
To enable custom backup paths:
1. Stop Confluence.
2. Edit the <confluence-home>/confluence.cfg.xml file.
3. Change the value of the following property to true:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 191

<property
name="admin.ui.allow.daily.backup.custom.location">true</propert
y>

4. Restart Confluence to pick up the change.

5. Go to

> General Configuration > Backup administration to enter the new path.
The directory must be on either a local drive or a mounted network drive. Make sure the mounted drive is on
a physical server and not a Virtual Machine image.
If you migrate Confluence to a new server or change your architecture, you will need to update this path.
Changing your home directory location will not automatically update your backup file path if you've enabled a
custom path.

Disable automatic backups

If you have an appropriate Production Backup Strategy, you may want to disable automatic backups to save
on disk space.
To disable automatic backups entirely:
1. Go to

> General Configuration > Scheduled jobs.

2. Choose Disable next to the Back up Confluence job.

Change the backup schedule

To change the frequency of backups, or to change the time the backup runs each day:
1. Go to

> General Configuration > Scheduled jobs.

2. Choose Edit next to the Back up Confluence job
3. Enter the new schedule using a cron expression.
The time zone used for the scheduled job is taken from the server on which Confluence is running. Go to

> General Configuration > System Information to look up the System Time.

Performing manual backups

If you need a one-off XML backup, you can manually perform a site export. See Manually Backing Up the
Site for more information.
These files are not saved to the same location as the automated backups, they are saved in the temp directo
ry. You can change where the zipped XML files are saved by changing the location of your <Confluence-
home>/temp directory. See Confluence Home and other important directories for more information on how
to do this.

Scheduled XML backups in Confluence Data Center

The scheduled XML backup is disabled by default in Confluence Data Center, as the job is known to cause
outages in sites with a lot of data.
We recommend that your backup strategy includes full backups of your database, local home and shared
home directories on a regular basis.
If you do choose to enable the scheduled XML backup (for example on a staging or test site), the default

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 192

backup path is <shared-home>/backups. You can find the location of your shared home in the confluen
ce.cfg.xml file, look for the confluence.cluster.home property.

User Submitted Backup & Restore Scripts

These scripts are user-submitted and should be used with caution as they are not covered by Atlassian technical
support. If you have questions on how to use or modify these scripts, please post them to Atlassian Answers.

Delete Old Backups - Wscript Script On Windows

This script examines backup filename and deletes them if necessary, it may need to be edited.

'If you want 3 day old files to be deleted then insert 3 next to Date -
"your number here"
'This script will search out and delete files with this string in them
".2005-12-04-" This of course depends on the number you enter.
'You can always do a wscript.echo strYesterday or strFileName to see
what the script thinks you are searching for.

dtmYesterday = Date - 3

strYear = Year(dtmYesterday)

strMonth = Month(dtmYesterday)
If Len(strMonth) = 1 Then
strMonth = "0" & strMonth
End If

strDay = Day(dtmYesterday)
If Len(strDay) = 1 Then
strDay = "0" & strDay
End If

strYesterday = strYear & "-" & strMonth & "-" & strDay

strFileName = "C:\test*." & strYesterday &"-*"

Set objFSO = CreateObject("Scripting.FileSystemObject")

objFSO.DeleteFile(strFileName)

Delete Old Backups - Basic Bash Script For Linux

Old XML backups can be deleted automatically by inserting a nightly or weekly automation script or cron similar
to the following:

ls -t <path to your backup dir>/* | tail -n +6 | xargs -i rm {}

Or, using the older form of the tail command if your system does not support the standard form:

ls -t <path to your backup dir>/* | tail +6 | xargs -i rm {}

Delete Old Backups - Advanced Bash Script For Linux

Old XML backups can be deleted automatically by inserting a nightly or weekly automation script or cron similar
to the following. Set the BACKUP_DIR and DAYS_TO_RETAIN variables to appropriate values for your site.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 193

Between runs, more files than DAYS_TO_RETAIN builds up.

#!/bin/sh

# Script to remove the older Confluence backup files.

# Currently we retain at least the last two weeks worth
# of backup files in order to restore if needed.

BACKUP_DIR="/data/web/confluence/backups"
DAYS_TO_RETAIN=14

find $BACKUP_DIR -maxdepth 1 -type f -ctime +$DAYS_TO_RETAIN -delete

Manual Database & Home Backup - Bash Script For Linux

This backs up a mySQL database and the Confluence home directory.

#!/bin/bash
CNFL=/var/confluence
CNFL_BACKUP=/backup/cnflBackup/`date +%Y%m%d-%H%M%S`

rm -rf $CNFL/temp/*
mkdir $CNFL_BACKUP
mysqldump -uroot -p<password> confluence|gzip >
$CNFL_BACKUP/confluence.mysql.data.gz
tar -cjvf $CNFL_BACKUP/data.bzip $CNFL > $CNFL_BACKUP/homedir.status

Backup by Date - Postgres

export d=`date +%u`

mkdir -p /home/backup/postgres/$d

sudo -u postgres pg_dumpall | bzip2 > /home/backup/postgres/$d/sql.bz2

Manually Backing Up the Site

Confluence can be configured automatically back up Related pages:
your data by performing a full site export at a
scheduled time each day. Restoring a Site
Configuring Backups
You can also manually back up Confluence at any Production Backup Strategy
time, by performing a full site export.
You'll need System Administrator permissions to do
this.

Good to know:
We don't recommend you rely on XML site exports as your main backup method. Instead, you
should regularly back up your database, install and home directories. See Production backup
strategy for more information.
Marketplace and user-installed apps are not included in the XML export. After importing your
site export file into a new Confluence site, you'll need to re-install all apps that are not bundled
with Confluence as the plugindata table is not backed up in a manual backup.
You can't import a site export XML file into an earlier version of Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 194

Create the site export file

To create an XML export of your site:

1. Go to

> General Configuration > Backup & Restore.

2. Choose Also save a copy to the backups directory to store a copy of the backup in the same folder
as Confluence's backups.
If you do not archive the backup it will be made available for you to download, and then deleted from
the server after 24 hours.
3. Choose Include attachments to include attachments in your backup.
4. Choose Export.
The process can take some time.

If you repeatedly experience timeout errors, try creating the export directly from the server. This will speed up
the process and prevent timeouts.
For example, use this URL: http://localhost:8090/confluence/admin/backup.action. directly
from your server.

What's included in the export?

The site export includes spaces (including pages, blogs, comments, attachments, and unpublished changes),
users and groups. Essentially everything in your site except add-ons.

Retrieving the site export file

Confluence will create the backup as a zipped XML file in your <home-directory>/backups> directory.
You'll need access to the Confluence server itself in order to retrieve this file.

Allow export files to be downloaded from within Confluence

By default, you can't retrieve the backup file from within Confluence. This feature is disabled for security
reasons, but you can choose to enable it. Once enabled, Confluence will prompt you to download the backup
file when the backup process finished. We recommend that you keep this feature off in production
environments.
To enable download of the backup file from within Confluence:
1. Stop Confluence.
2. Edit the <confluence-home>\confluence.cfg.xml file.
3. change admin.ui.allow.manual.backup.download to true.
4. Restart Confluence.
If the value of the above configuration property is 'true', it will be possible to download the backup file after
manually backing up the site via the Confluence Administration Console. If the value of this property is 'false'
or the property is not present in the configuration file, you will need to retrieve the backup file from the file
system on the Confluence server. By default, the value is 'false'.

Restoring the site export file

There are some restrictions on which Confluence versions you will be able to import this file into. The most
important is that you can't import into an earlier version of Confluence. See Restoring a Site for more
information and troubleshooting tips.

Restoring a Site
This page describes how to restore data from an
XML site export file into an existing Confluence site.

If you want to import data into a new site, see restori

ng from backup during setup.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 195

You need System Administrator permissions in order On this page:

to perform this function.
Before you start
Import a Confluence site
Troubleshooting
Note about using site exports as
backups

Related pages:
Production Backup Strategy
Exporting a site
Importing a Space

Importing a site export file will:

Overwrite all existing Confluence content in your database. Back up your database before you
start.
Log you out of Confluence. Make sure you know the login details contained in the file you're
about to import.

Before you start

All content replaced. Importing a site will replace all your content and users. Back up your database
before you start.
Selective space restoration not possible. You can't select a single space to restore from the entire
site backup.
Version compatibility. Confluence accepts site backups from many previous Confluence versions.
You can check which versions are accepted in the Backup and Restore screen. You can only import
into a later version of Confluence, not an earlier one.
For best results, export from and import into the same Confluence version.
XML export files should not be used to upgrade Confluence. Upgrade Confluence by following Up
grading Confluence.

Check your export is compatible

To check that your site export can be successfully restored:

1. Start up the Confluence site you'll be importing into.
2. Go to

> General Configuration > Backup and Restore.

3. Check the accepted Confluence version - it's listed under Import Confluence data.

Here's what it looks like for Confluence 6.15. The accepted versions for your Confluence version may
be different.

You can't import into an earlier version of Confluence.

For example, if your site export was generated from Confluence 6.12, you can't import it into

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 196

Confluence 6.6.
If your export is from Confluence Cloud you can only import it into Confluence 6.0 or later.

Import a Confluence site

There are two ways to import a site - by uploading a file, or from a directory on your Confluence server.
Uploading a file is only suitable for small sites. For best results, we recommend importing from the restore
directory.
To upload and import a small site:
1. Go to

> General Configuration > Backup and Restore.

2. Under Upload a site or space export file, click Choose File and browse for your space export file.
3. Uncheck Build Index if you want to create the index at a later stage.
4. Choose Upload and import.
To import a site from the home directory:
1. Copy your export file to <confluence-home>/restore.
(If you're not sure where this directory is located, the path is listed in the Backup and Restore screen)
2. Go to

> General Configuration > Backup and Restore.

3. Select your site export file under Import from home directory
4. Uncheck Build Index if you want to create the index at a later stage.
5. Choose Import.

Building the index is optional during the import process. The content of your site won't be searchable until the
index is created, but if you have a very large site, you may choose to rebuild the index manually after the
import is complete.

Using Confluence Data Center?

If you're using Confluence Data Center, and you run a Synchrony standalone cluster there are a
few extra steps. You need to stop Synchrony completley, and we also recommend performing the
import with just one Confluence node running, and directing traffic away from that node.
Once the import is complete, you can restart your Synchrony cluster, and then restart your remaining
nodes (one at a time).
This is not required if you allow Confluence to manage Synchrony for you.

Troubleshooting

If you have problems importing a site, check out these hints.

Is your file too large to upload?
This is a very common problem. It happens when the file can't be uploaded to the server in time. To
avoid this problem, drop your export file into the <confluence-home>/restore directory and
import it from there.
Are you trying to import into an earlier version of Confluence?
This is not possible. You can only import a site into the same version or a later compatible version.
Is the import timing-out or causing out of memory errors?
If the site to be imported is large, you may need to temporarily increase the memory available to
Confluence. See How to fix out of memory errors by increasing available memory.
Is your username or password not recognized?

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 197

All user data was overwritten during the import process. You need to log in with a system
administrator account from the site that was exported. If you don't know the password, you'll need to
reset it from the database. See Restore Passwords To Recover Admin User Rights.
Is your site export from Confluence Cloud?
You can only import into Confluence 6.0 or later. The Cloud export does not include a system
administrator account, so you will need to start Confluence in recovery mode, create a new system
administrator account, and make it a member of the confluence-administrators group. See Restore
Passwords To Recover Admin User Rights for more.
Did you download the export file on a Mac?
If you get an error saying that Confluence can't find the exportDescriptor.properties file,
chances are OS X has unzipped the backup for you and sent the original zipped file to the trash. You
need to retrieve the original zip file from the trash and then try the import again.
Importing into a site with a Synchrony standalone cluster?
You must stop your Synchrony cluster before commencing the site import.

Note about using site exports as backups

Production backup strategy preferred. We recommend that you follow the Production Backup
Strategy (which involves backing up your database and home directory) for your production
Confluence site, because Confluence XML exports are not recommended as the sole backup
mechanism.
Restoring from other backups. If your daily backup zip files can't be restored for some reason, but
you have backups of both your database and your Confluence home directory, you'll be able to restore
from these backups.

Restoring a Space
You can export a space – including pages, comments and attachments – to
a zip that contains an XML file and, optionally, all the attachments in the
space. To import the space to another Confluence site, restore the zip as
described below.
You need System Administrator permissions in order to restore a space
from an XML zip file.

Export and import compatibility

To find out which versions your current Confluence version can accept
space exports from, go to

> General Configuration > Backup and Restore.

If you need to import a space from Confluence 5.3 or earlier, you'll need to f
ollow a workaround.
To find out what is included in an XML export, see Export Content to Word,
PDF, HTML and XML.

You can't import into an earlier version of Confluence.

For example, if you export a space from Confluence 5.9, you can't
import it into Confluence 5.5.
If your export is from Confluence Cloud, you can only import it into
Confluence 6.0 or later.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 198

On this page:
Export and
import
compatibili
ty
Importing a
space from
Confluenc
e Cloud
Importing a
space from
Confluenc
e Server or
Data
Center
Upl
oad
a
site
or
spa
ce
exp
ort
file
Imp
ort
from
the
hom
e
dire
ctor
y
Groups
and
permission
s
Troublesho
oting
Workaroun
d for
restoring
spaces
from
Confluenc
e 5.3 and
earlier
Related pages:
Restoring
a Site

Importing a space from Confluence Cloud

As the way users are managed is different in Confluence Cloud there are a few extra steps when importing a
space from Confluence Cloud into Confluence Server or Data Center.
See Import a space from Confluence Cloud for a step-by-step guide.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 199

Importing a space from Confluence Server or Data Center

We recommend performing a full backup of your database before importing a space. Occasionally the
space import process may fail, and a backup will make it easier for you to roll back.
There are two ways to import a space – by uploading a file, or from a directory on your Confluence server.
Uploading a file is only suitable for small spaces. For best results, we recommend importing from the restore
directory.

Upload a site or space export file

To upload and import a small space:

1. Go to

> General Configuration > Backup and Restore.

2. Under Upload a site or space export file, click Choose File and browse for your space export file.
3. Uncheck Build Index if you want to create the index at a later stage.
4. Choose Upload and import.
Once the import is complete, you can either navigate directly to the space, or head to the Space Directory.

Import from the home directory

Importing from the home directory is a great alternative for large spaces, as you don't need to upload the file
via your browser.
To import a space from the home directory:
1. Copy your space export file to <confluence-home>/restore.
(If you're not sure where this directory is located, the path is listed in the Backup and Restore screen)
2. Go to

> General Configuration > Backup and Restore.

3. Select your space export file under Import from the Home Directory.
4. Uncheck Build Index if you want to create the index at a later stage.
5. Choose Import.
Building the index is optional during the import process. The content of your imported space won't be
searchable until the index is created, but, if you have a very large site, rebuilding the index can take a long
time and impact your site's performance. Alternatively, you can rebuild the index manually at a low peak time.

Groups and permissions

Importing a space will not import any users or groups that may have been granted specific space
permissions in your source Confluence site. This means that if any pages are restricted to these groups, you
may not be able to see them until you recreate these groups in your destination site.

Troubleshooting

If you have problems importing a space, check out these hints.

Is your file too large to upload?
This is a very common problem. It happens when the file can't be uploaded to the server in time. To
avoid this problem, drop your export file into the <confluence-home>/restore directory and
import it from there.
Are you trying to import into an earlier version of Confluence?
This is not possible. You can only import a space into the same version or a later compatible version.
Is your space export file from Confluence Cloud?
You can only import this file into Confluence 6.0 or later. Trying to import into earlier versions can
cause major problems. See Import a space from Confluence Cloud for other considerations.
Does a space with the same space key already exist?
Space keys are unique, so if you already have a space with the same key, you'll need to delete the
existing space before importing the new one.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 200

Is the import timing-out or causing out of memory errors?

If the space to be imported is very large, you may need to temporarily increase the memory available
to Confluence. See How to fix out of memory errors by increasing available memory.
Did you download the export file on a Mac?
If you get an error saying that Confluence can't find the exportDescriptor.properties file,
chances are OS X has unzipped the backup for you and sent the original zipped file to the trash. You
need to retrieve the original zip file from the trash and then try the import again.
Did your import fail? Sometimes importing a space may fail because the process times out or runs
out of memory. This can lead to data being left behind in your database. See After a failed space
import, it's not possible to re-import because of leftover space data for more information.

Workaround for restoring spaces from Confluence 5.3 and earlier

If you need to import a space from a version prior to Confluence 5.3 into a later version of Confluence, you
can use a temporary Confluence installation to upgrade the space export to the right version number:
1. Download the same version of Confluence as the version you exported the space from (you can get
older versions of Confluence at the Confluence Downloads Archive).
2. Install that version of Confluence on a temporary server.
3. Import the space into this temporary Confluence site.
4. Upgrade Confluence on your temporary site to the same version as the site where you want to import
the space (see Upgrading Confluence for instructions).
5. Export the space from your temporary Confluence site (it'll now have the right version number).
6. Import the space into your production Confluence site.

Restoring a Test Instance from Production

See Migrating Confluence Between Servers for a more comprehensive explanation.

Many Confluence administrators will have a production instance running the "live" version of Confluence, as well
as a test instance for testing upgrades and so on. In this situation, it's quite common that the two instances are
running different versions of Confluence. This document describes how to copy the data from a production
instance to a test instance, where the production version may be different to the test version.
Before proceeding with this guide, ensure you have read and understood the normal procedure for upgrading
Confluence.

Updating a test Confluence instance with production data

Essentially, we are copying both the production home directory and database to the test instance. We then
update the database details on the test instance to point to the test database, leaving all other instance
metadata (most importantly the Confluence build number) the same as production.
1. Shut down your test instance.
2. Restore the production database to the test database server.
3. Create a backup of the confluence.cfg.xml file found in the home directory of the test instance.
4. Copy the production confluence-home directory to the test application server.
5. Open the confluence.cfg.xml which has been copied in a text editor. Change the database settings
to match the test database server. Ensure you do not point to your production database. (You can
compare with the backup you made in Step 3 if you need to get the database settings. Don't just copy this
file – you need the build number unchanged from production to indicate the database is from an older
version of Confluence.)
Before starting your test instance, you need to do the following steps to ensure no contact with production
systems.

Ensuring no contact with production systems

To ensure no contact with external systems, you will need to disable both inbound and outbound mail services.
1. Disable global outbound mail by running the following database query:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation
1. 201

SELECT * FROM BANDANA WHERE BANDANAKEY =

'atlassian.confluence.smtp.mail.accounts';

2. Disable space-level mail archiving by running the following database query:

SELECT * FROM BANDANA WHERE BANDANAKEY =

'atlassian.confluence.space.mailaccounts';

Change the 'SELECT *' to a 'DELETE' in the above queries once you are sure you want to remove the specified
accounts.
Once this is done, you can start your test instance without any mails being sent or retrieved. Think carefully
about other plugins which may access production systems (SQL macro, etc.). These should be disabled
promptly after starting the test instance.
You can create a developer license for this server and update the License Details after starting up.
Restoring Data from other Backups

Typically, Confluence data is restored from the Administration Console or from the Confluence Setup Wizard.
If you are experiencing problems restoring from an zipped XML backup file, it is still possible to restore provided
you have:
1. A backup of your home directory.
2. A backup of your database (if you're using an external database).
Instructions for this method of restoring differ depending on whether you are using the embedded database or
an external database (like Oracle, MS SQL Server, MySQL or Postgres).

Embedded Database

If you are running against the embedded database, the database is located inside the database folder of your
Confluence Home Directory. Hence, all you need to do is:
1. Retrieve the most recent backup of your home directory.
2. Unpack the Confluence distribution and point the confluence-init.properties file to this directory.

External Database

If you're using an external database, you need to do the following.

1. Prepare backups of your home directory and database (preferably backups that are dated the same).
That is, make sure the home directory is accessible on the filesystem and the database available to be
connected to.
2. If this database happens to have a different name, or is on a different server, you need to modify the jdbc
url in the confluence.cfg.xml file inside the Confluence Home Directory. The value of this property is
specified as hibernate.connection.url.
3. Unpack the Confluence distribution and point the confluence-init.properties file to the home
directory.
Retrieving File Attachments from a Backup
File attachments on pages can be retrieved from a backup without needing to import the backup into
Confluence. This is useful for recovering attachments that have been deleted by users.
Both automated and manual backups allow this, as long as the 'Include attachments' property was set. If you
want to restore pages, spaces or sites, see the Confluence Administrator's Guide instead.
Before following the instructions for recovering attachments below, we will review how backups store file and
page information.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 202

The information on this page does not apply to

Confluence Cloud.

How Backups Store File and Page Information

The backup zip file contains entities.xml, an XML file containing the Confluence content, and a directory for
storing attachments.

Backup Zip File Structure

Page attachments are stored under the attachments directory by page and attachment id. Here is an example
listing:

Listing for test-2006033012_00_00.zip

\attachments\98\10001
\attachments\98\10002
\attachments\99\10001
entities.xml

Inside the attachment directory, each numbered directory inside is one page, and the numbered file inside is one
attachment. The directory number is the page id, and the file number is the attachment id. For example, the file
\attachments\98\10001 is an attachment with page id 98 and attachment id 10001. You can read entities.xml to
link those numbers to the original filename. Entities.xml also links each page id to the page title.

Entities.xml Attachment Object

Inside the entities.xml is an Attachment object written in XML. In this example, the page id is 98, the attachment
id is 10001 and the filename is myimportantfile.doc. The rest of the XML can be ignored:

<object class="Attachment" package="com.atlassian.confluence.pages">

<id name="id">98</id>
<property name="fileName"><![CDATA[myimportantfile.doc]]></property>
...
<property name="content" class="Page"
package="com.atlassian.confluence.pages"><id name="id">10001</id>
</property>
...
</object>

Entities.xml Page Object

This XML describes a page. In this example, the page id is 98 and the title is Editing Your Files. The rest of the
XML can be ignored:

<object class="Page" package="com.atlassian.confluence.pages">

<id name="id">98</id>
<property name="title"><![CDATA[Editing Your Files]]></property>
...
</object>

Instructions for Recovering Attachments

Each file must be individually renamed and re-uploaded back into Confluence by following the instructions

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 203

below. Choose one of the three methods:

Choice A - Recover Attachments By Filename

Best if you know each filename you need to restore, especially if you want just a few files:
1. Unzip the backup directory and open entities.xml.
2. Search entities.xml for the filename and find the attachment object with that filename. Locate its page and
attachment id.
3. Using the page and attachment id from entities.xml, go to the attachments directory and open that
directory with that page id. Locate the file with the attachment id.
4. Rename the file to the original filename and test it.
5. Repeat for each file.
6. To import each file back into Confluence, upload to the original page by attaching the file from within
Confluence.

Choice B - Restore Files By Page

Best if you only want to restore attachments for certain pages:

1. Unzip the backup directory and open entities.xml.
2. Search entities.xml for the page title and find the page object with that title. Locate its page id.
3. Go to the attachments directory and open that directory with that page id. Each of the files in the directory
is an attachment that must be renamed.
4. Search entities.xml for attachment objects with that page id. Every attachment object for the page will
have an attachment id and filename.
5. Rename the file with that attachment id to the original filename and test it.
6. Repeat for each page.
7. To import each file back into Confluence, upload to the original page by attaching the file from within
Confluence.

Choice C - Restore All Files

Best if you have a small backup but want to restore many or all the attachments inside:

Following process is applicable to space export only. Site xml backups do not require page id to be
updated manually due to the nature of persistent page_id's.

1. Unzip the backup directory and open entities.xml.

2. Go to the attachments directory and open any directory. The directory name is a page id. Each of the files
in the directory is an attachment that must be renamed.
3. Search entities.xml for attachment objects with that page id. When one is found, locate the attachment id
and filename.
4. Rename the file with that attachment id to the original filename and test it.
5. Find the next attachment id and rename it. Repeat for each file in the directory.
6. Once all files in the current directory are renamed to their original filenames, search entities.xml for the
page id, eg directory name. Find the page object with that page id and locate its page title.
7. Rename the directory to the page title and move on to the next directory. Repeat for each un-renamed
directory in the attachments directory.
8. To import each file back into Confluence, upload to the original page by attaching the file from within
Confluence.
Troubleshooting failed XML site backups
Related pages:
XML site backups are only necessary for
migrating to a new database. Setting up a Enabling detailed SQL logging
test server or Establishing a reliable backup
strategy is better done with an SQL dump.

Seeing an error when creating or importing a backup?

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 204

Problem Solution

Exception while creating backup Follow instructions below

Exception while importing backup Follow Troubleshooting XML backups that fail on restore instead

Common problems

Is the export timing out or causing out of memory errors?

If your site is large, you may need to temporarily increase the memory available to Confluence. See H
ow to fix out of memory errors by increasing available memory.

Resolve Errors With Creating An XML Backup

The errors may be caused by a slightly corrupt database. If you're seeing errors such as 'Couldn't backup
database data' in your logs, this guide will help you correct the error on your own. We strongly recommend
that you backup your database and your Confluence home directory beforehand, so that you can restore
your site from those if required. If you are unfamiliar with SQL, we suggest you contact your database
administrator for assistance.

Preferable solution

The Production Backup Strategy is a very reliable and more efficient way to do backups. If you are running
into problems with XML backups - whether memory related or because of problems like the one described
here - use the native backup tool as an alternate solution.

To Identify And Correct The Problem

To work out where the data corruption or problems are, increase the status information reported during
backup, then edit the invalid database entry:
1. Stop Confluence.
2. If you have an external database, use a database administration tool to create a manual database
backup.
3. Backup your Confluence home directory. You will be able to restore your whole site using this and the
database backup.
4. Open the my_confluence_install/confluence/WEB-INF/classes/log4j.propertiesand
add this to the bottom and save:

log4j.logger.com.atlassian.confluence.importexport.impl.XMLDatab
inder=DEBUG, confluencelog
log4j.additivity.com.atlassian.confluence.importexport.impl.XMLD
atabinder=false

5. Find your atlassian-confluence.log. Move or delete all existing Confluence logs to make it easier to
find the relevant logging output.
6. Restart Confluence and login.
7. Begin a backup so that the error reoccurs.
8. You must now check your log files to find out what object could not be converted into XML format.
Open confluence-home/logs/atlassian-confluence.log. Scroll to the bottom of the file.
9. Do a search for 'ObjectNotFoundException'. You should see an error similar to this:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 205

01 2005-08-24 00:00:33,743 DEBUG

[DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing
object: com.atlassian.confluence.core.ContentPermission with ID:
5 to XML.
02 2005-08-24 00:00:33,743 DEBUG
[DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing
property: type
03 2005-08-24 00:00:33,743 DEBUG
[DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing
property: group
04 2005-08-24 00:00:33,743 DEBUG
[DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing
property: expiry
05 2005-08-24 00:00:33,743 DEBUG
[DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing
property: content
06 [DOCPRIV2:ERROR] LazyInitializer - Exception initializing
proxy <net.sf.hibernate.ObjectNotFoundException: No row with the
given identifier exists: 2535,
07 of class:
com.atlassian.confluence.core.ContentEntityObject>net.sf.hiberna
te.ObjectNotFoundException:
08 No row with the given identifier exists: 2535, of class:
com.atlassian.confluence.core.ContentEntityObject
09 at
net.sf.hibernate.ObjectNotFoundException.throwIfNull(ObjectNotFo
undException.java:24)
10 at
net.sf.hibernate.impl.SessionImpl.immediateLoad(SessionImpl.java
:1946)
11 at
net.sf.hibernate.proxy.LazyInitializer.initialize(LazyInitialize
r.java:53)
12 at
net.sf.hibernate.proxy.LazyInitializer.initializeWrapExceptions(
LazyInitializer.java:60)
13 at
net.sf.hibernate.proxy.LazyInitializer.getImplementation(LazyIni
tializer.java:164)
14 at
net.sf.hibernate.proxy.CGLIBLazyInitializer.intercept(CGLIBLazyI
nitializer.java:108)
15 at
com.atlassian.confluence.core.ContentEntityObject$$EnhancerByCGL
IB$$cc2f5557.hashCode(<generated>)
16 at java.util.HashMap.hash(HashMap.java:261)
17 at java.util.HashMap.containsKey(HashMap.java:339)
18 at
com.atlassian.confluence.importexport.impl.XMLDatabinder.toGener
icXML(XMLDatabinder.java:155)

10. Open a DBA tool such as DbVisualizer and connect to your database instance. Scan the table names
in the schema. You will have to modify a row in one of these tables.
11. To work out which table, open atlassian-confluence.log, check the first line of the exception.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 206
11.

This says there was an error writing the ContentPermission object with id 5 into XML. This
translates as the row with primary key 5 in the CONTENTLOCK tableneeds fixing. To work out what
table an object maps to in the database, here's a rough guide:
Pages, blogposts, comments --> CONTENT table
attachments --> ATTACHMENTS table
More information can be found in the schema documentation
12. Now you must find the primary key of the incorrect row in this table. In this case, you can check the
first line and see that the row has a primary key of 5.
13. Each property is written to a column, so the last property that was being written has the incorrect
value. The row being written to when the exception was thrown was CONTENT (line 5) with a value of 2
535 (line 6). Now you know the column and value. This value 2535 is the id of an entry that no longer
exists.
14. Using a database administrative tool, login ot the Confluence database. Locate the row in the relevant
table and correct the entry. Check other rows in the table for the default column value, which may be
null, 0 or blank. Overwrite the invalid row value with the default.
15. Restart Confluence.
16. Attempt the backup again. If the backup fails and you are stuck, please lodge a support request with
your latest logs.

Troubleshooting "Duplicate Key" related problems

If you are encountering an error message such as:

could not insert:

[bucket.user.propertyset.BucketPropertySetItem#bucket.user.propertyse
t.BucketPropertySetItem@a70067d3]; SQL []; Violation of PRIMARY KEY
constraint 'PK_OS_PROPERTYENTRY314D4EA8'. Cannot insert duplicate key
in object 'OS_PROPERTYENTRY'.; nested exception is
java.sql.SQLException: Violation of PRIMARY KEY constraint
'PKOS_PROPERTYENTRY_314D4EA8'. Cannot insert duplicate key in object
'OS_PROPERTYENTRY'.

this indicates that the Primary Key constraint 'PK_OS_PROPERTYENTRY_314D4EA8' has duplicate entries
in table 'OS_PROPERTYENTRY'.
You can locate the constraint key referring to 'PK_OS_PROPERTYENTRY_314D4EA8' in your table
'OS_PROPERTYENTRY' and locate any duplicate values in it and remove them, to ensure the "PRIMARY
KEY" remains unique. An example query to list duplicate entries in the 'OS_PROPERTYENTRY' table is:

SELECT ENTITY_NAME,ENTITY_ID,ENTITY_KEY,COUNT(*) FROM

OS_PROPERTYENTRY GROUP BY ENTITY_NAME,ENTITY_ID,ENTITY_KEY HAVING
COUNT(*)>1

To Help Prevent This Issue From Reoccuring

1. If you are using the embedded database, be aware that it is bundled for evaluation purposes and does
not offer full transactional integrity in the event of sudden power loss, which is why an external
database is recommended for production use. You should migrate to an external database.
2. If you are using an older version of Confluence than the latest, you should consider upgrading at this
point.

Troubleshooting XML backups that fail on restore

XML site backups are only necessary for

migrating to a new database. Upgrading
Confluence, Setting up a test server or Prod
uction Backup Strategy is better done with
an SQL dump.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 207

Seeing an error when creating or importing a site or On this page:

space backup?
Common problems
Problem Solution Resolve Errors When Attempting
To Restore An XML Backup
Exception while See Troubleshooting Troubleshooting "Duplicate
creating backup failed XML site backups Entry" for key "cp_" or
"cps_"
Exception while See instructions below Troubleshooting "Duplicate
importing backup Key" related problems
Troubleshooting
"net.sf.hibernate.PropertyV
alueException: not-null"
related problems
To Help Prevent this Issue
from Recurring
Related Topics:
Troubleshooting failed XML site
backups

Common problems

To upload and import a small site:

1. Go to

> General Configuration > Backup and Restore.

2. Under Upload a site or space export file, click Choose File and browse for your space export file.
3. Uncheck Build Index if you want to create the index at a later stage.
4. Choose Upload and import.
To import a site from the home directory:
1. Copy your export file to <confluence-home>/restore.
(If you're not sure where this directory is located, the path is listed in the Backup and Restore screen)
2. Go to

> General Configuration > Backup and Restore.

3. Select your site export file under Import from home directory
4. Uncheck Build Index if you want to create the index at a later stage.
5. Choose Import.

Resolve Errors When Attempting To Restore An XML Backup

The errors may be caused by a slightly corrupt database. You will need to find the XML backup file entry that
is violating the DB rules, modify the entry and recreate the XML backup:
1. On the instance being restored, follow the instructions to disable batched updates (for simpler
debugging), log SQL queries and log SQL queries with parameters at Enabling Detailed SQL
Logging.
2. Once all three changes have been made, restart Confluence.
3. Attempt another restore.
4. Once the restore fails, check your log files to find out what object could not be converted into XML
format. For Confluence distribution users, check your Confluence install directory under the /logs/ a
nd check both atlassian-confluence.log and catalina.out file. The correct file will contain
SQL debug output.
5. Scroll to the bottom of the file and identify the last error relating to a violation of the database
constraint. For example:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 208

2006-07-13 09:32:33,372 ERROR

[confluence.importexport.impl.ReverseDatabinder] endElement
net.sf.hibernate.exception.ConstraintViolationException:
could not insert:
[com.atlassian.confluence.pages.Attachment#38]
net.sf.hibernate.exception.ConstraintViolationException: could
not insert: [com.atlassian.confluence.pages.Attachment#38]
...
Caused by: java.sql.SQLException: ORA-01400: cannot insert NULL
into ("CONFUSER"."ATTACHMENTS"."TITLE")
at
oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError
.java:112)
at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331)
at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:288)

This example indicates a row in your attachment table with ID = 38 that has a null title.
6. Go to the server that the backup was created on. You must have a copy of the database from which
the backup was created. If you do not have this, use a DBA tool to restore a manual backup of the
database.
7. Open a DBA tool and connect to the original database instance and scan the table names in the
schema. You will have to modify a row in one of these tables.
8. To work out which table, open catalina.out, check the first line of the exception. To work out what
table an object maps to in the database, here's a rough guide:
Pages, blogposts, comments --> CONTENT table.
attachments --> ATTACHMENTS table.
9. To correct the example error, go to the attachment table and find that attachment object with id 38.
This will have a a null title. Give a title using the other attachments titles as a guide. You may have a
different error and should modify the database accordingly.
10. Once the entry has been corrected, create the XML backup again.
11. Import the backup into the new version.
12. If the import succeeds, revert the changes made in your SQL logging to re-enable disable batched
updates and turn off log SQL queries and log SQL queries with parameters.
13. Restart Confluence.

Troubleshooting "Duplicate Entry" for key "cp_" or "cps_"

If you are encountering an error message such as:

com.atlassian.confluence.importexport.ImportExportException: Unable
to complete import because the data does not match the constraints in
the Confluence schema. Cause:
MySQLIntegrityConstraintViolationException: Duplicate entry
'1475804-Edit' for key 'cps_unique_type'

This indicates that the XML export came from a version of Confluence with a corrupt permissions database,
caused by some 3rd party plugin. This is an issue that was fixed when CONF-22123 was implemented in
Confluence 3.5.2. The simplest workaround is to export the space again after upgrading the instance to 3.5.2
or above. If that is not an option, then either the export will need to be edited manually to remove the
duplicate permission entries or the source instance will need to have the offending entries removed. The
following SQL queries can be used to look for such entries:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 209

SELECT * FROM CONTENT_PERM WHERE USERNAME IS NULL AND GROUPNAME IS

NULL;

SELECT cp.ID, cp.CP_TYPE, cp.USERNAME, cp.GROUPNAME, cp.CPS_ID,

cp.CREATOR,
cp.CREATIONDATE, cp.LASTMODIFIER, cp.LASTMODDATE
FROM CONTENT_PERM cp
WHERE cp.USERNAME IS NOT NULL AND cp.GROUPNAME IS NOT NULL;

SELECT cps1.ID, cps1.CONTENT_ID, cps1.CONT_PERM_TYPE FROM

CONTENT_PERM_SET cps1, CONTENT_PERM_SET cps2
WHERE cps1.ID <> cps2.ID AND
cps1.CONTENT_ID = cps2.CONTENT_ID AND
cps1.CONT_PERM_TYPE = cps2.CONT_PERM_TYPE
ORDER BY cps1.CONTENT_ID, cps1.CONT_PERM_TYPE, cps1.CREATIONDATE ASC;

SELECT cp.ID, cp.CP_TYPE, cps.CONTENT_ID,

(SELECT scps.ID FROM CONTENT_PERM_SET scps WHERE scps.CONTENT_ID =
cps.CONTENT_ID AND scps.CONT_PERM_TYPE = cp.CP_TYPE) AS
suggested_cps_id
FROM CONTENT_PERM cp, CONTENT_PERM_SET cps
WHERE cp.CPS_ID = cps.ID AND
cp.CP_TYPE <> cps.CONT_PERM_TYPE;

SELECT DISTINCT cp1.ID, cp1.CP_TYPE, cp1.USERNAME, cp1.GROUPNAME,

cp1.CPS_ID,
cp1.CREATOR, cp1.CREATIONDATE, cp1.LASTMODIFIER, cp1.LASTMODDATE
FROM CONTENT_PERM cp1, CONTENT_PERM_SET cps1, CONTENT_PERM cp2,
CONTENT_PERM_SET cps2
WHERE
cp1.CPS_ID = cps1.ID AND
cp2.CPS_ID = cps2.ID AND
cp1.ID <> cp2.ID AND
cps1.CONTENT_ID = cps2.CONTENT_ID AND
cp1.CP_TYPE = cp2.CP_TYPE AND
cp1.USERNAME = cp2.USERNAME
ORDER BY cp1.CPS_ID, cp1.CP_TYPE, cp1.USERNAME, cp1.CREATIONDATE;

SELECT DISTINCT cp1.ID, cp1.CP_TYPE, cp1.USERNAME, cp1.GROUPNAME,

cp1.CPS_ID,
cp1.CREATOR, cp1.CREATIONDATE, cp1.LASTMODIFIER, cp1.LASTMODDATE
FROM CONTENT_PERM cp1, CONTENT_PERM_SET cps1, CONTENT_PERM cp2,
CONTENT_PERM_SET cps2
WHERE
cp1.CPS_ID = cps1.ID AND
cp2.CPS_ID = cps2.ID AND
cp1.ID <> cp2.ID AND
cps1.CONTENT_ID = cps2.CONTENT_ID AND
cp1.CP_TYPE = cp2.CP_TYPE AND
cp1.GROUPNAME = cp2.GROUPNAME
ORDER BY cp1.CPS_ID, cp1.CP_TYPE, cp1.GROUPNAME, cp1.CREATIONDATE;

SELECT * FROM CONTENT_PERM_SET

WHERE ID NOT IN (SELECT DISTINCT CPS_ID FROM CONTENT_PERM);

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 210

Remove all matching entries and perform the export again.

Troubleshooting "Duplicate Key" related problems

If you are encountering an error message such as:

could not insert:

[bucket.user.propertyset.BucketPropertySetItem#bucket.user.propertyse
t.BucketPropertySetItem@a70067d3]; SQL []; Violation of PRIMARY KEY
constraint 'PK_OS_PROPERTYENTRY314D4EA8'. Cannot insert duplicate key
in object 'OS_PROPERTYENTRY'.; nested exception is
java.sql.SQLException: Violation of PRIMARY KEY constraint
'PKOS_PROPERTYENTRY_314D4EA8'. Cannot insert duplicate key in object
'OS_PROPERTYENTRY'.

This indicates that the Primary Key constraint 'PK_OS_PROPERTYENTRY_314D4EA8' has duplicate entries
in table 'OS_PROPERTYENTRY'.
You can locate the constraint key referring to 'PK_OS_PROPERTYENTRY_314D4EA8' in your table
'OS_PROPERTYENTRY' and locate any duplicate values in it and remove them, to ensure the "PRIMARY
KEY" remains unique. An example query to list duplicate entries in the 'OS_PROPERTYENTRY' table is:

SELECT ENTITY_NAME,ENTITY_ID,ENTITY_KEY,COUNT(*) FROM

OS_PROPERTYENTRY GROUP BY ENTITY_NAME,ENTITY_ID,ENTITY_KEY HAVING
COUNT(*)>1

Troubleshooting "net.sf.hibernate.PropertyValueException: not-null" related problems

If you're receiving a message like:

ERROR [Importing data task]

[confluence.importexport.impl.ReverseDatabinder] endElement
net.sf.hibernate.PropertyValueException: not-null property references
a null or transient value:
com.atlassian.user.impl.hibernate.DefaultHibernateUser.name

This means there's an unexpected null value in a table. In the above example, the error is in the name
column in the USERS table. We've also seen them in the ATTACHMENTS table.
Remove the row with the null value, redo the xml export, and reimport.

To Help Prevent this Issue from Recurring

1. If you are using the embedded database, be aware that it is bundled for evaluation purposes and does
not offer full transactional integrity in the event of sudden power loss, which is why an external
database is recommended for production use. You should migrate to an external database.
2. If you are using an older version of Confluence than the latest, you should consider upgrading at this
point.

The problem with different settings for case sensitivity varies between databases. The case
sensitivity of the database is usually set through the collation that it uses. Please vote on the existing
issue

Import a space from Confluence Cloud

This page provides information about a change to Confluence Cloud that is happening in the future.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 211

Currently, usernames are still included in space exports, so the information on this page about
attributing content by email address does not apply yet.

The user base of your Confluence Cloud and Confluence Server or Data Center sites are seperate. Although the
same people may have accounts in both sites, the way information is stored about them is different. For
example, in Confluence Cloud usernames may be replaced by email addresses, and they have an additional ID
(a random string of characters) that acts as a unique identifier.
When you import a space into Confluence we attempt to attribute content based on username. If the two
usernames match, we will attribute content to the user.
In spaces exported from Cloud, where we may not be able to match by username, we give you the choice to:
attempt to match users by their email address.
skip attributing content altogether, and instead attribute all content to 'unknown user'.
To reduce the risk of making restricted pages visible to the wrong person, imported content will always be
attributed to 'unknown user' if:
the email address is used by multiple user accounts (with different usernames), or
the user account doesn't have an email address (for example if it is private, and not included in the
export).
If your user directories are tightly managed, you can confidently choose to attribute content to existing users
based on their email address when importing a space from Cloud. But, if you allow people to change their email
address in Confluence, you may prefer to skip this, and attribute all content to 'unknown user', and then have an
administrator manually update any page restrictions.

Import a space from Confluence Cloud

To import a small space from Confluence Cloud:

1. In Confluence Cloud, export the space to XML.
2. In Confluence Server, go to

> General Configuration> Backup & Restore.

3. Scroll down to Restore Confluence Data and select your export file.
4. Choose whether to Attribute content created in Confluence Cloud to matching users in this site .
5. Choose Import.
To import a large space, the steps are the same, however we recommend dropping the export file into your
home directory, rather than uploading it via your browser. See Restoring a Space for more details.
Depending on whether you chose to attribute content, you may need to restore some permissions to the space.

About unknown users

Any Cloud user accounts found in the space export, that are not reconciled with an existing Server / Data Center
user, will appear in the Unsynced from directory list. They may be listed by email address, or by ID (depending
on whether the Cloud user has chosen to keep their email address private).
Permissions and restrictions are respected, so if a space or page is restricted to just one of these users, it will
not be visible to other people. An administrator will need to restore permissions after the import is complete.
Here's an example of how unknown users may appear in a page.

Restore permissions and restrictions

If the content you import is not attributed to existing users, there will be some work to do to restore the correct
permissions to the right people. People may not be able to see the space until you do this.

Restore space admin permissions

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 212

First step is to make sure the space has at least one space administrator. To do this:
1. Go to

> General Configuration > Space Permissions.

2. Choose Recover Permissions beside the newly imported space.
3. Choose Manage Permissions. This will take you to the Permissions page in that space.
4. Grant a user or group Space Admin permission for the space and save your changes.
If you're a member of the confluence-administrators super group, you can skip steps 2 and 3, and
navigate directly to the space.

Restore space permissions

Now that the space has at least one space admin, they can restore any other permissions.
1. Go to the space and choose Space tools > Permissions from the bottom of the sidebar
2. Grant each user the desired permissions. It can be useful to have the space permissions screen in
Confluence Cloud open while you do this.
As long as any groups are named the same in Cloud and Server / Data Center you shouldn't need to make any
changes to groups. If your groups aren't named the same, you can add any relevant groups at this point.

Restore page restrictions

Pages with view restrictions applied in Confluence Cloud may be associated with unknown users in Server /
Data Center. This means the pages won't be visible.
Space admins can remove individual page restrictions
1. Go to the space and choose Space tools > Permissions from the bottom of the sidebar
2. Go to the Restricted Pages tab. Any pages with view or edit restrictions will be listed.
3. Click the padlock icon beside the page to remove one of the View restrictions.
4. If the page is still restricted, use your browser back button and click the padlock beside another View
restriction. Repeat this process until enough restrictions have been removed that you can see the page
(you'll land on Page Information).
5. Choose

> Restrictions.
6. You can now reinstate the view and edit restrictions. It can be useful to have the Cloud page open to refer
to.
Removing restrictions so that you can see the page may mean that the page becomes temporarily visible to
others. If this is a concern you can either apply a temporary view restriction to a parent page, or perhaps remove
space permissions until you've finished restoring the right view restrictions.

Understanding the risks

When importing a space from Confluence Cloud, there's a small risk that content is attributed to the wrong user,
which would make any restricted pages visible to the wrong person. This is because the only information we can
use to match the user is their email address, which can be changed by the user themselves or by an
administrator.
It's essential that email addresses are associated with the correct user accounts. Content may be attributed to
the wrong user account if the email address has been changed maliciously, or accidentally, for example if a
username and email combination has been reused, so that a former and current employee share the same
username and email address.
We mitigate this risk by only associating content to user accounts that have a unique email address. We don't
match accounts with no email address, or where the same email address has been used for multiple user
accounts with different usernames, even if they exist in different user directories.
However, if the space you are importing is sensitive, you may want to manually check whether there have been
any changes to email addresses recently, before importing a space from Confluence Cloud.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 213

Attachment Storage Configuration

By default Confluence stores attachments in the On this page:
home directory (e.g. in a file system).
Attachment Storage Options
To configure Confluence attachment storage: Local File System
Database (deprecated)
Choose the cog icon
WebDav (deprecated)
Migrating to a supported
, then choose General Configuration attachment storage option
Choose Attachment Storage.
Related pages:
Working with Confluence Logs

Attachment Storage Options

Earlier Confluence versions allowed attachments to be stored in WebDav or the Confluence database. This
is not an option for new installations.

Local File System

By default, Confluence stores attachments in the attachments directory within the configured Confluence
home folder.

Database (deprecated)

Confluence 5.4 and earlier gives administrators the option to store attachments in the database that
Confluence is configured to use.

While storing attachments in the database can offer some advantages (such as ease of backup, and
avoiding issues with some characters in attachment filenames), please be aware that the amount of
space used by the database will increase because of greater storage requirements.

WebDav (deprecated)

WebDav is no longer available as an attachment storage option.

This has no impact on your ability to configuring a WebDAV client to access spaces, pages or attachments in
your Confluence site.

Migrating to a supported attachment storage option

If you are storing attachments in WebDav or your database, you can migrate to storing attachments in the file
system. When migrating attachments from your database to a filesystem, the attachments are removed from
the database after migration.

When the migration occurs, all other users will be locked out of the Confluence instance. This is to
prevent modification of attachments while the migration occurs. Access will be restored as soon as
the migration is complete.

To improve logging during the migration, add the package com.atlassian.confluence.pages.persis

tence.dao with level DEBUG. See Configuring Logging for more information.

To migrate, follow the steps below:

1. Go to

> General Configuration > Attachment storage.

2. Click Edit to modify the configuration.
3.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 214

3. Select Locally in Confluence home directory.

4. Click Save to save the changes.
5. A screen will appear, asking you to confirm your changes. Clicking 'Migrate' will take you to a screen
that displays the progress of the migration.
Screenshot: migration warning

The following external website provides further information on migrating attachments from database to file
system storage that you might find helpful - https://www.scandio.de/blog/de/2013/05/confluence-attachment-
migration-the-safe-way-2.

Configuring Attachment Size

Related pages:
You can limit the size of files that can be uploaded Recognized System Properties
and attached in Confluence.
Files
To configure the maximum file size that can be
uploaded:
1. Go to

> General Configuration.

2. Choose Edit.
3. Enter the maximum size next to Attachment
Maximum Size.
The default is 100 MB.
4. Choose Save.

How attachments are indexed

When a file is uploaded, Confluence will attempt to extract and index its text. This allows people to search for
the content of a file, not just the filename. This process is quite memory intensive and can cause out of
memory errors when very large files are uploaded. Confluence has a number of safeguards to prevent this
happening:
If the uploaded file is larger than 100 MB, Confluence will not attempt to extract text or index the file
contents. Only the filename will be searchable.
If the uploaded file is one of the following types, Confluence will only extract up to:
1 MB of text from Excel (.xlsx)
8 MB of text from PDF (.pdf)
10 MB of text from other text files (including .txt, .xml, .html, .rtf etc)
16 MB of text from Word (.docx)
If the text extracted from the file was greater than 1 MB, it will be searchable, but Confluence will not
show this text as an excerpt with the search result.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 215

If Confluence stops extracting text, only a portion of the file's content will be searchable.
Confluence will only attempt to extract and index the file once. If it fails, it will not try again.
Some of the values above are configurable via system properties. If you experience out of memory errors
when people upload large files, you may want to reduce these limits further, using the following properties:
atlassian.indexing.attachment.maxsize
officeconnector.excel.extractor.maxlength
officeconnector.textextract.word.docxmaxsize
atlassian.indexing.contentbody.maxsize

Hierarchical File System Attachment Storage

The way attachments are stored changed significantly in Confluence 3.0. If you are upgrading from
Confluence 2.10 or earlier see Upgrading Confluence for recommended upgrade paths, and read the
version of the Hierarchical File System Attachment Storage page in our Confluence 3.0 documentation
which provides more detail about migrating to the new file system structure.

Confluence stores attachments, such as files and images, in a file system. Confluence's attachment storage
layout is designed to:
1. Limit the number of entries at any single level in a directory structure (as some file systems have a limit
on the number of files that can be stored in a directory).
2. Partition attachments per space making it possible for a system admin to selectively back up attachments
from particular spaces.
Attachments in Confluence have a number of identifying attributes: content id of the file itself, the space id and c
ontent id of the page the file is attached to. This means the file logically belongs to a piece of content which
logically belongs in a space (not all content belongs to a space). For files within a space in Confluence, the
directory structure is typically 8 levels, with the name of each directory level based on the following algorithm:

level Derived From

1 (top) Always 'ver003' indicating the Confluence version 3

storage format

2 The least significant 3 digits of the space id, modulo

250

3 The next 3 least significant digits of the space id,

modulo 250

4 The full space id

5 The least significant 3 digits of the content id of the

page the file is attached to, modulo 250

6 The next 3 least significant digits of the content id of

the page the file is attached to, modulo 250

7 The full content id of the page the file is attached to

8 The full content id of the attached file

9 These are the files, named with the version number

of the file, e.g. 1, 2, 6.

The modulo calculation is used to find the remainder after division, for example 800 modulo 250 = 50.
An example:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 216

To find the directory where attachments for a particular space are stored, go to <confluence
url>/admin/findspaceattachments.jsp and enter a space key. It will return the directory on the file
system where attachments for that space are stored.
File D in the above diagram is stored in a slightly different structure. Files that are not conceptually within a
space replace the level 2 - 4 directories with a single directory called 'nonspaced'. Examples of such files are the
global site logo and attachments on unsaved content.

Extracted text files

When a text based file is uploaded in Confluence (for example Word, PowerPoint, etc), its text is extracted and
indexed so that people can search for the content of a file, not just the filename. We store the extracted text so
that when that file needs to be reindexed, we don't need to re-extract the content of the file.
The extracted text file will be named with the version number, for example 2.extracted_text, and stored
alongside the file versions themselves (within level 8 in the explanation above). We only keep the extracted text

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 217

for the latest version, not earlier versions of a file.

Confluence Data Model
This document provides a diagram of the On this page:
Confluence schema and a conceptual overview of Database diagrams
the data model. Database tables and references
Authentication
Notes:
Content
The Hibernate mapping files are the Clustering
authoritative reference for the Confluence System information
data model. These are the *.hbm.xml files Spaces
which you will find in the main Confluence Appearance
JAR file (<CONFLUENCE-INSTALLATION>\c Miscellaneous
onfluence\WEB-INF\lib\confluence-
x.x.x.jar).
The tables, columns and other attributes are
likely to change with each major release of
Confluence. To find the exact DDL of your
Confluence site, please run a query after
installation.

Database diagrams

We find that creating your own visualization of the Confluence database can be useful if you want to focus
on particular tables or relationships. There are a number of tools you can use to create a visualization. Your
own database tool may have options to do this.
View our visualization (excludes some tables, including ActiveObjects tables)
We used DbVisualizer. See Viewing Table Relationships in the DbVis documentation to find out how it's
done.

Database tables and references

Expand the link below to see a table of the primary and foreign keys for each table.
Click here to show/hide the table...
Note that Marketplace apps can also add tables to your database.

Primary Key Table Name Primary Key Foreign Key Table Name Foreign Key Column
Column Name Name

AUDITRECORD AUDITRECORDID AUDIT_AFFECTED_OBJECT AUDITRECORDID

AUDITRECORD AUDITRECORDID AUDIT_CHANGED_VALUE AUDITRECORDID

CONTENT CONTENTID ATTACHMENTDATA ATTACHMENTID

CONTENT CONTENTID BODYCONTENT CONTENTID

CONTENT CONTENTID CONFANCESTORS DESCENDENTID

CONTENT CONTENTID CONFANCESTORS ANCESTORID

CONTENT CONTENTID CONTENT PARENTCOMMENTID

CONTENT CONTENTID CONTENT PARENTCCID

CONTENT CONTENTID CONTENT PREVVER

CONTENT CONTENTID CONTENT PARENTID

CONTENT CONTENTID CONTENT PAGEID

CONTENT CONTENTID CONTENT_LABEL CONTENTID

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 218

CONTENT CONTENTID CONTENT_PERM_SET CONTENT_ID

CONTENT CONTENTID CONTENT_RELATION SOURCECONTENTID

CONTENT CONTENTID CONTENT_RELATION TARGETCONTENTID

CONTENT CONTENTID CONTENTPROPERTIES CONTENTID

CONTENT CONTENTID EXTRNLNKS CONTENTID

CONTENT CONTENTID IMAGEDETAILS ATTACHMENTID

CONTENT CONTENTID LIKES CONTENTID

CONTENT CONTENTID LINKS CONTENTID

CONTENT CONTENTID NOTIFICATIONS CONTENTID

CONTENT CONTENTID SPACES SPACEDESCID

CONTENT CONTENTID SPACES HOMEPAGE

CONTENT CONTENTID TRACKBACKLINKS CONTENTID

CONTENT CONTENTID USERCONTENT_RELATION TARGETCONTENTID

CONTENT_PERM_SET ID CONTENT_PERM CPS_ID

CWD_APP_DIR_MAPPING ID CWD_APP_DIR_GROUP_MAPPING APP_DIR_MAPPING_ID

CWD_APP_DIR_MAPPING ID CWD_APP_DIR_OPERATION APP_DIR_MAPPING_ID

CWD_APPLICATION ID CWD_APP_DIR_GROUP_MAPPING APPLICATION_ID

CWD_APPLICATION ID CWD_APP_DIR_MAPPING APPLICATION_ID

CWD_APPLICATION ID CWD_APPLICATION_ADDRESS APPLICATION_ID

CWD_APPLICATION ID CWD_APPLICATION_ATTRIBUTE APPLICATION_ID

CWD_DIRECTORY ID CWD_APP_DIR_GROUP_MAPPING DIRECTORY_ID

CWD_DIRECTORY ID CWD_APP_DIR_MAPPING DIRECTORY_ID

CWD_DIRECTORY ID CWD_DIRECTORY_ATTRIBUTE DIRECTORY_ID

CWD_DIRECTORY ID CWD_DIRECTORY_OPERATION DIRECTORY_ID

CWD_DIRECTORY ID CWD_GROUP DIRECTORY_ID

CWD_DIRECTORY ID CWD_GROUP_ATTRIBUTE DIRECTORY_ID

CWD_DIRECTORY ID CWD_USER DIRECTORY_ID

CWD_DIRECTORY ID CWD_USER_ATTRIBUTE DIRECTORY_ID

CWD_GROUP ID CWD_GROUP_ATTRIBUTE GROUP_ID

CWD_GROUP ID CWD_MEMBERSHIP CHILD_GROUP_ID

CWD_GROUP ID CWD_MEMBERSHIP PARENT_ID

CWD_USER ID CWD_MEMBERSHIP CHILD_USER_ID

CWD_USER ID CWD_USER_ATTRIBUTE USER_ID

CWD_USER ID CWD_USER_CREDENTIAL_RECORD USER_ID

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 219

EXTERNAL_ENTITIES ID EXTERNAL_MEMBERS EXTENTITYID

GROUPS ID EXTERNAL_MEMBERS GROUPID

GROUPS ID LOCAL_MEMBERS GROUPID

KEYSTORE KEYID TRUSTEDAPP PUBLIC_KEY_ID

LABEL LABELID CONTENT_LABEL LABELID

LABEL LABELID NOTIFICATIONS LABELID

OS_GROUP ID OS_USER_GROUP GROUP_ID

OS_USER ID OS_USER_GROUP USER_ID

PAGETEMPLATES TEMPLATEID CONTENT_LABEL PAGETEMPLATEID

PAGETEMPLATES TEMPLATEID PAGETEMPLATES PREVVER

SPACES SPACEID CONTENT SPACEID

SPACES SPACEID NOTIFICATIONS SPACEID

SPACES SPACEID PAGETEMPLATES SPACEID

SPACES SPACEID SPACEPERMISSIONS SPACEID

TRUSTEDAPP TRUSTEDAPPID TRUSTEDAPPRESTRICTION TRUSTEDAPPID

USER_MAPPING USER_KEY CONTENT CREATOR

USER_MAPPING USER_KEY CONTENT LASTMODIFIER

USER_MAPPING USER_KEY CONTENT USERNAME

USER_MAPPING USER_KEY CONTENT_LABEL OWNER

USER_MAPPING USER_KEY CONTENT_PERM CREATOR

USER_MAPPING USER_KEY CONTENT_PERM LASTMODIFIER

USER_MAPPING USER_KEY CONTENT_PERM USERNAME

USER_MAPPING USER_KEY CONTENT_RELATION CREATOR

USER_MAPPING USER_KEY CONTENT_RELATION LASTMODIFIER

USER_MAPPING USER_KEY EXTRNLNKS CREATOR

USER_MAPPING USER_KEY EXTRNLNKS LASTMODIFIER

USER_MAPPING USER_KEY FOLLOW_CONNECTIONS FOLLOWEE

USER_MAPPING USER_KEY FOLLOW_CONNECTIONS FOLLOWER

USER_MAPPING USER_KEY LABEL OWNER

USER_MAPPING USER_KEY LIKES USERNAME

USER_MAPPING USER_KEY LINKS CREATOR

USER_MAPPING USER_KEY LINKS LASTMODIFIER

USER_MAPPING USER_KEY LOGININFO USERNAME

USER_MAPPING USER_KEY NOTIFICATIONS CREATOR

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 220

USER_MAPPING USER_KEY NOTIFICATIONS LASTMODIFIER

USER_MAPPING USER_KEY NOTIFICATIONS USERNAME

USER_MAPPING USER_KEY PAGETEMPLATES CREATOR

USER_MAPPING USER_KEY PAGETEMPLATES LASTMODIFIER

USER_MAPPING USER_KEY SPACEPERMISSIONS CREATOR

USER_MAPPING USER_KEY SPACEPERMISSIONS LASTMODIFIER

USER_MAPPING USER_KEY SPACEPERMISSIONS PERMUSERNAME

USER_MAPPING USER_KEY SPACES CREATOR

USER_MAPPING USER_KEY SPACES LASTMODIFIER

USER_MAPPING USER_KEY TRACKBACKLINKS CREATOR

USER_MAPPING USER_KEY TRACKBACKLINKS LASTMODIFIER

USER_MAPPING USER_KEY USER_RELATION SOURCEUSER

USER_MAPPING USER_KEY USER_RELATION TARGETUSER

USER_MAPPING USER_KEY USER_RELATION CREATOR

USER_MAPPING USER_KEY USER_RELATION LASTMODIFIER

USER_MAPPING USER_KEY USERCONTENT_RELATION SOURCEUSER

USER_MAPPING USER_KEY USERCONTENT_RELATION CREATOR

USER_MAPPING USER_KEY USERCONTENT_RELATION LASTMODIFIER

USERS ID LOCAL_MEMBERS USERID

The following sections describe the principal tables involved in each logical area of Confluence –
authentication, content, system information, and so on.

Authentication

This section describes the tables involved in user authentication, which is implemented via the Atlassian
Crowd framework embedded in Confluence.

Table Description

cwd_user Information for each user in Confluence.

cwd_group The groups to which users can belong.

cwd_membership Mapping the membership of users to groups.

cwd_directory The user directories in your Confluence site. Examples of directories are the
Confluence internal directory, or an LDAP directory.

cwd_application The applications (Jira, Confluence, and so on) defined in the authentication
framework.

Content

This section describes the tables involved in storing content. Content is the information that Confluence users
are storing and sharing.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 221

Table Description

attachmentdata The binary data for attached files. This table is only used in older Confluence
versions where Confluence was configured to store attachments in the
database. Otherwise, attachments are stored in the local file system.

attachments Metadata for the files attached to Confluence pages.

bodycontent The content of Confluence pages. No version information or other metadata

is stored here. That is all in the content table.

content A persistence table for the ContentEntityObject class of objects. The

subclass is indicated by the contenttype column.

content_label Arbitrary text labels for content.

label The other half of the content_label system.

content_perm Content-level permissions objects.

content_perm_set A one-to-many mapping for content items and their permissions, with added
metadata.

pagetemplates The back end of the templates feature.

likes The pages and other content liked by a particular user.

follow_connections A mapping of users who are following other users.

Clustering

The following table contains information about clustered Confluence sites.

Table Description

clustersafety Normally, this table only contains one row. The value of the safetynumber is what
Confluence uses to find out whether another Confluence site is sharing its database
without being part of the cluster.

journalentry The journal service keeps the search index in synch across each Confluence node.

System information

These tables store data related to the status and configuration of the Confluence site.

Table Description

confversion Used by the upgrade system to determine what to expect from the database, so
as to negotiate upgrades.

plugindata A record of the plugins that have been installed, and when.
data is a blob of the actual plugin JAR file. This is principally cluster-related.

diagnosticalerts The diagnostics tool continuously checks for symptoms or behaviours that we
know may contribute to problems in your site. Events are stored for a limited
amount of time in this table.

Spaces

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 222

This table is related to the management of spaces.

Table Description

spaces Information about the spaces themselves: key, human-friendly name and numeric ID.

Appearance

The following table contains information about the look and feel of your Confluence site.

Table Description

decorator The custom display templates used to customize Velocity layouts.

Miscellaneous

This section includes other tables worth commenting on.

Table Description

os_propertyentry Arbitrary association of entities and properties.

bandana A catch-all persistence layer. This table contains things like user settings
and space- and global-level configuration data, and is used as storage by
plugins such as the Dynamic Task List plugin. Essentially, for storing
arbitrary data that doesn't fit anywhere else.

extrnlnks Referral links.

hibernate_unique_key Used by the high/low ID generator – the subsystem which generates our
primary keys.
If you interfere with this table, you may not be able to create objects in
Confluence.

indexqueueentries Manages full-content indexing across the system. The table generally
contains the last 12 hours (approximately) of updates, to allow re-syncing
of cluster nodes after restarts.

keystore Used by the trusted apps framework to store the server's private key, and
other servers' public keys.

links Tracks links within the server (that is, across and within spaces).

notifications Stores page- and space-level watches.

trackbacklinks Trackback links.

confancestors Used to speed up permissions checks, by allowing quick lookup of all a

page's ancestors.

Finding Unused Spaces

Sometimes, you want to know what is not being used. It's great to know what's getting most attention, but what
about stagnant pages, or even entire spaces that are no longer active?
While viewing space activity can provide hints, it doesn't always provide enough detail. It is possible to find out
this information directly from the database.

The following query identifies the last date on which content was modified in each space within a single
Confluence instance:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 223

SELECT spaces.spacename, MAX(content.lastmoddate)

FROM content, spaces
WHERE content.spaceid = spaces.spaceid
GROUP BY spaces.spacename;

It returns a list of space names, and the last date and time at which any content was added or changed.
Alternatively, this query identifies spaces where the content hasn't changed since a specified date:

SELECT spaces.spacename, spaces.spacekey

FROM content, spaces
WHERE content.spaceid = spaces.spaceid
GROUP BY spaces.spacename, spaces.spacekey
HAVING MAX(content.lastmoddate) < '2006-10-10';

The result is a simple list of space names and corresponding space keys.
Data Import and Export
Confluence administrators and users can import data into Confluence from a number of sources. The
permissions required differ, depending on the scope of the import. See Import Content Into Confluence.
You can also export Confluence content to various formats. See Export Content to Word, PDF, HTML and XML.

Related pages:
Managing Confluence Data
Confluence Administrator's Guide

Import a Text File

Confluence allows you to import text files from a directory on the Confluence Related pages:
server, and convert them into Confluence pages. Each file is imported as a
separate Confluence page with the same name as the file. Import
Content
Into
The text file may contain plain text, HTML or Confluence Confluenc
storage format e
You need to be part of the confluence-administrators Site
group or a System Administrator to import text files Backup
You can import pages from disk into site spaces, but not into and
personal spaces Restore
Please see Spaces for information about differences between
site spaces and personal spaces.

To make sure Confluence maintains the formatting of the text document, add <pre> to the beginning and
</pre> to the end. This will let Confluence know that it should treat the text as pre-formatted.
If you're working in a Unix-like environment, you can add the opening and closing tags to all files in a
particular directory by following these steps:
1. Go to the directory containing the files
2. Run the following command in the terminal:

for i in $(ls); do echo "<pre>" >> m$i; cat $i >> m$i; echo
"</pre>" >> m$i; mv m$i $i; done

To import text files:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 224

1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Import.
3. Type the directory path into the Import directory box.
4. Select Trim file extensions to remove file extensions from the page titles when converting the files to
Confluence pages
The Confluence pages will take their titles from the files' names (including their extensions). To avoid
having page titles with a suffix like '.txt' check this box.
5. Select Overwrite existing pages if you want to replace existing Confluence pages with the same title
with the one you're importing.
6. Choose Import.
Screenshot: Importing text files

Audit log
The audit log allows administrators to look back at changes that have been made in your site. This is useful
when you need to troubleshoot a problem or if you need to keep a record of important events, such as changes
to global permissions. You'll need Confluence Administrator permissions to view the audit log.
To view the audit log

> General Configuration > Audit log.

You can then filter the log by keyword and time to narrow down the results. Here's how it looks.

1. Filter it: dig into the log by keyword or by time.

2. More control: export the whole log or change how long to keep events
3.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 225

3. Get detailed: see the details of each change.

The audit log records information about the following events. This is not an exhaustive list, but gives you an idea
of what to expect in the log.
Spaces
Create and delete a space.
Edit space details, theme, color scheme or stylesheet.
Change space permission, including changing anonymous access.
Export and import a space.
Empty trash.
Users, groups and permissions
Add, delete, deactivate or reactivate a user.
Edit user details.
Change group membership.
Add or delete a group.
Modify permissions for a user or group.
Change global anonymous access.
Global administration
Modify global settings such as base URL, mail server, license, user directory, application links and more.
Modify global look and feel such as color scheme theme, site logo, favicon, custom HTML and more.
Install, uninstall, enable or disable apps or app modules.

The audit log doesn't record information directly relating to pages such as page edits (you can see these in the
page history) location, or changes to page restrictions.
By default, events are removed from the log after 3 years. You can choose how long to keep events in the log
settings (up to 10 years).
You can also export the log to CSV format if you'd like to explore it in more detail, or if you need to maintain a
longer term record.

Configuring Confluence
This section focuses on settings and configurations Related pages:
within the Confluence application.
Customizing your Confluence Site
For guidelines on external configuration, see Config Confluence administrator's guide
uring a Confluence Environment.
Viewing System Information
Configuring the Server Base URL
Configuring the Confluence Search and Index
Configuring Mail
Configuring Character Encoding
Other Settings
Configuring System Properties
Working with Confluence Logs
Scheduled Jobs
Configuring the Whitelist
Configuring the Time Interval at which Drafts
are Saved

Viewing System Information

The System Information screen provides information about Confluence's
configuration, which plugins are in use, and the environment in which
Confluence has been deployed.
To view your system information go to

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 226

> General Configuration > System Information. Related pages:

Notes: Cache
Statistics
The handy memory graph helps you keep track of Confluence's
Live
memory usage.
Monitoring
Your system configuration information is helpful to Atlassian Support
Using the
when diagnosing errors you may face using Confluence. When
JMX
logging a support request or bug report, please provide as much Interface
detail as possible about your installation and environment. Tracking
Customizat
ions Made
to your
Confluenc
e
Installation

Live Monitoring Using the JMX Interface

JMX (Java Management Extensions API) allows you to monitor the status of your Confluence instance in real
time. JMX uses objects called MBeans (Managed Beans) to expose data and resources from your application,
providing useful data such as the resource usage of your instance and its database latency, allowing you to
diagnose problems or performance issues.
In this page we'll guide you through how to use JConsole to monitor Confluence locally and remotely. JConsole
is included in the Java Development Kit (JDK), but you can use any JMX client.

This guide provides a basic introduction to the JMX interface and is provided as is. Our support team
can help you troubleshoot a specific Confluence problem, but aren't able to help you set up your
monitoring system or interpret the results.

Monitor Confluence locally using JConsole

If you are troubleshooting a particular issue, or only need to monitor Confluence for a short time, you can use
local monitoring. Local monitoring can have a performance impact on your server, so its not recommended for
long term monitoring of your production system.
To monitor locally:
1. Start JConsole (you'll find it in the bin directory of the JDK installation directory)
2. Select Local Process.
3. Select the Confluence process. It will be called something like org.apache.catalina.startup.Boo
tstrap start
See Using JConsole for more information on local monitoring.

Monitor Confluence remotely using JConsole

Remote monitoring is recommended for production systems, as it does not consume resources on your
Confluence server.
To monitor remotely:
1. Add the following properties to your setenv.sh / setenv.bat file. The port can be any port that is not
in use.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 227

set CATALINA_OPTS=-Dcom.sun.management.jmxremote %CATALINA_OPTS%

set CATALINA_OPTS=-Dcom.sun.management.jmxremote.port=8099
%CATALINA_OPTS%

2. Decide how you will secure your remote connection. See Remote Monitoring and Management for more
information.
Although it is possible to disable authentication, we do not recommend doing this on a production system.
3. Start JConsole (you'll find it in the bin directory of the JDK installation directory).
4. Select Remote Process.
5. Enter your hostname and port (this is the port you specified earlier, not the Confluence port).
6. Click Connect.
See Using JConsole for more information on remote monitoring.

Confluence MBeans

You can use the following Confluence MBeans to see live information about your Confluence instance.

CacheStatistics

This MBean shows information about Confluence caches. This info can also be found on the Cache Statistics pa
ge.

IndexingStatistics

This MBean shows information related to search indexing. Here's some useful attributes.

Property name Function Values

Flushing Indicate whether the cache is currently flushing True/False

LastElapsedMilliseconds Time taken during last indexing Milliseconds

TaskQueueLength Shows number of tasks in the queue Integer

ReIndexing Indicates whether Confluence is currently reindexing True/False

SystemInformation

This MBean shows information such as the Confluence version and uptime. This info can also be found on the S
ystem Information page.

Property name Function Values

DatabaseExampleLatency Shows the latency of an example Milliseconds

query performed against the
database

RequestMetrics

This MBean shows information related to system load and error pages served.

Property name Function Values

AverageExecutionTimeForLastTe Average execution time for the Milliseconds

nRequests last ten requests.

CurrentNumberOfRequestsBeing Number of requests being served Integer

Served at this instant.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 228

ErrorCount Number of times the Confluence Integer

error page was served.

NumberOfRequestsInLastTenSec The number of requests in the last Integer

onds ten seconds.

MailServer-SMTPServer

This MBean shows information related to email dispatch attempts and failures. There will be an MBean for every
SMTP Mailserver that has been configured in the Confluence instance.

Property name Function Values

EmailsAttempted The number of email messages Confluence has tried to send. Integer

EmailsSent The number of email messages sent successfully. Integer

MailTaskQueue

This MBean shows information related to the email workload.

Property name Function Values

ErrorQueueSize Number of errors in the queue. Integer

Flushing Shows state (i.e. flushing, or not) True/False

FlushStarted Time that operation began. Time

RetryCount The number of retries that were performed. Integer

TaskSize Number of email messages queued for dispatch. Integer

SchedulingStatistics

This MBean shows information related to current jobs, scheduled tasks and the time that they were last run.

Property name Function Values

AllJobNames Shows information on current String

scheduled jobs including the time
they were last run

CurrentlyRunningJobNames Lists the scheduled jobs that are List

currently running

Additional MBeans

To also monitor Hibernate and Hazelcast (Confluence Data Center only) you will need to add the following
properties to your setenv.sh / setenv.bat file first.

set CATALINA_OPTS=-Dconfluence.hazelcast.jmx.enable=true %CATALINA_OPTS%

set CATALINA_OPTS=-Dconfluence.hibernate.jmx.enable=true %CATALINA_OPTS%

This will make the Hibernate and Hazelcast MBeans available in your JMX client.

Monitoring high CPU consuming threads

The Top Threads Plugin for JConsole is useful for monitoring whether the CPU is spiking. Use the following
command to start JConsole with this plugin:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 229

JConsole -pluginpath /pathto/topthreads.jar

Tracking Customizations Made to your Confluence Installation

The 'Modification' section of the Confluence 'System Information' screen lists the files that have been
changed since your Confluence application was installed. You will find this information particularly useful when
upgrading Confluence to a new version, because you will need to re-apply all customizations after the upgrade.
To see the modifications made to files in your Confluence installation:
1. Choose the cog icon

, then choose General Configuration

2. Select 'System Information' in the 'Administration' section of the left-hand panel.
3. Scroll down to the section titled 'Modification'.
Screenshot: Modifications tracker on the Confluence System Information screen

Notes

The modification tracker does not detect changes to class files from the confluence.jar or other JAR
files. If you modify classes, the Confluence modification detection does not report the modification.
View Space Activity
Space activity information is disabled by default, and the 'Activity' tab won't
be visible unless the Confluence Usage Stats system app is enabled. See Related pages:
notes below. Page
If enabled, the space activity screen displays statistics on the activity in each History
space. These include: and Page
Compariso
How many pages and blog posts have been viewed, added or n Views
updated over a given period. Watch
Which content is the most popular (most frequently viewed). Pages,
Which content is the most active (most frequently edited). Spaces
Which people are the most active contributors/editors of content. and Blogs
How do I
To view the activity in a space:
get more
1. Go to the space and choose Space Tools at the bottom of the statistics
sidebar from
2. Choose Activity Confluenc
e?

You'll see a graphic display of the number of pages and blog posts that have been viewed, added, and
edited, showing trends over a period of time.
Screenshot: The Space Activity tab

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 230

In addition to the graphical representation of Views and Edits, the top ten most popular and most active
pages and/or blog posts will be listed, with a link to each.

Screenshot: Popular content, active content, and active contributors.

Enable Confluence Usage Stats

To enable the Confluence Usage Stats system app:

1. Go to

> Manage apps.

2. Select System from the dropdown then search for Confluence Usage Stats.
3. Expand the listing and choose Enable.

Notes

To view Space Activity the Confluence Usage Stats system plugin must be enabled. This plugin is
known to cause performance problems on large installations and is disabled by default. System
administrators can enable this system app.
The app only collects data when it's activated.
If you're using Confluence Data Center or Confluence Cloud, space activity information isn't available.
Page hits aren't unique - the graph on the Space Activity screen includes all page hits, including
multiple visits by the same user.

Viewing Site Statistics

Note that the site activity information is disabled by
default. See notes below.
If enabled, the global activity screen displays

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 231

statistics on the activity in your Confluence site. Related pages:

These include:
How do I get more statistics from
How many pages and blog posts have been Confluence?
viewed, added or updated over a given Cache Statistics
period. View Space Activity
Which spaces are the most popular (most Live Monitoring Using the JMX
frequently viewed). Interface
Which spaces are the most active (most
frequently edited).
Which people are the most active
contributors/editors of content.
To view the activity on your site:
1. Choose the cog icon

, then choose General Configuration

2. Choose 'Global Activity' in the
'Administration' section of the left-hand panel
(only appears if enabled - see below).
Screenshot: Global Activity

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 232

The top ten most popular and most active pages and/or blog posts will be listed, with a link to each.

Notes

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 233

The Confluence Usage Stats plugin, which provides the 'Global Activity' screen, is known to cause
performance problems on large installations. This plugin is disabled by default. A status report on the
progress of the performance issues with this plugin is available in this issue:
USGTRK-15 - Authenticate to see issue details .
Your Confluence system administrator can enable the plugin, but please be aware of the possible
impact upon your site's performance.
The plugin is sometimes called 'Confluence Usage Tracking'.
If your Confluence site is clustered, the global activity information will not be available.

Viewing System Properties

After adding memory, setting a proxy, or changing other Java options, it can be difficult to diagnose whether the
system has picked them up. This page tells you how to view the system properties that your Confluence site is
using.
You can see the expanded system properties on the 'System Information' screen of the Confluence
Administration Console. You do not need to restart Confluence before viewing the information.
To see the system properties recognized by your Confluence installation:
1. Choose the cog icon

, then choose General Configuration

2. Choose System Information in the left-hand panel.
3. Scroll down to the section titled System Properties.
Configuring the Server Base URL
The Server Base URL is the URL via which users access Confluence. The base URL must be set to the same
URL by which browsers will be viewing your Confluence site.
Confluence will automatically detect the base URL during setup, but you may need to set it manually if your site's
URL changes or if you set up Confluence from a different URL to the one that will be used to access it publicly.
You need to have System Administrator permissions in order to perform this function.
To configure the Server Base URL:
1. Choose the cog icon

, then choose General Configuration under Confluence Administration

2. Choose General Configuration in the left-hand panel
3. Choose Edit
4. Enter the new URL in the Server Base URL text box
5. Choose Save

Example

If Confluence is installed to run in a non-root context path (that is, it has a context path), then the server base
URL should include this context path. For example, if Confluence is running at:

http://www.foobar.com/confluence

then the server base URL should be:

http://www.foobar.com/confluence

Notes

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 234

Using different URLs. If you configure a different base URL or if visitors use some other URL to access
Confluence, it is possible that you may encounter errors while viewing some pages.
Changing the context path. If you change the context path of your base URL, you also need to make
these changes:
1. Stop Confluence.
2. Go to the Confluence installation directory and edit <installation-directory>\conf\serve
r.xml.
3. Change the value of the path attribute in the Context element to reflect the context path. For
example, if Confluence is running at http://www.foobar.com/confluence, then your path a
ttribute should look like this:

<context path="/confluence" docBase="../confluence" debug="0"

reloadable'"false" useHttpOnly="true">

In this example we've used /confluence as the context path. Note that you can't use /resourc
es as your context path, as this is used by Confluence, and will cause problems later on.
4. Save the file.
5. Restart Confluence and check you can access it at http://www.foobar.com/confluence.

Note: There's a known issue that affects some Confluence versions which can cause links to break
when the context path is changed. See
CONFSERVER-55267 - Links to internal pages and attachments are changed to a self-referential link after
changing the context path or protocol (http/https) in the base URL CLOSED
for details.
Proxies. If you are running behind a proxy, ensure that the proxy name matches the base URL. For
example: proxyName="foobar.com" proxyPort="443" scheme="https". This will make sure we
are passing the information correctly. For more information on proxing Atlassian applications, see Proxyi
ng Atlassian Server applications.
This information needs to be added in the Connector element at {CONFLUENCE_INSTALLATION}\con
f\server.xml.
Configuring the Confluence Search and Index
Confluence administrators can adjust the behavior of the Confluence search, and manage the index used by the
search.
Configuring Indexing Language
Configuring Search
Content Index Administration
Enabling OpenSearch
Rebuilding the Ancestor Table
Setting Up Confluence to Index External Sites
Setting Up an External Search Tool to Index Confluence

Related pages:
Search
Confluence Administrator's Guide

Configuring Indexing Language

Changing the indexing language to be used in your Confluence site may
improve the accuracy of Confluence search results, if the majority of the
content in your site is in a language other than English.
Confluence supports content indexing in:
Arabic
Brazilian
Chinese
CJK
Custom Japanese

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 235

Czech Related pages:

Danish
Dutch Choosing
English (default) a Default
Finish Language
French Installing a
German Language
Greek Pack
Hungarian Content
Italian Index
Norwegian Administra
Persian tion
Romanian How to
Russian Rebuild
Spanish the
Swedish Content
Indexes
To configure the indexing language: From
Scratch on
1. Go to
Confluenc
e Server
> General Configuration then choose Edit.
2. Select the Indexing Language from the dropdown list in the Formatt
ing and International Settings section.
3. Choose Save.

Configuring Search
There are a few ways to search for content in Related pages:
Confluence:
Search
Using the search panel, which allows you to
quickly search and filter results.
Using the advanced search page.
Using a search macro embedded on a
Confluence page (for example, the
Livesearch Macro or QuickNav Gadget).
Read more about the different search options in
Confluence.
By default, the search panel feature is enabled, with
the maximum number of simultaneous requests set
to 40. These options can be modified as described
below.

Set the number of simultaneous search requests

Confluence admins can set the maximum number of simultaneous searches users can perform using the
search panel. By default, the maximum is set to 40. This limit applies to a single Confluence node. If you're
running Confluence Data Center with multiple nodes, this number will increase.
If your Confluence server serves a large number of individuals who use this feature regularly, some of whom
are being denied access to it, you may wish to increase this value.
To change the maximum number of simultaneous search requests in Confluence:
1. Choose the cog icon

, then choose General Configuration

2. Choose Further Configuration in the left-hand panel.
3. Choose Edit.
4. Enter the appropriate number in the field beside Max Simultaneous Requests.
5. Choose Save.

Disable quick search options

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 236

The search panel feature offers a quick way for users to search and filter content in Confluence. We
recommend keeping this feature enabled, unless it's causing significant performance issues on your site.
If you disable the quick search option:
The search panel will no longer appear when users click the search field. When you enter a search
query, we'll take you to the advanced search page.
The Confluence QuickNav Gadget will no longer drop down a list of search results. When you enter a
search query, we'll take you to the advanced search page.
Other search macros, including the Livesearch Macro and the Page Tree Search Macro, won't be affected if
you disable the quick search option.
To disable quick search options from your Confluence site:
1. Choose the cog icon

, then choose General Configuration

2. Choose Further Configuration in the left-hand panel.
3. Choose Edit.
4. Deselect the Quick Search checkbox.
5. Choose Save.

Content Index Administration

The content index, also called the search index, On this page:
supports Confluence's search functionality. It is also
used for a number of related functions such as Viewing the content index
building email threads in the mail archive, the space summary
activity feature, and lists of recently-updated content. Rebuilding the search index
The Gliffy plugin also uses the index for some of its The 'Did You Mean' index is no
functionality. longer relevant
Slow reindexing
For reasons of efficiency, Confluence does not Viewing the index browser
immediately add content to the index. New and More hints and tips
modified Confluence content is first placed in a Related pages:
queue and the queue is processed once every five
seconds (by default). Scheduled Jobs
Search
Configuring the Confluence
Viewing the content index summary
Search and Index
To see information about your Confluence site's
content indexing:
1. Choose the cog icon

, then choose General Configuration

2. Choose 'Content Indexing' under the
heading 'Administration' in the left-hand
panel.
Screenshot: Index summary

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 237

Rebuilding the search index

The search index is maintained automatically, but you may need to rebuild it manually if your searching and
mail threading are malfunctioning, or if directed to in the upgrade notes for a new version.
To rebuild the search index:
1. Choose the cog icon

, then choose General Configuration

2. Choose 'Content Indexing' under the heading 'Administration' in the left-hand panel.
3. Choose the 'Rebuild' button in either the 'Search Index' section.
(If the indexes have never been built, its button will indicate 'Build' instead of 'Rebuild.)
Screenshot: Content indexing

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 238

The 'Did You Mean' index is no longer relevant

The 'Did You Mean' feature is no longer available in Confluence. This index is therefore redundant, and will
be removed at some time in the future.

Slow reindexing

Does the reindexing take a long time to complete? The length of time depends on the following factors:
Number of pages in your Confluence instance.
Number, type and size of attachments.
Amount of memory allocated to Confluence.
Disk throughput.
It may help to increase the heap memory allocation of Confluence by following the instructions here Increasin
g Jira application memory. The process is basically the same for Confluence or Jira applications.
If you are running an older version of Confluence and find that the index rebuild is not progressing, you may
need to shut down Confluence, and restart it with the following Java system property set: bucket.indexin
g.threads.fixed=1. This will cause the re-indexing to happen in a single thread and be much more stable
(but slower).

Viewing the index browser

Confluence uses a search engine called Lucene. If you need to see more details of the indexed pages in
your Confluence site, you can download and run Luke. Luke is a development and diagnostic tool that
accesses existing Lucene indexes and allows you to display and modify their content in several ways.
Start Luke and use it to open the index directory, located in your Confluence Home directory. For example:
c:\confluence\data\confluence-home\index.

Note: Confluence 5.2 (and later) use Lucene 4.3 (or later). If the Luke library has not been updated to
support the latest version of Lucene, you can compile Luke yourself, from the fork on Github – please read
the warnings and notes in the README file of that repository.

More hints and tips

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 239

If you are still experiencing problems after performing the above rebuild, the next step might be to rem
ove the index and rebuild it from scratch.
The space activity feature uses the index to store data. If you remove the index file, the existing
activity data will disappear.
A tip for the development community: If you have the Confluence source, you can look for references
to the SmartListManager to find the screens and lists that rely on the content index.

Enabling OpenSearch
With OpenSearch autodiscovery, you can add Confluence search to your Related pages:
Firefox or Internet Explorer search box. By default, OpenSearch
autodiscovery is enabled. This feature can be enabled or disabled as Search
described below. Confluenc
e
To enable or disable OpenSearch autodiscovery: Administra
tor's Guide
1. Choose the cog icon

, then choose General Configuration

2. Choose Further Configuration in the left-hand panel.
3. Choose Edit.
4. Select the Open Search checkbox to enable this feature (deselect to
disable).
5. Choose Save.

Information about OpenSearch

Confluence supports the autodiscovery part of the OpenSearch stand

ard, by supplying an OpenSearch description document. This is an
XML file that describes the web interface provided by Confluence's
search function.
Any client applications that support OpenSearch will be able to add
Confluence to their list of search engines.

Rebuilding the Ancestor Table

The way you fix problems with the ancestor table changed significantly in Confluence 6.14.
If you're using Confluence 6.13 or earlier, see Rebuilding the Ancestor Table in Confluence 6.13 or
earlier to find out how to rebuild the ancestor table.

The ancestor table records the parent and descendant (child) relationship between pages. It is also used when
determining whether a page will inherit view restrictions from a parent page.
Occasionally records in the ancestor table can become corrupted. The Repair the Ancestors Table scheduled
job finds and automatically fixes problems in the ancestors table. The job runs daily.

Repair the ancestor table manually

If you suspect there is a problem, you can also run this job manually.
1. Go to

> General Configuration > Scheduled Jobs.

2. Locate the Repair the Ancestors Table job and choose Run.
The job should complete quickly, and there won't be any impact on users.

Viewing the job results

If you want to see the result of the job each time it runs, you can change the logging level of com.atlassian.c
onfluence.pages.ancestors to INFO.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 240

You'll then see a message similar to the one below in the Confluence application log, each time the job runs:

Ancestors have been repaired. Found and fixed 3 broken pages.

It took 71 sec for 6407 spaces, average space processing time 0 sec.

Rebuilding the ancestor table in earlier Confluence versions

If you're using Confluence 6.13 or earlier the way you rebuild the ancestor table is different. See Rebuilding the
Ancestor Table in Confluence 6.13 or earlier for more information.
Setting Up Confluence to Index External Sites
Confluence cannot easily index external sites, due to Related pages:
the way Lucene search works in Confluence, but the
re are two alternatives: Setting Up an External Search
Tool to Index Confluence
1. Embed External Pages Into Confluence Configuring the Confluence
2. Replace Confluence Search Search and Index

Embedding external pages into Confluence

If you only have a small number of external sites to index, you may prefer to enable the HTML-include Macro
and use it embed the external content inside normal Confluence pages.

Replacing the Confluence search

Use your own programmer resources to replace Confluence's internal search with a crawler that indexes both
Confluence and external sites. This advanced option is easier than modifying the internal search engine. It
requires removing Confluence internal search from all pages and replacing the internal results page with your
own crawler front-end.
1. Setup a replacement federated search engine to index the Confluence site, as well as your other sites,
and provide the results that way. You would need to host a web crawler, such as these open-source
crawlers. Note that you can perform a search in Confluence via the Confluence API.
2. Replace references to the internal search by modifying the site layout so that it links to your search
front-end
3. Host another site containing the search front-end. You may wish to insert it into a suitable context path
in your application server so that it appears to be from a path under Confluence. Tomcat sets
Confluence's paths from the Confluence install\confluence\WEBINF\web.xml file.

Setting Up an External Search Tool to Index Confluence

Any web crawler can be configured to index Related pages:
Confluence content. If a login is required to view
content that will be indexed, you should create a Setting Up Confluence to Index
Confluence user specifically for the search crawler to External Sites
use. Grant this user view rights to all content you Configuring the Confluence
wish to index, but deny that user all delete and Search and Index
administration rights. This ensures that an
aggressive crawler will not be able to perform
actions that could modify the site.
External applications can also use the search
function in the Confluence APIs.

Configuring Mail

Configuring a Server for Outgoing Mail

Setting Up a Mail Session for the Confluence Distribution
Configuring the Recommended Updates Email Notification
The Mail Queue

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 241

Customizing Email Templates

Configuring a Server for Outgoing Mail
Configuring your Confluence server to send email On this page:
messages allows your Confluence users to:
Configuring Confluence to send
Receive emailed notifications and daily email messages
reports of updates. Testing the email settings
Send a page via email.
Related pages:
You can personalize email notifications by
configuring the 'From' field to include the name and The Mail Queue
email address of the Confluence user who made the Setting Up a Mail Session for the
change. Confluence Distribution

You need System Administrator permissions in order

to configure Confluence's email server settings.

Configuring Confluence to send email messages

To configure Confluence to send outgoing mail:

1. Go to

> General Configuration > Mail Servers. This will list all currently configured SMTP servers.
2. Click Add New SMTP Server (or edit an existing server).
3. Edit the following fields as required:
Name: By default, this is simply 'SMTP Server'.
From Address: Enter the email address that will be displayed in the 'from' field for email
messages originating from this server.
This field is mandatory. This must be an ordinary email address, you can't enter variables in this
field.
From Name: Enter the name that will be displayed in the 'from' field for email messages
originating from this server. This is the text which appears before the user's registered email
address (in square brackets).
This field accepts the following variables, which reference specific details defined in the relevant
Confluence user's profile:

Variable Description

${fullname} The user's full name.

${email} The user's email address.

${email.hostname} The domain/host name component of the user's email address.

The default is '${fullname} (Confluence)'.

Hence, if Joe Bloggs made a change to a page he was watching and the Confluence site's
'From Address' was set to [email protected], then the
'From' field in his email notification would be: Joe Bloggs (Confluence)
<[email protected]>.
Subject Prefix: Enter some text to appear at the beginning of the subject line.
4. Enter your Hostname, Port, User name and Password details.
If your SMTP host uses the Transport Layer Security (TLS) protocol select Use TLS.
OR
Specify the JNDI location of a mail session configured in your application server. For more
information on how to set up a JNDI mail session, see Setting Up a Mail Session for the Confluence
Distribution.

Testing the email settings

A Confluence administrator can test the email server as follows:

1. Set up a mail server as described above.
2.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 242

2. Click Send Test Email to check that the server is working. Check that you get the test email in your
inbox.
3. You can flush the email queue to send the email message immediately. Go to Mail Queue, and click F
lush Mail Queue. See The Mail Queue.
A user can test that notifications are working as follows:
1. Go to your user profile (using the Settings link) and edit your email preferences. See Email
Notifications.
2. Enable Notify On My Actions. (By default, Confluence does not send you notifications for your own
changes.)
3. Go to a page you wish to get notifications about.
4. Choose Watch at the top-right of the page. See Watch Pages, Spaces and Blogs.
5. Edit the page, make a change, and save the page.
6. Check your email inbox. You may need to wait a while for the email message to arrive.

Setting Up a Mail Session for the Confluence Distribution

The simplest way to set up a mail server through the Confluence Administration console. See Configuring a
Server for Outgoing Mail.
If you want to add different options or parameters you can also set up a mail session for the Confluence
distribution. In the example below we'll set up Gmail.
To set up a mail session for the Confluence distribution:
1. Stop Confluence.
2. Move (don't copy) mail-x.x.x.jar from <confluence-install>\confluence\WEB-INF\lib to
<confluence-install>\lib (x.x.x. represents the version numbers on the jar files in your
installation).
Don't leave a renamed backup of the jar files in \confluence\WEB-INF\lib. Even with a different file
name, the files will still be loaded as long as it remains in the directory.
3. Edit the <confluence-install>\conf\server.xml file and add the following at the end of the
Confluence <context> tag, just before </Context>.
Note: you're editing the <context> tag that contains the Confluence context path, not the one that contains
the Synchrony context path.

<Resource name="mail/GmailSMTPServer"
auth="Container"
type="javax.mail.Session"
mail.smtp.host="smtp.gmail.com"
mail.smtp.port="465"
mail.smtp.auth="true"
mail.smtp.user="[email protected]"
password="yourPassword"
mail.smtp.starttls.enable="true"
mail.transport.protocol="smtps"
mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"
/>

4. Restart Confluence.
5. Go to

> General Configuration > Mail Servers.

6. Choose either Edit an existing configuration, or Add a new SMTP mail server.
7. Edit the server settings as necessary, and set the JNDI Location as:

java:comp/env/mail/GmailSMTPServer

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 243

Note that the JNDI Location is case sensitive and must match the resource name specified in server.xml.
8. Save your changes and send a test email.

Configuring the Recommended Updates Email Notification

Confluence sends a regular email report to subscribers, containing the top On this page:
content that is relevant to the person receiving the message, from spaces
they have permission to view. This is called the 'Recommended Updates' Initial
notification. settings of
the
If you have Confluence Administrator or System Administrator permissions, defaults
you can configure the default settings that determine how often the Configurin
Recommended Updates notification is sent. When new users are added to g the
Confluence, the default settings will be applied to their user profiles. Recomme
nded
Confluence users can choose their personal settings, which will override the
Updates
defaults. See Email Notifications.
notification
Disabling
Initial settings of the defaults the
Recomme
When you install Confluence, the initial values of the default settings are as nded
follows: Updates
notification
The default frequency is weekly.
for the
If your Confluence site has public signup enabled, the Recommended
entire site
Updates notification is disabled by default. If public signup is not
enabled, the notification is enabled by default. Related pages:
You can change the above settings, specifying a different default value for Email
the site. Notification
s
Notes:
The Recommended Updates notification is sent only to people who
have a user profile in Confluence. If your Confluence site uses
external user management, such as LDAP, then people will receive
the report only after they have logged in for the first time. (The first
login creates their user profile.)
The daily email message is sent at 1 p.m. in the user's configured
time zone.
The weekly email message is sent at 1 p.m. on Thursdays in the
user's configured time zone.

Configuring the Recommended Updates notification

You can set the default send option (send / do not send) and the default schedule (daily or weekly).
To configure the Recommended Updates email notification:
1. Choose the cog icon

, then choose General Configuration

2. Click Recommended Updates Email in the left-hand panel.

Disabling the Recommended Updates notification for the entire site

You can also turn off the recommended updates notification for the entire site, by disabling the 'Confluence
daily summary email' system app. See Disabling and enabling apps.

The Mail Queue

Email messages waiting to be sent are queued in a mail queue and periodically flushed from Confluence once a
minute. A Confluence administrator can also manually flush messages from the mail queue.
If there is an error sending messages, the failed email messages are sent to an error queue from which you can

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 244

either try to resend them or delete them.

To view the mail queue:
1. Choose the cog icon

, then choose General Configuration

2. Choose Mail Queue in the left-hand panel. This will display the email messages currently in the queue.
3. Choose Flush Mail Queue to send all email messages immediately.
4. Choose Error Queue to view failed email messages. You can try to Resend the messages, which will
flush the mails back to the mail queue, or you can Delete them from here.
Related pages:
Configuring a Server for Outgoing Mail
Setting Up a Mail Session for the Confluence
Distribution

The information on this page does not apply to

Confluence Cloud.

Configuring Character Encoding

Confluence and your database must be configured
to use the same character encoding. To avoid On this page:
problems with character encoding always set all Configuring Confluence character
character encodings to UTF-8 (or the equivalent encoding
for your database, for example, AL32UTF8 for Database character encoding
Oracle databases). Problems with character
encodings
Related pages:
Configuring Database Character
Encoding

Configuring Confluence character encoding

By default, Confluence uses UTF-8 character encoding. Confluence has a number of checks in place to
make sure your database is also using UTF-8 (or equivalent for your database).
While it is possible to change the character encoding, it is not recommended. Changing the Confluence
character encoding will change your HTTP request and response encoding and your filesystem encoding as
used by exports and Velocity templates. You may also be prevented from restarting or upgrading
Confluence, depending on your database.
To change the Confluence character encoding (not recommended):
1. Go to

> General Configuration and choose Edit

2. Enter the new character encoding of your choice in the text box next to Encoding then Save.

Database character encoding

Your database, and the JDBC or datasource connection to it, must be configured to use UTF-8 (or the
equivalent for your database, for example, AL32UTF8 for Oracle databases). There are a number of checks
in place to warn you if your database character encoding is incorrect.
See Configuring Database Character Encoding for more information.

Problems with character encodings

See Troubleshooting Character Encodings to find out how to test your character encoding.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 245

Troubleshooting Character Encodings

If character encoding is not configured correctly in your Confluence site, you may experience problems like:
Non-ASCII characters appearing as question marks (?)
Page links with non-ASCII characters not working
Single characters being displayed as two characters
Garbled text appearing
To diagnose the problem, follow these steps.

1. Run the encoding test

Confluence includes an encoding test that can reveal problems with your configuration. You'll need to be a
Confluence admin to do this.
1. Head to <your-confluence-url>/admin/encodingtest.action
2. Follow the prompts to paste a line of text and start the test. You can also paste text in a specific
language, for example Japanese, if you're experiencing a particular problem with that language.
If the text displayed in the encoding test is different to what you entered, then there are problems with your
character encoding settings. Here's what a successful test looks like.

2. Use the same encoding for your database

Your database and Confluence must use the same character encoding. See Configuring Database Character
Encoding for more information.

3. Get help

If you're still having problems with character encoding, create a support request, and our support team will help
you solve the problem.
Include the following details to help us identify your problem:
screenshots of the problem occurring
results of the encoding test
information about your database (including version)
A copy of the information on your System Information page.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 246

"€" Euro character not displaying properly

The € (euro) symbol is a three byte character, with byte values in file (UTF-8) of 0xE2, 0x82, 0xAC.
Sometimes, if the character encoding is not set consistently among all participating entities of the system,
Confluence, server and the database, one may experience strange behavior.
...
I write a page with a Euro sign in it (€). All is well, the Euro sign shows up in the wiki markup
text-box, and the preview, and the display of the saved page.
One day later, the Euro sign has changed into a question mark upside down!
...
What is going on? Why does the Euro sign mysteriously change? How do I prevent it?
Interestingly enough the character encoding test passes with no problems, demonstrating that Confluence and
the connected Database both recognize the € symbol.
There are two potential reasons for this behavior:

Database and Confluence is using utf-8 encoding. The connection is not.

When data transferred to it via the connection which does not use utf-8 encoding gets encoded incorrectly.
Hence, updating the connection encoding may resolve this problem from now on, yet it probably would not affect
already existing data.

Database is not using utf-8. Confluence and your connection are.

If your Database encoding is not set to UTF-8, yet is using some other encoding such as latin1, it could be one
of the potential reasons why you lose the "€" characters at some stage. It could be occurring due to caching.
When Confluence saves data to the database, it may also keep a local cached copy. If the database encoding is
set incorrectly, the Euro character may not be correctly recorded in the database, but Confluence will continue to
use its cached copy of that data (which is encoded correctly). The encoding error will only be noticed when the
cache expires, and the incorrectly encoded data is fetched from the database.

For instance the latin1 encoding would store and display all 2-byte UTF8 characters correctly except
for the euro character which is replaced by '?' before being stored. As Confluence's encoding was set
to UTF-8, the 2-byte UTF-8 characters were stored in latin1 database assuming that they were two la
tin1 different characters, instead of one utf8 character. Nevertheless, this is not the case for 3-byte
utf8 characters, such as the Euro symbol.

Please ensure that you set the character encoding to UTF-8 for all the entities of your system as advised in this
guide.
MySQL 3.x Character Encoding Problems

MySQL 3.x is known to have some problems upper- and lower-casing certain (non-ASCII) characters.

Diagnosing the problem

1. Follow the instructions for Troubleshooting Character Encodings.

2. If the upper- and lower-cased strings displayed on the Encoding Test are different, then your database is
probably affected.
An example (faulty) output of the Encoding Test is shown below:
Screenshot: Encoding Test Output (excerpt)

Solution

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 247

Upgrade to a newer version of MySQL. (4.1 is confirmed to work.)

Other Settings

Configuring a WebDAV client for Confluence

Configuring HTTP Timeout Settings
Configuring Number Formats
Configuring Shortcut Links
Configuring Time and Date Formats
Enabling the Remote API
Enabling Threaded Comments
Installing a Language Pack
Installing Patched Class Files

Configuring a WebDAV client for Confluence

WebDAV allows users to access Confluence content On this page:
via a WebDAV client, such as 'My Network Places' in
Microsoft Windows. Provided that the user has Introduction to Confluence's
permission, they will be able to read and write to WebDAV Client Integration
spaces, pages and attachments in Confluence. Using a WebDAV Client to Work
Users will be asked to log in and the standard with Pages
Confluence content access permissions will apply to Restricting WebDAV Client Write
the equivalent content available through the Access to Confluence
WebDAV client. Disabling Strict Path Checking
Virtual Files and Folders
Mapping a Confluence WebDAV network Related pages:
drive requires a set of specific criteria to be
met. For specific information, please see Wi Global Permissions Overview
ndows Network Drive Requirements. Disabling and enabling apps
Attachment Storage Configuration

Introduction to Confluence's WebDAV Client

Integration

By default, all WebDAV clients have permission to

write to Confluence. Write permissions include the
ability for a WebDAV client to create, edit, move or
delete content associated with spaces, pages and
attachments in a Confluence installation.
On the 'WebDAV Configuration' screen in the Confluence Administration Console, you can:
Deny a WebDAV client write permissions to a Confluence installation using a regular expression
(regex)
Disable or enable strict path checking
Enable or disable access to specific virtual files/folders
Note:
The 'WebDav Configuration' page is only available if the WebDAV plugin has been enabled. This
plugin is bundled with Confluence, and can be enabled or disabled by the System Administrator.
The settings on the 'WebDav Configuration' page do not apply to external attachment storage
configuration.

Using a WebDAV Client to Work with Pages

The following sections tell you how to set up a WebDAV client natively for a range of different operating
systems. WebDAV clients typically appear as drives in your operating system's file browser application, such
as Windows Explorer in Microsoft Windows, or Konqueror in Linux.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 248

Accessing Confluence in Finder on Mac OSX

You can successfully connect but you can't see content when using HTTPS, so this technique won't
work for Confluence Cloud. Use a third-party WebDAV client instead.

To use Finder to view and manage Confluence content:

1. In Finder choose Go > Connect to Server
2. Enter your Confluence URL in this format:

http://<confluence base URL>/plugins/servlet/confluence/default

For example if your Confluence URL is http://ourconfluence.sample.com/wiki you would enter:

http://ourconfluence.sample.com/wiki/plugins/servlet/confluence/
default

3. Enter your Confluence username and password and click Connect

Use your username (jsmith), not your email address, unless your email address is your
username.

Confluence will appear as a shared drive in Finder. You can use the same URL to connect using a third party
WebDav client, like CyberDuck.

Accessing Confluence in Explorer in Microsoft Windows

This section covers the two methods for configuring a WebDAV client natively in Microsoft Windows:
As a network drive
As a web folder
If possible, use the network drive method as this will enable more comprehensive WebDAV client interaction
with Confluence than that provided by a web folder. However, your Confluence instance must meet several
environmental constraints if you use this method. If you cannot configure your instance to meet these
requirements, then use the web folder method or third-party WebDAV client software.
If you're using SSL you may need to add @SSL to the end of your server URL, for example:

http://<confluence server
url>@SSL/confluence/plugins/servlet/confluence/default

If you run into any problems with the procedures in this section, please refer to the WebDAV Troubleshooting
page.

Windows Network Drive

To map a Confluence WebDAV client network drive, your Confluence instance must be configured so that all
of the following criteria is met:
Has no context root
There's an issue that can prevent Network Drives from being mapped. Please use the Network
Folders steps below as a workaround.
The reason for these restrictions results from limitations in Microsoft's Mini-Redirector component. For more
information, please refer to Microsoft's server discovery issue.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 249

To map a Confluence WebDAV client network drive in Microsoft Windows:

1. In Windows go to Map Network Drive.
See Map a network drive in the Windows documentation to find out how to get to this in your version
of Windows.
2. Specify the following input to map the WebDAV client as a network drive:
Drive:<Any drive letter> (for example, Z:)
Folder:\\<hostname>\webdav (for example, \\localhost\webdav)
3. Click Finish
When prompted for login credentials, specify your Confluence username and password.

Windows Web Folder

To map a Confluence WebDAV client web folder:

1. Go to My Network Places and choose Add a network place and follow the prompts.
2. In the 'Internet or network address' field, enter the URL for the Confluence WebDAV location (for
example, http://<confluence server
url>/confluence/plugins/servlet/confluence/default or http://<confluence
server url>/plugins/servlet/confluence/default) and click Next

3. Enter your Confluence username and password

4. Provide a meaningful name for your web folder and proceed with the wizard
5. Click Finish
Screenshot: A Confluence WebDAV Client Web Folder in Windows XP

Setting up a WebDAV client in Linux

There are many tools and mechanisms available for configuring WebDAV clients in these operating systems.
Therefore, we have chosen to demonstrate this using the file manager Konqueror, which is part of the Linux
K Desktop Environment.
To set up a Confluence WebDAV client in Konqueror:
1. Open Konqueror
2. In the 'Location' field, enter the URL for the Confluence WebDAV location using the 'protocol' webdav
s (for example, webdavs://<confluence server
url>/confluence/plugins/servlet/confluence/default or webdavs://<confluence

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 250

server url>/plugins/servlet/confluence/default) and press Enter.

3. Enter your Confluence username and password if prompted

You should be able to click to load many, but not all files. In practice, you would normally save a modified file
locally, then drag it to the Konqueror window to upload it to Confluence.

Restricting WebDAV Client Write Access to Confluence

In earlier versions of the WebDAV plugin, separate options for restricting a WebDAV client's write
permissions (that is, create/move, edit and delete actions), were available. However, in the current version of
this plugin, they have been simplified and combined into a general write permission restriction that covers all
of these actions.
WebDAV clients are now denied write permission to your Confluence installation by setting a regex that
matches specific content within the WebDAV client's user agent header. Upon setting a regex, it will be
added to a list of restricted WebDAV clients. Any WebDAV clients whose user agent header matches a regex
in this list will be denied write permission to your Confluence installation.

Example: A PROPFIND method header generated by a Microsoft Web Folder WebDAV client, showing the
user agent header field:

PROPFIND /plugins/servlet/confluence/default HTTP/1.1

Content-Language: en-us
Accept-Language: en-us
Content-Type: text/xml
Translate: f
Depth: 1
Content-Length: 489
User-Agent: Microsoft Data Access Internet Publishing Provider DAV
Host: 127.0.0.1:8082
Connection: Keep-Alive

Unlike earlier versions of the WebDAV plugin, which could only restrict write permissions for all Web
DAV clients, the current version of this plugin allows you to restrict write permissions to specific
WebDAV clients.

To restrict a WebDAV client's write access permissions to your Confluence installation:

1. Choose the cog icon

, then choose General Configuration

2. Choose 'WebDav Configuration' in the left panel
3. Enter a regex that matches a specific component of the user agent header sent by the WebDAV client
you want to restrict.
4. Click the 'Add new regex' button
Repeat steps 3 and 4 to add a regex for each additional WebDAV client you want to restrict.
5. Hit Save
To restore one or more restricted WebDAV client's write access permissions to your Confluence installation:
1. Choose the cog icon

, then choose General Configuration

2. Click WebDav Configuration under 'Configuration' in the left panel
3. Select the regex(es) from the list that match(es) the user agent header sent by the restricted WebDAV

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 251
3.

client(s) you want to restore

4. Click the Remove selected regexes button
5. Hit Save
Screenshot: WebDAV configuration

Disabling Strict Path Checking

If you observe any idiosyncrasies with your WebDAV client, such as a folder that does exist on your
Confluence site but is missing from the client, you can disable the WebDAV plugin's strict path checking
option, which may minimize these problems.
To disable the WebDAV plugin's strict path checking option:
1. Choose the cog icon

, then choose General Configuration

2. Click WebDav Configuration under 'Configuration' in the left panel
3. Clear the 'Disable strict path check' check box
4. Hit Save

Virtual Files and Folders

In the unlikely event that you have problems with the WebDAV client's performance or stability, you can
enable access to automatically generated (that is, virtual) files and folders.
Note:
By default, these options are hidden on the 'WebDAV Configuration' page. To make them visible, append the
parameter ?hiddenOptionsEnabled=true to the end of your URL and reload the page. For example:

<Confluence base
URL>/admin/plugins/webdav/config.action?hiddenOptionsEnabled=true

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 252

Screenshot: The Hidden Virtual Files and Folders Option

To enable or disable access to virtual files and folders:

1. Choose the cog icon

, then choose General Configuration

2. Click WebDav Configuration under 'Configuration' in the left panel
3. Amend your URL as described in the note above and reload the 'WebDav Configuration' page
4. Select or clear the check box options in the 'Virtual Files and Folders' section as required
5. Hit Save

Configuring HTTP Timeout Settings

When macros such as the RSS Macro make HTTP requests to servers which are down, a long timeout value is
used. You can set this timeout value through a system parameter to avoid this.
To configure the HTTP Timeout Settings:
1. Choose the cog icon

, then choose General Configuration

2. Select 'General Configuration' under the 'Configuration' heading in the left-hand panel.
3. Find the 'Connection Timeouts' section in the lower portion of the screen.
4. Click 'Edit' to adjust the settings:
Adjust External connections enabled: This setting allows system administrators to disable
external connections so macros like the RSS Macro won't be allowed to make connections to an
external server. It provides protection against external servers providing insecure HTML, timing out
or causing performance problems. The default setting is 'true'.
Connection Timeout (milliseconds): Sets the maximum time for a connection to be established.
A value of zero means the timeout is not used. The default setting is ten seconds (10000).
Socket Timeout (milliseconds): Sets the default socket timeout (SO_TIMEOUT) in milliseconds,
which is the maximum time Confluence will wait for data. A timeout value of zero is interpreted as
an infinite timeout. The default setting is ten seconds (10000).
Configuring Number Formats

There are two number format settings in Confluence:

Long number format. For example: ###############
Decimal number format. For example: ###############.##########

Confluence uses the guidelines in this Java document from Oracle: Class NumberFormat.
To change the number formats in Confluence:
1. Choose

> General Configuration

2. Choose Edit
3. Update the Long Number Format and Decimal Number Format to suit your requirements
4. Choose Save
Configuring Shortcut Links

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 253

Shortcut links provide a quick way of linking to On this page:

resources that are frequently referenced from Creating shortcut links
Confluence. When you create a shortcut link, you Using shortcut links
assign a key to an URL so that, when editing, a user Deleting shortcut links
can type just the key instead of the complete URL.
Related pages:
Example: Creating a shortcut to Google
Links
Most Google searches look like this: http://www. Confluence administrator's guide
google.com/search?q=. If you create a shortcut
for this search with the key 'google', every time a
user needs to use http://www.google.com/sea
rch?q=searchterms, they can just type [search
terms@google] instead.
Here is a screenshot showing the shortcuts currently defined on http://confluence.atlassian.com:

Shortcut links are added and maintained by Confluence administrators from the Administration Console.

Creating shortcut links

To create a shortcut link:

1. Choose the cog icon

, then choose General Configuration

2. Choose Shortcut Links in the left-hand panel.
3. Enter a Key for your shortcut. This is the shortcut name a user will use to reference the URL.
4. Enter the Expanded Value. This is the URL for the link. You can use '%s' in the URL to specify where
the user's input is inserted. If there is no '%s' in the URL, the user's input will be put at the end.
5. Enter a Default Alias. This is the text of the link which will be displayed on the page where the
shortcut is used, with the user's text being substituted for '%s'.
6. Choose Submit.

Using shortcut links

Enter a shortcut link on the Advanced tab of the Insert Link dialog. See Links for details.
Specify in the link what should be appended to the end of the shortcut URL, followed by an at-sign (@) and
the key of the shortcut. Shortcut names are case-insensitive. So, for example, using the keys shown in the
above screenshot:

To Type this Resulting URL

link
to...

a issue CONF-1000@JIRA http://jira.atlassian.com/secure/QuickSearch.jspa?searchString=CONF-1000

a Atlassian http://www.google.com/search?q=Atlassian+Confluence
Google Confluence@Google
search

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 254

Deleting shortcut links

Shortcut links are listed on the Shortcut Links tab of the Administration Console. Click Remove to delete
the shortcut.

Configuring Time and Date Formats

You can localize the formats that Confluence uses to
display dates and times within the web interface. Related pages:
The settings use the syntax of Java's Choosing a Default Language
SimpleDateFormat class, as described in this Installing a Language Pack
document: Java SimpleDateFormat.
Confluence administrator's guide
There are three time and date format settings:
Time format: Used when displaying only the
time of day. For example, when a blog post is
published. Example of configuration: h:mm a
Date time format: Used when displaying both
the date and the time of day. For example, in
historical versions of pages. Example of
configuration: MMM dd, yyyy HH:mm
Date format: Used when displaying only the
date. For example, the creation and most
recent modification dates of pages. Example
of configuration: MMM dd, yyyy
To change the time and date formats:
1. Choose the cog icon

, then choose General Configuration

2. Choose General Configuration in the left-hand panel.
3. Choose Edit.
4. Enter the values for Time Format, Date Time Format and Date Format, to suit your requirements.
5. Choose Save.

Enabling the Remote API

XML-RPC and SOAP remote APIs were deprecated in Confluence 5.5. We recommend using the fully
supported Confluence Server REST API wherever possible.

To use the XML-RPC and SOAP remote APIs you need to enable the APIs from the Administration Console.
You'll need System Administrator permissions to do this.
To enable the remote API:
1. Choose the cog icon

, then choose General Configuration

2. Click Further Configuration in the left-hand panel.
3. Click Edit.
4. Click the check box next to Remote API (XML-RPC & SOAP).
5. Click Save.
Enabling Threaded Comments
Comments on pages or blog posts are displayed in one of two views:
Threaded: Shows the comments in a hierarchy of responses. Each
reply to a comment is indented to indicate the relationships between
the comments.
Flat: Displays all the comments in one single list and does not
indicate the relationships between comments.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 255

Related pages:
By default, comments are displayed in threaded mode. A Confluence
Administrator (see Global Permissions Overview) can enable or disable the Comment
threaded view for the entire Confluence site. on pages
and blog
To enable or disable the threaded view:
posts
1. Choose the cog icon Confluenc
e
, then choose General Configuration administrat
2. Select Further Configuration in the left-hand panel or's guide
3. Choose Edit
4. Select or unselect the Threaded Comments checkbox to enable or
disable threaded mode
5. Choose Save

Installing a Language Pack

Confluence ships with a number of bundled language packs. These Related pages:
languages appear as options on the 'Language Configuration' screen in the
Administration Console when choosing a default language and as Choosing
'Language' options for users in their user settings. a Default
Language
Confluence is available in these languages right out of the box: Configurin
g Indexing
eština (eská republika | Czech Republic)
Language
Dansk (Danmark | Denmark)
Installing
Deutsch (Deutschland | Germany)
Marketplac
Eesti (Eesti | Estonia)
e apps
English (UK)
English (US)
Español (España | Spain)
Français (France)
Íslenska (Ísland | Iceland)
Italiano (Italia | Italy)
Magyar (Magyarország | Hungary)
Nederlands (Nederland | The Netherlands)
Norsk (Norge | Norway)
Polski (Polska | Poland)
Português (Brasil | Brazil)
Român (România | Romania)
Slovenina (Slovenská republika | Slovak Republic)
Suomi (Suomi | Finland)
Svenska (Sverige | Sweden)
( | Russia)
( | China)
( | Japan)
( | Republic of Korea)
You can make additional languages available by installing language pack
apps. You'll need to be a Confluence administrator to install a language
pack.

Download a language pack

You can download language packs from the Atlassian Marketplace, or you can download language packs
developed by the Confluence user community from https://translations.atlassian.com.

Installing a language pack manually

The easiest way to install a language pack is by uploading the file in UPM (Universal Plugin Manager).
Language packs are usually distributed as JAR or OBR files.
To install a language pack:

1.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 256

1. Go to

> Manage apps.

2. Choose Upload App then browse to find the language pack file you downloaded.
3. Choose Upload.
4. Check the list of user-installed plugins to ensure that the add-on is available.
Once installed, you can then change the site language (or let users set this new language in their profile).
See Choosing a Default Language.

Showing User Interface Key Names for Translation

This feature is useful if you are working on creating translations of the Confluence user interface. After
opening the Confluence dashboard, you can add the following action to the end of your Confluence URL:

?i18ntranslate=on

For example http://myconfluencesite.com?i18ntranslate=on

This will cause each element of the user interface to display its special key name. This makes it easier to
find the context for each key within the user interface. You can then search for the key on http://translations.a
tlassian.com where you can enter an appropriate translation for your custom language pack.
The key names are displayed with a 'lightning bolt' graphic. Here's an example from a space sidebar:

To turn off the translation view, add the following to the end of the Confluence URL:

?i18ntranslate=off

Installing Patched Class Files

Atlassian support or the Atlassian bug-fixing team may occasionally provide patches for critical issues that have
been resolved but have not yet made it into a release. Those patches will be class files which are attached to the
relevant issue in our Jira bug-tracking system.

Installation Instructions for the Confluence Distribution

Follow these steps to install a patched class file:

1. Shut down your confluence instance.
2. Copy the supplied class files to <installation-directory>/confluence/WEB-INF/classes/<s
ubdirectories>, where:
<installation-directory> must be replaced with your Confluence Installation directory. (If
you need more information, read about the Confluence Installation Directory.)
<subdirectories> must be replaced by the value specified in the relevant Jira issue. This value
will be different for different issues. In some cases, the subdirectories will not exist and you will
need to create them before copying the class files. Some issues will contain the patch in the form
of a ZIP file which will contain the desired directory structure.
3. Restart your Confluence instance for the changes to become effective.
Class files in the /WEB-INF/classes directory of a web application will be loaded before classes located in

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 257

JAR files in the /WEB-INF/lib directory. Therefore, classes in the first directory will effectively replace classes
of the same name and package which would otherwise be loaded from the JAR files.

Reverting the patch

To revert the patch, simply remove the class files from the <installation-directory>/confluence/WEB
-INF/classes/ folder (taking care to only remove those that apply to the patch you wish to revert), then restart
the instance.

Once the issue that the patch relates to is resolved, you should upgrade to the version of Confluence
that contains the fix, and revert the patch. Patches are often naive and untested and may not solve the
problem in the most efficient way. As such, an official fix should be preferred in all cases.

Configuring System Properties

This page describes how to set Java properties and options on startup for On this page:
Confluence.
Linux
Windows
See How to fix out of memory errors by increasing available memory (starting
for specific instructions for OutOfMemory Errors. from .bat
file)
Windows
service
Confluenc
e Data
Center
deployed
in AWS
Verifying
your
settings
Recognize
d system
properties
Related pages:
Recognize
d System
Properties
How to fix
out of
memory
errors by
increasing
available
memory

Linux

To configure System Properties in Linux installations:

1. Edit the <installation-directory>/bin/setenv.sh file.
2. Find the section CATALINA_OPTS=
(this is JAVA_OPTS= in Confluence 5.5 and earlier)
3. Refer to the list of parameters in Recognized System Properties.
Add all parameters in a space-separated list, inside the quotations.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 258

Windows (starting from .bat file)

To Configure System Properties in Windows Installations When Starting from the .bat File:
1. Edit the <installation-directory>/bin/setenv.bat file.
2. Find the section set CATALINA_OPTS=%CATALINA_OPTS%
(this is JAVA_OPTS=%JAVA_OPTS% in Confluence 5.5 and earlier)
3. Refer to the list of parameters in Recognized System Properties.
Add all parameters in a space-separated list. Make sure to keep the string %CATALINA_OPTS% in
place.

Windows service

There are two ways to configure system properties when you Start Confluence Automatically on Windows as
a Service, either via command line or in the Windows Registry

Setting properties for Windows services via command line

To set properties for Windows services via a command line:

1. Identify the name of the service that Confluence is installed as in Windows (Go to Control Panel > Ad
ministrative Tools > Services):

In the above example, the service name is Confluence121213135538.

2. Open the command window (Choose Start > cmd.exe)
3. cd to the bin directory of your Confluence instance and run the following command:

tomcat9w //ES//<SERVICENAME>

In the above example, it would be tomcat9w //ES//Confluence121213135538

The Tomcat version number may be different if you are using an earlier version of Confluence.
4. Click on the Java tab to see the list of current start-up options:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 259

5. Append any new option on its own new line by adding to the end of the existing Java Options. Refer to
the list of parameters in Recognized System Properties.

Setting properties for Windows services via the Windows registry

In some versions of Windows, there is no option to add Java variables to the service. In these cases, you
must add the properties by viewing the option list in the registry.
1. Go to the Registry Editor (Start > regedit.exe).
2. Find the Services entry:
64bit: HKEY_LOCAL_MACHINE >> SOFTWARE >> WOW6432Node >> Apache Software
Foundation >> Procrun 2.0 >> Confluence service name
32bit: HKEY_LOCAL_MACHINE >> SOFTWARE >> Apache Software Foundation >>
Procrun 2.0 >> Confluence service name

3. To change existing properties double-click the appropriate value.

4. To change additional properties, double-click options.
5. Refer to the list of parameters in Recognized System Properties. Enter each on a separate line.

Confluence Data Center deployed in AWS

If you've used the Quick Start or CloudFormation template to deploy Confluence Data Center in AWS, you
will pass system properties via the Cloud Formation Template, and not using the methods described above.
1. In the AWS Console, choose Update Stack
2. Under Advanced, enter system properties in the Catalina Properties field as follows:

-Xms1024m -Xmx1024m -Dsystemproperty=value

3. Changes are applied when a new nodes are provisioned.

Verifying your settings

To see what Confluence is using, check Viewing System Properties.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 260

Recognized system properties

See Recognized System Properties for the full list of system properties available to your Confluence version.

Recognized System Properties

Confluence supports some configuration and debugging settings that can be enabled through Java system
properties. System properties are usually set by passing the -D flag to the Java virtual machine in which
Confluence is running. See the full instructions: Configuring System Properties.

Since Default Value Effect

atlassian.forceSchemaUpdate

1.0 false By default, Confluence will only

run its database schema update
when it detects that it has been
upgraded. This flag will force
Confluence to perform the
schema update on system
startup.

confluence.home

1.0 Any filesystem path If this system property is set,

Confluence will ignore the
contents of the confluence-in
it.properties file, and use
this property as the setting for the
Confluence Home directory.

confluence.dev.mode

1.0 false Enables additional debugging

options that may be of use to
Confluence developers
(additionally it changes spring
bean creation to use
lazy initialization by default to
decrease startup time). Do not
enable this flag on a production
system.

confluence.disable.mailpolling

2.4 false If set to "true", will prevent

Confluence from retrieving mail
for archiving within spaces.
Manually triggering "check for
new mail" via the web UI will still
work. This property has no effect
on outgoing mail

confluence.i18n.reloadbundles

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 261

1.0 true Setting this property will cause

Confluence to reload its i18n
resource bundles every time an
internationalized string is looked
up. This can be useful when
testing translations, but will make
Confluence run insanely slowly.

confluence.ignore.debug.logging

1.0 true Confluence will normally log a

severe error message if it detects
that DEBUG level logging is
enabled (as DEBUG logging
generally causes a significant
degradation in system
performance). Setting this
property will suppress the error
message.

confluence.jmx.disabled

3.0 false If set to "true", will disable

Confluence's JMX monitoring.
This has the same effect as
setting the "enabled" property to
false in WEB-INF/classes/jmx
Context.xml

confluence.optimize.index.modulo

2.2 20 Number of index queue flushes

before the index is optimized.

confluence.plugins.bundled.disable

2.9 false Starts confluence without bundled

plugins. May be useful in a
development environment to
make Confluence start quicker,
but since bundled plugins are
necessary for some of
Confluence's core functionality,
this property should not be set on
a production system.

atlassian.indexing.contentbody.maxsize

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 262

3.0 1048576 When a file is uploaded, its text is

extracted and indexed. This
allows people to search for the
content of a file, not just the
filename.
If the amount of content extracted
from the file exceeds the limit set
by this property (default is 1MB, in
bytes), the file's contents will still
be indexed and searchable, but
will not appear when the file is
returned in search results.
Increasing this limit may make
displaying search results slower.
See Configuring Attachment Size
for more info.

atlassian.mail.fetchdisabled

3.5 false Disables mail fetching services for

IMAP and POP

atlassian.mail.senddisabled

3.5 false Disables sending of mail

atlassian.disable.caches

2.4 true Setting this property will disable

conditional get and expires:
headers on some web resources.
This will significantly slow down
the user experience, but is useful
in devlopment if you are
frequently changing static
resources and don't want to
continually flush your browser
cache.

confluence.html.encode.automatic

2.9 Setting this property forces the

antixss encoding on or off,
overriding the behavior dictated
by settings. The default behavior
differs between Confluence
versions.

org.osgi.framework.bootdelegation

2.10 empty Comma-separated list of package

names to provide from application
for OSGi plugins. Typically
required when profiling
Confluence. For example:
"com.jprofiler.,com.yourkit.".

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 263

confluence.diff.pool.size

3.1 20 Maximum number of concurrent

diffs. When that number is
exceeded, additional attempts by
RSS feeds to create diffs are
ignored and logged. (The RSS
requests succeed, they are just
missing diffs).

confluence.diff.timeout

3.1 1000 Number of milliseconds to wait for

a diff operation (comparing two
page versions) to complete before
aborting with an error message.

confluence.html.diff.timeout

4.0 10000 Number of milliseconds to wait for

a diff operation (comparing two
page versions) to complete before
aborting with an error message.

atlassian.user.experimentalMapping

2.10 false Setting this property changes the

relationship between local users
and local groups to reduce
performance degradation when
adding a local user to a local
group with a large number of
users. Please note, setting this
property can slow down other
user management functions. We
recommend that you set it only if
you are experiencing performance
problems when adding local users
to large local groups. Please refer
to CONF-12319, fixed in
Confluence 3.1.1.

confluence.import.use-experimental-importer

3.2 false Setting this property changes

Confluence to use the
Experimental XML Importer. It is
designed to be a more stable
implementation but, at the time of
the release of 3.2, the importer is
largely untested and thus not
supported.

atlassian.webresource.disable.minification

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 264

3.3 false Disables automatic minification of

JavaScript and CSS resources
served by Confluence.

index.queue.thread.count

3.3 See "Effect" Sets the number of threads to be

used for the reindex job. The
value has to be in the range of 1
to 50 (inclusive), i.e. at least one
thread but no more than 50
threads will be used. There is no
default value, i.e.
If you don't set index.queue
.thread.count, the number
of threads to be used are
calculated based on the
number of objects that need to
be reindexed and the number
of processors available (a
maximum of 50 threads will be
used).
If you set index.queue.thr
ead.count=2, then two
threads will be used to reindex
the content (regardless of the
number of objects to be
reindexed or the number of
processors available)
If you set index.queue.thr
ead.count=200, then ten
threads (the maximum
allowed) will be used to
reindex the content.
Note: For Confluence versions
from 3.3 to 5.6 the maximum
threads is 10.

index.queue.batch.size

3.3 1500 Size of batches used by the

indexer. Reducing this value will
reduce the load that the indexer
puts on the system, but indexing
takes longer. Increasing this value
will cause indexing to be
completed faster, but puts a
higher load on the system.
Normally this setting does not
need tuning.

password.confirmation.disabled

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 265

3.4 false This property disables the

password confirmation
functionality that Confluence uses
as an additional security measure.
With this property set, Confluence
will not require password
confirmation for the following
actions: administrative actions,
change of email address and Cap
tcha for failed logins. Disabling
password confirmations is useful
if you are using a custom
authenticator.

confluence.browser.language.enabled

3.5 true Setting this property to "false"

disables the detection of browser
language headers, effectively
restoring Confluence behavior to
that of earlier releases. Setting
this property to "true" enables the
detection of the language headers
sent by the browser. Confluenc
will change the UI language
based on the browser headers.
See documentation on how users
can choose a language
preference.

upm.pac.disable

Universal Plugin Manager 1.5 false When this property is set to true,
then UPM will not try to access
the The Atlassian Marketplace.
This is useful for application
servers that do not have access
to the Internet. See the UPM
documentation.

confluence.reindex.documents.to.pop

3.5.9 20 Indicates how many objects each

indexing thread should process at
a time during a full re-index.
Please note that this number does
not include attachments

confluence.reindex.attachments.to.pop

3.5.9 10 Indicates how many attachments

each indexing thread should
process at a time during a full
re-index.

confluence.upgrade.active.directory

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 266

3.5.11 false Forces Confluence to treat any

LDAP directories it migrates as
Active Directory, rather than
relying on looking for
sAMAccountName in the
username attribute. This is
necessary if you are upgrading
from before Confluence 3.5, and
need to use an attribute other
than sAMAccountName to identify
your users and are seeing LDAP:
error code 4 - Sizelimit
Exceeded exceptions in your
logs. For more details, see Unabl
e to Log In with Confluence 3.5 or
Later Due to 'LDAP error code 4 -
Sizelimit Exceeded'

confluence.context.batching.disable

4.0 false Disables batching for web

resources in contexts (e.g. editor,
main, admin). Useful for
diagnosing the source of
javascript or CSS errors.

com.atlassian.logout.disable.session.invalidation

4.0 false Disables the session invalidation

on log out. As of 4.0 the default
behavior is to invalidate the
JSession assigned to a client
when they log out. If this is set to
true the session is kept active (but
the user logged out). This may be
valuable when using external
authentication systems, but
should generally not be needed.

officeconnector.spreadsheet.xlsxmaxsize

4.0.5 2097152 Indicates the maximum size in

bytes of an Excel file that can be
viewed using the viewxls macro
. If empty, the maximum size
defaults to 2Mb. See CONF-2104
3 for more details.

com.atlassian.confluence.extra.calendar3.display.events.calendar.maxpercalendar

200 Specifies the maximum number of

events per calendar. This property
is effective only if the Team
Calendars plugin is installed on
your Confluence site.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 267

com.atlassian.confluence.allow.downgrade

4.3.2 false Allows Confluence to start up

against the home directory of a
newer version of Confluence.
Note that running Confluence like
that is unsupported. You should
only turn this on if you know what
you are doing. See After
Downgrading, Confluence Will No
Longer Run for details.

confluence.skip.reindex

false When true, allows Confluence to

skip rebuilding the search index
when Confluence is upgraded.
This can be useful if you have a
very large site and wish to delay
rebuilding the index until a time
after the upgrade is complete.

reindex.thread.count

5.2 Sets the number of threads to be

used for a one-off reindex job.
The value has to be in the range
of 1 to 50 (inclusive), i.e. at least
one thread but no more than 50
threads will be used. There is no
default value. This system
property does not affect the
incremental indexing that
Confluence does.

reindex.attachments.thread.count

5.2 4 Sets the number of threads to be

used for reindexing attachments
specifically, and allows you to
reduce the concurrency for these
more memory intensive index
items.

atlassian.confluence.export.word.max.embedded.images

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 268

5.2 50 This property limits the number of

images that are included when
you export a Confluence page to
Word. When you export a page
with many large images images to
Word, all the images are loaded
into memory, which can then
cause out of memory errors
affecting your entire Confluence
site. You can temporarily increase
this limit, using this system
property, if you need to export a
page with lots of images.

confluence.mbox.directory

5.4.1 Setting this property defines the

directory on your Confluence
Server where mailboxes can be
imported from (for use with the
Confluence Mail Archiving system
app). Mailboxes are not able to be
imported from any other location.
We recommend administrators
create a directory in the
Confluence Home directory
specifically for this purpose. Mail
cannot be imported from the
server until this system property is
set.

confluence.search.max.results

5.5 1000 Setting this property changes the

maximum number of items
Confluence Search will return.

confluence.upgrade.recovery.file.enabled

5.5 true By default, Confluence creates an

upgrade recovery file before and
after an upgrade. The operation
can take long time on large
databases and can be safely
turned off if there is a process to
back up database and verify the
backup before performing an
upgrade. Setting this property to
false will disable upgrade
recovery file creation.

confluence.junit.report.directory

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 269

5.5 Setting this property defines the

directory on your Confluence
Server where JUnit Reports can
be imported from (for use in the
JUnit Report Macro). No other
locations are permitted. We
recommend administrators create
a directory in the Confluence
Home directory specifically for this
purpose. JUnit Test result files
cannot be imported from the
server until this system property is
set.

officeconnector.textextract.word.docxmaxsize

5.5.3 16777216 When a file is uploaded, its text is

extracted and indexed. This
allows people to search for the
content of a file, not just the
filename.
Confluence will only extract
content from a Word document up
to the limit set by this property
(defaults to 16MB, in bytes),
before proceeding to index it. This
will mean that only part of file's
contents are searchable. See Con
figuring Attachment Size for more
info.

cluster.login.rememberme.enabled

5.6 False In a cluster, setting this property

to True will enable the
'Remember Me' checkbox on the
login page. This is not
recommended in a cluster, and is
disabled by default (i.e.
'Remember me' is always on and
users can move seamlessly
between nodes).
This system property has no
effect in standalone Confluence.

confluence.cluster.hazelcast.listenPort

5.6 5801 In a cluster, this property can be

used to override the default port
that Hazelcast will bind to, for
example, if the port is unavailable,
or you need to run more than one
node on the same host (not
recommended). It defaults to
5801.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 270

confluence.document.conversion.threads

5.7 The number of threads allocated

to the file conversion service is
calculated dynamically based on
the amount of memory assigned
to the instance and the number of
CPU cores (usually 4 to 6
threads). This property can be
used to change the number of
threads. Decrease threads to
resolve OOME issues, increase
threads to resolve problems with
documents spending too long in
the queue.

confluence.document.conversion.threads.wait

5.7 1000 Set this property to change the

maximum number of items that
can be queued for conversion.Any
file conversion requests that are
made when this maximum limit
has been reached are aborted.

confluence.cluster.node.name

5.7 Set this property to give each

node in your Data Center cluster
a human readable name
(displayed in email notifications
and in the footer). If left unset,
Confluence will assign a node
identifier to each node.

confluence.document.conversion.fontpath

5.8.7 Set this property to define a

directory where you can add
additional fonts to be used when
rendering files (in previews and
thumbnails).
This is useful if you need to
support previewing files with
specific fonts, or fonts with
multibtye characters (such as
Japanese).

confluence.document.conversion.words.defaultfontname

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 271

5.8.7 Set this property to change the

default font for rendering Word (.
doc and .docx) files in
Confluence.
Specify just the name of the font (
not the path).

confluence.document.conversion.slides.defaultfontname.regular

5.8.7 Set this property to change the

default font for rendering regular
fonts in Powerpoint (.ppt and .p
ptx) files in Confluence.

Specify just the name of the font (

not the path).

confluence.document.conversion.slides.defaultfontname.asian

5.8.7 TakaoPGothic Set this property to change the

default font for rendering asian
fonts in Powerpoint (.ppt and .p
ptx) files in Confluence.

Specify just the name of the font (

not the path).

confluence.document.conversion.slides.defaultfontname.symbol

5.8.7 Set this property to change the

default font for rendering symbols
in Powerpoint (.ppt and .pptx) f
iles in Confluence.
This is the font that will be used
for bullets and other symbols
when the font Symbol is not
found.
Specify just the name of the font (
not the path).

confluence.clickjacking.protection.disable

5.8.15 false Security features prevent

Confluence from being embedded
in an <iframe>. To disable this
protection, set this property to tr
ue which will allow Confluence to
be embedded in an <iframe>.

confluence.cluster.index.recovery.query.timeout

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 272

5.9.1 10 In Confluence Data Center, the

amount of time, in seconds, that a
confluence node needing index
recovery will wait for another node
to offer an index snapshot, before
it gives up and stops attempting to
recover the index.

confluence.cluster.index.recovery.generation.timeout

5.9.1 120 In Confluence Data Center, the

amount of time, in seconds, that a
confluence node needing index
recovery will wait for an index
snapshot to be created by another
node, before it gives up and and
stops attempting to recover the
index.

confluence.cluster.index.recovery.num.attempts

5.9.1 1 In Confluence Data Center, the

number of times that a node
needing index recovery will
attempt to recover its index. Set
this property to 0 to disable index
recovery on that node (for
example, when you want to force
a node to automatically rebuild its
own index on startup).

com.atlassian.confluence.officeconnector.canary.memory_value

5.9.1 1024 Sets the memory (in megabytes)

available to the Office Connector
Canary process, which is a
workaround for a known issue
with the Import from Word option.
See JVM crashes during Import
from Word in Confluence for more
information.

com.atlassian.confluence.officeconnector.canary.timeout

5.9.1 120000 Sets the maximum timeout (in

milliseconds) for the Office
Connector Canary process, which
is a workaround for a known issue
with the Import from Word option.
See JVM crashes during Import
from Word in Confluence for more
information.

atlassian.plugins.enable.wait

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 273

5.9.5 300 Set this property to increase the

default time to wait for plugins to
start up. This is useful if you have
problems with plugins not starting
up in time, causing Confluence to
fail to start.

confluence.cluster.hazelcast.max.no.heartbeat.seconds

5.9.7 30 In Confluence Data Center, this

sets how long (in seconds) a node
can be out of communication with
the cluster before it's removed
from the cluster. See balancing
uptime and data integrity for more
info on when you may want to
change this setting.

confluence.startup.remigration.disable

5.10.8 False Set this property to true if you

repeatedly experience issues with
Confluence creating a new page
version as it attempts to migrate
pages containing unmigrated
wiki-markup macros each time a
plugin is install or updated. See
CONFSERVER-37710
CLOSED
for more details.

cluster.safety.time.to.live.split.ms

6.0.0 60000 In Confluence Data Center, this is

the amount of time (in
milliseconds) that the cluster
safety job will wait to allow the
nodes to rejoin after a split brain
is detected. If the node still can't
find the cluster safety number in
the cache after this time, the node
will panic.

confluence.cph.max.entries

6.0.0 2000 This is the maximum number of

pages that can be copied when
you copy a page and its child
pages. Increase this if you need
to copy a page with more than the
default number of child pages.

confluence.cph.batch.size

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 274

6.0.0 10 This is the number of pages

copied in each batch when you
copy a page and its children.
Increase or reduce this number if
you experience problems copying
a page with many child pages.

synchrony.port (formerly known as reza.port)

6.0.0 8091 This is the port that Synchrony,

the service that powers
collaborative editing, runs on. You
should only need to change this if
port 8091 is not available. From
6.0.4, Confluence Server will
accept either reza.port or syn
chrony.port.

synchrony.memory.max (formerly reza.memory.max)

6.0.0 1g This is the maximum heap size

(Xmx) allocated to Synchrony, the
service that powers collaborative
editing. Change this value if you
need to increase or decrease the
heap size. From 6.0.4,
Confluence Server will accept
either reza.memory.max or syn
chrony.memory.max.

synchrony.stack.space

6.0.0 2048k This sets the stack size (Xss) of

the Synchrony JVM. Increase if
you experience stack overflow
errors, or decrease if you
experience out of memory errors
from Synchrony.
This property only applies when
Synchrony is managed by
Confluence.

synchrony.enable.xhr.fallback

6.0.0 True XML HTTP Request (XHR) fallbac

k allows a user, who cannot
connect to Synchrony via a
WebSocket, to use the
Confluence Editor. From
Confluence 6.1 this is enabled by
default, and only used when a
WebSocket connection is not
available. You should not need to
disable this, unless directed by
our support team.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 275

synchrony.database.test.connection.on.checkin

6.0.0 True Verifies the connection to the

database is valid at every
connection checkin. Atlassian
Support may suggest you set this
property to False if you
experience performance issues in
sites that have very frequent page
edits.

synchrony.proxy.enabled

6.0.0 True By default, Confluence uses an

internal proxy to communicate
between the Confluence JVM and
Synchrony JVM. See Administerin
g Collaborative Editing for more
information.
In Confluence 6.0, set this
property to true to manually
enable the internal proxy (useful if
you have configured a reverse
proxy and want to also use the
internal Synchrony proxy).
In Confluence 6.1 or later it
should not be necessary to use
this system property, as
Confluence intelligently
determines when to use the
proxy.
This property only applies when
Synchrony is managed by
Confluence. It has no effect on a
Synchrony standalone cluster.

synchrony.bind (formerly known as reza.bind)

6.0.0 0.0.0.0 This is the specific network

interface that Synchrony listens
on. It is unlikely that you will need
to change this when Synchrony is
managed by Confluence. In
Confluence Data Center, when
running a Synchrony standalone
cluster this should be set to the
same value as synchrony.clus
ter.bind.
From 6.0.4, Confluence Server
will accept either reza.bind or s
ynchrony.bind.

synchrony.context.path

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 276

6.0.0 /synchrony This is the context path for

Synchrony. There should be no
need to change this in Confluence
Server, or when Synchrony is
managed by Confluence.

confluence.pdfexport.permits.size

6.0.0 (number of cores) This property sets the number of

concurrent PDF exports that can
be performed. It defaults to the
number of cores on your server or
cluster node.

confluence.pdfexport.timeout.seconds

6.0.0 30 This property sets the amount of

time (in seconds) a new PDF
export request should wait before
failing, if the maximum number of
concurrent PDF exports (as set in
confluence.pdfexport.permits.size
) has already been reached.

confluence.flyingpdf.default.characters.per.line

6.0.3 80 If the total characters in a table

column heading exceeds the
value of this property, Confluence
will automatically adjust the width
of the other table columns so that
all columns will fit within one page
when the page is exported to
PDF.

synchrony.host

6.0.4 127.0.0.1 This is the IP that Confluence

uses to connect to Synchrony. It
defaults to localhost. Change this
if you need to allow Confluence to
contact Synchrony via a custom
hostname or IP address.
This property only applies when
Synchrony is managed by
Confluence. It has no effect on a
Synchrony standalone cluster.

synchrony.proxy.healthcheck.disabled

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 277

6.1.0 false The Synchrony proxy health

check is used to check whether
the Synchrony proxy is running
and responding to requests. It
requires a http connection. If a
http connector is not present in
your server.xml (for example
you're using a https or AJP
connector) the health check will
fail even if the Synchrony proxy is
operational. You can use this
system property to disable the
health check if necessary.

page.index.macro.max.pages

6.1.4 5000 Sets the maximum number of

pages that the Page Index macro
can display. The Page Index
macro can significantly slow down
your Confluence instance and
cause out of memory errors when
used in a space with a large
number of pages. If the number of
pages in the space exceeds this
limit, the Page Index macro will
show a page count, and a
message that there are too many
pages to display.

atlassian.indexing.attachment.maxsize

6.2.2 104857600 When a file is uploaded, its text is

extracted and indexed. This
allows people to search for the
content of a file, not just the
filename.
If the uploaded file is larger than
the limit set by this property
(default is 100MB, in bytes), text
extraction and indexing will be
skipped. See Configuring
Attachment Size for more info.

officeconnector.excel.extractor.maxlength

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 278

6.2.2 1048576 When a file is uploaded, its text is

extracted and indexed. This
allows people to search for the
content of a file, not just the
filename.
Confluence will only extract
content from an Excel
spreadsheet up to the limit set by
this property (default is 1MB, in
bytes), before proceeding to index
it. This will mean that only part of
file's contents are searchable. Se
e Configuring Attachment Size for
more info.

confluence.collab.edit.user.limit

6.3.0 12 When collaborative editing is

enabled, this sets the maximum
number of users that can
simultaneously edit a page.
Reduce this number if you
experience degraded
performance when many people
are editing.

jobs.limit.per.purge

6.4.3 2000 The Purge Old Job Run Details

scheduled job deletes details of
old scheduled jobs from the
database in batches.
Set this property to change the
number of records to remove in
each batch.

all.jobs.ttl.hours

6.4.3 2160 By default, the Purge Old Job

Run Details scheduled job
deletes details of successful
scheduled jobs older than 90 days
(or 2160 hours).
Set this property, to change
number of hours to keep details of
successful jobs in the database.

unsuccessful.jobs.ttl.hours

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 279

6.4.3 168 By default, the Purge Old Job

Run Details scheduled job
deletes details of unsuccessful
(failed or aborted) scheduled jobs
older than 7 days (or 168 hours).
Set this property, to change
number of hours to keep details of
unsuccessful jobs in the
database.

hide.system.error.details

6.5.0 False Set this property to true if you

want to hide details on the error
screen that appears in the
browser when Confluence can't
start up. This can be useful for
public-facing sites, where you
may not want to display details of
the problem.

atlassian.recovery.password

6.6.1 Allows an administrator to start

Confluence in recovery mode and
specify a temporary administrator
password. This is useful if the
administrator is locked out of the
instance after a site import, or
cannot reset their password by
other methods. See Restore
Passwords To Recover Admin
User Rights for more information.
This system property must be
removed immediatley after the
admin account has been
recovered or a new admin
account created.

confluence.extra.userlister.limit

6.6.3, 10000 Set this property to change the

6.7.1 maximum number of people the U
ser List macro can display. This
macro is known to cause out of
memory errors when attempting
to display a very large number of
users.

conversion.sandbox.pool.size
(formerly document.conversion.sandbox.pool.size)

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 280

6.10.0 2 Use this property to increase the

number of processes (sandboxes)
in the external process pool. More
processes means more tasks can
be executed in parallel, but will
consume more memory and CPU
resources on each node.
This property only applies to Data
Center. This property was
renamed in Confluence 6.12.

conversion.sandbox.startup.time.limit.secs
(formerly document.conversion.sandbox.startup.time.limit.secs)

6.10.0 30 When a document file is inserted

into a page, thumbnails are
generated of its contents, so it
can be viewed inline and
previewed. In Confluence Data
Center this is handled by the exter
nal process pool.
This property sets the amount of
time (in seconds) that a process
will wait for document conversion
to start, before terminating the
process.
This property only applies to Data
Center. This property was
renamed in Confluence 6.12.

document.conversion.sandbox.request.time.limit.secs

6.10.0 30 When a document file is inserted

into a page, thumbnails are
generated of its contents, so it
can be viewed inline and
previewed. In Confluence Data
Center this is handled by the exter
nal process pool.
This property sets the amount of
time (in seconds) that a process
will wait for document conversion
to complete, before terminating
the process, and marking
thumbnail generation for that file
as failed.
This property only applies to Data
Center.

sandbox.termination.tolerance

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 281

6.10.0 5 This property specifies how often

a process in the external process
pool will check if the request time
limit (set in the
request.time.limit.secs property
above) has been exceeded. It's
calculated by dividing the request
time limit by the value of this
property. For example, if the
request time limit is 30 seconds,
and the tolerance set in this
property is 5, the process will
check if the request time limit has
been exceeded every 6 seconds.
This property only applies to Data
Center.

conversion.sandbox.memory.limit.megabytes
(formerly document.conversion.sandbox.memory.limit.megabytes)

6.10.0 512 When a document file is inserted

into a page, thumbnails are
generated of its contents, so it
can be viewed inline and
previewed. In Confluence Data
Center this is handled by the exter
nal process pool.
This property limits the amount of
heap memory each process in the
external process pool can
consume.
This property only applies to Data
Center. This property was
renamed in Confluence 6.12.

document.conversion.sandbox.log.level

6.10.0 INFO Use this property to change the

logging level of document
conversion in the external process
pool to WARNING, INFO, or
FINE. This is useful if you need to
troubleshoot a problem with the
sandbox.
This property only applies to Data
Center.

sandbox.error.delay.millis

6.10.0 50 This property sets how often (in

milliseconds) document
conversion errors are captured for
diagnostic purposes.
This property only applies to Data
Center.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 282

document.conversion.sandbox.disable

6.10.0 false Set this property to true if you

don't want to handle document
conversion (thumbnail generation)
in the external process pool.
When disabled, document
conversion will be handled in the
Confluence JVM, as is the case in
Confluence Server.
This property only applies to Data
Center.

diagnostics.os.check.period.secs

6.11.0 120 Set this property to change how

often operating system diagnostic
s checks should be performed (in
seconds).
This property only applies to the L
ow free memory (OS-1001) and L
ow free disk space (OS-1002)
alerts.

diagnostics.os.min.free.memory.megabytes

6.11.0 256 This property applies to the free

memory diagnostic alert (OS-100
1).
Set this property to change the
threshold at which the amount of
free memory (in megabytes)
should trigger this alert.

diagnostics.os.min.free.disk.space.megabytes

6.11.0 8192 This property applies to the free

disk space diagnostic alert (OS-1
002).
Set this property to change the
threshold at which the amount of
free disk space (in megabytes) in
the local or shared home directory
should trigger this alert.

diagnostics.slow.http.request.secs

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 283

6.11.0 60 This property applies to the HTTP

request diagnostic alert (HTTP-10
01). This alert is disabled by
default.
Set this property to change the
threshold (in seconds) at which a
slow HTTP request should trigger
this alert.

diagnostics.slow.long.running.task.secs

6.11.0 300 This property applies to the long

running task diagnostic alert (JOB
-1001).
Set this property to change the
threshold (in seconds) at which a
long running task should trigger
this alert.

diagnostics.slow.macro.rendering.secs

6.11.0 30 This property applies to the macro

rendering diagnostic alert (MACR
O-1001). This alert is disabled by
default.
Set this property to change the
threshold (in seconds) at which
rendering a macro on a page
should trigger this alert.

diagnostics.jvm.memory.check.period.secs

6.11.0 10 Set this property to change how

often JVM diagnostics checks sho
uld be performed (in seconds).
This property only applies to the
Thread memory allocation rate (J
VM-1001) and Garbage collection
(JVM-1002)alerts.

diagnostics.jvm.memory.allocation.rate.percent

6.11.0 5 This property applies to the thread

memory allocation rate diagnostic
alert (JVM-1001). This alert is
disabled by default.
Set this property to change the
threshold (as a percentage) at
which the memory allocation to a
particular thread, during the
monitoring period (set in
diagnostics.jvm.memory.allocatio
n.monitoring.period.secs), should
trigger this alert.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 284

diagnostics.jvm.memory.allocation.monitoring.period.secs

6.11.0 20 This property applies to the thread

memory allocation rate diagnostic
alert (JVM-1001). This alert is
disabled by default.
Set this property to change the
monitoring period (in seconds) for
this alert.

diagnostics.jvm.garbage.collector.percent

6.11.0 10 This property applies to the

garbage collection diagnostic alert
(JVM-1002). This alert checks
how much memory has been
allocated to garbage collection
during the monitoring period (set
in
diagnostics.jvm.garbage.collector.
monitoring.period.secs).
Set this property to change the
threshold (as a percentage) at
which the memory allocated to
garbage collection should trigger
this alert.

diagnostics.jvm.garbage.collector.monitoring.period.secs

6.11.0 20 This property applies to the

garbage collection diagnostic alert
(JVM-1002).
Set this property to change the
monitoring period (in seconds) for
this alert.

diagnostics.alert.retention.period.days

6.11.0 30 Set this property to change how

often diagnostic alert data should
be retained in the database (in
days).

diagnostics.alert.truncation.interval.minutes

6.11.0 30 Set this property to change how

often we check for, and remove di
agnostic alert data that is older
than 30 days (the limit set by dia
gnostics.alert.retention.
period.days)

pdf.export.sandbox.disable

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 285

6.12.0 false Set this property to true if you

don't want to handle PDF exports
in the external process pool.
When disabled, PDF exports will
be handled in the Confluence
JVM, as is the case in Confluence
Server.
This property only applies to Data
Center.

pdf.export.sandbox.request.time.limit.secs

6.12.0 180 When you export a space to PDF,

Confluence exports the content of
each page to HTML, converts that
HTML to PDF, and then finally
merges all the pages together into
a single PDF file. In Confluence
Data Center this is handled by
the external process pool.
This property sets the amount of
time (in seconds) that a process
should wait to complete, before
being terminated. This time limit
applies both to the time to convert
the content from HTML to PDF,
and the time to merge the final
PDF file.
This property only applies to Data
Center.

pdf.export.sandbox.memory.requirement.megabytes

6.12.0 64 In Confluence Data Center PDF

exports are handled by the extern
al process pool.
This property sets the minimum
memory (in megabytes) that a
sandbox process must have
available to start a PDF export.
If conversion.sandbox.memory.li
mit.megabytes is set to less than
the value of this property, PDF
export will not start. We don't
recommend setting this property
to less than 64MB.
This property only applies to Data
Center.

Working with Confluence Logs

Confluence uses Apache's log4j logging service.
This allows administrators to control the logging
behavior and the log output file by editing a
configuration file. There are six log4j logging levels.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 286

If you request help from Atlassian Support, we will On this page:

almost always ask for the Confluence application
logs. The easiest way to get these logs is to go to Finding the Confluence log files
Finding the log configuration file
Changing the destination of the log
> General Configuration > Troubleshooting and
files
support tools and follow the prompts to create a Su
Changing the size and number of
pport Zip.
log files
Changing the logging levels
Specific Confluence logging
options
Scanning log files for known
problems

Related pages:

Enabling Detailed SQL Logging

Enabling user access logging
Generating a Thread Dump
Enabling Page Request Profiling

Finding the Confluence log files

This section describes Confluence's default logging behavior, and assumes that you have not changed the
destination of the logs. In order to unify logging across different application servers, Confluence uses the atl
assian-confluence.log as its primary log, not the application server log.

When you start Confluence, log entries will be sent to the application server logs until Confluence has
completed its initial bootstrap. Any log entries written to the console will be repeated into the log in the
Confluence home directory as described below.
Once the initial startup sequence is complete, all logging will be to <confluence-home>/logs/atl
assian-confluence.log. For example: c:/confluence/data/logs/atlassian-confluenc
e.log.

Note that the default location is the Confluence home directory, not the application server's log file. The
home directory is specified in <confluence-installation>/confluence/WEB-INF/classes/confl
uence-init.properties.

Finding the log configuration file

The logging behavior for Confluence and Synchrony is defined in the following properties file:
<CONFLUENCE-INSTALL>/confluence/WEB-INF/classes/log4j.properties

This file is a standard log4j configuration file, as described in the Apache log4j documentation.

Changing the destination of the log files

In log4j, an output destination is called an 'appender'. To change the destination of the log files, you need to
stop Confluence and then change the settings in the 'Logging Location and Appender' section of the log4
j.properties file. The location of this file is described above.

In the standard properties file, you will find entries for two appenders:
com.atlassian.confluence.logging.ConfluenceHomeLogAppender – This is a custom
appender which controls the default logging destination described above. This appender allows the
following settings:
MaxFileSize
MaxBackupIndex
org.apache.log4j.RollingFileAppender – If you want to log to a different location,
uncomment the RollingFileAppender line and change the destination file in the line below it.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 287

Comment out the previous lines referring to the ConfluenceHomeLogAppender.

The Synchrony log destination can also be changed in the same way in file.
Confluence ships with the full suite of appenders offered by log4j. Read more about appenders in the log4j
documentation.

Changing the size and number of log files

By default, Confluence keeps 5 log files, which are overwritten as they reach 20 MB.
You can change the default log size and the number of log files to keep by editing the following values in <CO
NFLUENCE-INSTALL>/confluence/WEB-INF/classes/log4j.properties file.

log4j.appender.confluencelog.MaxFileSize=20480KB
log4j.appender.confluencelog.MaxBackupIndex=5

Changing the logging levels

See Configuring Logging for instructions on how to change the logging configuration of Confluence.

Specific Confluence logging options

Here's some specific log configurations you may need when troubleshooting.

Log the details of SQL requests made to the database

You may want to increase Confluence's logging so that it records individual SQL requests sent to the
database. This is useful for troubleshooting specific problems.
You can enable detailed SQL logging in two ways:
At runtime – see instructions above.
Via the logging properties file – see the detailed instructions.

Log the details of users viewing/accessing each Confluence page

You can configure the log to show which users are accessing which pages in Confluence. This can only be
done via the logging properties file – see the detailed instructions.

Scanning log files for known problems

Atlassian Troubleshooting and support tools includes a log analyzer that can check for you Confluence logs
for errors and match them against known problems in our knowledge base and issue tracker.
See Troubleshooting Problems and Requesting Technical Support to find out how to set up a periodic scan
of your log files.

Configuring Logging

We recommend that you configure Confluence's logging to your own requirements. You can change the log
settings in two ways:
Configure logging in Confluence Administration – Your changes will be in effect only until you next restart
Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 288

Edit the properties file – Your changes will take effect next time you start Confluence, and for all
subsequent sessions.
Both methods are described below. In some rare circumstances you may also need to configure the logging.pro
perties file.
Terminology: In log4j, a 'logger' is a named entity. Logger names are case-sensitive and they follow a
hierarchical naming standard. For example, the logger named com.foo is a parent of the logger named com.fo
o.Bar.

Configure logging in Confluence Administration

You can change some of Confluence's logging behavior via the Administration Console while Confluence is
running. Any changes made in this way will apply only to the currently-running Confluence lifetime. The changes
are not written to the log4j.properties file and are therefore discarded when you next stop Confluence.

Not all logging behavior can be changed via the Administration Console. For logging configuration not mentioned
below, you will need to stop Confluence and then edit the logging properties file instead.
The 'Logging and Profiling' screen shows a list of all currently defined loggers. On this screen you can:
Turn page profiling on or off.
Turn detailed SQL logging on or off.
Add a new logger for a class/package name.
Remove a logger for a class/package name.
Set the logging level (INFO, WARN, FATAL, ERROR or DEBUG) for each class or package name.
Reset all logging levels to a predefined profile.
Changing the logging configuration
1. Choose the cog icon

, then choose General Configuration

2. Select 'Logging and Profiling' in the 'Administration' section of the left-hand panel.
You need to have System Administrator permissions in order to perform this function.
3. The 'Logging and Profiling' screen appears, as shown below. Use the following guidelines to change
the logging behavior while Confluence is running:
'Performance Profiling' — See Page Request Profiling.
'SQL Logging' — Click the 'Enable SQL Logging' button to log the details of SQL requests made
to the database.
If you need to enable logging of SQL parameter values, you will need to change the setting in
the properties file. This option is not available via the Administration Console.
'Log4j Logging' — Click one of the profile buttons to reset all your loggers to the predefined
profiles:
The 'Production' profile is a fairly standard profile, recommended for normal production
conditions.
The 'Diagnostic' profile gives more information, useful for troubleshooting and debugging. It
results in slower performance and fills the log files more quickly.
'Add New Entry' — Type a class or package name into the text box and click the ' Add Entry'
button. The new logger will appear in the list of 'Existing Levels' in the lower part of the screen.
'Existing Levels' - These are the loggers currently in action for your Confluence instance.
You can change the logging level by selecting a value from the ' New Level' dropdown list.
Read the Apache documentation for a definition of each level.
Click the 'Remove' link to stop logging for the selected class/package name.
4. Click the 'Save' button to save any changes you have made in the 'Existing Levels' section.
Screenshot: Changing Log Levels and Profiling

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 289

Editing the Properties File

To configure the logging levels and other settings on a permanent basis, you need to stop Confluence and then
change the settings in the log4j.properties file, described above.

The properties file contains a number of entries for different loggers that can be uncommented if you are
interested in logging from particular components. Read more in the Apache log4j documentation.
See Working with Confluence Logs for some guidelines on specific configuration options you may find useful.

Configuring Levels for java.util.logging in logging.properties

A few libraries used by Confluence use java.util.logging rather than log4j or slf4j. These libraries include:
com.sun.jersey
org.apache.shindig
net.sf.ehcache
Confluence's logging.properties file is set to redirect java.util.logging at specific levels to log4j via slf4j.

To increase logging levels for these libraries you must first configure the logging.properties file in <CONFL
UENCE-INSTALL>/confluence/WEB-INF/classes/. The logging levels are different from log4j and are
listed here.
For example, to increase logging for shindig change the following line in the logging.properties file:

org.apache.shindig.level = INFO

to

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 290

org.apache.shindig.level = FINE

And then use one of the methods above as well to configure the log4j level.
log4j Logging Levels

Logging Levels

DEBUG - designates fine-grained informational events that are most useful to debug an application (what
is going on)
INFO - announcements about the normal operation of the system - scheduled jobs running, services
starting and stopping, user-triggered processes and actions
WARN - any condition that, while not an error in itself, may indicate that the system is running
sub-optimally
ERROR - a condition that indicates something has gone wrong with the system
FATAL - a condition that indicates something has gone wrong so badly that the system can not recover
TRACE - n/a within confluence

There are two ways to modify the logging levels, as described in Working with Confluence Logs.
1. Modifying the runtime log levels via the Administration Console (changes made here will not
persist across restarts).
2. Manually modifying the <Confluence-Install>\confluence\WEB-INF\classes\log4j.
properties file.

Default Log Level

The standard Confluence log level WARN is a way for Confluence to communicate with the server administrator.
Logging at WARN level and higher should be reserved for situations that require some kind of attention from the
server administrator, and for which corrective action is possible.
See log4j manual for more information.
Troubleshooting SQL Exceptions

If you get an exception similar to those shown below, it is a good idea to increase the logging levels of your
Confluence instance. If you request Atlassian support, this additional logging will help us work out the cause of
the error.
Increased logging levels will enable us to diagnose errors like these:

org.springframework.dao.DataIntegrityViolationException:
(HibernateTemplate): data integrity violated by SQL ''; nested exception
is java.sql.BatchUpdateException: Duplicate entry '1234' for key 1
at
org.springframework.jdbc.support.SQLStateSQLExceptionTranslator.translat
e(SQLStateSQLExceptionTranslator.java:88)
caused by: java.sql.BatchUpdateException: Duplicate entry '1234' for key
1
at
com.mysql.jdbc.ServerPreparedStatement.executeBatch(ServerPreparedStatem
ent.java:647)

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 291

or

(HibernateTemplate): data integrity violated by SQL ''; nested exception

is java.sql.BatchUpdateException: ORA-00001: unique constraint
(CONFLUENCE.SYS_C0012345) violated

This document outlines the steps to take to increasing logging on your system.

Changing the logging levels via the Administration Console

With Confluence 2.7 and later, you can adjust logging levels at runtime via the Administration Console
— read the instructions. Below we tell you how to edit the log4j files directly.

1. Open confluence/WEB-INF/classes/log4j.properties and uncomment the following lines. The

double ## lines are comments, leave them intact.

## log hibernate prepared statements/SQL queries (equivalent to

setting 'hibernate.show_sql' to 'true')
#log4j.logger.net.sf.hibernate.SQL=DEBUG

## log hibernate prepared statement parameter values

#log4j.logger.net.sf.hibernate.type=DEBUG

If you can not locate these lines in your log4j.properties file, please add them to the end of it.
2. Restart Confluence.
3. Redo the steps that led to the error.
4. Zip up your logs directory and attach it your support ticket.
5. If you are using Oracle and received a constraint error, please ask your database administrator which ta
ble and column the constraint (that is, CONFLUENCE.SYS_C0012345) refers to and add that information
to your support ticket.
6. Open confluence/WEB-INF/classes/log4j.properties again and remove the 4 lines you added
in step 1. (The additional logging will impact performance and should be disabled once you have
completed this procedure.)

RELATED TOPICS

Enabling Detailed SQL Logging

Working with Confluence Logs
Troubleshooting failed XML site backups
Scheduled Jobs
The administration console allows you to schedule On this page:
various administrative jobs in Confluence, so that
they are executed at regular time intervals. The Accessing Confluence's scheduled
types of jobs which can be scheduled cover: jobs configuration
Running a job manually
Confluence site backups Changing a job's schedule
Storage optimization jobs to clear Disabling or re-enabling a job
Confluence's temporary files and caches Viewing a job's execution history
Index optimization jobs to ensure Types of jobs
Confluence's search index is up to date Cron expressions
Mail queue optimization jobs to ensure
Confluence's mail queue is maintained and Related pages:
notifications have been sent. Trigger Module
You'll need System Administrator permissions in Configuring Backups
order to edit and manually run jobs.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 292

Accessing Confluence's scheduled jobs configuration

To access Confluence's Scheduled Jobs configuration page:

1. Go to

> General Configuration > Scheduled Jobs

2. All scheduled jobs are listed with:
Status - the job's status, which is either 'Scheduled' (it it is currently enabled) or 'Disabled'.
Last Execution - the date and time when the job was last executed. This field will be empty of
the job was never executed.
Next Execution -the date and time when the job is next scheduled to be executed. This field
will contain dash symbol ('-') if the job is disabled.
Avg. Duration - the length of time (in milliseconds) that it took to complete the job (the last time
it ran).
Actions - Options to edit the job's schedule, run it manually, view the history or disable the job.
Screenshot: Scheduled Jobs

Running a job manually

To run a job manually head to the Scheduled Jobs list and choose Run next to the job. It will
run immediately.
Not all jobs can be run manually.

Changing a job's schedule

To change a job's schedule:

1. Choose Edit next to the job you want to change.
2. Enter the new day or time to run the job as a cron expression - there's more info about cron
expressions below.
3. Save your changes to the job's schedule, or Revert back to the default setting.
Not all jobs' schedules are configurable.
Screenshot: Configuring a Job Schedule

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 293

Disabling or re-enabling a job

By default, all jobs in Confluence are enabled.

Use the Disable / Enable links in the action column to disable and re-enable each job.
Not all jobs in Confluence can be disabled.

Viewing a job's execution history

To see when a job was last run, and how long the job took to run, click the History link beside the job.
If a job has not run at least once the History link won't appear.
Screenshot: Job Execution History

Execution history is not available in Confluence Data Center.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 294

Types of jobs

Here's a summary of some of the scheduled jobs that you may want to adjust.

Job Name Description Execution Default

Behavior Schedule

Back Up Performs a backup of your entire Confluence site. Per cluster At 2am
Confluence every day

Check Cluster For clustered Confluence installations, this job ensures that Per cluster Every 30
Safety only one Confluence instance in the cluster writes to the seconds
database at a time.
For standard (non-clustered) editions of Confluence, this job
is useful for alerting customers who have accidentally
connected a second Confluence instance to a Confluence
database which is already in use.

Clean Journal Periodically clears journal entries that have already been Per cluster At 2am
Entries processed to ensure that its size does not grow indefinitely. every day

Clean Cleans up temporary files generated in the <confluence-h Per node At 4am
Temporary ome>/temp directory. This temp directory is created by every day
Directory exports etc.
This doesn't include the temp directory located in the
confluence install directory.

Clear Expired Clears notification errors in the mail error queue. A Per cluster At 3am
Mail Errors notification error is sent to the mail error queue whenever the every day
notification fails to be sent due to an error.

Clear Expired Clears all expired 'Remember Me' tokens from the Per cluster On the
Remember Me Confluence site. Remember Me tokens expire after two 20th of
Tokens weeks. each
month

Email Daily Emails a daily summary report of all Confluence changes to Per cluster At 12am
Reports all subscribers. every day
Since each email report only records changes from the last
24-hour period, it is recommended that you only change the
time of this job while keeping the job's frequency to 24 hours.

Flush Edge Flushes the Edge Index Queue so Confluence's search Per node Every 30
Index Queue results stay up to date. seconds

Flush Local Flushes the local task queue. (These are internal Confluence Per node Every
Task Queue tasks that are typically flushed at a high frequency.) minute

Flush Mail Sends notifications that have been queued up in the mail Per node Every
Queue queue. This doesn't include batched notifications. Edit the Se minute
nd batched notifications job if you also want to change how
often notifications are sent for changes to a page or blog
post.

Send batched Sends email notifications containing all changes to a page or Per cluster Every 10
notifications blog post since the last time the job ran. Increase the time for minutes
fewer emails or reduce the time if more immediate
notifications are important in your site.

Flush Task Flushes the task queue. (These are internal Confluence Per node Every
Queue tasks that are typically flushed at a high frequency.) minute

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 295

Send Triggers sending recommended update emails to users. The Per cluster Hourly
Recommended job runs hourly, but users will receive the notification weekly
Updates Email or daily, depending on the setting in their profile, at a time
that matches their timezone.

Purge Old Job Confluence stores the details of each scheduled job that is Per cluster at 11pm
Run Details run in the scheduler_run_details table in your every day
database. In order to keep this table small for troubleshooting
and debugging, the Purge Old Job Run Details job
regularly removes the details of:
successful jobs run more than 90 days ago
unsuccessful jobs run more than 7 days ago
You can override these settings using the following system
properties; jobs.limit.per.purge, all.jobs.ttl.ho
urs and unsuccessful.jobs.ttl.hours.

Property Entry When a page is created from a blueprint, some data is left Per cluster At 12am
Gardening behind in the os_property table after the page is published. every day
This job cleans up leftover data, which could contain
personally identifiable information.

Cron expressions

A cron expression is a string of 6-7 'time interval' fields that defines the frequency with which a job is
executed. Each of these fields can be expressed as either a numerical value or a special character and each
field is separated by at least one space or tab character.
The table below is shows the order of time interval fields in a cron expression and each field's permitted
numerical values.
You can specify a special character instead of a numerical value for any field in the cron expression to
provide flexibility in defining a job's frequency. Common special characters include:
'*' — a 'wild card' that indicates 'all permitted values'.
'?' — indicates 'ignore this time interval' in the cron expression. That is, the cron expression will not be
bound by the time interval (such as 'Month', 'Day of week' or 'Year') to which this character is
specified.
For more information about cron expressions, please refer to the Cron Trigger tutorial on the Quartz website.

Order in cron Time interval Permitted Required?

values*
expression field

1 Seconds 0-59 Yes

2 Minutes 0-59 Yes

3 Hours 0-23 Yes

4 Day of month 1-31 Yes

5 Month 1-12 or JAN-DEC Yes

6 Day of week 1-7 or SUN-SAT Yes

7 Year 1970-2099 No

* Excluding special characters.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 296

Configuring the Whitelist

Confluence administrators can choose to allow incoming and outgoing connections and content from specified
sources for use in the:
RSS Feed Macro
HTML Include macro (disabled by default)
gadgets
Shared Links Blueprint
by adding URLs to the whitelist.
Confluence will display an error if content has been added that is not from an allowed source, and prompt the
user to add the URL to the whitelist.
Application links are automatically added to the whitelist. You don't need to manually add them.

Add allowed URLs to the whitelist

To add a URL to the whitelist:

1. Go to

> General Configuration > Whitelist.

2. Enter the URL or expression you want to allow.
3. Choose the Type of expression (see below for examples of the types available).
4. Choose Allow Incoming if you need to allow CORS requests (see below).
5. Choose Add.
Your URL or expression appears in the whitelist.
To test that your whitelisted URL is working as expected you can enter a URL in the Test a URL field. Icons will
indicate whether incoming and / or outgoing traffic is allowed for that URL.

Expression Types

When adding a URL to the whitelist, you can choose from a number of expression types.

Type Description Example

Domain name Allows all URLs from the specified https://www.example.com

domain.

Exact match Allows only the specified URL. https://www.example.com/t

hispage

Wildcard Expression Allows all matching URLs. Use https://*example.com

the wildcard * character to replace
one or more characters.

Regular Expression Allows all URLs matching the http(s)?://www\.example\.

regular expression. com

Allow Incoming

Allow Incoming enables CORS requests from the specified origin. The URL must match the format scheme:/
/host[:port], with no trailing slashes (:port is optional). So http://example.com/ would not
allow CORS requests from the domain example.com.

Disabling the whitelist

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 297

The whitelist is enabled by default. You can choose to disable the whitelist however this will allow all URLs,
including malicious content, and is not recommended.
To disable the whitelist:
1. Choose the cog icon

, then choose General Configuration

2. Choose Whitelist.
3. Choose Turn off whitelist.
4. Choose Confirm.
All URLs will now be allowed. We strongly recommend not disabling the whitelist.
Configuring the Time Interval at which Drafts are Saved
Related pages:
This setting only applies to Confluence 6.0 or later if you've chosen
to disable collaborative editing. Drafts
When collaborative editing is enabled we're saving all the time!

When collaborative editing is disabled, Confluence saves a draft of your

page once every thirty seconds by default. Confluence administrators can
configure how often drafts are saved.
As a Confluence administrator, you can set the time interval at which drafts
are saved as follows:
1. Choose the cog icon

, then choose General Configuration

2. Click Further Configuration in the left-hand panel.
3. Edit the setting for Draft Save Interval.

Configuring Confluence Security

This section gives guidelines on configuring the
security of your Confluence site: Related pages:

Confluence Security Overview and Advisories Permissions and restrictions

Proxy and HTTPS setup for Confluence Configuring a Confluence
Configuring Secure Administrator Sessions Environment
Confluence Cookies Confluence administrator's guide
Using Fail2Ban to limit login attempts
Securing Confluence with Apache
Trackback and External Referrers
Best Practices for Configuring Confluence
Security
Hiding the People Directory
Configuring Captcha for Spam Prevention
Hiding External Links From Search Engines
Configuring Captcha for Failed Logins
Configuring XSRF Protection
User Email Visibility
Anonymous Access to Remote API
Configuring RSS Feeds
Preventing and Cleaning Up Spam

Confluence Security Overview and Advisories

This document is for system administrators who want to evaluate the security of the Confluence web application.
The page addresses overall application security and lists the security advisories issued for Confluence. As a

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 298

public-facing web application, Confluence's application-level security is important. This document answers a
number of questions that commonly arise when customers ask us about the security of our product.
Other topics that you may be looking for:
For information about user management, groups and permissions, please refer to the internal security
overview.
For guidelines on configuring the security of your Confluence site, see the administrator's guide to
configuring Confluence security.

Application Security Overview

Password Storage

When Confluence's internal user management is used, since version 3.5 of Confluence passwords are hashed
through the salted PKCS5S2 implementation provided by Embedded Crowd before being stored in the
database. There is no mechanism within Confluence to retrieve a user's password – when password recovery is
performed, a reset password link is generated and mailed to the user's registered address.
When external user management is enabled, password storage is delegated to the external system.
On this page:
Application Security Overview
Finding and Reporting a Security Vulnerability
Publication of Confluence Security Advisories
Severity Levels
Our Security Bugfix Policy
Published Security Advisories

Buffer Overflows

Confluence is a 100% pure Java application with no native components. As such it is highly resistant to buffer
overflow vulnerabilities – possible buffer overruns are limited to those that are bugs in the Java Runtime
Environment itself.

SQL Injection

Confluence interacts with the database through the Hibernate Object-Relational mapper. Database queries are
generated using standard APIs for parameter replacement rather than string concatenation. As such,
Confluence is highly resistant to SQL injection attacks.

Script Injection

Confluence is a self-contained Java application and does not launch external processes. As such, it is highly
resistant to script injection attacks.

Cross-Site Scripting

As a content-management system that allows user-generated content to be posted on the web, precautions
have been taken within the application to prevent cross-site scripting attacks:
The wiki markup language in Confluence does not support dangerous HTML markup
Macros allowing the insertion of raw HTML are disabled by default
HTML uploaded as a file attachment is served with a content-type requesting the file be downloaded,
rather than being displayed inline
Only system administrators can make HTML-level customizations of the application
When cross-site scripting vulnerabilities are found in the Confluence web application, we endeavor to fix them as
quickly as possible.

Transport Layer Security

Confluence does not directly support SSL/TLS. Administrators who are concerned about transport-layer security
should set up SSL/TLS at the level of the Java web application server, or the HTTP proxy in front of the

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 299

Confluence application.
For more information on configuring Confluence for SSL, see: Running Confluence Over SSL or HTTPS

Session Management

Confluence delegates session management to the Java application server in which it is deployed. We are not
aware of any viable session-hijacking attacks against the Tomcat application server shipped with Confluence. If
you are deploying Confluence in some other application server, you should ensure that it is not vulnerable to
session hijacking.

Plugin Security

Administrators install third party plugins at their own risk. Plugins run in the same virtual machine as the
Confluence server, and have access to the Java runtime environment, and the Confluence server API.
Administrators should always be aware of the source of the plugins they are installing, and whether they trust
those plugins.

Administrator Trust Model

Confluence is written under the assumption that anyone given System Administrator privileges is trusted.
System administrators are able, either directly or by installing plugins, to perform any operation that the
Confluence application is capable of.
As with any application, you should not run Confluence as the root/Administrator user. If you want Confluence to
listen on a privileged network port, you should set up port forwarding or proxying rather than run Confluence with
additional privileges. The extra-careful may consider running Confluence inside a chroot jail.

Stack Traces

To help when debugging a problem, Confluence provides stack traces through the web interface when an error
occurs. These stack traces include information about what Confluence was doing at the time, and some
information about your deployment server.
Only non-personal information is supplied such as operating system and version and Java version. With proper
network security, this is not enough information to be considered dangerous. No usernames or passwords are
included.

Finding and Reporting a Security Vulnerability

Atlassian's approach to reporting security vulnerabilities is detailed in How to Report a Security Issue.

Publication of Confluence Security Advisories

Atlassian's approach to releasing security advisories is detailed in Security Advisory Publishing Policy.

Severity Levels

Atlassian's approach to ranking security issues is detailed in Severity Levels for Security Issues.

Our Security Bugfix Policy

Our approach to releasing patches for security issues is detailed in our Security Bugfix Policy.

Published Security Advisories

Proxy and HTTPS setup for Confluence

Many customers choose to run Confluence behind a reverse proxy, often with HTTPS enabled. Getting your

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 300

proxy configuration right is essential, to avoid problems later when using Confluence.
Proxy and HTTPS access are both configured in Tomcat, Confluence's application server.

Sample connectors

To make setup and configuration as straightforward as possible, we've provided a number of sample connectors
in the Tomcat <install-directory>/conf/server.xml file.

Sample connector Description

DEFAULT - Direct connector with no proxy, for This is the default option. Use this option when you
unproxied HTTP access to Confluence don't have a reverse proxy and are not enabling
HTTPS.

HTTP - Proxying Confluence via Apache or Nginx Choose this option if you have a reverse proxy, but
over HTTP are not enabling HTTPS.

HTTPS - Direct connector with no proxy, for Choose this option if you want to use HTTPS
unproxied HTTPS access to Confluence. without a reverse proxy. HTTPS will be terminated at
Tomcat.

HTTPS - Proxying Confluence via Apache or Nginx Use this option when you want to use a reverse
over HTTPS proxy and enable HTTPS. This is the most common
configuration.

We only provide HTTP/HTTPS connector examples. You can't use the AJP connector (for example, with Apache
mod_jk), as Synchrony, which is required for collaborative editing, can't accept AJP connections.
If you plan to use collaborative editing, there are a number of proxy and SSL considerations you'll need to take
into account when deciding the best way to configure your proxy.

Step-by-step guides

In addition to the sample connectors, we also provide a number of step-by-step guides to help you enable
HTTPS and configure your proxy correctly.
HTTPS:
Running Confluence Over SSL or HTTPS (terminating HTTPS at Tomcat)
Running Confluence behind NGINX with SSL (terminating HTTPS at your proxy)
Securing your Atlassian applications with Apache using SSL (terminating HTTPS at your proxy)
Reverse proxy:
Using Apache with mod_proxy (Confluence)
Running Confluence behind NGINX with SSL (Confluence)
Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http) (any Atlassian
product)
Proxying Atlassian server applications with Microsoft Internet Information Services (IIS) (any Atlassian
product)
Outbound proxy:
Configuring Web Proxy Support for Confluence (Confluence)
How to Configure Outbound HTTP and HTTPS Proxy for your Atlassian application (any Atlassian
product)

Although we provide guides for some third-party solutions, and mention Apache and Nginx in the serve
r.xml file, you can choose your own proxy solution.

Atlassian Support can't provide assistance with configuring third-party tools like NGINX, Apache, or IIS.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 301

If you have questions, check your proxy server's documentation, ask the Atlassian Community, or get
help from a Solution Partner.

Configuring Web Proxy Support for Confluence

The content on this page relates to platforms which are not supported. Consequently, Atlassian Support
cannot guarantee providing any support for it. Please be aware that this material is provided for your
information only and using it is done so at your own risk.

Some of Confluence's macros, such as {rss} and {jiraissues} need to make web requests to remote servers in
order to retrieve data. If Confluence is deployed within a data centre or DMZ, it may not be able to access the
Internet directly to make these requests. If you find that the {rss} macro does not work, ask your network
administrator if Confluence needs to access the Internet through a web proxy.

Configuring an outbound HTTP proxy in Confluence

Proxy support is configured by passing certain system properties to the Java Virtual Machine on startup.
http.proxyHost
http.proxyPort (default: 80)
http.nonProxyHosts (default: <none>)
https.proxyHost
https.proxyPort

At a minimum, you need to define http.proxyHost to configure an HTTP proxy, and https.proxyHost to
configure an HTTPS proxy. System property configuration is described in the Configuring System Properties.
Properties http.proxyHost and http.proxyPort indicate the proxy server and port that the http protocol
handler will use, and https.proxyHost and https.proxyPort indicate the same for the https protocol
handler.

-Dhttp.proxyHost=proxy.example.org -Dhttp.proxyPort=8080
-Dhttps.proxyHost=proxy.example.org -Dhttps.proxyPort=8080

Property http.nonProxyHosts indicates the hosts which should be connected to directly and not through the
proxy server. The value can be a list of hosts, each separated by a pipe character | . In addition, a wildcard
character (asterisk) * can be used for matching. For example:

-Dhttp.nonProxyHosts=*.foo.com|localhost

If you're using Confluence 6.0 or later with Synchrony, you'll need to pass the following to ensure Confluence
can connect directly to Synchrony. Replace localhost|127.0.0.1 with your Synchrony IP if you have used
the synchrony.host system property to change the IP Synchrony uses.

-Dhttp.nonProxyHosts=localhost|127.0.0.1
-Dhttps.nonProxyHosts=localhost|127.0.0.1

Note: You may need to escape the pipe character | in some command-line environments.
If the http.nonProxyHosts property is not configured, all web requests will be sent to the proxy.

Please note that any command line parameters set are visible from the process list, and thus anyone who has
the approriate access to view the process list will see the proxy information in the clear. To avoid this, you can
set these properties in the catalina.properties file, located in confluence-install/conf/. Add this to the
end of the file:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 302

http.proxyHost=yourProxyURL
http.proxyPort=yourProxyPort
http.proxyUser=yourUserName
http.proxyPassword=yourPassword
https.proxyHost=yourProxyURL
https.proxyPort=yourProxyPort
https.proxyUser=yourUserName
https.proxyPassword=yourPassword

Configuring HTTP proxy authentication

Proxy authentication is also configured by providing system properties to Java in your application server's
configuration file. Specifically, the following two properties:
http.proxyUser – username
http.proxyPassword – secret

HTTP proxy (Microsoft ISA) NTLM authentication

Confluence supports NTLM authentication for outbound HTTP proxies when Confluence is running on a
Windows server.
This means that the {rss} and {jiraissues} macro will be able to contact external websites if requests have to go
through a proxy that requires Windows authentication. This support is not related to logging in Confluence users
automatically with NTLM, for which there is a user-contributed authenticator available.
To configure NTLM authentication for your HTTP proxy, you need to define a domain system property, http.au
th.ntlm.domain, in addition to the properties for host, port and username mentioned above:

-Dhttp.auth.ntlm.domain=MYDOMAIN

Configuring authentication order

Sometimes multiple authentication mechanisms are provided by an HTTP proxy. If you have proxy
authentication failure messages, you should first check your username and password, then you can check for
this problem by examining the HTTP headers in the proxy failure with a packet sniffer on the Confluence server.
(Describing this is outside the scope of this document.)
To set the order for multiple authentication methods, you can set the system property http.proxyAuth to a
comma-separated list of authentication methods. The available methods are: ntlm, digest and basic; this is also
the default order for these methods.
For example, to attempt Basic authentication before NTLM authentication, and avoid Digest authentication
entirely, you can set the http.proxyAuth property to this value:

-Dhttp.proxyAuth=basic,ntlm -Dhttps.proxyAuth=basic,ntlm

Troubleshooting

1. There's a diagnostic jsp file in CONF-9719 for assessing the connection parameters.
2. 'Status Code [407]' errors are described in APR-160.
3. Autoproxies are not supported. See CONF-16941.
Connecting to LDAP or Jira applications or Other Services via SSL

This page documents configuration of SSL,

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 303

rather than of Confluence itself. Atlassian Related pages:

will support Confluence with this
configuration, but we cannot guarantee to Configuring an SSL Connection to
help you debug problems with SSL. Please Active Directory
be aware that this material is provided for Configuring Web Proxy Support
your information only, and that you use it at for Confluence
your own risk. Running Confluence Over SSL or
HTTPS

This page describes how to get Confluence connecting to external servers over SSL, via the various
SSL-wrapped protocols.
Here are some examples of when you may need to connect to an external server over SSL/HTTPS:
You need to connect to an LDAP server, such as Active Directory, if the LDAP server is running over
SSL.
For specific instructions for Active Directory, see Configuring an SSL Connection to Active
Directory.
You want to set up your Jira application as a trusted application in Confluence, when Jira is running
over SSL.
You want to refer to an https://... URL in a Confluence macro.
If you want to run Confluence itself over SSL, see Running Confluence Over SSL or HTTPS.

There's a Confluence SSL plugin that facilitates this process.

Importing SSL Certificates

For more information on these commands, see the Keytool documentation.

1. Add the root certificate to your default Java keystore with the following command. This is the certificate
that was used to authorize the LDAP server's certificate. It will be either the one that was used for
signing it, or will come from further up in the trust chain, possibly the root certificate. This is often a
self-signed certificate, when both ends of the SSL connection are within the same network. Again, the
exact alias is not important.

keytool -importcert -alias serverCert -file RootCert.crt

-keystore %JAVA_HOME%/jre/lib/security/cacerts (Windows)
keytool -importcert -alias serverCert -file RootCert.crt
-keystore $JAVA_HOME/jre/lib/security/cacerts (Linux/Unix/Mac)

2. Import your LDAP or Jira server's public certificate into the JVM Keystore. This is the certificate that
the LDAP server will use to set up the SSL encryption. You can use any alias of your choosing in
place of "JIRAorLDAPServer.crt".

keytool -importcert -alias ldapCert -file JIRAorLDAPServer.crt

-keystore %JAVA_HOME%/jre/lib/security/cacerts (Windows)
keytool -importcert -alias ldapCert -file JIRAorLDAPServer.crt
-keystore $JAVA_HOME/jre/lib/security/cacerts (Linux/Unix/Mac)

3. Verify that the certificate has been added successfully by entering the following command:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 304

keytool -list -keystore %JAVA_HOME%/jre/lib/security/cacerts

(Windows)
keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts
(Unix/Linux)
keytool -list -keystore /Library/Java/Home/lib/security/cacerts
(Mac)

4. Ensure that you have updated CATALINA_OPTS to specify the path to the keystore, as specified in C
onnecting to SSL services before restarting Confluence.
There is no need to specify an alias for Confluence to use. On connecting to the LDAP server, it will
search through the keystore to find a certificate to match the key being presented by the server.

Troubleshooting

Check the following knowledge base articles:

Unable to Connect to SSL Services due to PKIX Path Building Failed
SSL troubleshooting articles

Using Apache with mod_proxy

Atlassian applications allow the use of reverse-proxies, however Atlassian Support does not provide
assistance for configuring them. Consequently, Atlassian can not guarantee providing any
support for them.
If assistance with configuration is required, please raise a question on Atlassian Answers.

This page describes one possible way to use On this page:

Apache HTTP Server 2.4 to proxy requests for
Confluence running in a standard Tomcat container. Base configuration
You can find additional documentation that explains 1 Set the context path
how to use NGINX for the same purpose. 2 Set the URL for
redirection
You might use this configuration when: 3 Configure mod_proxy
4 Restart Apache
You have an existing Apache website, and
5 Disable HTTP
want to add Confluence (for example, http://
Compression
www.example.com/confluence).
6 Change the Confluence
You have two or more Java applications,
Base URL
each running in their own application server
Adding SSL
on different ports, for example, http://exampl More information
e:8090/confluence and http://example:8080
/jira and want to make them both available on
the regular HTTP port (80) (for example, at ht
tp://www.example.com/confluence and htt
p://www.example.com/jira). Each
application can be restarted, managed and
debugged separately.
Note: This page documents a configuration of
Apache, rather than of Confluence itself. Atlassian
will support Confluence with this configuration, but
we cannot guarantee to help you debug problems
with Apache. Please be aware that this material is
provided for your information only, and that you use
it at your own risk.

Base configuration

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 305

In these examples, we use the following:

http://www.example.com/confluence - your intended URL
http://example:8090 - the hostname and port Confluence is currently installed to
http://example:8091 - the hostname and port Synchrony, the service that powers collaborative
editing, defaults to
/confluence - the intended context path for Confluence (the part after hostname and port)
/synchrony - the context path for Synchrony, the process that powers collaborative editing
You'll need to replace these URLs with your own URLs.

1 Set the context path

If you want to access Confluence without a context path, such as www.example.com, skip this step.
Set your Confluence application path (the part after hostname and port) in Tomcat. In this example the
context path will be /confluence.

Edit <installation-directory>conf/server.xml, locate the "Context" definition:

<Context path="" docBase="../confluence" debug="0" reloadable="true">

and change it to:

<Context path="/confluence" docBase="../confluence" debug="0"

reloadable="true">

In this example we've used /confluence as the context path. Note that you can't use /resources as your
context path, as this is used by Confluence, and will cause problems later on.
Restart Confluence, and check you can access it at http://example:8090/confluence.

2 Set the URL for redirection

Next, set the URL for redirection. In the same <installation-directory>conf/server.xml file, use
the example connectors as a starting point.
Comment out the default connector (for unproxied access).
Show me how to do this...
In XML a comment starts with <!-- and ends with -->, and is used to make sure only the relevant
portions of the file are read by the application.
Add <!-- and --> around the default connector. It should now look like this.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 306

<!--
========================================================
DEFAULT - Direct connector with no proxy, for unproxied HTTP access
to Confluence.
========================================================
-->
<!--
<Connector port="8090" connectionTimeout="20000"
redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"/>
-->

Uncomment the connector listed under the HTTP - Proxying Confluence via Apache or Nginx over HTTP
heading.
Show me how to do this...
To uncomment a section, remove the <!-- and --> surrounding the connector.

Here's an example showing the default connector commented out, and the HTTP connector
uncommented. The headings remain commented out.

<!--
========================================================
DEFAULT - Direct connector with no proxy, for unproxied HTTP access
to Confluence.
========================================================
-->
<!--
<Connector port="8090" connectionTimeout="20000"
redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"/>
-->
<!--
========================================================
HTTP - Proxying Confluence via Apache or Nginx over HTTP
========================================================
-->
<Connector port="8090" connectionTimeout="20000"
redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10"
debug="0"URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"
scheme="http" proxyName="<subdomain>.<domain>.com"
proxyPort="80"/>

Insert your proxyName and proxyPort as shown in the last line below:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 307

<Connector port="8090" connectionTimeout="20000" redirectPort="8443"

maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"
scheme="http" proxyName="www.example.com" proxyPort="80"/>

If you plan to enable HTTPS, use the connector under HTTPS - Proxying Confluence via Apache
or Nginx over HTTPS.

3 Configure mod_proxy

Use one of the examples below to edit your Apache http.conf file to proxy requests to the application
server.
You will need to enable the following required Apache modules if they are not already enabled:
mod_proxy
mod_proxy_http
proxy_wstunnel
mod_rewrite
(proxy_wstunnel and mod_rewrite are new requirements in Confluence 6.0)
The format of the http.conf file, and location of the modules may differ on your operating system. We
recommend Windows users specify the absolute path to the module files.

Example 1: Configuration with context path

Use this example if you set a context path in step 1, and will access Confluence with a context path like this h
ttp://www.example.com/confluence.
In this example, users will connect to Synchrony, which is required for collaborative editing, directly via
WebSockets.
The order of directives in the config is important.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 308

Apache HTTP server 2.4

# Put this after the other LoadModule directives
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module
/usr/lib/apache2/modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module
/usr/lib/apache2/modules/mod_proxy_wstunnel.so
LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so

# Put this in the main section of your configuration (or virtual

host, if using Apache virtual hosts)
ProxyRequests Off
ProxyPreserveHost On

<Proxy *>
Require all granted
</Proxy>

ProxyPass /synchrony http://<domain>:8091/synchrony

<Location /synchrony>
Require all granted
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} Upgrade$ [NC]
RewriteRule .* ws://<domain>:8091%{REQUEST_URI} [P]
</Location>

ProxyPass /confluence http://<domain>:8090/confluence

ProxyPassReverse /confluence http://<domain>:8090/confluence

<Location /confluence>
Require all granted
</Location>

Note: It's not possible to use Apache HTTP Server 2.2 with Confluence 6.0 or later. If you plan to use SSL,
you will need version 2.4.10 or later.

Example 2: Configuration without context path

Use this example if you skipped step 1, and will access Confluence without a context path like this http://ww
w.example.com.
As in the previous example, users will connect to Synchrony, which is required for collaborative editing,
directly via WebSockets.
The order of directives in the config is important.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 309

Apache HTTP server 2.4

# Put this after the other LoadModule directives
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module
/usr/lib/apache2/modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module
/usr/lib/apache2/modules/mod_proxy_wstunnel.so
LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so

# Put this in the main section of your configuration (or virtual

host, if using Apache virtual hosts)

ProxyRequests Off
ProxyPreserveHost On

RewriteEngine On
RewriteCond %{REQUEST_URI} !^/synchrony
RewriteRule ^/(.*) http://<domain>:8090/$1 [P]

<Proxy *>
Require all granted
</Proxy>

ProxyPass /synchrony http://<domain>:8091/synchrony

<Location /synchrony>
Require all granted
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} Upgrade$ [NC]
RewriteRule .* ws://<domain>:8091%{REQUEST_URI} [P]
</Location>

ProxyPass / http://<domain>:8090
ProxyPassReverse / http://<domain>:8090

<Location />
Require all granted
</Location>

Note: It's not possible to use Apache HTTP Server 2.2 with Confluence 6.0 or later. If you plan to use SSL,
you will need version 2.4.10 or later.

4 Restart Apache

This is needed to pick up on the new configuration. To restart Apache, run the following command:

sudo apachectl graceful

5 Disable HTTP Compression

Having compression run on both the proxy and Tomcat can cause problems integrating with other Atlassian
applications, such as Jira. Please disable HTTP compression as per our Compressing an HTTP Response
within Confluence docs.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 310

6 Change the Confluence Base URL

The last stage is to set the Base URL to the address you're using within the proxy, for example http://www.e
xample.com/confluence.

Adding SSL

If you plan to enable HTTPS, see Securing your Atlassian applications with Apache using SSL, and make
sure you choose the HTTPS sample connector.

More information

The mod_proxy_html site has documentation and examples on the use of this module in the complex
configuration.
Apache Week has a tutorial that deals with a complex situation involving two applications and
ProxyHTMLURLMap.

Running Confluence behind NGINX with SSL

This page describes how to set up NGINX as a rever On this page
se proxy for Confluence. Step 1: Set the context path
Step 2: Configure the Tomcat
The configuration described on this page results in a
connector
scenario where:
Step 3: Configure NGINX
External client connections with NGINX are Step 4: Restart Confluence and
secured using SSL. Connections between NGINX
NGINX and Confluence Server are
unsecured.
Confluence Server and NGINX run on the
same machine.
We assume that you already have a running instance of NGINX. If not, refer to the NGINX documentation for
instructions on downloading and installing NGINX. SSL certificates must be installed on the server machine.
You'll an NGINX version that supports WebSockets (1.3 or later).
If your team plans to use the Confluence Server mobile app, you'll need a certificate issued by a trusted
Certificate Authority. You can't use the app with a self-signed certificate, or one from an untrusted or private
CA.

Atlassian Support can't provide assistance with configuring third-party tools like NGINX. If you have
questions, check the NGINX documentation, ask the Atlassian Community, or get help from a Solutio
n Partner.

Step 1: Set the context path

If you want to access Confluence without a context path (www.example.com), or via a sub-domain
(confluence.example.com) skip this step.
Set your Confluence application path (the part after hostname and port) in Tomcat. Edit <installation-d
irectory>/conf/server.xml, locate the "Context" definition:

<Context path="" docBase="../confluence" debug="0"

reloadable="false">

and change it to:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 311

<Context path="/confluence" docBase="../confluence" debug="0"

reloadable="false">

In this example we've used /confluence as the context path. Note that you can't use /resources as your
context path, as this is used by Confluence, and will cause problems later on.
Restart Confluence, and check you can access it at http://example:8090/confluence

Step 2: Configure the Tomcat connector

In the same <installation-directory>conf/server.xml file, use the example connectors as a

starting point.
Comment out the default connector (for unproxied access).
Show me how to do this...
In XML a comment starts with <!-- and ends with -->, and is used to make sure only the relevant
portions of the file are read by the application.
Add <!-- and --> around the default connector. It should now look like this.

<!--
========================================================
DEFAULT - Direct connector with no proxy, for unproxied HTTP access
to Confluence.
========================================================
-->
<!--
<Connector port="8090" connectionTimeout="20000"
redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"/>
-->

Uncomment the connector listed under the HTTPS - Proxying Confluence via Apache or Nginx over
HTTPS heading.
Show me how to do this...
To uncomment a section, remove the <!-- and --> surrounding the connector.

Here's an example showing the default connector commented out, and the HTTPS connector
uncommented. The headings remain commented out.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 312

<!--
========================================================
DEFAULT - Direct connector with no proxy, for unproxied HTTP access
to Confluence.
========================================================
-->
<!--
<Connector port="8090" connectionTimeout="20000"
redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"/>
-->
...
<!--
========================================================
HTTPS - Proxying Confluence via Apache or Nginx over HTTPS
========================================================
-->
<Connector port="8090" connectionTimeout="20000"
redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"
scheme="https" secure="true"
proxyName="<subdomain>.<domain>.com" proxyPort="443"/>

Insert your proxyName and proxyPort as shown in the last line below:

<Connector port="8090" connectionTimeout="20000" redirectPort="8443"

maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"
scheme="https" secure="true" proxyName="www.example.com"
proxyPort="443"/>

Make sure you've included correct values for protocol and proxyName.

Step 3: Configure NGINX

You will need to specify a listening server in NGINX, as in the example below. Add the following to your
NGINX configuration.
Replace your server name and the location of your SSL certificate and key.
In this example, users will connect to Synchrony, which is required for collaborative editing, directly.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 313

server {
listen www.example.com:80;
server_name www.example.com;

listen 443 default ssl;

ssl_certificate /usr/local/etc/nginx/ssl/nginx.crt;
ssl_certificate_key /usr/local/etc/nginx/ssl/nginx.key;

ssl_session_timeout 5m;

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-
POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:
ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA
-
AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RS
A-
AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-
ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-
RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-
SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-
SHA:!DSS';
ssl_prefer_server_ciphers on;

location /confluence {
client_max_body_size 100m;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8090/confluence;
}
location /synchrony {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8091/synchrony;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
}
}

See https://nginx.org/en/docs/http/ngx_http_proxy_module.html for more information.

Note: do not include ssl on; if you are configuring SSL and Confluence on the same server, as in this
example.
If you're not sure what to include for ssl_ciphers, https://mozilla.github.io/server-side-tls/ssl-config-generat
or/ is a useful resource.
If you experience 413 Request Entity Too Large errors, make sure that the client_max_body_size in the /co
nfluence location block matches Confluence's maximum attachment size. You may also need to increase
the client_max_body_size in the /synchrony location block if you experience errors when editing large
pages.
If you plan to use the Confluence mobile app...
If you plan to allow users to use the Confluence mobile app with your site, and you have configured a

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 314

context path, as in the example above, you may also need to add the following line to your nginx
configuration.

location /server-info.action {
proxy_pass
http://localhost:8090/confluence/server-info.action;
}

If you're accessing Confluence via a sub-domain...

If you're accessing Confluence via a sub-domain, your config will look like this:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 315

server {
listen confluence.example.com:80;
server_name confluence.example.com;

listen 443 default ssl;

ssl_certificate /usr/local/etc/nginx/ssl/nginx.crt;
ssl_certificate_key /usr/local/etc/nginx/ssl/nginx.key;

ssl_session_timeout 5m;

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-
POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:
ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECD
SA-
AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-
RSA-
AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-
ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDH
E-
RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-
SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-
SHA:!DSS';
ssl_prefer_server_ciphers on;

location / {
client_max_body_size 100m;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For
$proxy_add_x_forwarded_for;
proxy_pass http://localhost:8090;
}
location /synchrony {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For
$proxy_add_x_forwarded_for;
proxy_pass http://localhost:8091/synchrony;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
}
}

Step 4: Restart Confluence and NGINX

1. Restart Confluence and NGINX for all the changes to take affect.
2. Update Confluence's base URL to include the context path you set earlier - see Configuring the Server
Base URL.

Running Confluence Over SSL or HTTPS

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 316

Atlassian applications can be accessed via HTTPS, however Atlassian Support does not provide
assistance for configuring it. Consequently, Atlassian cannot guarantee providing any support for
it.
If assistance with conversions of certificates is required, please consult with the vendor who
provided the certificate.
If assistance with configuration is required, please raise a question on Atlassian Community.

This page provides a basic outline of how to On this page:

configure Confluence to enable access via HTTPS
(HTTP Secure), so that your Confluence logins and Step 1. Create or request an SSL
data are encrypted during transport to and from certificate
Confluence. This is a good way to safeguard your Step 2. Modify your Confluence
Confluence data and user logins from being server.xml file
intercepted and read by outsiders. Step 3. Specify the location of your
certificate
In this article we use 'SSL' as a general term to refer Step 4. Change your confluence
to the protocol used to encrypt traffic. In most cases base URL to HTTPS
the protocol will be TLS. Step 5. Add a security constraint
to redirect all URLs to HTTPS
Notes
Troubleshooting

Related Topics

SSL Configuration HOW-TO in the

Apache Tomcat 8.0
documentation
keytool - Key and Certificate
Management Tool in the Java SE
documentation
Connecting to LDAP or Jira
applications or Other Services via
SSL

These instructions cover terminating SSL at Tomcat, the application server shipped with Confluence.
If you want to terminate SSL at your web server or proxy, see Apache with mod_proxy or Running
Confluence behind NGINX with SSL for examples of how to terminate SSL at an external web server.
You'll need JDK 1.8 for some of the steps in this guide. The JRE is not enough.

Running Confluence without HTTPS enabled may leave your site exposed to vulnerabilities, such as
man-in-the-middle or DNS rebinding attacks. We recommend you enable HTTPS on your site.

Step 1. Create or request an SSL certificate

You'll need a valid certificate before you can enable HTTPS. If you already have a certificate, skip to step 2.
You can create your own self-signed certificate, or acquire one from a trusted Certificate Authority.
If your team plans to use the Confluence Server mobile app, you'll need a certificate issued by a trusted
Certificate Authority. You can't use the app with a self-signed certificate, or one from an untrusted or private
CA.

Option 1: Create a self-signed certificate

Self-signed certificates are useful if you require encryption but don't need to verify the identity of the
requesting website. In general, you might use a self-signed certificate on a test environment and on internal
corporate networks (intranets).

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 317

Because the certificate is not signed by a certificate authority (CA), users may receive a message that the
site is not trusted and may have to perform several steps to accept the certificate before they can access the
site. This usually will only occur the first time they access the site. Users won't be able to log in to your site at
all via the Confluence Server mobile app if you use a self-signed certificate.
In this example, we'll use Java's keytool utility, which is included with the JDK. If you're not comfortable
using command line utilities KeyStore Explorer is a useful alternative to the command line.
To generate a self-signed certificate using keytool:

1. From the command line, run the appropriate command for your operating system:

Windows
"%JAVA_HOME%\bin\keytool" -genkeypair -keysize 2048 -alias
tomcat -keyalg RSA -sigalg SHA256withRSA

Linux (and MacOS)

$JAVA_HOME/bin/keytool -genkeypair -keysize 2048 -alias tomcat
-keyalg RSA -sigalg SHA256withRSA

2. When prompted, create a password for the certificate (private key).

Only use alphanumeric characters. Tomcat has a known issue with special characters.
Make a note of the password, you'll need it in the next step.
The default password is 'changeit'.
3. Follow the prompts to specify the certificate details. This info is used to construct the X.500
Distinguished Name (DN) of the entity.

First and last name: this is not your name, it is the Common Name (CN), for example
'confluence.example.com'. The CN must match the fully qualified hostname of the server
running Confluence, or Tomcat won't be able to use the certificate for SSL.
Organizational unit: this is the team or department requesting the certificate, for example
'marketing'.
Organization: this is your company name, for example 'SeeSpaceEZ'.
City, State / province, country code: this is where you're located, for example Sydney, NSW,
AU.
4. The output will look something like the example below. Hit 'y' to confirm the details.

CN=confluence.example.com, OU=Marketing, O=SeeSpaceEZ, L=Sydney,

ST=NSW, C=AU

5. When asked for the password for 'tomcat', enter the password you created in step 2 (or hit return to
use the same .
'tomcat' is the alias we entered in the keytool command above, it refers to your.
Your keystore entry must have the same password as your private key. This is a Tomcat
requirement.

6. You certificate is now ready. Go to step 2 below.

Option 2: Use a certificate issued by a Certificate Authority (recommended)

Production environments will need a certificate issued by a Certificate Authority (CA). These instructions are
adapted from the Tomcat documentation.
First you will generate a local certificate and create a 'certificate signing request' (CSR) based on that
certificate. You will submit the CSR to your chosen certificate authority. The CA will use that CSR to generate
a certificate for you.

1.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 318

1. Use Java's keytool utility to generate a local certificate (follow the steps in option 1, above).
2. From the command line, run the following command to generate a certificate signing request.

keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr

-keystore <MY_KEYSTORE_FILENAME>

Replace <MY_KEYSTORE_FILENAME> with the path to and file name of the .keystore file generated
for your local certificate.
3. Submit the generated file called certreq.csr to your chosen certificate authority.
Check your CA's documentation to find out how to do this.
4. The CA will send you a certificate.
5. Import the new certificate into your local keystore:

keytool -importcert -alias tomcat -keystore

<MY_KEYSTORE_FILENAME> -file <MY_CERTIFICATE_FILENAME>

Some CAs require you to install an intermediate certificate before importing your certificate. You
should follow your CA documentation to successfully install your certificate.

If you receive an error, and you use Verisign or GoDaddy, you may need to export the certificate to
PKCS12 format along with the private key.
1. First, remove the certificate added above from the keystore:

keytool -delete -alias tomcat -keystore

<MY_KEYSTORE_FILENAME>

2. Then export to PKCS12 format:

openssl pkcs12 -export -in <MY_CERTIFICATE_NAME> -inkey

<MY_PRIVATEKEY_NAME> -out <MY_PKC12_KEYSTORE_NAME> -name
tomcat -CAfile
<MY_ROOTCERTIFICATE_NAME-alsoCalledBundleCertificateInGoDa
ddy> -caname root

3. Then import from PKCS12 to jks:

keytool -importkeystore -deststorepass

<MY_DESTINATIONSTORE_PASSWORD> -destkeypass
<MY_DESTINATIONKEY_PASSWORD> -destkeystore
<MY_KEYSTORE_FILENAME> -srckeystore
<MY_PKC12_KEYSTORE_NAME> -srcstoretype PKCS12
-srcstorepass <MY_PKC12_KEYSTORE_PASSWORD> -alias tomcat

Step 2. Modify your Confluence server.xml file

The next step is to configure Confluence to use HTTPS.

1.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 319

1. Edit <install-directory>/conf/server.xml.
2. Uncomment the following lines:

<Connector port="8443" maxHttpHeaderSize="8192"

maxThreads="150" minSpareThreads="25"
protocol="org.apache.coyote.http11.Http11NioProtocol"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocols="TLSv1,TLSv1.1,TLSv1.2"

sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2"
SSLEnabled="true"
URIEncoding="UTF-8"
keystorePass="<MY_CERTIFICATE_PASSWORD>"/>

3. Replace <MY_CERTIFICATE_PASSWORD> with the password you specified for your certificate.
4. Make sure that the attribute-value pair SSLEnabled="true" is part of the Connector element, as
shown above. If this attribute is not present, attempts to access Confluence will time out.
5. Save the server configuration file.
Don't remove or comment out the http connector, as the Synchrony proxy health check, still requires
HTTP. If you don't want to include the http connector, you can use the synchrony.proxy.healthcheck
.disabled system property to disable the health check.

You should also not disable the internal Synchrony proxy (by setting the synchrony.proxy.enabled syst
em property to false) as this is known to cause problems when you're terminating SSL at Tomcat.

The default connector port for Confluence is 8090.

Step 3. Specify the location of your certificate

By default, Tomcat expects the keystore file to be named .keystore and to be located in the user home
directory under which Tomcat is running (which may or may not be the same as your own home directory).
This means that, by default, Tomcat will look for your SSL certificates in the following location:
On Windows: C:\users\#CURRENT_USER#\.keystore
On OS X and UNIX-based systems: ~/.keystore

Don't store your keystore file in your Confluence installation directory as the contents of that directory
are removed when you upgrade Confluence.

You may decide to move the certificate to a custom location. If your certificate is not in the default location,
you'll need to update your server configuration file as outlined below, so that Tomcat can find the certificate.
1. Edit <confluence-install-directory>/conf/server.xml
2. Add the attribute keystoreFile="<MY_CERTIFICATE_LOCATION>" to the Connectorelement, so
that the element looks like this:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 320

<Connector port="8443" maxHttpHeaderSize="8192"

maxThreads="150" minSpareThreads="25"
maxSpareThreads="75"
enableLookups="false"
disableUploadTimeout="true"
acceptCount="100" scheme="https"
secure="true"
clientAuth="false" sslProtocol="TLS"
SSLEnabled="true"
URIEncoding="UTF-8"
keystorePass="<MY_CERTIFICATE_PASSWORD>"
keystoreFile="<MY_CERTIFICATE_LOCATION>"/>

3. Replace the text <MY_CERTIFICATE_LOCATION> with the path to your certificate, including the path
and the name of the .keystore file.
4. Save the configuration file.

Step 4. Change your confluence base URL to HTTPS

1. In your browser, go to

> General Configuration.

2. Click Edit.
3. Change the Server Base URL to HTTPS. See the documentation on configuring the server base URL.
4. Restart Confluence and access Confluence on https://<MY_BASE_URL>:8443/.

Step 5. Add a security constraint to redirect all URLs to HTTPS

Although HTTPS is now activated and available, the old HTTP URLs (http://localhost:8090) are still available.
Now you need to redirect the URLs to their HTTPS equivalent. You will do this by adding a security constraint
in web.xml. This will cause Tomcat to redirect requests that come in on a non-SSL port.

1. Check whether your Confluence site uses the RSS macro. If your site has the RSS macro enabled,
you may need to configure the URL redirection with a firewall rule, rather than by editing the web.xml
file. Skip the steps below and follow the steps on the RSS Feed Macro page instead.
2. Otherwise, Edit the file at <CONFLUENCE_INSTALLATION>/confluence/WEB-INF/web.xml.
3. Add the following declaration to the end of the file, before the </web-app>tag:

<security-constraint>
<web-resource-collection>
<web-resource-name>Restricted URLs</web-resource-name>
<url-pattern>/</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

4. Restart Confluence and access http://localhost:8090. You should be redirected to https://localhost:844

3/login.action.
Confluence has two web.xml files. The other one is at <CONFLUENCE_INSTALLATION>/conf/web.xml
. Please only add the security constraints to <CONFLUENCE_INSTALLATION>/confluence/WEB-INF/we
b.xml, as described above.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 321

Notes

Background information on generating a certificate: The 'keytool -genkeypair' command

generates a key pair consisting of a public key and the associated private key, and stores them in a
keystore. The command packages the public key into an X.509 v3 self-signed certificate, which is
stored as a single-element certificate chain. This certificate chain and the private key are stored in a
new keystore entry, identified by the alias that you specify in the command. The Java SE
documentation has a good overview of the utility.
Custom SSL port: If you have changed the port that the SSL connector is running on from the default
value of 8443, you must update the redirectPort attribute of the standard HTTP connector to
reflect the new SSL port. Tomcat needs this information to know which port to redirect to when an
incoming request needs to be secure.
Multiple instances on the same host: When running more than one instance on the same host, it is
important to specify the address attribute in the <CONFLUENCE_INSTALLATION>/conf/server.xm
l file because by default the connector will listen on all available network interfaces, so specifying
the address will prevent conflicts with connectors running on the same default port. See the Tomcat
Connector documentation for more about setting the address attribute:

<Connector port="8443" address="your.confluence.url.com"

maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" SSLEnabled="true"
URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>"
keystoreFile="<MY_CERTIFICATE_LOCATION>"/>

HTTPS must be configured for your whole site. It can't be enabled for individual pages or spaces.
Before you upgrade Confluence, make a note of the changes you have made to your server.xml
and web.xml files. It is always best to re-apply these changes manually after upgrading, rather than
copying over your existing files.

Troubleshooting

Check the Confluence knowledge base articles on troubleshooting SSL

Problems with Internet Explorer being unable to download attachments: Applying SSL site wide
can prevent IE from downloading attachments correctly. To fix this problem, edit <CONFLUENCE_INST
ALLATION>/conf/server.xml and add the following line within the <Context ... />element:

<Valve
className="org.apache.catalina.authenticator.NonLoginAuthenticat
or"
disableProxyCaching="true" securePagesWithPragma="false"
/>

Using Apache to limit access to the Confluence administration interface

Limiting administration to specific IP addresses

The Confluence administration interface is a critical part of the application; anyone with access to it can
potentially compromise not only the Confluence instance but the entire machine. As well as limiting access to
users who really need it, and using strong passwords, you should consider limiting access to it to certain
machines on the network or internet. If you are using an Apache web server, this can be done with Apache's Lo
cation functionality as follows:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 322

1. Create a file that defines permission settings

This file can be in the Apache configuration directory or in a system-wide directory. For this example we'll call it
"sysadmin_ips_only.conf". The file should contain the following:

Order Deny,Allow
Deny from All

# Mark the Sysadmin's workstation

Allow from 192.168.12.42

2. Add the file to your Virtual Host

In your Apache Virtual Host, add the following lines to restrict the administration actions to the Systems
Administrator:

This configuration assumes you've installed Confluence under '/confluence'. If you have installed under
'/' or elsewhere, adjust the paths accordingly.

<Location /confluence/admin>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/consumers/list>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/view-consumer-info>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/service-providers/list>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/service-providers/add>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/consumers/add>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/consumers/add-manually>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/update-consumer-info>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/pages/templates/listpagetemplates.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/pages/templates/createpagetemplate.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/spacepermissions.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/pages/listpermissionpages.action>
Include sysadmin_ips_only.conf
</Location>

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 323

<Location /confluence/spaces/removespace.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/importmbox.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/viewmailaccounts.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/addmailaccount.action?>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/importpages.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/flyingpdf/flyingpdf.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/exportspacehtml.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/exportspacexml.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/embedded-crowd>
Include sysadmin_ips_only.conf
</Location>

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 324

<Location /confluence/plugins/servlet/upm>
Include sysadmin_ips_only.conf
</Location>

Using Apache with mod_jk

It's not possible to use only mod_jk to proxy Confluence 6.0 or later. This is because Synchrony, which
is required for collaborative editing, cannot accept AJP connections. The preferred configuration is Using
Apache with mod_proxy.
If you are unable to switch to mod_proxy, see How to configure Apache mod_jk to proxy Confluence 6.x
or later for a workaround.

Using mod_rewrite to Modify Confluence URLs

Note: This page documents a configuration of Apache, rather than of Confluence itself. Atlassian will support
Confluence with this configuration, but we cannot guarantee to help you debug problems with Apache. Please
be aware that this material is provided for your information only, and that you use it at your own risk.
Confluence requires URL rewriting for proper functionality, if Confluence is accessible via different domain
names. If Confluence is configured for multiple domains without URL rewriting, you will experience an array of
problems. See Various Issues Caused when Server Base URL Does Not Match the URL Used to Access
Confluence.
An example of why you may want to access Confluence from different domains:
From an internal network:
http://wiki
The externally visible domain:
http://wiki.domain.com

Using URL rewriting to access Confluence over multiple domains

To configure Confluence over multiple domains:

1. Add a DNS entry mapping http://wiki to the externally visible IP address of the Confluence server.
2. Set Confluence's server base URL to http://wiki.domain.com.
3. Add Apache HTTP proxy, using the instructions from Running Confluence behind Apache.
4. Add the mod_rewrite module to change the URL.

Further information

You may be interested in the UrlRewriteFilter that is Java web filter that works in a similar way of the Apache's
mod_rewrite.
Configuring Secure Administrator Sessions
Confluence protects access to its administrative functions by requiring a secure administration session to use
the Confluence administration console or administer a space. When a Confluence administrator (who is logged
into Confluence) attempts to access an administration function, they are prompted to log in again. This logs the
administrator into a temporary secure session that grants access to the Confluence/space administration
console.
The temporary secure session has a rolling timeout (defaulted to 10 minutes). If there is no activity by the
administrator in the Confluence/space administration console for a period of time that exceeds the timeout, then
the administrator will be logged out of the secure administrator session (note, they will remain logged into
Confluence). If the administrator does click an administration function, the timeout will reset.
To configure secure administrator sessions:

1.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 325

1. Choose the cog icon

, then choose General Configuration

2. Choose Security Configuration in the left-hand panel.
3. Choose Edit.
4. Configure the setting as follows:
To disable secure administrator sessions, uncheck the Enable check box next to Secure
administrator sessions. When this setting is disabled, administrators will no longer be required to
log into a secure session to access the administration console.
To change the timeout for secure administrator sessions, update the value next to minutes before
invalidation. The default timeout for a secure administration session is 10 minutes.
5. Choose Save.

Notes

Disabling password confirmation. Confluence installations that use a custom authentication

mechanism may run into problems with the Confluence security measure that requires password
confirmation. If necessary, you can set the password.confirmation.disabled system property to
disable the password confirmation functionality. See Recognized System Properties. See issue CONF-20
958 "Confluence features that require password confirmation (websudo, captcha) do not work with
custom authentication".
WebSudo. The feature that provides secure administrator sessions is also called 'WebSudo'.
Manually ending a secure session. An administrator can choose to manually end their secure session
by clicking the 'drop access' link in the banner displayed at the top of their screen. For example:

Note for developers. Secure administrator sessions can cause exceptions when developing against
Confluence or deploying a plugin. Please read this FAQ: How do I develop against Confluence with
Secure Administrator Sessions? Note: The Confluence XML-RPC and REST APIs are not affected by
secure administration sessions.
Confluence Cookies
This page lists cookies stored in Confluence users' browsers which are On this page:
generated by Confluence itself. This page does not list cookies that may
originate from 3rd-party Confluence plugins. Authentica
tion
cookies
Authentication cookies Other
Confluenc
Confluence uses Seraph, an open source framework, for HTTP cookie e cookies
authentication. Confluence uses two types of cookies for user Notes
authentication:
The JSESSIONID cookie is created by the application server and
used for session tracking purposes. This cookie contains a random
string and the cookie expires at the end of every session or when the
browser is closed.
The 'remember me' cookie, seraph.confluence, is generated by
Confluence when the user selects the Remember me check box on
the login page.
You can read about cookies on the Wikipedia page about HTTP cookies.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 326

The 'remember me' cookie

The 'remember me' cookie, seraph.confluence, is a long-lived HTTP cookie. This cookie can be used to
authenticate an unauthenticated session. Confluence generates this cookie when the user selects the Reme
mber me check box on the login page.

Cookie key and contents

By default, the cookie key is seraph.confluence, which is defined by the login.cookie.key parameter
in the CONFLUENCE-INSTALLATION/confluence/WEB-INF/classes/seraph-config.xml file.

The cookie contains a unique identifier plus a securely-generated random string (i.e. token). This token is
generated by Confluence and is also stored for the user in the Confluence database.

Use of cookie for authentication

When a user requests a web page, if the request is not already authenticated via session-based
authentication or otherwise, Confluence will match the 'remember me' cookie (if present) against the token
(also if present), which is stored for the user in the Confluence database.
If the token in the cookie matches the token stored in the database and the cookie has not expired, the user
is authenticated.

Life of 'remember me' cookies

You can configure the maximum age of the cookie. To do that you will need to modify the CONFLUENCE-INS
TALLATION/confluence/WEB-INF/classes/seraph-config.xml file and insert the following lines
below the other init-param elements:

<init-param>
<param-name>autologin.cookie.age</param-name>
<param-value>2592000</param-value><!-- 30 days in seconds -->
</init-param>

Automatic cleanup of 'remember me' tokens

Every cookie issued by Confluence has a corresponding record in the database. A scheduled job runs on the
20th of every month to clean up expired tokens. The name of the trigger is clearExpiredRememberMeTok
ensTrigger.

Note: The only purpose of this job is to prevent the database table from growing too big. For authentication

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 327

purposes, Confluence will ignore expired tokens even if they still exist in the database.

Is it possible to disable the 'remember me' feature?

Confluence does not offer an option for disabling the 'Remember Me' feature. See the workaround.

Other Confluence cookies

There are several cookies that Confluence uses to store basic 'product presentation' states. Confluence
users' authentication details are not stored by these cookies.

Cookie Key Purpose Cookie Expiry

Contents

confluence.list.pages.cookie Remembers the user's last chosen The name of One

tab in the "list pages" section. the last year
selected tab. from the
For example, date it
list-content-tree was set
or was
last
updated.

confluence.browse.space.cookie Remembers the user's last chosen The name of One

tab in the "browse space" section the last year
selected tab. from the
For example, date it
space-pages was set
or was
last
updated.

confluence-language Remembers the user's language A locale 360

chosen on the login page. This cookie relating to the days
relates to a feature that allows a user chosen from the
to change Confluence's language language. For date it
from (and including) the login page, example, was set
when the language presented to the de_DE or was
user prior to logging in is not last
appropriate. updated.

AJS.conglomerate.cookie Tracks which general tabs were last One or more One
used or expansion elements were last key-value year
opened or closed. strings which from the
indicate the date it is
states of your set or
last general tab was last
views or updated.
expansion
elements.

Notes

The autocomplete feature in browser text fields (which are typically noticeable when a user logs in to
Confluence) is a browser-specific feature, not a Confluence one. Confluence cannot enable or disable
this autocompletion, which is typically set through a browser's settings.

Using Fail2Ban to limit login attempts

What is Fail2Ban?

We need a means of defending sites against brute-force login attempts. Fail2Ban is a Python application which

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 328

trails logfiles, looks for regular expressions and works with Shorewall (or directly with iptables) to apply
temporary blacklists against addresses that match a pattern too often. This can be used to limit the rate at which
a given machine hits login URLs for Confluence.

The information on this

page does not apply to
Confluence Cloud.

Prerequisites

Requires Python 2.4 or higher to be installed

Needs a specific file to follow, which means your Apache instance needs to log your Confluence access
to a known logfile. You should adjust the configuration below appropriately.

How to set it up

This list is a skeletal version of the instructions

There's an RPM available for RHEL on the download page, but you can also download the source and set
it up manually
Its configuration files go into /etc/fail2ban
The generic, default configuration goes into .conf files (fail2ban.conf and jail.conf). Don't
change these, as it makes upgrading difficult.
Overrides to the generic configuration go into .local files corresponding to the .conf files. These only
need to contain the specific settings you want overridden, which helps maintainability.
Filters go into filter.d — this is where you define regexps, each going into its own file
Actions go into action.d — you probably won't need to add one, but it's handy to know what's available
"jails" are a configuration unit that specify one regexp to check, and one or more actions to trigger when
the threshold is reached, plus the threshold settings (e.g. more than 3 matches in 60 seconds causes that
address to be blocked for 600 seconds)
Jails are defined in jail.conf and jail.local. Don't forget the enabled setting for each one — it
can be as bad to have the wrong ones enabled as to have the right ones disabled.

Running Fail2Ban

Use /etc/init.d/fail2ban {start|stop|status} for the obvious operations

Use fail2ban-client -d to get it to dump its current configuration to STDOUT. Very useful for
troubleshooting.
Mind the CPU usage; it can soak up resources pretty quickly on a busy site, even with simple regexp
It can log either to syslog or a file, whichever suits your needs better

Common Configuration

jail.local

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 329

# The DEFAULT allows a global definition of the options. They can be

override
# in each jail afterwards.

[DEFAULT]

# "ignoreip" can be an IP address, a CIDR mask or a DNS host. Fail2ban

will not
# ban a host which matches an address in this list. Several addresses
can be
# defined using space separator.
# ignoreip = <space-separated list of IPs>

# "bantime" is the number of seconds that a host is banned.

bantime = 600

# A host is banned if it has generated "maxretry" during the last

"findtime"
# seconds.
findtime = 60

# "maxretry" is the number of failures before a host get banned.

maxretry = 3

[ssh-iptables]

enabled = false

[apache-shorewall]

enabled = true
filter = cac-login
action = shorewall
logpath = /var/log/httpd/confluence-access.log
bantime = 600
maxretry = 3
findtime = 60
backend = polling

Configuring for Confluence

The following is an example only, and you should adjust it for your site.

filter.d/confluence-login.conf

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 330

[Definition]

failregex = <HOST>.*"GET /login.action

ignoreregex =

Securing Confluence with Apache

Error rendering macro 'viewport-redirect' : null

Trackback and External Referrers

Trackback On this page:
Trackback
When Trackback is enabled, any time you link to an External referrers
external webpage that supports Trackback Excluding external
Autodiscovery, Confluence will send a trackback referrers
ping to that page to inform it that it has been linked Hiding external referrers
to. Ignoring external referrers
Confluence pages also support Trackback
Autodiscovery and when Trackback is enabled, can
receive trackback pings from other sites.
To enable trackback:
1. Go to

> General Configuration > Further Configuration

2. Choose Edit
3. Select the Trackback checkbox then Save

External referrers

An external referrer is any site that links to your Confluence instance. Each time someone clicks on the
external link, your Confluence site can record the click as a referral.
By default, external referrers for a page are listed under 'Hot Referrers' on the 'Info' screen of the page.
Confluence shows a maximum of 10 referrers. If there are more than 10, confluence shows the 10 with the
highest number of hits.
Note that you do not need to enable trackback in order to have external referrers enabled.
Screenshot: hot referrers on the page information screen.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 331

Excluding external referrers

Confluence Administrators can exclude external referrers to prevent them from being recorded or displayed
anywhere on your site. Once you have specified your list of blocked URLs, any incoming links from URLs
that match the list will no longer be recorded.
Referrer URLs are blocked if they start with any of the URLs in the exclusion list. So http://evilspamsite.blogs
pot.com will also match http://evilspamsite.blogspot.com/nastypage.html
You might want to do this if:
1. You're running a Confluence installation that is open to public
In a site that is open to public, one unfortunate problem is that malicious sites can spam the display of
a page's incoming links statistics. This is usually done to get the site's URL to appear in the sidebar.
By adding these sites to the 'excluded referrers' list, you can prevent them from being listed on your
site.
2. Confluence is installed on a server with multiple domain names or IP addresses
Confluence will consider any URL originating from the domain name where Confluence is installed as
an internal link. However, if Confluence is installed on a server with multiple domain names or IP
addresses, you will need to add the other domain name prefixes to this list to let Confluence know that
any links from these domains should not be considered external links.
To add a URL to the excluded referrers list:
1. Go to

> General Configuration > Manage Referrers

2. Enter the URL in the Referrer URL Prefix field (you must include http://)
3. Choose Add
You can add multiple URLs to the list.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 332

Hiding external referrers

By default, Confluence lists the external referrers as 'Hot Referrers' on the page information screen for a
page. If you turn this option off, external referrers will not be listed on the page.
To hide external referrers:
1. Go to

> General Configuration > Manage Referrers.

2. Deselect Show Referrers in Page Info.
Screenshot: Managing external referrers

Ignoring external referrers

An external referrer is any site that links to your Confluence instance. Each time someone clicks on the
external link, your Confluence site can record the click as a referral. By default, Confluence records the
number of hits made to a page from any link on an external site. If you turn this option off, Confluence will not
record the hits.
To ignore external referrers:
1. Go to

> General Configuration > Manage Referrers

2. Deselect Record External Referrers
Screenshot: Managing external referrers

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 333

Best Practices for Configuring Confluence Security

The best way to harden a system is to look at each of the involved systems individually. Contact your company's
security officer or department to find out what security policies you should be using. There are many things to
consider, such as the configuration of your underlying operating systems, application servers, database servers,
network, firewall, routers, etc. It would be impossible to outline all of them here.
This page contains guidelines on good security practices, to the best of our knowledge.

Configuring the Web Server

Please refer to the following guides for system administrators:

How to configure Apache to lock down the administration interface to those people who really need it: Usi
ng Apache to limit access to the Confluence administration interface.
How to reduce the risk of brute force attacks: Using Fail2Ban to limit login attempts.

Configuring the Application Server

See the following system administrator guide for general hints on the application server level:
Tomcat security best practices

Configuring the Application

The way you set up Confluence roles, permissions and processes makes a big difference in the security of your
Confluence site.
Below are some more Confluence-specific items to consider. None of these provides 100% security. They are
measures to reduce impact and to slow down an intruder in case your system does become compromised.
Keep the number of Confluence administrators extremely low. For example, 3 system administrator
accounts should be the maximum.
Similarly, restrict the number of users with powerful roles or group memberships. If only one department
should have access to particularly sensitive data, then do restrict access to the data to those users. Do
not let convenience over-rule security. Do not give all staff access to sensitive data when there is no
need.
The administrators should have separate Confluence accounts for their administrative roles and for their
day to day roles. If John Doe is an administrator, he should have a regular user account without
administrator access to do his day to day work (such as writing pages in the wiki). This could be a
'john.doe' account. In addition, he should have an entirely separate account (that cannot be guessed by
an outsider and that does not even use his proper name) for administrative work. This account could be
'jane smith' – using a username that is so obscure or fake that no outsider could guess it. This way, even

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 334

if an attacker singles out the actual person John Doe and gets hold of his password, the stolen account
would most likely be John's regular user account, and the attacker cannot perform administrative actions
with that account.
Lock down administrative actions as much as you can. If there is no need for your administrators to
perform administrative actions from outside the office, then lock down access to those actions to known
IP adresses, for example. See Using Apache to limit access to the Confluence administration interface.
Put documented procedures in place for the case of employees leaving the company.
Perform security audits regularly. Know who can help in case a security breach occurs. Perform 'what if'
planning exercises. ('What is the worst thing that could happen if a privileged user's password were stolen
while he's on vacation? What can we do to minimize damage?').
Make sure the Confluence database user (and all datasource database users) only has the amount of
database privileges it really needs.
Monitor your binaries. If an attacker compromises an account on your system, he will usually try to gain
access to more accounts. This is sometimes done by adding malicious code, such as by modifying files
on the system. Run routine scripts that regularly verify that no malicious change has been made.
As another precaution:
Regularly monitor the above requirements. There are many things that could start out well, but deteriorate
over time:
A system may start out with just 3 administrators, but over the course of a year this could grow to
30 administrators if no one prevents expansion.
Apache administration restrictions may be in place at the start of the year, but when the application
server is migrated after a few months, people may forget to apply the rules to the new system.
Again, keep in mind that the above steps may only be a fraction of what could apply to you, depending on your
security requirements. Also, keep in mind that none of the above rules can guarantee anything. They just make it
harder for an intruder to move quickly.
Hiding the People Directory
The People Directory provides a list of all users in your Confluence system.
If you need to disable the People Directory set the following system properties on your application server
command line:
To disable the People Directory for anonymous users:

-Dconfluence.disable.peopledirectory.anonymous=true

To disable the People Directory entirely:

-Dconfluence.disable.peopledirectory.all=true

This workaround will prevent the People directory from appearing on the dashboard, but if you navigate to the
profile of a user, and then click on the "People" in the breadcrumb link (Dashboard >> People >> FullName >>
Profile) or you go to the URL directly <CONFLUENCE_INSTALL>/browsepeople.action, you will be able to
access the people directory.
To workaround this, set up your Apache webserver in front of Confluence and redirect requests to this URL.
Configuring Captcha for Spam Prevention
If your Confluence site is open to the public (you
allow anonymous users to add comments, create Related pages:
pages etc) you may find that automated spam is Configuring Confluence Security
being added, in the form of comments or new pages.
You can configure Confluence to deter automated
spam by asking users to prove that they are human
before they are allowed to:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 335

Sign up for an account.

Add a comment.
Create a page.
Edit a page.
Send a request to the Confluence
administrators.
Captcha is a test that can distinguish a human being from an automated agent such as a web spider or
robot. When Captcha is switched on, users will see a distorted picture of a word, and must enter it in a text
field before they can proceed.
Screenshot: Example of a Captcha test

By default, Captcha is disabled. When enabled, the default is that only anonymous users will have to
perform the Captcha test when creating comments or editing pages. You can also choose to enforce
Captcha for all users or members of particular groups.
You need System Administrator permissions to configure Captcha for spam prevention in Confluence.
To enable Captcha for spam prevention in Confluence:
1. Choose the cog icon

, then choose General Configuration

2. Choose Spam Prevention in the left-hand panel
3. Choose ON to turn on Captcha
4. If you want to disable Captcha for certain groups:
Select No one if you want everyone to see Captchas.
Select Signed in users if you want only anonymous users to see Captchas.
If you want everyone to see Captchas except members of specific groups, select Members of
the following groups and enter the group names in the text box.
You can click the magnifying-glass icon to search for groups. Search for all or part of a group
name and click the Select Groups button to add one or more groups to the list.
To remove a group from the list, delete the group name
5. Choose Save

Hiding External Links From Search Engines

Hiding external links from search engines helps to discourage spammers from posting links on your site. If you
turn this option on, any URLs inserted in pages and comments will be given the 'nofollow' attribute, which
prevents search engines from following them.
Shortcut links (e.g. CONF-2622@JIRA) and internal links to other pages within Confluence are not tagged.
To hide external links from search engines:
1. Choose the cog icon

, then choose General Configuration

2. Click 'Security Configuration' in the left panel.
3. This will display the 'Security Configuration' screen. Click 'Edit'.
4. Check the 'Hide External Links From Search Engines' checkbox.
5. Click the 'Save' button.

Background to the nofollow attribute

As part of the effort to combat the spamming of wikis and blogs (Confluence being both), Google came
up with some markup which instructs search engines not to follow links. By removing the main benefit of

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 336

wiki-spamming it's hoped that the practice will stop being cost-effective and eventually die out.

Configuring Captcha for Failed Logins

If you have confluence administrator permissions, On this page:
you can configure Confluence to impose a maximum Enabling, Disabling and
number of repeated login attempts. After a given Configuring Captcha for Failed
number of failed login attempts (the default is three) Logins
Confluence will display a Captcha form asking the Notes
user to enter a given word when attempting to log in
again. This will prevent brute force attacks on the
Confluence login screen.
Similarly, after three failed login attempts via the
XML-RPC or SOAP API, an error message will be
returned instructing the user to log in via the web
interface. Captcha will automatically be activated
when they attempt this login.
'Captcha' is a test that can distinguish a human being from an automated agent such as a web spider or
robot. When Captcha is activated, users will need to recognize a distorted picture of a word, and must type
the word into a text field. This is easy for humans to do, but very difficult for computers.
Screenshot: example of a Captcha test

Enabling, Disabling and Configuring Captcha for Failed Logins

By default, Captcha for failed logins is enabled and the number of failed login attempts is set to three.
To enable, disable and configure Captcha for failed logins:
1. Choose the cog icon

, then choose General Configuration

2. Choose 'Security Configuration' from the left menu.
3. Choose 'Edit'.
4. To enable Captcha:
Select the 'Enable' checkbox next to 'CAPTCHA on login'.
Set the maximum number of failed logins next to 'Maximum Authentication Attempts
Allowed'. You must enter a number greater than zero.
5. To disable Captcha, deselect the 'Enable' checkbox.
6. Choose 'Save'.
Screenshot: Configuring Captcha for failed logins

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 337

Notes

Disabling all password confirmation requests, including Captcha on login. Confluence

installations that use a custom authentication mechanism may run into problems with the Confluence
security measure that requires password confirmation. If necessary, you can set the password.conf
irmation.disabled system property to disable the password confirmation functionality on administ
rative actions, change of email address and Captcha for failed logins. See Recognized System
Properties.

Configuring XSRF Protection

Confluence requires an XSRF token to be present on comment creation, to prevent users being tricked into
unintentionally submitting malicious data. All the themes bundled with Confluence have been designed to use
this feature. However, if you are using a custom theme that does not support this security feature, you can
disable it.
Please carefully consider the security risks before you disable XSRF protection for comments in your
Confluence installation.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 338

Read more about XSRF (Cross Site Request Forgery) at cgisecurity.com.

To configure XSRF protection for comments:
1. Choose the cog icon

, then choose General Configuration

2. Choose Security Configuration in the left-hand panel.
3. Choose Edit.
4. Uncheck the Adding Comments checkbox in the XSRF Protection section, to disable XSRF protection.
5. Choose Save.
Related pages:
Configuring
Confluence Security
Confluence
Administrator's Guide
Developer
documentation on
XSRF protection in Co
nfluence

User Email Visibility

Confluence provides three options for email address privacy which can be configured by a Confluence
administrator from the Administration Console:
Public: email addresses are displayed publicly.
Masked: email addresses are still displayed publicly, but masked in such a way to make it harder for
spam-bots to harvest them.
Only visible to site administrators: only Confluence administrators can see the email addresses. Note
that, if you select this option, email addresses will not be available in the 'User Search' popup (e.g. when
setting Page Restrictions).

To configure user email visibility:

1. Choose the cog icon

, then choose General Configuration

2. Choose 'Security Configuration'.
3. Choose 'Edit'. The fields on the 'Security Configuration' screen will be editable.
4. Select one of the options from the 'User email visibility' dropdown: 'public', 'masked', or 'only visible to
site administrators'.
5. Choose 'Save'.
Screenshot: Email Visibility

Anonymous Access to Remote API

Administrators may wish to disable anonymous access to the Confluence remote API. to make it harder for
malicious users to write 'bots' that perform bulk changes to the site.
To disable anonymous access to the remote API:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 339

1. Choose the cog icon

, then choose General Configuration

2. Choose Security Configuration in the left-hand panel. The Security Configuration screen will appear.
3. Choose Edit.
4. Uncheck the Anonymous Access to API check box.
5. Choose Save.

Notes

This page is about access to the remote API. If you are looking for information about preventing anonymous
users from accessing Confluence, see Global Permissions Overview.
Configuring RSS Feeds
A Confluence System Administrator can configure On this page:
the following aspects of RSS feeds: Notes
The maximum number of items that Related pages:
Confluence returns to an RSS feed request.
The maximum time period that Confluence The RSS Feed Builder
allows to respond to an RSS feed request.
Both of these are set in the 'Edit Security
Configuration' screen.
To configure RSS feeds:
1. Choose the cog icon

, then choose General Configuration

2. Choose Security Configuration.
3. Choose Edit.
4. Enter a value for Maximum RSS Items. The
default value is 200.
5. Enter a value for RSS timeout.
6. Choose Save.
Screenshot: Configuring RSS feeds

Notes

When using the RSS Feed Builder, a user could potentially enter such a large value for the number of
feed items returned that Confluence would eventually run out of memory.
When using the Feed Builder, if a users a value greater than this setting (or less than 0) they will get a
validation error.
If any pre-existing feeds are set to request more than the configured maximum, they will be supplied
with only the configured maximum number of items. This is done silently - there is no logging and no
message is returned to the RSS reader.
If Confluence times out when responding to an RSS feed request, any items already rendered are
returned.

Preventing and Cleaning Up Spam

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 340

If your Confluence site is public-facing you may be affected by spammers.

Stopping Spammers

To prevent spammers:
1. Enable Captcha. See Configuring Captcha for Spam Prevention.
2. Run Confluence behind an Apache webserver and create rules to block the spammer's IP address.

Blocking Spam at Apache or System Level

If a spam bot is attacking your Confluence site, they are probably coming from one IP address or a small range
of IP addresses. To find the attacker's IP address, follow the Apache access logs in real time and filter for a
page that they are attacking.
For example, if the spammers are creating users, you can look for signup.action:

$ tail -f confluence.atlassian.com.log | grep signup.action

1.2.3.4 - - [13/Jan/2010:00:14:51 -0600] "GET /signup.action HTTP/1.1"
200 9956 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
37750

Compare the actual spam users being created with the log entries to make sure you do not block legitimate
users. By default, Apache logs the client's IP address in the first field of the log line.
Once you have the offender's IP address or IP range, you can add it to your firewall's blacklist. For example,
using the popular Shorewall firewall for Linux you can simply do this:

# echo "1.2.3.4" >> /etc/shorewall/blacklist

# /etc/init.d/shorewall reload

To block an IP address at the Apache level, add this line to your Apache vhost config:

Deny from 1.2.3.4

You can restart Apache with a "graceful" command which will apply the changes without dropping any current
sessions.
If this still does not stop the spam, then consider turning off public signup.

Deleting Spam

Profile Spam

By 'profile spam', we mean spammers who create accounts on Confluence and post links to their profile page.
If you have had many such spam profiles created, the easiest way to delete them is via SQL.
To delete a spam profile:
1. Shut down Confluence and back up your database.
Note: This step is essential before you run any SQL commands on your database.
2. Find the last real profile:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 341

SELECT bodycontentid,body FROM bodycontent WHERE contentid IN

(SELECT contentid FROM content WHERE contenttype='USERINFO')
ORDER BY bodycontentid DESC;

3. Look through the bodies of the profile pages until you find where the spammer starts. You may have to
identify an number of ranges.
4. Find the killset:

CREATE TEMP TABLE killset AS SELECT

bc.bodycontentid,c.contentid,c.username FROM
bodycontent bc JOIN content c ON bc.contentid=c.contentid WHERE
bodycontentid >= BOTTOM_OF_SPAM_RANGE AND bodycontentID <=
TOP_OF_SPAM_RANGE
AND c.contenttype='USERINFO';

DELETE FROM bodycontent WHERE bodycontentid IN (SELECT

bodycontentid FROM killset);

DELETE FROM links WHERE contentid IN (SELECT contentid FROM

killset);

DELETE FROM content WHERE prevver IN (SELECT contentid FROM

killset);

DELETE FROM content WHERE pageid IN (SELECT contentid FROM

killset);

DELETE FROM content WHERE contentid IN (SELECT contentid FROM

killset);

DELETE FROM os_user_group WHERE user_id IN (SELECT id FROM killset

k JOIN os_user o ON o.username=k.username);

DELETE FROM os_user WHERE username IN (SELECT username FROM

killset);

If you're using Confluence 5.6 or earlier use the SQL commands below:
For Confluence 5.6 and earlier...

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 342

CREATE TEMP TABLE killset AS SELECT

bc.bodycontentid,c.contentid,c.username FROM
bodycontent bc JOIN content c ON bc.contentid=c.contentid
WHERE
bodycontentid >= BOTTOM_OF_SPAM_RANGE AND bodycontentID <=
TOP_OF_SPAM_RANGE
AND c.contenttype='USERINFO';

DELETE FROM bodycontent WHERE bodycontentid IN (SELECT

bodycontentid FROM killset);

DELETE FROM links WHERE contentid IN (SELECT contentid FROM

killset);

DELETE FROM content WHERE prevver IN (SELECT contentid FROM

killset);

DELETE FROM attachments WHERE pageid IN (SELECT contentid FROM

killset);

DELETE FROM content WHERE contentid IN (SELECT contentid FROM

killset);

DELETE FROM os_user_group WHERE user_id IN (SELECT id FROM

killset k JOIN os_user o ON o.username=k.username);

DELETE FROM os_user WHERE username IN (SELECT username FROM

killset);

5. Once the spam has been deleted, restart Confluence and rebuild the index. This will remove any
references to the spam from the search index.

Configuring a Confluence Environment

This section describes the external setup of your Related pages:
Confluence installation. It includes information on
configuring the web server, application server, Getting Started as Confluence
directories and files – everything to do with the Administrator
environment that Confluence runs in. For guidelines Supported Platforms
on modifying settings inside the application, see Con
figuring Confluence instead.
Confluence is a J2EE web application. On the client
side, users access Confluence primarily via a web
browser.
This section contains the following guidelines:
Confluence Home and other important directories
Application Server Configuration
Starting Confluence Automatically on System Startup
Diagram: A Confluence installation

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 343

Confluence Home and other important directories

Confluence installation directory On this page:
Confluence installation directory
The 'Confluence Installation directory' is the directory Confluence home directory
where Confluence was installed. This directory is Changing the location of the home
also sometimes called the 'Confluence Install directory
directory'. Database
Important files in the installation directory: Temp directory (installation
directory)
bin/setenv.bat or bin/setenv.sh
This file is used to edit CATALINA_OPTS
memory and garbage collection settings and
define system properties.
confluence/WEB-INF/classes/conflu
ence-init.properties
This file contains the location of the
Confluence Home directory.

Confluence home directory

The Confluence Home directory is the folder where Confluence stores its configuration information, search
indexes and page attachments. Another term for 'Home directory' would be 'data directory'.

Finding the home directory

The location of the Confluence home directory is defined when you install Confluence. This location is stored
in the confluence-init.properties file, which is located in the confluence/WEB-INF/classes dire
ctory of your Confluence Installation directory.
When Confluence is running you can find the location of the home directory in

> General Configuration > System Information > Confluence Information - Confluence Home.

If you're using Confluence Data Center (a clustered instance), you will also have a shared home directory
which will contain some data (such as attachments and backups) that would otherwise reside in the home

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 344

directory. The location of your shared home directory can be found in your <local-home>/confluence.
cfg.xml file in the confluence.cluster.home property.

Contents of the home directory

The Confluence home directory contains some of the configuration data used by Confluence. This section
outlines the purpose of the files and directories in the Confluence home directory.

File or directory Purpose

confluence.cfg.xml This file contains all of the information necessary for Confluence to start up,
such as:
Product license
Context path
Database details, such as location and connection pool settings
Paths to important directories

attachments/ This directory contains every version of each attachment stored in

Confluence.
You can specify an alternative directory for attachment storage by setting the
attachments.dir property in confluence.cfg.xml.

In Data Center this directory is usually found in the Shared Home directory.

backups/ Confluence will place its daily backup archives in this directory, as well as any
manually generated backups. Backup files in this directory take the following
form daily-backup-YYYY_MM_DD.zip

You can specify an alternative directory for backups by setting the daily.ba
ckup.dir property in confluence.cfg.xml.

In Data Center this directory is usually found in the Shared Home directory.

bundled-plugins/ Confluence includes a set of bundled plugins. The bundled-plugins direct

ory is where Confluence will unpack its bundled plugins when it starts up.
This directory is refreshed on every restart, so removing a plugin from this
directory will not uninstall the plugin, as it will be replaced the next time
Confluence starts up.

database/ This is where Confluence stores its database when configured to run with the
Embedded H2 Database. In such cases this directory contains all Confluence
runtime data. Installations configured to run using an external database such
as MySQL will not use this directory.
The H2 database is provided for evaluating Confluence and is not supported
as a production database.

index/ The Confluence index is heavily used by the application for content searching
and recently updated lists and is critical for a running Confluence instance. If
data in this directory is lost or corrupted, it can be restored by running a full
reindex from within Confluence. This process can take a long time depending
on how much data is stored Confluence's database.
An alternative directory may be specified for the index by setting the lucene
.index.dir property in confluence.cfg.xml.

journal/ Entries are added to the journal when changes occur (such as a comment,
like, new page). Journal entries are then processed and the entries added to
the index (about every 5 seconds). In a cluster, the journal keeps the indexes
on each node in sync.

logs/ Confluence's application logs are stored in this directory.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 345

plugin-cache/ All Confluence plugins are stored in the database. To allow for quicker access
to classes contained within the plugin JARs, Confluence will cache these
plugins in the plugin-cache directory. This directory is updated as plugins
are installed and uninstalled from the system and is completely repopulated
from the database every time Confluence is restarted. Removing plugins from
this directory does not uninstall them.

temp/ The temp directory is used for runtime functions such as exporting, importing,
file upload and indexing. Files in this directory are temporary and can be
safely removed when Confluence is offline. A daily job within Confluence
deletes files that are no longer needed.
You can specify a different temp directory location, if necessary. Edit <confl
uence-home>/confluence.cfg.xml and set the new location in the web
work.multipart.saveDir property.

thumbnails/ Stores temporary files for image thumbnails. This directory is essentially a
thumbnail cache, and files deleted from this directory will be regenerated the
next time the image is accessed.
In Data Center this directory is usually found in the Shared Home directory.

Changing the location of the home directory

When Confluence first starts up, it reads the confluence-init.properties file to determine where to
look for the Home directory.
To change the location of the home directory edit the confluence.home property in the confluence-ini
t.properties file as follows:

Windows
In Windows, the path C:\confluence\data would be written as:
confluence.home=C:/confluence/data
Note that all backslashes (\) are written as forward slashes (/)
Linux / Solaris
On any Linux-based system, the property is defined using the normal directory syntax:
confluence.home=/var/confluence/

Symbolic links

There can be no symbolic links within the Confluence home directory. You must define an absolute path. If
disk space is an issue, place the entire confluence.home directory on a disk partition where there is
enough space. The absolute path of generated files (such as exports) is compared with the absolute path of
the confluence.home directory when constructing URLs. When a sub-directory has a different path, the
URL will be incorrect, and you may receive "Page not found" errors. These measures are in place to prevent
"directory traversal" attacks.

Fixing the Confluence Configuration

The Confluence configuration file: confluence-cfg.xml inside the home directory may contain references
to the original location of your Confluence home. You will need to edit this file to update these references to
also point to the new location. The two properties in this file that need to change are:
daily.backup.dir if you have not configured your backups to be placed elsewhere already
hibernate.connection.url if you are using the embedded HSQL database.

Database

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 346

All other data, including page content, is kept in the database. If you installed Confluence as a trial, or chose
to use the embedded HSQL database during setup, the database will store its files under database/ in
the Confluence Home Directory. Otherwise, the database management system you are connecting to is
responsible for where and how your remaining data is stored.

Temp directory (installation directory)

The temp directory is configured in the Java runtime and some Confluence components write temporary files
or lockfiles into this directory.
The temp directory is located in the installation directory as /temp.
To change the location of this directory, start the Java Virtual Machine in which confluence is running with the
argument:
-Djava.io.tmpdir=/path/to/your/own/temp/directory.

Note: this is not the same as the temp directory in Confluence Home where exports, for example, are
saved. See the table above to find out how to change the location of the <confluence-home>/temp direct
ory.

Application Server Configuration

The following pages contain information about configuring your application server for Confluence:
Managing Application Server Memory Settings
Managing Application Server Memory Settings

The minimum and maximum JVM heap space allocated to the application server affects performance.
Confluence administrators may wish to modify this value from the defaults depending on their server load. This
document only provides guidelines rather than rules, so administrators optimizing for performance should use
this document as a starting point only.

For a comprehensive overview of memory management, and memory tuning in Confluence under Sun
JRE, please read Garbage Collector Performance Issues

Testing For Optimum Memory Settings

In the general case, both Jira & Confluence users will benefit from setting the minimum and maximum values
identical. In larger installations, there is benefit to memory tuning, if there is a perceived performance issue. If
you are experiencing Out of Memory Heap errors, try increasing the -Xmx and -Xms values for your installation
to see if this resolves or helps resolve your issue. It's best to increase in small increments (eg 512mb at a time),
to avoid having too large a heap, which can cause different problems. If increasing the memory does not help,
please lodge a support ticket as there may be other factors contributing.
Memory usage is most likely to be maximized under peak load, and when creating a site XML backup. In many
cases, the backup can be the cause of the OOM, so increase -Xmx values and verify if a backup was occurring
at the time of OOM. A quick rule of thumb for gauging the success of a memory adjustment is using simple
anecdotal evidence from users. Is it snappier? The same? How does it handle while a backup is occurring?

Atlassian recommends in normal use, to disable the XML backup and use a Production Backup Strategy
.

If you normally perform manual XML site backups on your server, test your maximum memory
requirements by performing a site XML backup while the server is under maximum load
If you do not create manual XML site backups, simply monitor the server while under maximum load

Applying Memory Settings

See How to fix out of memory errors by increasing available memory.

Related Topics

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 347

Garbage Collector Performance Issues

How to fix out of memory errors by increasing available memory
Server Hardware Requirements Guide
Performance Tuning
Troubleshooting Slow Performance Using Page Request Profiling
Tomcat JVM options and Modify the Default JVM Settings
Starting Confluence Automatically on System Startup
You can configure Confluence to start automatically on system startup, allowing it to recover automatically after
a reboot.
Start Confluence Automatically on Linux
Start Confluence Automatically on Windows as a Service

Start Confluence Automatically on Linux

On Linux/Solaris, the best practice is to install, configure and run each service (including Confluence) as a
dedicated user with only the permissions they require.
To install, configure and run Confluence automatically on Linux/Solaris:
1. Create a confluence user for instance, using the following command:

sudo useradd --create-home -c "Confluence role account" confluence

2. Create a directory to install Confluence into. In this example we're using /usr/local/confluence.

sudo mkdir /usr/local/confluence

sudo chown confluence: /usr/local/confluence

3. Log in as the confluence user to install Confluence:

sudo su - confluence
cd /usr/local/confluence/
tar zxvf /tmp/confluence-5.6.4.tar.gz
ln -s confluence-5.6.4/ current

4. Edit
<<CONFLUENCE_INSTALL_DIRECTORY>>/confluence/WEB-INF/classes/confluence-init.properties file,
and set confluence.home=/usr/local/confluence/<Confluence_Data_Home> (ensure you have removed
the comment '#')
5. Then back as root, create the file /etc/init.d/confluence (code shown below), which will be
responsible for starting up Confluence after a reboot (or when manually invoked).
If you are running Ubuntu Jaunty (or later) do not perform this step. Please use the instructions further
down this page.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 348

#!/bin/sh -e
# Confluence startup script
#chkconfig: 2345 80 05
#description: Confluence

# Define some variables

# Name of app ( JIRA, Confluence, etc )
APP=confluence
# Name of the user to run as
USER=confluence
# Location of Confluence install directory
CATALINA_HOME=/usr/local/confluence/current
# Location of Java JDK
export JAVA_HOME=/usr/lib/jvm/java-7-oracle

case "$1" in
# Start command
start)
echo "Starting $APP"
/bin/su -m $USER -c "$CATALINA_HOME/bin/start-confluence.sh &>
/dev/null"
;;
# Stop command
stop)
echo "Stopping $APP"
/bin/su -m $USER -c "$CATALINA_HOME/bin/stop-confluence.sh &>
/dev/null"
echo "$APP stopped successfully"
;;
# Restart command
restart)
$0 stop
sleep 5
$0 start
;;
*)
echo "Usage: /etc/init.d/$APP {start|restart|stop}"
exit 1
;;
esac

exit 0

6. Make this file executable:

sudo chmod +x /etc/init.d/confluence

7. Set this file to run at the appropriate runlevel. For example, use sudo chkconfig --add confluence
on Redhat-based systems, sudo update-rc.d confluence defaults or rcconf on Debian-based
systems.
8. You should now be able to start Confluence with the init script. A successful startup output typically looks
like this:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 8.
Confluence 6.15 Documentation 349

$ sudo /etc/init.d/confluence start

Starting Confluence:
If you encounter issues starting up Confluence, please see the
Installation guide at
http://confluence.atlassian.com/display/DOC/Confluence+Installation
+Guide
Using CATALINA_BASE: /usr/local/confluence/current
Using CATALINA_HOME: /usr/local/confluence/current
Using CATALINA_TMPDIR: /usr/local/confluence/current/temp
Using JRE_HOME: /usr/lib/jvm/java-1.7.0-oracle
done.

You should then see this running at http://<server>:8090/

The port for this will be whatever is defined in your Confluence server.xml file.

Adding Confluence as a service for Ubuntu Jaunty (or later)

To continue configuring Confluence to start automatically as a service on Ubuntu Jaunty (or later):
1. After logging in as the confluence user to install Confluence, create start and stop scripts in /usr/l
ocal/confluence:

Example startscript:

#!/bin/bash
export JAVA_HOME=/usr/lib/jvm/java-7-oracle-1.7.0.71/
export JDK_HOME=/usr/lib/jvm/java-7-oracle-1.7.0.71/
cd /usr/local/confluence/current/bin
./startup.sh

Example stopscript:

#!/bin/bash
export JAVA_HOME=/usr/lib/jvm/java-7-oracle-1.7.0.71/
export JDK_HOME=/usr/lib/jvm/java-7-oracle-1.6.0.71/
cd /usr/local/confluence/current/bin
./shutdown.sh

2. Make both of these scripts executable. For example, by issuing the command: sudo chmod a+x
/usr/local/confluence/start /usr/local/confluence/stop.
3. Karmic and later: Create two text files in /etc/init/ called confluence-up.conf and confluence-
down.conf:

confluence-up:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 350

start on runlevel [2345]

script

date >> /tmp/confluence-startup.out

exec sudo -u confluence /usr/local/confluence/start >>
/tmp/confluence-startup.out 2>&1

end script

confluence-down:

start on runlevel [16]

expect fork
respawn

exec sudo -u confluence /usr/local/confluence/stop >>

/tmp/confluence-shutdown.out 2>&1

... and make them readable to all users:

sudo chmod a+r /etc/init/confluence-up.conf /etc/init/confluence-down.conf

1. Jaunty, Intrepid: Create two text files in /etc/event.d/ called confluence-up and confluence-do
wn:

confluence-up:

start on runlevel 2
start on runlevel 3
start on runlevel 4
start on runlevel 5

exec sudo -u confluence /usr/local/confluence/start >>

/tmp/confluence-startup.out 2>&1

confluence-down:

start on runlevel 1
start on runlevel 6

exec sudo -u confluence /usr/local/confluence/stop >>

/tmp/confluence-shutdown.out 2>&1

... and make them readable to all users:

sudo chmod a+r /etc/event.d/confluence-up /etc/event.d/confluence-down

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 351
RELATED TOPICS

Starting Confluence Automatically on System Startup

Start Confluence Automatically on Windows as a Service

For long-term use, we recommend that you configure Confluence to start automatically when the operating
system restarts. For Windows servers, this means configuring Confluence to run as a Windows service.
There are two ways to install the Confluence distribution as a service: using the Confluence installer or manually
as described below.
On this page:
Reasons for Starting Confluence as a Service
Changing the User Running the Service
Manually Installing the Confluence Distribution as a Service
Managing Confluence as a Service
Upgrading Confluence
Troubleshooting Confluence while Running as a Windows Service
Requesting Support

Problem with 64-bit Windows

If you are running 64-bit Windows, please note that you may encounter problems with Apache Tomcat
running as a Windows service if you are using a 64-bit JDK. Refer to our knowledge base article for
more information.

Reasons for Starting Confluence as a Service

Installation as a Windows service offers these advantages:

Reduced risk of shutting down Confluence by accident (If you start Confluence manually, a console
window opens and there is a risk of someone accidentally shutting down Confluence by closing the
window).
Automated Confluence recovery after server restart.
Improved troubleshooting through logging server output to file.
You can read more about Windows services in the Microsoft Developer Network.

Changing the User Running the Service

If you wish to run the service as a non-administrator user for security, or if you are using network drives for
backups, attachments or indexes, you can run the service as another user. To change users, open the Apache
Tomcat Confluence properties, go to the 'Log On' tab and enter the required username and password. Go to
your Windows Control Panel -> User Accounts and confirm that the user has write permissions for the <CONFLU
ENCE-INSTALL> and <CONFLUENCE-HOME> directories, and all subfolders. Note that any network drives must
be specified by UNC and not letter mappings (eg. \\backupserver\confluence not z:\confluence).

For more detail, see Creating a Dedicated User Account on the Operating System to Run Confluence.

Manually Installing the Confluence Distribution as a Service

In Windows:
1. Open a command prompt and change directory to the <CONFLUENCE-INSTALL>/bin directory.
You'll need to run the command prompt using 'Run as administrator' so that you can complete some of
these steps.
2. Confirm that the JAVA_HOME variable is set to the JDK base directory with the command:

echo %JAVA_HOME%

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 352

If you installed the Java Runtime Environment (JRE) or used the Confluence installer, replace JAVA_HOM
E with JRE_HOME. See Setting the JAVA_HOME Variable in Windows for more info.

Note that any directory in the path with spaces (eg. C:\Program Files must be converted to its
eight-character equivalent (e.g. C:\Progra~1).
3. Use the following command to install the service with default settings:

service.bat install Confluence

The service will be called Atlassian Confluence and will be configured to start automatically by default,
but will not automatically start up until the next server reboot.
4. If you have a large Confluence installation, you can increase the maximum memory Confluence can use
(the default is 1024MB). For example, you can set the maximum memory to 2048MB using:

tomcat9w //US//Confluence --JvmMx 2048

5. If you don't have any JVM parameters that you pass to your distribution of Confluence, you can skip this
step. If you do, add them to the service using:

tomcat9w //US//Confluence ++JvmOptions="-Djust.an.example=True"

Alternatively you can use the following command to launch the service properties dialog then navigate to
the Java tab to add more JVM parameters.

tomcat9w //ES//Confluence

For further configuration options, please refer to the Tomcat Windows Service How-To guide.
6. Go to Control Panel > Administrative Tools > Services > Atlassian Confluence and right-click Proper
ties to verify the settings are correct. Start the Confluence service with the command:
7. Finally, start the Confluence service. From now on this will happen automatically after the a server
reboot.

net start Confluence

Managing Confluence as a Service

You can manage the Confluence service from the command prompt.
Stop Confluence with:

net stop Confluence

Uninstall the Confluence service with:

service.bat remove Confluence

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 353

Upgrading Confluence

After upgrading Confluence, you can either uninstall and reinstall the Windows service or change the StartPath
parameter to your new folder. Refer to the Tomcat documentation for help.

Troubleshooting Confluence while Running as a Windows Service

Check the Knowledge Base articles:

Getting 'The image file tomcat6.exe is valid, but is for a machine type other than the current machine'
Confluence Does Not Start Due to Windows Firewall
Unable to start Confluence Windows service after allocating JVM memory
Unable to Configure Confluence to Run as a Service on Tomcat 5
Unable to Install Service on Windows Vista
If none of the above solves your problem, please refer to the complete list of known issues in our
Knowledge Base.
When investigating memory issues or bugs, it may be useful to view information from Confluence's
garbage collection. To turn on the verbose garbage collection see How to Enable Garbage Collection
(GC) Logging.
You can use a Sysinternals tool called Procmon.exe from the The Microsoft Windows Sysinternals
Team, to check that the error occurred at the specific time when the Confluence service started. You
need to match the time when Tomcat failed, as captured by this tool, against the time in the Windows
Event Viewer.

Note
We do not recommend that you run this tool for too long as it may disrupt other Atlassian
applications. Once you have captured the required information you will need to press Ctrl + E t
o stop capturing.

Requesting Support

If, after following the troubleshooting guide above, you still cannot make Confluence run as a Windows Service
or if there is an error when setting the JVM configuration for the service, you can create a support request.
Please provide the following information when creating your support request, because we will need it to assist
you:
Give us the result of running java -version from Windows command line console.
A screen shot of your Windows Registry setting for Tomcat.
If you have modified service.bat, please give us a copy of this file for review.
Your atlassian-confluence.log file.

Performance Tuning
This document describes tuning your application for
improved performance. It is not a guide to
troubleshooting Confluence outages. Check Trouble
shooting Confluence hanging or crashing for help if
Confluence is crashing.
Like any server application, Confluence may require
some tuning as it is put under heavier use. We do
our best to make sure Confluence performs well
under a wide variety of circumstances, but there's no
single configuration that is best for everyone's
environment and usage patterns.
If you are having problems with the performance of
Confluence and need our help resolving them, you

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 354

should read Requesting Performance Support. On this page:

Performance Data Collector
Performance Data Collector Use the latest version of your tools
Avoid swapping due to not enough
The Performance Data Collector is a server-side, RAM
standalone application that exposes a number of Being aware of other systems
REST APIs for collecting performance data. It can using the same infrastructure
be used to collect data, such as thread dumps, disk Choice of database
speed and CPU usage information, to troubleshoot Database connection pool
performance problems. Database in general
See How to use the Performance Data Collector for Database statistics and query
more information. analyzers
Cache tuning in Confluence and
Apache
Antivirus software
Enabling HTTP compression
Performance testing
Access logs
Built-in profiler
Application server memory
settings
Web server configuration
Troubleshooting possible memory
leaks

Use the latest version of your tools

Use the latest versions of your application servers and Java runtime environments. Newer versions are
usually better optimized for performance.

Avoid swapping due to not enough RAM

Always watch the swapping activity of your server. If there is not enough RAM available, your server may
start swapping out some of Confluence's heap data to your hard disk. This will slow down the JVM's garbage
collection considerably and affect Confluence's performance. In clustered installations, swapping can lead to
a Cluster Panic due to Performance Problems. This is because swapping causes the JVM to pause during G
arbage Collection, which in turn can break the inter-node communication required to keep the clustered
nodes in sync.

Being aware of other systems using the same infrastructure

It may sound tempting: Just have one powerful server hosting your database and/or application server, and
run all your crucial programs on that server. If the system is set up perfectly, then you might be fine.
Chances are however that you are missing something, and then one application's bug might start affecting
other applications. So if Confluence is slow every day around noon, then maybe this is because another
application is using the shared database to generate complicated reports at that time? Either make sure
applications can't harm each other despite sharing the same infrastructure, or get these systems untangled,
for example by moving them to separate instances that can be controlled better.

Choice of database

The embedded H2 database is provided for evaluating Confluence, not for production Confluence sites.
After the evaluation finishes, you must switch to a supported external database. We recommend using what
you are familiar with, because your ability to maintain the database will probably make far more difference to
what you get out of it than the choice of database itself.

Database connection pool

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 355

If load on Confluence is high, you may need more simultaneous connections to the database.
If you are using JNDI data-sources, you will do this in your application server's configuration files.
If you have configured Confluence to access the database directly, you will need to manually edit the
hibernate.c3p0.max_size property in the confluence.cfg.xml file in your confluence.home directory.
After you have changed the URL in this file, restart Confluence.
To assess whether you need to tune your database connection pool, take thread dumps during different
times (including peak usage). Inspect how many threads have concurrent database connections.

Database in general

If Confluence is running slowly, one of the most likely cause is that there is some kind of bottleneck in (or
around) the database.
The first item you should check is the "Database Latency" field in the System Information tab in the admin
console.

The latency is calculated by sending a trivial request to the database, querying a table which is known to
have only one column and one row. ("select * from CLUSTERSAFETY"). Obviously this query should be
blazing fast, and return within 1 or 2 milliseconds. If the value displayed is between 3 and 5 milliseconds, you
might already have an issue. If the value is above 10ms, then you definitely need to investigate and improve
something! A few milliseconds may not sound so bad, but consider that Confluence sends quite a few
database queries per page request, and those queries are a lot more complex too! High latency might stem
from all sorts of problems (slow network, slow database, connection-pool contention, etc), so it's up to you to
investigate. Don't stop improving until latency is below 2ms on average.
Obviously, latency is just the very first thing to look at. You may get zero latency and still have massive
database problems, e.g. if your tables are poorly indexed. So don't let a low latency fool you either.

Database statistics and query analyzers

Modern databases have query optimizers based on collecting statistics on the current data. Using the SQL
EXPLAIN statement will provide you information on how well the query optimizer is performing. If the cost
estimate is wildly inaccurate then you will need to run statistics collection on the database. The exact
command will depend on your database and version. In most cases you can run statistics collection while
Confluence is running, but due to the increased load on the database it's best to do this after normal hours or
on a week-end.

Cache tuning in Confluence and Apache

To reduce the load on the database, and speed up many operations, Confluence keeps its own cache of
data. Tuning the size of this cache may speed up Confluence (if the caches are too small), or reduce memory
(if the caches are too big).
Please have a look at our documentation on Cache Performance Tuning for information on how to tune
Confluence caches.

Antivirus software

Antivirus software greatly decreases the performance of Confluence. Antivirus software that intercepts
access to the hard disk is particularly detrimental, and may even cause errors with Confluence. You should
configure your antivirus software to ignore the Confluence home directory, its index directory and any
database-related directories.

Enabling HTTP compression

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 356

If bandwidth is responsible for bottlenecking in your Confluence installation, you should consider enabling
HTTP compression. This may also be useful when running an external facing instance to reduce your
bandwidth costs.
Take note of the known issues with HTTP compression in versions of Confluence prior to 2.8, which may
result in high memory consumption.

Performance testing

You should try out all configuration changes on a demo system. Ideally, you should run and customize
loadtests that simulate user behavior.

Access logs

You can find out which pages are slow and which users are accessing them by enabling Confluence's built-in
access logging.

Built-in profiler

You can identify the cause of page delays using Confluence's built-in profiler according to Troubleshooting
Slow Performance Using Page Request Profiling.

Application server memory settings

See How to fix out of memory errors by increasing available memory.

Web server configuration

For high-load environments, performance can be improved by using a web server such as Apache in front of
the application server. There is a configuration guide to Running Confluence behind Apache.
When configuring your new web server, make sure you configure sufficient threads/processes to handle the
load. This applies to both the web server and the application server connector, which are typically configured
separately. If possible, you should enable connection pooling in your web server connections to the
application server.

Troubleshooting possible memory leaks

Some external plugins, usually ones that have been written a long time ago and that are not actively
maintained anymore, have been reported to consume memory and never return it. Ultimately this can lead to
a crash, but first this manifests as reduced performance. The Troubleshooting Confluence hanging or
crashing guide is a good place to start. Some of the known causes listed there could result in performance
issues short of a crash or hang.

Cache Performance Tuning

Confluence performance can be significantly On this page:
affected by the performance of its caches. It is
essential for the administrator of a large production Cache tuning example
installation of Confluence to size the caches to suit Finding the configuration file
its environment. Cache key mappings
Caching in Confluence Data
To change the size of a cache: Center
Important caches
1. Go to

> General Configuration > Cache

Management.
2. Choose Show Advanced View.
3. Choose Adjust Size next to the cache you
want to change.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 357

Cache tuning example

As an example of how to tune Confluence's caches, let's have a look at the following table:

Caches % Used % Effectiveness Objects/Size Hit/Miss/Expiry

Attachments 87% 29% 874/1000 78226/189715/187530

Content Attachments 29% 9% 292/1000 4289/41012/20569

Content Bodies 98% 81% 987/1000 28717/6671/5522

Content Label Mappings 29% 20% 294/1000 4693/18185/9150

Database Queries 96% 54% 968/1000 105949/86889/83334

Object Properties 27% 18% 279/1000 5746/25386/8102

Page Comments 26% 11% 261/1000 2304/17178/8606

Users 98% 5% 982/1000 6561/115330/114279

The maximum size of the caches above is 1000 (meaning that it can contain up to 1000 objects). You can tell
when a cache size needs to be increased because the cache has both:
a high usage percentage (above 75%)
a low effectiveness percentage.
Check the 'effectiveness' versus the 'percent used'. A cache with a low percent used need not have its size
lowered; it does not use more memory until the cache is filled.
Based on this, the sizes of the "Attachments", "Database Queries", and "Users" caches should be increased
to improve their effectiveness.
As the stored information gets older or unused it will expire and be eliminated from the cache. Cache expiry
may be based on time or on frequency of use.
There is not much that you can do with a cache that has both a low percentage of usage and
effectiveness. Over time, as the cache is populated with more objects and repeat requests for them are
made, the cache's effectiveness will increase.

Finding the configuration file

Cache configurations are stored in <confluence-home>/shared-home/config/cache-settings-ov

errides.properties

For Confluence Data Center (clustered) it can be found in <confluence-shared-home>/config/cache

-settings-overrides.properties (in the shared home directory for the cluster).

Cache key mappings

The cache configuration file configures caches by their keys. To find out a cache key hover your mouse over
the cache name in the Cache Management screen.

Caching in Confluence Data Center

In Confluence Data Center (clustered) you have a distributed cache and a cluster node-local cache. The

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 358

Cluster Management page will indicate cluster distributed cache and cluster node-local cache.
The cache configuration file is stored in the shared home directory for the cluster.

Important caches

The following suggestions are general guidelines. In cases of large databases, 20-30% of the size of
the table may be unnecessarily large. Check the effectiveness and percent used categories in the
cache for more specific assessments.

Content Objects cache (com.atlassian.confluence.core.ContentEntityObject)

should be set to at least 20-30% of the number of content entity objects (pages, comments, emails,
news items) in your system. To find the number of content entity objects, use the query select
count(*) from CONTENT where prevver is null.
Content Body Mappings cache (com.atlassian.confluence.core.ContentEntityObject
.bodyContents)
should be set to at least 20% of the number of content entity objects (pages, comments, emails, news
items) in your system. To find the number of content entity objects, use the query select count(*)
from CONTENT where prevver is null.
Embedded Crowd Internal User cache (com.atlassian.crowd.model.user.InternalUser)
should be set to the number of users you have in the internal directory. You can discover this number
by using the following SQL:

SELECT
COUNT(*)
FROM
cwd_user u
JOIN
cwd_directory d
ON
u.directory_id = d.id
AND d.directory_name = 'Confluence Internal Directory';

Embedded Crowd Users cachecom.atlassian.confluence.user.crowd.CachedCrowdUse

rDao.USER_CACHE
should be set to the number of rows in the cwd_user table.

SELECT
COUNT(*)
FROM
cwd_user u;

Space permissions by ID cache (com.atlassian.confluence.security.SpacePermission

)
should be set to the number of space permissions in your deployment (a good rule of thumb is 20
times the number of spaces). You can find the number of space permissions using the query select
count(*) from SPACEPERMISSIONS.

Cache Statistics

Confluence provides statistics about its internal caches that allow you to track the size and hit ratio of each
cache and tune it for better performance (if necessary). See Performance Tuning for more information.

Configurable Caches

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 359

System administrators can change the sizes of Confluence's internal caches through the Administration Console
and these changes will take effect without the need to first shut down and then restart Confluence. The
maximum number of units for any of the defined cache regions can be adjusted individually.
Note that larger cache sizes will require more memory at runtime, so you should review the memory allocation of
the Confluence Java process and the physical memory available on your server.

Viewing Cache Statistics and Modifying Cache Sizes

To view the cache statistics:

1. Go to

> General Configuration > Cache Management.

2. Choose Show Advanced View.
Here is an example for one of the most frequently used caches, the 'Content Object' cache.

About the generated numbers:

Capacity Utilization =(Objects)/(Size)

For example Percent Used = 4023 / 5000 = 80%

Effectiveness: =(Hits)/(Hits + Misses)

For example Effectiveness = 374550 / (374550 +
140460) = 73%

Current / Max Entries The number of entries in the cache / the number of
total possible entries allowed (this is the size of the
cache).

Current Heap Size Heap memory (in MB) allocated to this cache (if
applicable)

Hit / Miss / Evicted The number of reads accessing cache where

required content was found / the number of reads
accessing cache where required content was not
found / the number of objects evicted from the
cache.

Adjust Size Use this option to specify a different maximum

cache size.

Flush Flushes the cache.

Changes to cache size configurations are saved in the shared-home/config/cache-settings-override

s.properties file in your home directory (in a Confluence Data Center cluster this is in the shared home
directory, not local home).
If you need to reset all the values back to the default, you can simply delete the file and restart Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 360

Memory Usage and Requirements

Managing Confluence's performance and memory On this page:
usage really depends on what resources are
available. Confluence will run faster if you give it lots Increasing the amount of memory
of memory for its caches, but it should still be able to available to Confluence
run quite well in low-memory environments, with the Embedded database
right tuning. Below are some tips on getting the most Caching
out of your Confluence site. Mail error queue
Attachments
System backup and restore
Increasing the amount of memory available to Known issues that we do not have
Confluence control over
Confluence is taking long periods
See Increasing JIRA Memory for details on how to of time to respond to some actions
increase the memory available to web application Related pages:
servers typically used to run Confluence.
Performance Tuning
Requesting Performance Support
Embedded database

The embedded HSQL database that comes with

Confluence essentially holds all your data in memory
while the Confluence server is running. If you are
running out of memory, you should consider migratin
g Confluence to an external database.

Caching

By default, Confluence keeps large in-memory caches of data to improve its responsiveness and the user
experience. The trade off is an increase in memory requirements to support the cache. Administrators of
larger Confluence sites may need to configure the size of their caches to improve performance.
To customize Confluence's cache to meet your needs, see cache tuning.
To increase the amount of memory available to Confluence, see How to fix out of memory errors by
increasing available memory.

Mail error queue

Confluence keeps a copy of all emails that it failed to send within an internal error queue. In the event of
intermittent failures such as network connectivity issues, the emails in this queue can be manually resent
when the problem is fixed. Under certain circumstances, the mail queue can fill up with large objects. The
queue is regularly flushed, but if you get a lot of mail errors, you might get a spike in memory usage.

Attachments

The indexing of large attachments requires that the attachment be loaded into memory. In the case of large
attachments, this can cause a temporary strain on the systems resources, and may result in indexing failing
because the attachment could not be fully loaded into memory.

System backup and restore

The Confluence backup and restore process scales linearly with the size of data. This can have a significant
impact on large Confluence instances where the amount of data exceeds the amount of available memory. If
you are experiencing an OutOfMemoryError during either a backup or restore processes, then we strongly
recommend that you choose and Production Backup Strategy.
If you encounter an OutOfMemoryError while restoring a backup and wish to overcome this issue by
increasing memory, how much more will you need to make this process work? A good rule of thumb is to
have a look at the size of the entities.xml file in your backup. This file contains all of the data Confluence
will be loading, so at least that much is required. Add another 64-128Mb to ensure that Confluence has

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 361

enough memory to load and function and that should be enough. To increase the amount of memory
available to Confluence, see How to fix out of memory errors by increasing available memory.

Known issues that we do not have control over

There are also some memory issues we don't have any control over. For example,
There's a memory leak in the Oracle 10g JDBC drivers. Not much we can do about that.
One customer found a rather nasty memory leak that appeared to originate inside Tomcat 5, but only
using the IBM JDK on PowerPC.
If you are having problems that appear to result from a memory leak, log an issue on http://support.atlassian.
com. Our memory profiler of choice is YourKit. It would be helpful to us if you can provide us with a memory
dump from that tool showing the leak.

Confluence is taking long periods of time to respond to some actions

A common cause of random pauses in Confluence is the JVM running garbage collection. To determine if
this is what is happening, enable verbose garbage collection and look at how long Java is taking to free up
memory. If the random pauses match when Java is running its garbage collection, garbage collection is the
cause of the pause.
Verbose garbage collection will generate log statements that indicate when Java is collecting garbage, how
long it takes, and how much memory has been freed.
To enable gc (garbage collection) logging, start Confluence with the option -XX:+PrintGCDetails
-XX:+PrintGCTimeStamps -verbose:gc -Xloggc:gc.log. Replace gc.log with an absolute path to
a gc.log file.

For example, with a Windows service, run:

tomcat5 //US//Confluence ++JvmOptions="-XX:+PrintGCDetails

-XX:+PrintGCTimeStamps -verbose:gc -Xloggc:c:\confluence\logs\gc.log"

or in bin/setenv.sh, set:

export CATALINA_OPTS="$CATALINA_OPTS -XX:+PrintGCDetails

-XX:+PrintGCTimeStamps -verbose:gc
-Xloggc:${CATALINA_BASE}/logs/gc.log"

If you modify bin/setenv.sh, you will need to restart Confluence for the changes to take effect.

What can you do to minimize the time taken to handle the garbage collection? See http://java.sun.com/docs/
hotspot/gc1.4.2/ for details on tuning the JVM to minimize the impact that garbage collection has on the
running application.

Requesting Performance Support

Basic performance troubleshooting steps On this page:
Basic performance troubleshooting
Begin with the following procedures: steps
1. Go through the Troubleshooting Confluence Requesting basic performance
hanging or crashing page to identify the major support
known performance problems. Advanced performance
2. Proceed with the Performance Tuning tips to troubleshooting
help optimize performance. Related pages:
Memory Usage and Requirements
Requesting basic performance support Confluence for Enterprise

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 362

If the above tips don't help or you're not sure where

to start, open a support ticket starting with at least
the basic information:
1. The atlassian-confluence.log
2. The catalina.out log (or your application server log), with a series of three thread dumps separate
d by 10 seconds
3. A description with as much detail as possible regarding:
a. What changes have been made to the system?
b. When did performance problems begin?
c. When in the day do performance issues occur?
d. What pages or operations experience performance issues?
e. Is there a pattern?
Continue with as much of the advanced performance troubleshooting information as you can.

Advanced performance troubleshooting

Please gather all of the information listed below and include it in your support request, even if you think you
have a good idea what's causing the problem. That way we don't have to ask for it later.

System information

Confluence server

Take a screenshot of Confluence's Administration System Information (or save the page
as HTML)
Take a screenshot of Confluence's Administration Cache Statistics (or save the page as
HTML)
Find out the exact hardware Confluence is running on
How many CPUs? What make and model? What MHz?
How much memory is installed on the machine?
How much memory is assigned to Confluence's JVM? (i.e. what are the -Xmx and -Xms
settings for the JVM?)
What other applications are being hosted on the same box?

Confluence content

How many users are registered in Confluence?

On average, to how many groups does each user belong?
How many spaces (global and personal) are there in your Confluence server?
How many of those spaces would be viewable by the average user?
Approximately how many pages? (Connect to your database and perform 'select count(*) from
content where prevver is null and contenttype = 'PAGE'')
How much data is being stored in Bandana (where plugins usually store data)? (Connect to your
database and perform 'select count(*), sum(length(bandanavalue)) from bandana')

The database

What is the exact version number of Confluence's database server?

What is the exact version number of the JDBC drivers being used to access it? (For some databases,
the full filename of the driver JAR file will suffice)
Is the database being hosted on the same server as Confluence?
If it is on a different server, what is the network latency between Confluence and the database?
What are the database connection details? How big is the connection pool? If you are using the
standard configuration this information will be in your confluence_cfg.xml file. Collect this file. If you
are using a Data source this information will be stored in your application server's configuration file,
collect this data.

User management

Are you using external user management or authentication? (i.e. Jira or LDAP user delegation, or

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 363

single sign-on)
If you are using external Jira user management, what is the latency between Confluence and Jira's
database server?
If you are using LDAP user management:
What version of which LDAP server are you using?
What is the latency between Confluence and the LDAP server?

Diagnostics

Observed problems

Which pages are slow to load?

If it is a specific wiki page, attach the wiki source-code for that page
Are they always slow to load, or is the slowness intermittent?

Monitoring data

Before drilling down into individual problems, helps a lot to understand the nature of the performance
problem. Do we deal with sudden spikes of load, or is it a slowly growing load, or maybe a load that follows a
certain pattern (daily, weekly, maybe even monthly) that only on certain occasions exceeds critical
thresholds? It helps a lot to have access to continuous monitoring data available to get a rough overview.
Here are sample graphs from the confluence.atlassian.com system, showing
Load
This graph shows the load for two consecutive days. The obvious pattern is that the machine is under decent
load, which corresponds to the user activity, and there is no major problem.

Resin threads and database connections

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 364

Active number of Java Threads

These two charts show the active threads in the application server (first chart) and the size database
connection pool (second chart). As you can see, there was a sudden spike of server threads and a
corresponding spike of db-connections.

The database connection pool size

The database connection pool size peaked over 112, which happened to be more than the maximum number
of connections the database was configured for (100). So it was no surprise that some requests to
Confluence failed and many users thought it had crashed, since many requests could not obtain the crucial
database connections.
We were able to identify this configuration problem quite easily just by looking at those charts. The next
spikes were uncritical because more database connections were enabled.
The bottom line being: it helps a lot to monitor your Confluence systems continuously (we use Hyperic, for
example), and it helps even more if you are able to send us graphs when you encounter problems.

Access logs

How to Enable User Access Logging, including redirecting the logs to a separate file
You can run this file through a log file analyzer such as AWStats, or manually look through for
pages which are slow to load.

Profiling and logs

Enable Confluence's built-in profiling for long enough to demonstrate the performance problem using T

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 365

roubleshooting Slow Performance Using Page Request Profiling.

If a single page is reliably slow, you should make several requests to that page
If the performance problem is intermittent, or is just a general slowness, leave profiling enabled
for thirty minutes to an hour to get a good sample of profiling times
Find Confluence's standard output logs (which will include the profiling data above). Take a zip of the
entire logs directory.
Take a thread dump during times of poor performance

CPU load

If you are experiencing high CPU load, please install the YourKit profile and attach two profiler dumps
taken during a CPU spike. If the CPU spikes are long enough, please take the profiles 30-60 seconds
apart. The most common cause for CPU spikes is a virtual machine operating system.
If the CPU is spiking to 100%, try Live Monitoring Using the JMX Interface, in particular with the Top
threads plugin.

Site metrics and scripts

It is essential to understand the user access and usage of your instance. Please use the access log
scripts and sql scripts to generate Usage statistics for your instance.

Next step

Open a ticket on https://support.atlassian.com and attach all the data you have collected. This should give us
the information we need to track down the source of your performance problems and suggest a solution.
Please follow the progress of your enquiry on the support ticket you have created.

Access Log Scripts

The access log scripts are attached to this page. To use the scripts:
1. Unzip the 7z file.
2. Copy all the daily access logs to a folder called logs.
3. Run Atlassian-processDailyLog.rb. This will generate a csv file called summary.csv and
several directories which contain the access logs of each defined user action.
4. Run the appropriate script Atlassian-processDailyLog-hourly.rb
<admin/comment/create/edit/search/rss>. Each script will generate a different csv file. For
example, Atlassian-processDailyLog-hourly.rb admin will process the admin logs extracted in
step 3.
5. Import the csv files to www-log-Analysis.xls (summary.csv to 'raw stats - daily' sheet and admin.
csv to 'admin -hours' sheet, etc) to generate the load profiles and graphs. You may need to modify the
number of rows in each sheet depending on the number of logs.

Note
All scripts are written in Ruby and assume the log file name contains the string
'confluence.atlassian.com-access.log'. Scripts need to be changed if another name is used. Modify the
line: filenameRegexp = Regexp.new('confluence.atlassian.com-access.log')

Compressing an HTTP Response within Confluence

Confluence supports HTTP GZip transfer encoding. This means that Confluence will compress the data it sends
to the user, which can speed up Confluence over slow or congested Internet links, and reduce the amount of
bandwidth consumed by a Confluence server.
Turn on Confluence's GZip encoding if:
Users are accessing Confluence over the Internet, or a WAN connection with limited bandwidth.
You wish to reduce the amount of data transfer between the Confluence server and client.
If you are accessing Confluence over a Local Area Network or over a particularly fast WAN, you may wish to
leave GZip encoding disabled. If the network is fast enough that transferring data from Confluence to the user
isn't a limiting factor, the additional CPU load caused by compressing each HTTP response may slow

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 366

Confluence down.

Enabling HTTP Compression

1. Choose the cog icon

, then choose General Configuration

2. Select 'General Configuration' in the left-hand panel.
3. Enable 'Compress HTTP Responses'.
It is possible to configure which types of content are compressed within Confluence. By default, the following
mime types will be compressed:
text/htmltext
javascript
text/css
text/plain
application/x-javascript
application/javascript
If you wish to change the types of content to be compressed, add a replacement urlrewrite-gzip-default
.xml file within the WEB-INF/classes/com/atlassian/gzipfilter/ directory in your Confluence
Installation Directory. A sample file is provided as an attachment. It is unlikely that you will need to alter this file.
Garbage Collector Performance Issues
This document relates broadly to memory management with Oracle's Hotspot JVM. These
recommendations are based on Support's successful experiences with customers with large Confluence
instances.

Please do not use the Concurrent Mark Sweep (CMS) Collector with Confluence, unless otherwise
advised by Atlassian Support. It requires extensive manual tuning and testing, and is likely to result in
degraded performance.

Use a small heap

Keep your heap as small as possible, without the instance experiencing OutOfMemory errors. If you experience
OutOfMemory errors and need to increase this, we recommend you do it in 512mb or 1gb allotments, and
monitor the instance. If you continue to receive OutOfMemory errors, increase the heap by another 512mb or
1gb, and continue this process until you are operating stably with no OutOfMemory errors. Do not increase the
heap further than required, as this will result in longer garbage collections.

Remove any old tuning parameters

On every full GC, the JVM will resize the allocations of Eden, Survivor etc based on the throughput it is actually
seeing. It will tune itself based on the real world data of the objects that are being created and collected. Most of
the time simply allowing JVM to tune itself will give you better performance.
If you have added JVM parameters in the past and are experiencing difficulties with GC now, we'd recommend
you remove all GC related parameters, unless you added them to solve a specific problem, and they did in fact
solve that problem. You should also consider re-benchmarking now to ensure that they are still solving that
problem, and are not causing you any other issues.

Check your VM resources

If you run Confluence on a VM, check that is it not using the swap file. If it does, when the JVM garbage collects
it has to load the objects from the swap file into memory to clean them, and this can cause significantly longer
GC pauses. Instead of using swapping, ballooning and bursting, allocate adequate memory to the VM.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 367

Manual Tuning

If you find you are still experiencing difficulties with GC after following these recommendations and you would
like to see if you can tune the JVM better to improve performance, we recommend following the instructions in
our Garbage Collection (GC) Tuning Guide. This document will take you through the process of choosing
performance goals (throughput/footprint/latency), and how to tune for those goals.

Viewing your GC logs

How to Enable Garbage Collection (GC) Logging, and use a tool like Chewiebug's GCViewer to view the
resulting logs.
Troubleshooting Slow Performance Using Page Request Profiling
This page tells you how to enable page-request On this page:
profiling. With profiling turned on, you will see a
record of the time it takes (in milliseconds) to Enabling Page-Request Profiling
complete each action made on any Confluence Profiling an Activity
page. If Confluence is responding slowly, an internal Example of a Profile
timing trace of the slow page request can help to Start Confluence with Profiling
identify the cause of the delay. Enabled

You will need access to the Confluence server to Related pages:

view a profile. Requesting Performance Support
Working with Confluence Logs
Enabling Page-Request Profiling

To see just the slow performing macros, see

Identifying Slow Performing Macros.

You need to have System Administrator permissions in order to enable or disable profiling.
To enable page profiling:
1. Choose the cog icon

, then choose General Configuration

2. Choose 'Logging and Profiling' in the left-hand panel.
3. The 'Logging and Profiling' screen appears. Choose 'Enable Profiling'.
If profiling is already enabled, the button will be labeled 'Disable Profiling'.
To disable page profiling:
1. Choose the cog icon

, then choose General Configuration

2. Choose 'Logging and Profiling' in the left-hand panel.
3. The 'Logging and Profiling' screen appears. Choose 'Disable Profiling'.
If profiling is already disabled, the button will be labeled 'Enable Profiling'.

Screenshot: Changing Log Levels and Profiling

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 368

Profiling an Activity

1. Enable profiling, using either of the methods described above.

Profiles for every page hit, for all users, will now be logged to your application server's default logs
until Confluence is restarted. Note that each time a user visits a link, a single profile is printed.
2. Confirm that profiles are being written to the Confluence log file — see Working with Confluence Logs
for location of the log files and other details.
3. Perform the activity that is resulting in unusually slow response time.
4. Copy the profile for that action. When deciding which profiles to copy, look for the links that took a long
time to respond. If a single page is slow, only that profile is necessary. If Confluence is generally or
intermittently slow, copy all profiles logged during the slowdown until a reasonable sample has been
collected.
5. If you were instructed to profile your instance by Atlassian technical support, attach all relevant profiles
to your support ticket.
6. Turn profiling off again, using either of the methods described above.
7. Confirm that profiles are no longer being printed to the Confluence log file.

Example of a Profile

Below are the first few lines of a normal profile for accessing a page called Confluence Overview.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 369

[344ms] - /display/ds/Confluence+Overview
[313ms] - SiteMesh: parsePage:
http://localhost:8080/display/ds/Confluence+Overview
[313ms] - XW Interceptor: Before defaultStack:
/pages/viewpage.action (ViewPageAction.execute())
[0ms] - SpaceAwareInterceptor.intercept()
[16ms] - PageAwareInterceptor.intercept()
[0ms] - AOP: PageManager.getPage()
[16ms] - AOP: PermissionManager.hasPermission()
[0ms] - AOP: SpacePermissionManager.hasPermission()
[16ms] - AOP: SpacePermissionManager.hasPermission()
[0ms] - AOP: SpacePermissionManager.hasPermission()
[0ms] - AOP: SpacePermissionManager.hasPermission()
[281ms] - XW Interceptor: After defaultStack:
/pages/viewpage.action (ViewPageAction.execute())
[281ms] - XW Interceptor: After validatingStack:
/pages/viewpage.action (ViewPageAction.execute())
...

Notice that each indented line is a recursive call that rolls up into the parent line. In the example above,
the Confluence Overview page takes 344ms. Part of that, 313ms, is spent in sitemesh.

Start Confluence with Profiling Enabled

There may be some situations where you may wish to have Confluence profiling enabled during startup. This
may be useful if you restart often and may forget to enable profiling for Support/Trouble-shooting purposes.
Edit the file CONFLUENCE_HOME\confluence\WEB-INF\web.xml. You should see a section similar to the
one below. Set the parameter value for autostart to true:

<filter>
<filter-name>profiling</filter-name>

<filter-class>com.atlassian.confluence.util.profiling.ConfluenceProfi
lingFilter</filter-class>
<init-param>
<!-- specify the which HTTP parameter to use to turn the
filter on or off -->
<!-- if not specified - defaults to "profile.filter" -->
<param-name>activate.param</param-name>
<param-value>profile</param-value>
</init-param>
<init-param>
<!-- specify the whether to start the filter
automatically -->
<!-- if not specified - defaults to "true" -->
<param-name>autostart</param-name>
<param-value>true</param-value>
</init-param>
</filter>

Remember to turn it back to false or your logs will grow very large.

Identifying Slow Performing Macros

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 370

Page Profiling gives good detail on what operations are slow in a page load. In addition, you can add debug
level logging:

Version 3.1 and Later

Set the package name com.atlassian.renderer.v2.components.MacroRendererComponent to

DEBUG in Administration >> Logging and Profiling.

Prior to version 3.1

Download WikiMarkupParser.class, available from the attachments to this page. This will result in logs like:

2009-04-23 10:27:54,789 DEBUG [http-8080-1]

[atlassian.renderer.v2.WikiMarkupParser] parse Entering macro rendering.
Processed text: {spaces}
2009-04-23 10:27:55,768 DEBUG [http-8080-1]
[atlassian.renderer.v2.WikiMarkupParser] parse Exiting macro text
rendering. Total time: 979ms
2009-04-23 10:27:55,785 DEBUG [http-8080-1]
[atlassian.renderer.v2.WikiMarkupParser] parse Entering macro rendering.
Processed text: {create-space-button}
2009-04-23 10:27:55,857 DEBUG [http-8080-1]
[atlassian.renderer.v2.WikiMarkupParser] parse Exiting macro text
rendering. Total time: 72ms
2009-04-23 10:27:55,862 DEBUG [http-8080-1]
[atlassian.renderer.v2.WikiMarkupParser] parse Entering macro rendering.
Processed text:
{recently-updated-dashboard:dashboard|showProfilePic=true}
2009-04-23 10:27:56,704 DEBUG [http-8080-1]
[atlassian.renderer.v2.WikiMarkupParser] parse Exiting macro text
rendering. Total time: 842ms
2009-04-23 10:27:56,707 DEBUG [http-8080-1]
[atlassian.renderer.v2.WikiMarkupParser] parse Entering macro rendering.
Processed text: {favpages:maxResults=10}
2009-04-23 10:27:56,889 DEBUG [http-8080-1]
[atlassian.renderer.v2.WikiMarkupParser] parse Exiting macro text
rendering. Total time: 182ms

To add the class:

1. Add this line to the file <confluence-install>/confluence/WEB-INF/classes/log4j.properties:
log4j.logger.com.atlassian.renderer=DEBUG
2. Add the appropriate WikiMarkupParser.class to /confluence/WEB-INF/classes/com/atlassian/renderer/v2.
You'll have to make the renderer and v2 folders.
In combination with page profiling, this should give good specifics on the amount of time various plugins take.
You can also use this utility to Search Confluence for Uses of a Macro.

Resolution

Experiment with the tips from the performance tuning page, or open an enhancement request about the specific
macro. In some instances there is no resolution - you'll just be aware of the overhead of various macros.

Confluence Diagnostics
When investigating a performance problem or outage, it's useful to know as much as possible about what was
happening in your site in the lead-up to the problem. This is when diagnostics information can help.
While often not individually actionable, diagnostic alerts can help you build up a detailed picture of your site's

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 371

behaviour, and identify symptoms that may be contributing to the problem.

This feature is still experimental in Confluence 6.11. We plan to fine-tune the thresholds and provide a
UI for this diagnostic information in an upcoming Confluence release. Stay tuned!

About diagnostic alerts

The purpose of the diagnostics tool is to continuously check for symptoms or behaviours that we know may
contribute to problems in your site. An alert is triggered when a set threshold is exceeded.
For example, if the free disk space for your local home (or shared home) directory falls below 256MB, an alert is
triggered. This is useful because if you run out of space, your users may not be able to upload new files, export
spaces, or perform other tasks that rely on writing files to that directory.
It's important to note that the thresholds are just the point at which the alert is triggered. It's not the same as a
timeout, or other hard limit. For example a long running task may trigger an alert after 5 minutes, and still
complete successfully after 8 minutes.
When an alert is triggered a message is written to the atlassian-confluence.log file (your application log),
and further details provided in the atlassian-diagnostics.log file. It's also included in support zips.

Some behaviours trigger a single alert, for others, multiple alerts are possible. Diagnostic information is stored in
the database, and retained for 30 days. Old alerts are cleaned up automatically.

Types of alerts

There a several types of alerts.

Alert and KB Level Default threshold Configurable

Low free disk space Critical 8192 megabytes Yes

Low free memory Warn 256 megabytes Yes

Node left or joined the cluster Info N/A No

Long running task exceeded time limit Warn 300 seconds Yes

Garbage collection exceeded time limit Warn 10% (over the last 20 Yes
seconds)

Availability

Some diagnostic alerts are disabled by default, because they may have a performance impact on your site, or
are not designed to run continuously.
Our support team may ask you to enable one of the following alerts when troubleshooting a specific problem.
They'll provide you with information on how to do this.

Alert and KB Level Default threshold Configurable

HTTP request exceeded time limit Warn 60 seconds Yes

Macro rendering exceeded time limit Warn 30 seconds Yes

Thread memory allocation rate exceeded limit Warn 5% over the last 20 Yes
seconds)

Sandbox crashed or was terminated during document Info N/A No

conversion

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 372

Alert levels

There are three levels of diagnostic alerts:

Info - information that might be useful when troubleshooting a problem, for example a node joined the
cluster
Warning - a problem that may impact performance or availability in future, for example low memory
Critical - a serious problem that is likely to impact system stability or availability, for example low disk
space.
Most alerts don't require any immediate action.

Change alert thresholds

Some alert thresholds are configurable. If you find you are seeing too many instances of an alert, you can
change the threshold, so it's not triggered so easily.
Head to Recognized System Properties for a list of system properties for each alert. This info can also be found
on the knowledge base article for each alert.

Change diagnostics behaviour

You can also change the way the diagnostics framework itself behaves. For example, you might change how
often checks are performed, or how long diagnostics information is retained.
Head to Recognized System Properties for the full list of system properties.

Data Collection Policy

Why does Confluence collect usage data?

We're proud that Confluence is one of the most versatile collaboration tools on the planet, and we will continue
to deliver innovative new features as quickly as we can. In order to prioritize the features we deliver, we need to
understand how our customers use Confluence, what's important, what's not, and what doesn't work well. The
collection of usage data allows us to measure the user experience across many thousands of users and deliver
features that matter.

What data is collected?

The type of data we collect is covered in our Privacy Policy. Please read it - we've tried to avoid legal jargon and
made it as straightforward as possible.
To view a sample of data that might be collected from your specific installation, go to

> General Configuration > Analytics.

Data is always collected in Confluence Cloud.

How is data collected from Confluence?

Older versions of Confluence (prior to Confluence 5.6 or Confluence Questions 1.0.618) didn't collect usage
data. Analytics are collected using the Atlassian Analytics system app. The app collects analytics events in a log
file which is located in <confluence-home>/analytics-logs. The logs are periodically uploaded using an
encrypted session and then deleted. If Confluence is unable to connect to the Internet, no logs are ever
uploaded.

Enabling/disabling data collection in Confluence

You can turn off analytics collection at any time. Go to

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 373

> General Configuration > Analytics.

Administering Collaborative Editing

Collaborative editing takes teamwork to the next On this page:
level. This page covers everything you need to know
about administering collaborative editing. About Synchrony
Change the editing mode
Head to Collaborative editing to find out how your Maximum editor limit
team can work together in real time on software Auditing considerations
requirements, meeting notes, retros, and any other No version history in
Confluence page you can think of. unpublished drafts
Visibility of edits made by
anonymous users
About Synchrony
Proxy and SSL considerations
Collaborative editing is powered by Synchrony which SSL
synchronizes data in real time. Synchrony is Proxies
managed by Confluence, so administrators should WebSockets
rarely need to interact with it directly. Change your Synchrony
configuration
Synchrony runs on port 8091 by default, and an Start and stop Synchrony
internal Synchrony proxy means that you shouldn't Monitor Synchrony
need to open this additional port. Accessing Synchrony logs
How you connect to Synchrony will depend on your Related pages:
environment, and your Confluence license. See Pos
sible Confluence and Synchrony Configurations. Troubleshooting Collaborative
Editing

To see your collaborative editing and Synchrony setup, head to

> General Configuration > Collaborative editing.

Change the editing mode

The editing mode determines the editing experience for all users in your site. This is how you turn
collaborative editing on or off.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 374

To change the editing mode:

1. Go to

> General Configuration > Collaborative editing.

2. Choose Change mode.
3. Select a mode and choose Change.
Changing the editing mode is not trivial, and some changes can result in the loss of your users' drafts, so it is
good to understand the implications of each mode.
The following modes are available:

Mode Implications

On This mode allows your team to edit a shared draft of a page at the same time, and see each
others' changes in real time.
This the recommended editing mode.

Limited This mode protects your users' shared drafts if you need to troubleshoot Synchrony. You
would only switch to this mode if your users are experiencing problems editing and publishing.
The editing experience will be very limited for your users:
Only one person can edit a shared draft at one time.
You can't revert to an earlier version of the page in the page history.
You can't move pages.
You can't make inline comments on pages.
As soon as Synchrony is running again, we recommend turning collaborative editing back on.

Off This mode means that your team can only edit their own personal draft of a page. Confluence
will attempt to merge any conflicts on save. This mode replicates the Confluence 5 editing
experience.
This mode is useful if you are unable to run Synchrony successfully in your environment, or if
you have decided that collaborative editing is not for you (for example if you have auditing
requirements that would prohibit using collaborative editing just yet).
You should make sure your users have published any work they want to keep before you turn
collaborative editing off.

Maximum editor limit

A maximum of 12 people can edit a page at the same time. This means that people can't enter the editor if
there are already 12 other people editing the page, and will need to wait until someone leaves.
Administrators can increase or decrease this limit using a system property. If you experience performance
issues when many people are editing, you might want to decrease this limit.

Auditing considerations

We know that auditing is a major consideration for some customers. We don't yet have very granular auditing
capabilities with collaborative editing. All page changes are currently attributed to the person that publishes
the page, rather than the people who made each specific change.
If this is going to be a problem in your site, we recommend turning collaborative editing off in your site for
now.

No version history in unpublished drafts

We're saving all the time in collaborative editing, but we don't save versions of unpublished changes. When
restoring an earlier page version, you can only roll back to an existing published version. Any unpublished

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 375

changes will be lost when you restore a previous version.

Visibility of edits made by anonymous users

There are some additional things to be aware of if you have granted the Add page permission (and Can use
global permission) to anonymous users.
You won't be alerted, when closing the editor or publishing a page, if the only unpublished changes on the
page were made by anonymous users. This means a logged in user may inadvertently publish changes they
were not aware had been made to the page.
The changes themselves are visible in the page, but the usual warning dialog will not appear if the only
people to have made changes were not logged in.
If there are unpublished changes from both logged in users and anonymous users, the warning dialog will
appear, but only the logged in users will be listed in the dialog. Changes made by all users (including
anonymous) will be included if you view the changes from that dialog.

Proxy and SSL considerations

How you connect to Synchrony will depend on your environment. We know that most Confluence sites run
behind a reverse proxy, often with SSL. Here's some information to help you identify the right configuration
for your environment, and any changes you might need to make to your environment to use collaborative
editing in your site.

SSL

Synchrony runs in a seperate JVM, and does not support direct HTTPS connections. If you are not using a
reverse proxy, SSL should be terminated at Tomcat. If you are using a reverse proxy or load balancer, SSL
should be terminated at your reverse proxy or load balancer.
See Possible Confluence and Synchrony Configurations for detailed diagrams and examples.

Proxies

If you run Confluence behind a reverse proxy, you should take a look at the Possible Confluence and
Synchrony configurations for guidance on how your Confluence and Synchrony setup may impact your
proxy.
See Possible Confluence and Synchrony Configurations for detailed diagrams and examples, plus links to
example proxy configuration files.

WebSockets

For best results, your load balancer and proxies should allow WebSocket connections. If your users are
unable to get a WebSocket connection, Confluence will fall back to a XML HTTP Request (XHR), allowing
them to edit pages successfully.
XHR fallback is enabled by default, but can be disabled using a system property (passed to Confluence) if
necessary. You shouldn't need to change this.

Change your Synchrony configuration

You can't change your Synchrony configuration through the Confluence UI. In most cases you shouldn't need
to make changes to the default configuration.
If you need to change the port Synchrony runs on or the maximum memory available, for example, you can
do this using a system property, or in your start-synchrony script (if you're running your own Synchrony
cluster).
See Configuring Synchrony for more information.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 376

Start and stop Synchrony

If Synchrony is managed by Confluence (recommended), Confluence will automatically start Synchrony for
you when it starts up. You can also restart Synchrony from the collaborative editing admin screen in
Confluence.
If you're running Synchrony standalone in a cluster, you'll use the start-synchrony.sh or start-syn
chrony.bat. scripts on each Synchrony node. A process ID (PID) file will be created in your synchrony
directory.
Stop Synchrony the same way, using stop-synchrony.sh or stop-synchrony.bat. This will destroy
the PID file that the start script created in your Synchrony directory. If you've customised the location for
storing the PID file in the start-synchrony script, you'll need to also update this in the stop-synchrony
script.
If you're unable to start Synchrony, check that there isn't an existing PID file in your Synchrony directory.

Monitor Synchrony

To check if Synchrony is running, go to

> General Configuration > Collaborative editing.

If you're running Confluence in a cluster, you can check the status of Synchrony on each node from the
clustering screen.
Go to

> General Configuration > Clustering, then on each node choose Collaborative editing. You can access
all nodes in this way, you don't need to hit a specific node in your browser.

From here you can see the Synchrony status, mode, and URL Confluence is using to connect to it. Here's
what it looks like when Synchrony is managed by Confluence.

All Confluence nodes must use the same Synchrony mode. For example, you can't have one node using
managed Synchrony, and another node connecting to an standalone Synchrony cluster.

Accessing Synchrony logs

If Synchrony is managed by Confluence (recommended), Synchrony logs will be stored in your <local-ho
me>/logs directory, with the Confluence application logs.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 377

If you're running Synchrony standalone in a cluster, your Synchrony logs will be stored in the Synchrony
directory on each Synchrony node (wherever you run the start and stop scripts from).

Possible Confluence and Synchrony Configurations

Synchrony is the engine that powers collaborative On this page:
editing in Confluence.
Possible configurations for
There are a few different options for running Confluence Server
Synchrony, and it is worth taking some time to Possible configurations for
determine which option will best meet the needs of Confluence Data Center
your organisation.

Possible configurations for Confluence Server

If you have a Confluence Server license, Synchrony is managed by Confluence.

The diagrams below show examples of a common implementation where Confluence is running under the
/confluence context path (e.g. www.mysite.com/confluence). The concepts are the same if you use
Confluence without a context path (e.g. www.myconfluence.com).

No reverse proxy

If you don't run Confluence behind a reverse proxy, you'll connect to Synchrony via Confluence's internal
Synchrony proxy. SSL, if used, is terminated at Tomcat. This is the default configuration, and you shouldn't
need to make any additional changes to use collaborative editing.

With a reverse proxy

If you run Confluence behind a reverse proxy, you will connect to Synchrony via Confluence's internal
Synchrony proxy. This is the default configuration with a reverse proxy, and a good choice if you do not want
to open port 8091. SSL should be terminated at your reverse proxy.
You do not need to make any additional changes to your reverse proxy configuration for Synchrony, but for
best results your reverse proxy must support WebSocket connections (you may need to manually enable this
in your proxy).

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 378

To tell Confluence that you want to use the internal proxy, set the synchrony.proxy.enabled system
property to true. (This is optional, but will prevent Confluence from trying to reach Synchrony via /synchrony
first, before retrying via the internal proxy).

If Synchrony can't be reached via /synchrony-proxy we'll automatically try /confluence/synchrony-proxy

(where /confluence is your Confluence context path).

Direct to Synchrony with a reverse proxy

If you run Confluence behind a reverse proxy, and experience latency or other issues connecting to
Synchrony via Confluence's internal Synchrony proxy, you can choose to connect direct to Synchrony. This is
the optimal setup, but does require some changes to your environment. You will need to open port 8091 and
add /synchrony to your reverse proxy configuration. SSL will still be terminated at your reverse proxy, as
Synchrony does not accept direct HTTPS connections.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 379

If Synchrony can't be reached via /synchrony we'll automatically try the internal Synchrony proxy via
/confluence/synchrony-proxy (where /confluence is your Confluence context path).
See the following guides for example reverse proxy configurations. The order of directives is important, so
check our examples.
Using Apache with mod_proxy
Running Confluence behind NGINX with SSL
Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http)
Proxying Atlassian server applications with Microsoft Internet Information Services (IIS)
How to configure Amazon Web Service Elastic Load Balancer with Confluence 6.0

Possible configurations for Confluence Data Center

If you have a Confluence Data Center license, two methods are available for running Synchrony:
managed by Confluence (recommended)
Confluence will automatically launch a Synchrony process on the same node, and manage it for you.
No manual setup is required.
Standalone Synchrony cluster (managed by you)
You deploy and manage Synchrony standalone in its own cluster with as many nodes as you need.
Significant setup is required.
If you want simple setup and maintenance, we recommend allowing Confluence to manage Synchrony for
you. If you want full control, or if making sure the editor is highly available is essential, then managing
Synchrony in its own cluster may be the right solution for your organisation.

Managed by Confluence

Here's a simplified view of the architecture when Synchrony is managed by Confluence. This is the
recommended approach, as no manual set up, or ongoing upgrades are required - it works right out of the
box.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 380

If you choose this approach, the guidance provided for Confluence Server above, also applies to your load
balancer and any proxies.
This option is only available in Confluence 6.12 and later.

Standalone Synchrony cluster

If you choose to manage Synchrony yourself, the architecture looks more like this. Again the diagram has
been simplified, and doesn't show communication between nodes.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 381

If you choose this approach you will need to:

Set up and manage multiple Synchrony cluster nodes.
Always start Confluence with the synchrony.service.url system property (this tells Confluence
where to find your Synchrony cluster, instead of launching a Synchrony process on the current node).
Open the Synchrony port (8091), as the Synchrony proxy is never used when you manage Synchrony
yourself.
Terminate SSL at your load balancer. Synchrony cannot accept HTTPS connections.
Upgrade Synchrony manually, each time you upgrade Confluence.
For a step-by-step guide to setting up your Synchrony cluster, see Set up a Synchrony cluster for Confluence
Data Center.

If you enabled collaborative editing prior to Confluence Data Center 6.12, standalone Synchrony will
be your default setup.
If you would prefer a less complex setup, see Migrate from a standalone Synchrony cluster to
managed Synchrony to find out how to allow Confluence to manage Synchrony for you.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 382

Configuring Synchrony
Synchrony is the engine that powers collaborative editing in Confluence. On this page:
There's no UI for configuring Synchrony. Configuration changes, such as Passing
changing the Synchrony port or memory settings, are made via system recognized
properties. How you pass these properties depends on whether Synchrony system
is managed by Confluence, or deployed as a seperate cluster. properties
to
In most cases, Synchrony is managed by Confluence.
Synchrony
If you have a Data Center license, you may choose to deploy and manage S Common
ynchrony standalone in a cluster, instead of allowing Confluence to configurati
manage Synchrony for you. See Possible Confluence and Synchrony on
Configurations for more information. changes
Troublesho
oting

Passing recognized system properties to Synchrony

If Synchrony is managed by Confluence (the most common setup), you make changes to Synchrony by
passing system properties to Confluence. See Configuring System Properties to find out the best way to do
this for your operating system.
You can find a full list of system properties at Recognized System Properties.
If you're running Synchrony standalone in a cluster, you pass properties directly to Synchrony via the
start-synchrony scripts.
Note that the properties are not always the same as those used when Synchrony is managed by
Confluence. A full list of required and optional properties can be found at Set up a Synchrony cluster for
Confluence Data Center.

Passing JVM arguments to Synchrony

Sometimes you may want to pass additional arguments, that are not already provided by a system property,
directly to Synchrony's JVM.
If Synchrony is managed by Confluence, you will need to create a file called synchrony-args.properti
es in your home directory (or shared home if you have a Data Center license) and include the arguments you
want to pass to Synchrony, one per line, as follows:

property1=value1
property2=value2

Remember, you can't use this method for passing any value that is already handled by a system property,
such port, Xmx or Xss etc.
If you're running Synchrony standalone in a cluster, you pass arguments to Synchrony's JVM directly, by
adding them to your start-synchrony script, in the Optional Overrides section.

Common configuration changes

The two most common changes people make to Synchrony is to change the port that Synchrony runs on, if
port 8091 is already in use, and to change the maximum heap memory allocated to Synchrony.

Change the port Synchrony runs on

Synchrony runs on port 8091 by default. If this port is already in use by another application on your server
you can use the the synchrony.port system property to change it to an available port.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 383

If you're Confluence 6.0.3 or earlier you'll need to use reza.port instead of synchrony.port.

To change the maximum heap for Synchrony

Synchrony has a maximum heap size of 1 GB by default.

If you experience out of memory errors related to Synchrony, you can change the heap size allocated to
Synchrony using the synchrony.memory.max system property.

If you're Confluence 6.0.3 or earlier you'll need to use reza.memory.max instead of synchrony.memory.
max.

Troubleshooting

If you have a Data Center license, and Synchrony is managed by Confluence, we recommend storing
the synchorny-args.properties file in the shared home directory, so that all Synchrony
processes are started with the same JVM arguments. If you do locate the synchrony-args.proper
ties file in the local home, the arguments will only be passed to the Synchrony process on that
node.

Set up a Synchrony cluster for Confluence Data Center

If you have a Confluence Data Center license, two On this page:
methods are available for running Synchrony:
Architecture overview
managed by Confluence (recommended) Set up a Synchrony standalone
Confluence will automatically launch a cluster
Synchrony process on the same node, and 1 Provision your Synchrony
manage it for you. No manual setup is nodes
required. 2 Create the Synchrony
Standalone Synchrony cluster (managed home directory
by you) 3 Edit the start and stop
You deploy and manage Synchrony scripts
standalone in its own cluster with as many 4 Add additional Synchrony
nodes as you need. Significant setup is nodes and configure your
required. load balancer
5 Start Confluence one
If you want simple setup and maintenance, we
node at a time
recommend allowing Confluence to manage
6 Enable collaborative
Synchrony for you. If you want full control, or if
editing
making sure the editor is highly available is
Required properties for
essential, then managing Synchrony in its own
Synchrony standalone
cluster may be the right solution for your
Optional properties for Synchrony
organisation.
standalone
Run Synchrony standalone in an
IPv6 environment
Run Synchrony standalone as a
service
Provide credentials to Synchrony
standalone using environment
variables

On this page we'll guide you through the process of setting up a standalone Synchrony cluster, hosted on
your own infrastructure. The ability to run your own Synchrony cluster is only available with a Data Center
license.

Architecture overview

Here's a simplified view of the architecture when you manage Synchrony yourself, in a seperate cluster. Note

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 384

that this diagram doesn't show communication between nodes.

If you enabled collaborative editing prior to Confluence Data Center 6.12, standalone Synchrony will
be your default setup.
If you would prefer a less complex setup, see Migrate from a standalone Synchrony cluster to
managed Synchrony to find out how to allow Confluence to manage Synchrony for you.

Set up a Synchrony standalone cluster

This page will guide you through setting up a Synchrony standalone cluster on your own infrastructure.
If you're using AWS or Azure, using one of our templates may be a more efficient way to set up Confluence
with a standalone Synchrony cluster.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 385

1 Provision your Synchrony nodes

For the purposes of this guide, we assume you have already provisioned the hardware or virtual instances for
your Synchrony nodes. We recommend starting with 2 Synchrony nodes.
You should allow 2GB memory for Synchrony, and enough disk space for the Synchrony application and
logs.

2 Create the Synchrony home directory

To create the Synchrony directory on your first Synchrony node:

1. Grab the <install-directory>/bin/synchrony directory from one of your Confluence nodes
and move it to your new Synchrony node. We'll call this your <synchrony-home> directory.
2. Copy synchrony-standalone.jar from your Confluence local home directory to your <synchron
y-home> directory.
3. Copy your database driver from your Confluence <install-directory>/confluence/web-inf/
lib to your <synchrony-home> directory or other appropriate location on your Synchrony node.

3 Edit the start and stop scripts

We provide scripts to start and stop Synchrony on each node. These need to be edited to add information
about your environment:
1. Edit the <synchrony-home>/start-synchrony.sh or start-synchrony.bat file
2. Enter details for all of the required parameters listed under Configure parameters.
See Required properties below, for a description of each.
3. Enter detail for any optional properties you may want to specify.
See Optional properties below for a description of each.
4. Save the file.
5. Start Synchrony by running the start-synchrony script.
6. Visit http://<SERVER_IP>:<SYNCHRONY_PORT>/synchrony/heartbeat to check Synchrony
is running.

4 Add additional Synchrony nodes and configure your load balancer

To create your second Synchrony node:

1. Copy your <synchrony-home> directory to the second Synchrony node.
2. Start Synchrony on that node using the start-synchrony script. As each node joins you'll see
something like this in your console.

Members [2] {
Member [172.22.52.12]:5701
Member [172.22.49.34]:5701
}

3. Configure your load balancer for Synchrony traffic.

For best results, your load balancer should allow WebSocket connections. SSL connections must be
terminated at your load balancer, as Synchrony can't accept HTTP requests.

You can choose to use the same load balancer for both Confluence and Synchrony, or two seperate
load balancers. When we refer to the Synchrony load balancer, we mean whichever load balancer is
handling Synchrony traffic.

5 Start Confluence one node at a time

Now that Synchrony is running in a cluster, it's time to get Confluence involved. It is essential that you stop
Confluence on all nodes before continuing.

1.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 386

1. Stop Confluence on all nodes.

2. Start Confluence on one node with the following system property.
This property is used to tell Confluence where to find Synchrony, and prevents Confluence
from automatically launching a Synchrony process on your Confluence node.

-Dsynchrony.service.url=http://<synchrony-load-balancer-url>/syn
chrony/v1

For example http://42.42.42.42/synchrony/v1 or

http://synchrony.example.com/synchrony/v1
3. Check that Confluence can connect to Synchrony. Head to

> General Configuration > Clustering then choose

> Collaborative editing beside the Confluence node you just started.

The Synchrony mode should be Standalone Synchrony cluster.

If the mode is 'Managed by Confluence', your Confluence node is not connected to your Synchrony
cluster. Make sure you're passing the Synchrony service URL system property correctly.

4. Repeat this process, starting each Confluence node, one at a time, with the synchrony.service.u
rl.

6 Enable collaborative editing

If you're installing Confluence for the first time, collaborative editing is enabled by default. If you've upgraded
from an earlier Confluence version, or have disabled it in the past, collaborative editing may still be disabled.
To enable collaborative editing:
1. Head to

> General Configuration > Collaborative editing.

2. Choose Change mode.
3. Select On and choose Change.
You can now try editing a page. You'll need to access Confluence via your load balancer. You can't create or
edit pages when accessing a node directly.
Any users who had the editor open before you made this change will need to refresh in order to continue
editing, as the Synchrony URL they're connected to will have changed.

Required properties for Synchrony standalone

These properties only apply when you're running Synchrony standalone in its own cluster. If Synchrony is
managed by Confluence (Server or Data Center) these properties don't apply.
The following properties must be provided in the start-synchrony script.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 387

Property name Description

SERVER_IP Public IP address or hostname of this Synchrony node. It could also be

a private IP address - it should be configured to the address where
Synchrony is reachable by the other nodes.

DATABASE_URL This is the URL for your Confluence database. For example jdbc:po
stgresql://yourserver:5432/confluence . You can find this
URL in <local-home>/confluence.cfg.xml .

DATABASE_USER This is the username of your Confluence database user.

DATABASE_PASSWORD (Optional) This is the password for your Confluence database user. If
your password contains special characters, Synchrony may silently fail
to connect to the database.
Rather than hardcoding your password, we recommend setting your
password with the environment variable SYNCHRONY_DATABASE_PAS
SWORD. Any dots (".") in variable names (identifiers) will need to be
replaced with underscores ("_").

CLUSTER_JOIN_PROPERTIES This determines how Synchrony should discover nodes. You'll be

prompted to uncomment a set of parameters for either:
TCP/IP
Multicast
AWS
Follow the prompts in the script for the values you need to enter for
each of these.

DATABASE_DRIVER_PATH This is the path to your database driver file. If you're running
Synchrony on its own node, you'll need to copy your database driver to
an appropriate location then provide the path to this location.

SYNCHRONY_JAR_PATH This is the path to the synchrony-standalone.jar file you copied

to this node.

SYNCHRONY_URL This is the URL that the browser uses to contact Synchrony. Generally
this will be the full URL of the load balancer Synchrony will run behind
plus the Synchrony context path, for example http://yoursite.co
m:8091/synchrony .

Note that it does not end with /v1 , unlike the synchrony.service.
url system property passed to Confluence. If this URL doesn't match
the URL coming from a users' browser, Synchrony will fail.

OPTIONAL_OVERRIDES You can choose to specify additional system properties. See the table
below for recognised Synchrony system properties.

Optional properties for Synchrony standalone

These properties only apply if you're running Synchrony standalone in a cluster.

When you start Synchrony, we pass default values for the properties listed below. You can choose to
override these values by specifying any of these properties when you start Synchrony.

Property name Default Description

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 388

cluster.listen.port 5701 This is Synchrony's Hazelcast port.

Specify this property if you do not want
to use port 5701 or if it is not available.
As with the Confluence Hazelcast port
(5801) you should ensure that only
permitted cluster nodes are allowed to
connect to Synchrony's Hazelcast port,
through the use of a firewall and or
network segregation.

synchrony.cluster.base.port 25500 This is the Aleph binding port.

Synchrony uses Aleph to communicate
between nodes. Specify this property if
you don't want to use the default.

cluster.join.multicast.group 224.2.2.3 If the cluster join type is multicast, you

can specify an IP address for the
multicast group if you don't want to use
the default.

cluster.join.multicast.port 54327 If the cluster join type is multicast, you

can specify a multicast port if you don't
want to use the default.

cluster.join.multicast.ttl 32 If the cluster join type is multicast, this

is the time to live threshold. The default,
32, means the scope is restricted to the
same site, organization or department.
Specify this property if you want to use
a different threshold.

cluster.join.aws.access.key If the cluster join type is AWS, this is

your AWS access key.

cluster.join.aws.secret.key If the cluster join type is AWS, you can

authenticate by IAM role or Secret key.
This is your AWS secret key.

cluster.join.aws.iam If the cluster join type is AWS, you can

authenticate by IAM role or Secret key.
This is your AWS IAM role.

cluster.join.aws.region us-east-1 If the cluster join type is AWS, this is

the AWS region your Synchrony nodes
will be running in.

cluster.join.aws.security.group If the cluster join type is AWS, and you

want to narrow the members of your
cluster to only resources in a particular
security group, specify the name of your
AWS security group.

cluster.join.aws.tag.key If the cluster join type is AWS, and you

want to narrow the members of your
cluster to only resources with particular
tags, specify the AWS tag key.

cluster.join.aws.tag.value If the cluster join type is AWS, and you

want to narrow the members of your
cluster to only resources with particular
tags, specify the AWS tag key value.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 389

cluster.join.aws.host.header If the cluster join type is AWS, t his is

the AWS endpoint for Synchrony to use
(the address where the EC2 API can be
found, for example ' ec2.amazonaws.co
m ').

cluster.join.aws.timeout 5 If the cluster join type is AWS, this is

the joining timeout (in seconds).

cluster.interfaces Defaults to the This is the network interface Synchrony

same value as S will use to communicate between
ERVER_IP nodes. Specify this property if you don't
want to use the default, which uses the
value of the required property Defaults
to the same value as SERVER_IP (also
known as synchrony.bind).

synchrony.cluster.bind Defaults to the This is the Aleph binding address. This

same value as S should be set to the same value as clu
ERVER_IP ster.interfaces.

Specify this property if you did not use

the default value for cluster.interf
aces.

synchrony.port 8091 This is the HTTP port that Synchrony

runs on. If port 8091 is not available,
specify this property to choose a
different port.

synchrony.context.path Defaults to the This is the context path for Synchrony.

context path of S There should be no need to change
YNCHRONY_URL this.

hazelcast.prefer.ipv4.stack True If you're running Confluence in an IPv6

environment, you will need to set this
property to False.

Run Synchrony standalone in an IPv6 environment

If you're running a Synchrony standalone in a cluster in an IPv6 environment, you will need to start
Synchrony with the following JVM argument:

-Dhazelcast.prefer.ipv4.stack=false

If you're using the start-synchrony scripts, simply uncomment this line in the script.

Run Synchrony standalone as a service

If you're running Synchrony standalone in a cluster, and you'd prefer to run Synchrony as a service on
each node, see Run Synchrony-standalone as a service on Linux.
It's not possible to run Synchrony standalone as a service on Windows. Consider switching to managed
Synchrony instead.

Provide credentials to Synchrony standalone using environment variables

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 390

If you're running Synchrony standalone in a cluster, and you prefer to store sensitive information in your
environment, rather than directly in the Synchrony startup scripts you can create a synchronyenv file, and
use it to provide your database credentials. This is only available in Linux environments.
See Provide credentials to Synchrony standalone using environment variables (Linux)

Migrate from a standalone Synchrony cluster to managed Synchrony

If you have a Confluence Data Center license, and enabled collaborative editing prior to Confluence 6.12, you
will likely be running standalone Synchrony, either in it's own cluster, or manually on each Confluence node.
If you'd prefer a simpler setup, with less ongoing maintenance, you can choose to let Confluence manage
Synchrony for you. Confluence will automatically start up a Synchrony process when Confluence is started.
Some Confluence downtime is required for this process.
To switch from managing your own Synchrony cluster to letting Confluence manage Synchrony:
1. Configure your load balancer to direct traffic away from all Confluence and Synchrony nodes.
2. Stop Confluence and Synchrony on all nodes.
3. Start Confluence on one node without the synchrony.service.url system property. This property
tells Confluence where to find your external Synchrony cluster.
Show me how to do this...
The way you remove this system property depends on how you run Confluence. Note that this system
property is passed to Confluence, not Synchrony itself.
If you start Confluence manually on Windows, edit the <install
directory>/bin/setenv.bat file and remove the following line:

set
CATALINA_OPTS=-Dsynchrony.service.url=http://example-synchrony.c
om/synchrony/v1 %CATALINA_OPTS%

If you start Confluence manually on Linux, edit the <install directory>/bin/setenv.sh file
and remove the following line:

CATALINA_OPTS="-Dsynchrony.service.url=http://example-synchrony.
com/synchrony/v1 ${CATALINA_OPTS}"

If you're running as a Confluence as a Windows Service, you'll need to edit the service and remove
the following from the Java options:

-Dsynchrony.service.url=http://example-synchrony.com/synchrony/v
1

See Configuring System Properties for a step-by-step guide to passing system properties to Windows
services via the command line or Windows Registry.
4. In Confluence, edit a page and check that you can successfully make changes.
5. Repeat this process on each Confluence node, starting each node one at a time.
Once all nodes are back up and running, and you've confirmed that collaborative editing is working as expected,
you can decommission your external Synchrony cluster, including removing any startup scripts or services you
may have configured.
Any users who had the editor open before you made this change will need to refresh in order to continue editing,
as the Synchrony URL they're connected to will have changed.
You may also need to make some changes to your load balancer configuration. See Possible Confluence and
Synchrony Configurations for more information.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 391

Troubleshooting Collaborative Editing

Collaborative editing is powered by Synchrony which On this page:
synchronizes data in real time. Under normal
circumstances it should not need to be managed First steps
manually by an administrator. Check Synchrony is running
Check you can edit a page
This page will help you troubleshoot problems with Check the logs
Synchrony in your instance. Restart Synchrony
Check port 8091 is available
First steps
Reverse proxy issues
Forward proxy issues
Websocket issues
Check Synchrony is running
SSL issues
To check if Synchrony is running, g o to Memory issues
Multiple Synchrony processes
Mixed Synchrony modes in cluster
> General Configuration > Collaborative editing
Incompatible browser extensions
.
Firewall or anti-virus interference
Note: if you're running Confluence Data Center, this Too many people in the editor
page will only be able to tell you if the current
Related pages:
Confluence node is connected to your Synchrony
cluster. You may want to use a third party monitoring Administering Collaborative
tool to help you monitor your Synchrony cluster. Editing

Check you can edit a page

If you see an error when you edit a page, but

Synchrony is running, something is preventing your
browser from connecting to Synchrony.
The most common issue is a misconfigured reverse
proxy. See our proxy troubleshooting tips later in this
page or head to Administering Collaborative Editing t
o find out more about possible proxy and SSL
configurations.
Check the logs

You can find the Confluence application logs at <home-directory>/logs/atlassian-confluence.lo

g and Synchrony specific logs at <home-directory>/logs/atlassian-synchrony.log .

Restart Synchrony

Go to

> General Configuration > Collaborative editing and choose Restart Synchrony.

Check port 8091 is available

Synchrony runs on port 8091 by default. If this port is already in use by another application on your server
you can use the the synchrony.port system property to change it to an available port.

(If you're using Confluence 6.0.3 or earlier you'll need to use reza.port instead of synchrony.port.)

See Configuring System Properties to find out how to change this.

For Confluence Data Center the way you run Synchrony is a little different. See Configuring Synchrony for
more information.

Reverse proxy issues

If you have configured your reverse proxy, but can't edit pages, here's some things to check in your
configuration:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 392

Go to installation-directory>/conf/server.xml and check the Connector directive.

Make sure that you have correct values for <protocol> and <proxyName>. See the examples in the
guides below for more information.
The http connector always needs to be present in the <installation-directory>/conf/serv
er.xml file, even if you're configuring SSL or using the AJP connector. The Synchrony health check
uses HTTP and will fail if this connector is not present. Alternatively, if you do not want to include the
http connector, you can use the synchrony.proxy.healthcheck.disabled system property to
disable the health check.
If you're using Apache, make sure you're using Apache 2.4 (with WebSockets support) and all
required modules have been enabled (mod-proxy, mod_rewrite, proxy_wstunnel).
If you're using Apache and want to connect directly to Synchrony, in your proxy config file, make sure
you've included /synchrony and that the order of the Confluence and Synchrony directives and
location blocks is correct. See the examples in the guides below for more information.
See Administering Collaborative Editing to find out more about possible proxy and SSL configurations then
check out the following guides for more information on how to include Synchrony in your reverse proxy
config, if you want to connect direct to Synchrony:
Using Apache with mod_proxy
Running Confluence behind NGINX with SSL
Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http)
Proxying Atlassian server applications with Microsoft Internet Information Services (IIS)
How to configure Amazon Web Service Elastic Load Balancer with Confluence 6.0

Forward proxy issues

If you're using a forward or outbound proxy, you will need to add the IP that Synchrony listens on to your
config to ensure it is bypassed. See Configuring Web Proxy Support for Confluence for more info.
By default, the IP is 127.0.0.1, or it will be the value of the synchrony.host system property, if you've
customized the hostname or IP that Confluence uses to connect to Synchrony.

Websocket issues

Collaborative editing works best with a WebSocket connection. If one can't be established due to a timeout,
or a proxy server or firewall that doesn't allow WebSocket connections, the editor will attempt to connect via
an XML HTTP Request (XHR).
You can use http://websocket.org/echo.html to perform a quick HTML5 WebSocket test against an echo
server.

SSL issues

Synchrony cannot accept direct HTTPS connections, so you will need to terminate SSL at your reverse proxy
or load balancer, or at Tomcat if you are not using a reverse proxy.

Memory issues

If you experience out of memory errors related to Synchrony, you can change the heap size allocated to
Synchrony using the synchrony.memory.max system property.

If you're Confluence 6.0.3 or earlier you'll need to use reza.memory.max instead of synchrony.memory.
max.

See Configuring System Properties to find out how to change this.

For Confluence Data Center the way you run Synchrony is a little different. See Configuring Synchrony for
more information.

Multiple Synchrony processes

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 393

If you see an error immediatley in the editor, but Confluence reports that Synchrony is running, check to
make sure that you only have one Synchrony process running.
If you do have multiple Synchrony processes running, stop Confluence, kill the additional Synchrony
processes and then restart Confluence.
You can avoid this problem by always using stop-confluence.sh / stop-confluence.bat to stop
Confluence, rather than simply closing the Tomcat window.

Mixed Synchrony modes in cluster

If you're running Confluence in a cluster, all of your Confluence nodes must connect to Synchrony in the
same way.
If users are able to use collaborative editing on one Confluence node, but not on another Confluence node,
go to

> General Configuration > Clustering, then on each node choose Collaborative editing.
Make sure all of your Confluence nodes are reporting the same Synchrony mode - either Managed by
Confluence, or Standalone Synchrony cluster.

You can access all nodes in this way, you don't need to hit a specific node in your browser.

Incompatible browser extensions

Some third party browser extensions that interact with the editor, such as Grammarly, may not function
correctly with collaborative editing. See Confluence Collaborative Editing blocks Grammarly Extension to find
out how to disable Grammarly for just your Confluence site.

Firewall or anti-virus interference

We've had a few reports of firewalls or anti-virus software blocking some requests to the server, resulting in
unexpected behavior in the editor. You may need to add Confluence to your whitelist / trusted URLs if you
experience issues. See Weird Page or Editor Behaviors with Kaspersky Internet Security for more
information.

Too many people in the editor

We don't enforce a maximum number of people who can edit together, but we recommend you keep it to no
more than 12 people editing the same page at the same time. We may enforce a limit to the number people
who can enter the editor in a later release if necessary.

Using read-only mode for site maintenance

If you need to perform maintenance while Confluence is still running, or if you're preparing to migrate to a new
site, you can put your site into read-only mode to limit what users can do. Your users will be able to view pages,
but not create or change them.

Read-only mode is only available for Confluence Data Center. The information on this page does not
apply to Confluence Server.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 394

Turn on read-only mode

You need System Administrator global permissions to do this.

To enable read-only mode:
1. Go to

> General Configuration > Maintenance

2. In the Read-only mode section, choose Edit.
3. Select Read-only mode.
4. Update the wording of the banner message, if you'd like to provide a customised message.
5. Choose Save.
The banner message will display above the header on all pages in your site. It's not possible to disable this
banner while read-only mode is enabled, but you can customise the message, for example to let your users
know when you expect the maintenance to be complete.
It's also possible to turn on the banner before you enable read-only mode. This can be helpful if you want to
warn users that you'll be doing some maintenance later that day.

Impact of read-only mode on your site and database

Read-only mode limits the actions that an end user can perform. Some operations may still write to your
database, but for the most part people will be unable to make any changes.
While read-only mode is on, you won't be able to:
Create, edit, rename, move, delete or otherwise interact with pages.
Create, delete or rename spaces.
Access most space tools, including reorder pages, make changes to the look and feel, or add
integrations.
Here's how a page looks when read-only mode is enabled:

1. Customizable banner - the banner appears on all pages in your site. Admins can customize the
message to let you know when the site will be available again.
2. Options are limited - we hide buttons and menu items that are not available, including create, edit,
move, and delete.
If you happen to be in the editor at the point read-only mode is enabled, you'll be able to keep typing, but any
further changes won't be saved.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 395

1. Read-only warning - although you can keep typing in the editor (including comment fields), changes you
make after read-only mode is enabled won't be saved. It's best to stop editing at this point.
While read-only mode is on, people with system administrator global permissions will be able to perform some
administrative functions, such as:
Install, uninstall, enable, disable system and user installed apps
Manage users, groups, and permissions
Change the site appearance
Export and import spaces
Change logging levels, and other configuration.
Not all admin features will be available, and just like end-users, admins won't be able to create, edit, or delete
any content.
People with Confluence administrator global permissions will also be able to perform some administrative
functions, but they won't be able to make changes to space permissions while read-only mode is enabled.

It's important to note that read-only mode does not prevent data being written to the database, but
will significantly limit the changes that can be made.
If you're doing database maintenance, and need to make sure that absolutely nothing is written to the
database during that time, it may be best to stop Confluence, rather than using read-only mode.

User-installed app compatibility

Not all apps (also known as plugins or add-ons) are compatible with read-only mode, and may continue to allow
users to create or update content while read-only mode is enabled.
To check if your apps are compatible:
Go to

> General Configuration > Maintenance

Check whether any of your user-installed apps are listed as incompatible.
If an app is incompatible, you may want to disable it while you perform maintenance, to avoid users being able to
create content via the app.
If you've developed your own custom apps, see How to make your app compatible with read-only mode to find
out how to test your app and mark it as compatible.

Ways you might use read-only mode

If you're excited by the possibilities of read-only mode, but not sure when you might use it, here are some
examples.

Upgrading Confluence

The way you upgrade Confluence hasn't changed, but read-only mode can help you minimize the impact on your

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 396

organization.
If some downtime is acceptable, the simplest option is to enable read-only mode while you perform the
pre-upgrade steps, such as checking Marketplace app compatibility and backing up your file system and
database (if your database supports online backups). This helps you keep the overall downtime to a bare
minimum, as users can view pages right up to the point you need to stop Confluence.
If you need to provide uninterrupted access, the approach you take may depend on whether Confluence is
running on virtualized or physical hardware.
If virtualized, you might want to take a 'move forwards' approach. You could enable read-only on your
production site, clone your database, install, and home directories, then upgrade the clone. Once the
upgrade is complete and you've validated that everything is working fine, you can direct traffic to the
upgraded site, and tear down the old site.
If you're running Confluence on physical hardware it might be more appropriate to create a temporary
read-only site. You could clone your production database, install, and home directories to create a
temporary read-only site (similar to the process involved in creating a staging site), and direct traffic to
that site while you upgrade your production Confluence site in place.
You should also always test the upgrade on a staging or test instance first. As when creating a staging site, it's
essential to make sure Confluence is always pointing to the correct database and home directory.

Upgrading your infrastructure

Need to move Confluence to another server, or provision more space for your shared home directory? The
approaches outlined above for upgrading Confluence can also be useful when upgrading parts of your
infrastructure.
Note that some data may still be written to the database while read-only mode is enabled, so if you're doing
database maintenance of any sort, directing your users to a secondary site (with a copy of your database) that
has read-only enabled, may be a good approach. You can't, for example, upgrade your production database
while Confluence is still running, even if read-only mode is enabled.
Again, always make sure Confluence is pointing to the correct database!

Consolidating multiple confluence sites

It's quite common for multiple Confluence sites to pop up in big organisations. If you're consolidating or merging
sites, read-only mode can help limit changes to content while you work through the process of exporting spaces
and importing them into your new site.

Administering the Atlassian Companion App

Confluence users can edit an attached file using its On this page:
native desktop application, then automatically save
the file back to Confluence. Download and install the Atlassian
Companion app
The download and re-upload of files is managed by Disable file editing
the Atlassian Companion app, which needs to be Compatibility with virtual desktop
installed on each user's machine (not in the environments
Confluence installation directory) to enable file Recover edited files
editing.

Download and install the Atlassian Companion app

To edit files, users need to install the Atlassian Companion app and have it running in the background. The
first time a user selects 'Edit with' in file preview, we prompt them to download and install the app. See Edit
Files for details.
Screenshot: the download prompt shown in file preview

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 397

If your users aren't able to install applications themselves, you may want to distribute the app to them or
deploy using the Microsoft Installer.

Download the latest version

Download the Atlassian Companion app for Mac or Windows.

Proxy and SSL considerations

When a user tries to edit an attached file, Confluence makes a DNS request to https://atlassian-doma
in-for-localhost-connections-only.com, which resolves to localhost (https://127.0.0.1). This
allows Confluence to establish a secure WebSocket connection to the Companion app.
If your outgoing internet requests are filtered through a proxy server, you may need to exclude https://at
lassian-domain-for-localhost-connections-only.com from the browser's forward proxies,
otherwise the proxy server won't be able to route the request back to the local machine.

Install the Companion app via Microsoft Installer (MSI)

We also provide a Microsoft Installer package (.msi file) to deploy the Atlassian Companion app for Windows
across multiple users or machines. By default, the Companion app installs to the Program Files directory, but
you can customize this.
Download the Atlassian Companion MSI (69 MB)
If you deploy using the Microsoft Installer, the Companion app won’t automatically get the latest updates,
including security and bug fixes, so some maintenance is required.
We may update the Companion app before or after we release a new version of Confluence. Check the Atlas
sian Companion app release notes to make sure you're on the latest version.

Disable file editing

System Administrators can remove the edit files option from their Confluence site.
To disable the edit files option when previewing a file:
1. Go to

> Manage apps

2. From the drop-down menu, select System.
3. Click Confluence Previews from the displayed list.
4. Click the enabled modules link.
5. Hover on the Edit With plugin for the Media Viewer (companion-plugin) module, and click Disable
.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 398

To disable the edit option from the Attachments page, Attachments macro and View File macros:
1. Go to

> Manage apps

2. From the drop-down menu, select System.
3. Click Confluence Previews from the displayed list.
4. Click the enabled modules link.
5. Hover on the Embedded 'Edit With' button (embedded-edit) module and click Disable.

Compatibility with virtual desktop environments

The Atlassian Companion app only works in some virtual desktop environments. If a user's environment isn't
compatible with the Companion app, they won't be able to edit files in Confluence.
This table outlines which environments are compatible with the Companion app:

Environment Compatibility
with Companion
app

Virtual desktop infrastructure (VDI) Compatible

In this set up, each user gets their own VM (virtual machine), with a centralized
service managing deployments.

Session-based virtual desktops Not compatible

Also referred to as Remote Desktop Service (RDS) or Remote Desktop Session
Host (RDSH). In this set up, each user shares the same operating system (server).

Virtual app streaming Not compatible

Also referred to as Remote app publishing. This is where a single app runs on a
remote server, but appears on the user's computer as if it were a local app.

Recover edited files

When a user edits a file, that file is also downloaded and saved to the Atlassian Companion folder on their
computer. Files are cleared every time the Companion app restarts.
Follow our guide to accessing Confluence files edited with the Atlassian Companion app.

Confluence installation and upgrade guide

About the installation and upgrade guide
This guide covers how to install and upgrade Confluence.
Information on the features and changes in specific Confluence releases can be found in the Confluence
Release Notes.
For information on using and administering Confluence refer to the Confluence Documentation.

Enterprise releases

An Atlassian Enterprise release is a feature release that gets backported security updates and critical bug
fixes during its entire two-year support window. If you can only upgrade once a year, consider upgrading to
an Enterprise release. Learn more
System Requirements
Downloads
Server Hardware Requirements Guide
Running Confluence in a Virtualized
Environment Download the Confluence documentation
Confluence Installation Guide in PDF format.
Installing Confluence
Installing Confluence Data Center

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 399

Installing Java for Confluence Other resources

Creating a Dedicated User Account on
the Operating System to Run Confluence Release Notes
Confluence
Confluence Setup Guide Confluence administrator's guide
Configuring Jira Integration in the
Confluence Knowledge Base
Setup Wizard
Upgrading Confluence Atlassian Answers
Upgrading Beyond Current Licensed
Period
Confluence Post-Upgrade Checks
Migration from Wiki Markup to
XHTML-Based Storage Format
Migration of Templates from Wiki
Markup to XHTML-Based Storage
Format
Upgrading Confluence Manually
Create a staging environment for
upgrading Confluence
Supported Platforms
End of Support Announcements for
Confluence
Supported Platforms FAQ
Migrating Confluence Between Servers
From Confluence Evaluation through to
Production Installation
Migrate from Confluence Server to
Cloud
Migrate from Confluence Cloud to
Server

System Requirements
Confluence can run on a wide range of operating On this page:
systems and databases, on physical or virtualized Software requirements
servers. Operating systems
Application server
See Supported Platforms for the full list of platforms Databases
that we support in this version of Confluence or Sup Java
ported Platforms FAQ for details on our support Antivirus considerations
handling procedures. Hardware requirements
Hosted solutions – Confluence
Cloud
Software requirements

Operating systems

Atlassian supports the operating systems listed on

the Supported Platforms page.
If you would like to run Confluence on virtualized
hardware, please read our Running Confluence in a
Virtualized Environment document first.

Application server

We only support running Confluence on the version of Apache Tomcat that is bundled with the Confluence
distribution.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 400

Databases

You'll need an external database to run Confluence. See the Supported Platforms page for a list of all the
databases we support.
When evaluating Confluence, you can use the embedded H2 database included in the Confluence
installation, but you will need to migrate to a supported external database once you're ready to roll
Confluence out to your team.

Java

The Java Runtime Environment (JRE) is packed up and ready to go when you install Confluence using the
Windows or Linux installer. You don't need to install Java yourself.
If you choose to install Confluence from an archive file, you'll need a supported JRE or JDK, and your
JAVA_HOME variable set correctly. See Installing Java for Confluence for more information.

Antivirus considerations

Antivirus software on the operating system running Confluence can greatly decrease the performance of
Confluence. Antivirus software that intercepts access to the hard disk is particularly detrimental and may
even cause errors in Confluence. This is particularly important if you are running Confluence on Windows. No
matter how fast your hardware is, antivirus software will almost always have a negative impact on
Confluence's performance.
You should configure your antivirus software to ignore the following directories:
Confluence home directory
Confluence's index directory
All database-related directories

Hardware requirements

Please be aware that while some of our customers run Confluence on SPARC-based hardware, Atlassian
only officially supports Confluence running on x86 hardware and 64-bit derivatives of x86 hardware.
See Server Hardware Requirements Guide for more information.
You may also like to check out our tips on reducing out of memory errors, in particular the section on Perman
ent Generation Size.

Hosted solutions – Confluence Cloud

If you do not have the resources to set up and maintain a Confluence installation locally, consider trying
Confluence Cloud. Atlassian can run and maintain your installation of Confluence, handling all the testing,
monitoring and upgrading processes for you.

Server Hardware Requirements Guide

Server administrators can use this guide in combination with the free
Confluence trial period to evaluate their server hardware requirements.
Because server load is difficult to predict, live testing is the best way to
determine what hardware a Confluence instance will require in production.
Peak visitors are the maximum number of browsers simultaneously making
requests to access or update pages in Confluence. Visitors are counted
from their first page request until the connection is closed and if public
access is enabled, this includes internet visitors as well as logged in users.
Storage requirements will vary depending on how many pages and
attachments you wish to store inside Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 401

Enterprise-scale Confluence sites On this page:

Minimum
These recommendations are designed for small or medium sized
hardware
Confluence sites. For guidance on large or extra large sites, read
requireme
our enterprise-scale infrastructure recommendations.
nts
We've also created load profiles to help you determine the size of Example
your site. hardware
specificatio
ns
Server
load and
Minimum hardware requirements scalability
Maximum
The values below refer to the minimum available hardware required to run reported
Confluence only; for example, the minimum heap size to allocate to usages
Confluence is 1 GB and 1 GB for Synchrony (which is required for Hard disk
collaborative editing). You'll need additional physical hardware, of at least requireme
the minimum amount required by your Operating System and any other nts
applications that run on the server. Profession
al
On small instances, server load is primarily driven by peak visitors, so assistance
minimum system requirements are difficult to judge. We provide these Example
figures as a guide to the absolute minimum required to run Confluence, and site
your configuration will likely require better hardware.
Related pages:
Here is our minimum hardware recommendation:
Confluenc
CPU: Quad core 2GHz+ CPU e
RAM: 6GB Installation
Minimum database space: 10GB Guide
Managing
Application
Server
Memory
Settings
Running
Confluenc
e in a
Virtualized
Environme
nt

Note: Please be aware that while some of our customers run Confluence on SPARC-based hardware, we
only officially support Confluence running on x86 hardware and 64-bit derivatives of x86 hardware.
Confluence typically will not perform well in a tightly constrained, shared environment - examples include an
AWS micro.t1 instance. Please be careful to ensure that your choice of hosting platform is capable of
supplying sustained processing and memory capacity for the server, particularly the processing-intense
startup process.

Example hardware specifications

These are example hardware specifications for non-clustered Confluence instances. It is not recorded
whether the amount of RAM refers to either the total server memory or memory allocated to the JVM, while
blank settings indicate that the information was not provided.

Accounts Spaces Pages CPUs CPU RAM Notes

(GHz) (MB)

150 30 1,000 1 2.6 1,024

350 100 15,000 2 2.8 1,536

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 402

5,000 500 4 3 2,048

10,000 350 16,000 2 3.8 2,048

10,000 60 3,500 2 3.6 4,096

21,000 950 2 3.6 4,096

85,000 100 12,500 4 2.6 4,096 3 machines total: application server, database
server, Apache HTTPD + LDAP tunnel server.

Server load and scalability

When planning server hardware requirements for your Confluence deployment, you will need to estimate the
server scalability based on peak visitors, the editor to viewer ratio and total content.
The editor to viewer ratio is how many visitors are performing updates versus those only viewing
content
Total content is best estimated by a count of total spaces
Confluence scales best with a steady flow of visitors rather than defined peak visitor times, few editors and
few spaces. Users should also take into account:
Total pages is not a major consideration for performance. For example, instances hosting 80K of
pages can consume under 512MB of memory
Always use an external database, and check out the performance tuning guides.

Maximum reported usages

These values are largest customer instances reported to Atlassian or used for performance testing.
Clustering, database tuning and other performance tuning is recommended for instances exceeding these
values.

Most Spaces 1700

Most Internal Users 15K

Most LDAP Users 100K

Most Pages 80K

Hard disk requirements

All page content is stored in the database, while attachments are stored in the file system. The more
attachments you have, the more disk space you will require.

Private and public comparison

Private instances manage their users either internally or through a user repository such as LDAP, while
online instances have public signup enabled and must handle the additional load of anonymous internet
visitors. Please keep in mind that these are examples only, not recommendations:

Use Case Spaces User Editors Editor Pages Page Attachments Comments
Accounts To Revisions
Viewer
Ratio

Online 140 11,500 1,000 9% 8,800 65,000 7,300 11,500

Documentation

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 403

Private Intranet 130 180 140 78% 8,000 84,000 3,800 500

Company-Wide 100 85,000 1,000+ 1%+ 12,500 120,000 15,000

Collaboration

Professional assistance

For large instances, it may be worthwhile contacting an Atlassian Solution Partner for expertise on hardware
sizing, testing and performance tuning.

Example site

Here is a breakdown of the disk usage and memory requirements a large documentation site as at April
2013:

Database size 2827 MB

Home directory size 116 GB

Average memory in use 1.9 GB

Size of selected database tables

Data Relevant Table Rows Size

Attachment metadata attachments 193903 60

MB

Content and user properties os_propertyentry (?) 639737 255

MB

Content bodies (incl. all versions of blogs, pages and bodycontent 517520 1354
comments) MB

Content metadata (incl. title, author) content 623155 459

MB

Labels label (5982, 1264 kB), 140133 47.2

MB
content_label (134151,
46 MB)

Users users 38766 6200

kB

Note: not all database tables or indexes are shown, and average row size may vary between instances.

Size of selected home directory components

Data Files Size

Attachments (incl. all versions) 207659 105 GB

Did-you-mean search index 10 14 MB

Office Connector cache 3506 456 MB

Plugin files 1851 669 MB

Search index 448 3.9 GB

Temporary files 14232 5 GB

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 404

Thumbnails 86516 1.7 GB

Usage index (now disabled) 239 2.6 GB

Note: not all files are shown, and average file size may vary between instances.

Running Confluence in a Virtualized Environment

This page provides pointers for things to look at On this page:
when running Confluence on virtualized hardware. Summary
Recommendations
Further help
Summary
Related pages:
Running Confluence in a virtual machine (VM)
requires specialized skills to set up and manage the Server Hardware Requirements
virtualized environment. In particular, the Guide
performance of Confluence can be affected by the Confluence Installation Guide
activity of other VMs running on the same Confluence Data Center
infrastructure, as well as how you configure the AWS Quick Start (Data Center
Confluence VM itself. only)

Atlassian supports running Confluence and

Confluence Data Center in a virtualized
environment, but we cannot offer support for
problems which are related to the environment itself.

Recommendations

The following recommendations come from our experience in running and testing Confluence in virtualized
environments like VMWare and KVM, and our experience in working with customers running on these
platforms.
Know your platform. Consult the documentation for your operating system and your chosen
virtualization technology, for details on setting up a reliable VM (virtual machine) image.
Allocate enough memory. As a Java web application, Confluence requires a relatively large memory
allocation, compared to some other web technologies. Ensure that your VM images have enough
physical memory allocated to run Confluence without swapping.
Handle high I/O. Under normal usage, Confluence requires a significant number of input/output (I/O)
operations to the database and home directory for each web request. Ensure that you use the correct
drivers and consider how you make storage available to your VMs to optimize this access.
Handle peak CPU and memory usage. For certain operations (including PDF export, Office
document processing, and displaying large pages) Confluence requires a significant amount of CPU
and memory. Ensure that your virtualization infrastructure has the flexibility and capacity to deal with
peak load, not just idle load.
Synchronize time correctly. Some customers have had problems with time synchronization between
the VM and the host system. This causes problems in Confluence due to irregularities in the execution
of scheduled tasks. We strongly recommend checking your VM time sync if you have issues with
scheduled tasks in a virtualized environment.

Further help

For further assistance in setting up a virtualized environment for running Confluence, you may want to
consult an Atlassian Solution Partner. Several experts have experience with installation and performance
tuning, and can help you with your Confluence configuration.

Confluence Installation Guide

Before you start

Before installing Confluence, please check that you meet the minimum system requirements and Supported
Platforms.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 405

If you're planning to run Confluence in a virtualized environment see Running Confluence in a Virtualized
Environment.

Choose your installation method

There are a number of ways to install Confluence. Choose the method that is best for your environment.

Install method Is this right for you?

Install a Confluence trial This is the fastest way to get a Confluence site up and running.
If you're evaluating Confluence, use this option or try Confluenc
Windows, Linux or OS X e Cloud free.
You don't need an external database to install a Confluence
trial.

Install Confluence using an installer This option uses an installer, and is the most straightforward
way to get your production site up and running on a Windows
Windows or Linux server.
Linux

Install Confluence from a zip or This option requires you to manually install files and configure
archive file some system properties. It gives you the most control over the
install process. Use this option if there isn't an installer for your
Windows operating system.
Linux

Run Confluence in a Docker container This option gets Confluence Server up and running in no time
using a pre-configured Docker image. Head to https://docs.doc
Docker ker.com/ to find out more about Docker.
Atlassian supports running Confluence in a Docker container,
but we cannot offer support for problems which are related to
the environment itself.

Install Confluence in a cluster Confluence Data Center is a clustered solution for large
enterprises. It can be hosted on your own infrastructure or
Windows and Linux deployed to AWS or Azure for a private cloud solution.
AWS Quick Start
Azure Read the Confluence Data Center Technical Overview to find
out if Confluence Data Center is right for your organization.

Note: we do not support installing Confluence as a production system on OS X. An OS X download is available

for the purposes of evaluating Confluence only. There are no limitations to using Confluence on a mac with any
one of the supported browsers.
The EAR/WAR distribution is no longer available, you'll need to install Confluence from a zip or archive file if you
previously deployed Confluence into an existing application server.

Installing Confluence
There are a number of ways to install Confluence. Choose the method that is best for your environment.

Install method Is this right for you?

Install a Confluence trial This is the fastest way to get a Confluence site up and running.
If you're evaluating Confluence, use this option or try Confluenc
Windows, Linux or OS X e Cloud free.
You don't need an external database to install a Confluence
trial.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 406

Install Confluence using an installer This option uses an installer, and is the most straightforward
way to get your production site up and running on a Windows
Windows or Linux server.
Linux

Install Confluence from a zip or This option requires you to manually install files and configure
archive file some system properties. It gives you the most control over the
install process. Use this option if there isn't an installer for your
Windows operating system.
Linux

Run Confluence in a Docker container This option gets Confluence Server up and running in no time
using a pre-configured Docker image. Head to https://docs.doc
Docker ker.com/ to find out more about Docker.
Atlassian supports running Confluence in a Docker container,
but we cannot offer support for problems which are related to
the environment itself.

Install Confluence in a cluster Confluence Data Center is a clustered solution for large
enterprises. It can be hosted on your own infrastructure or
Windows and Linux deployed to AWS or Azure for a private cloud solution.
AWS Quick Start
Azure Read the Confluence Data Center Technical Overview to find
out if Confluence Data Center is right for your organization.

Installing a Confluence trial

Want to get up and running with Confluence ASAP? On this page:
This page will guide you through three simple steps
to install and set up an evaluation Confluence site. Before you begin
1. Download the installer
2. Install Confluence
3. Set up Confluence

If you're ready to set up a production Confluence site or you want more control, check out our full installation
guides.

Before you begin

Our installers come with all the bits and pieces you need to run the application, but there's a few things you'll
need to get up and running:
A computer or laptop with a supported operating system - you'll be installing Confluence so you'll need
admin rights.

Supported operating systems...

You can install Confluence on a Windows or Linux operating system.
Apple Mac isn't supported for production sites, but if you're comfortable setting up applications on
your Mac from scratch, you can download the tar.gz file and follow the instructions for Installing
Confluence on Linux from Archive File as the process is similar.
A supported web browser - you'll need this to access Confluence, we support the latest versions of
Chrome and Mozilla Firefox, Internet Explorer 11, and Microsoft Edge.
A valid email address - you'll need this to generate your evaluation license and create an account.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 407

Ready to get going? Let's start with grabbing the installer.

1. Download the installer

Head to www.atlassian.com/software/confluence/download and download the installer for your operating

system.

2. Install Confluence

The installer allows you to choose Express or Custom installations.

The Custom installation allows you to pick some specific options for Confluence, but for this guide we'll use
the Express installation.

For Windows
1. Run the installer - we recommend running with a Windows administrator account.
If prompted, make sure you allow the installer to make changes to your computer. This will allow
you to install Confluence as a service.
2. Choose Express Install, then click Next.
3. Once installation is complete, it will ask you if you want to open Confluence in your browser. Make
sure this option is selected then click Done.
4. Confluence will open in your default browser, and you're ready to start the set up wizard.
For Linux
1. Change to the directory where you downloaded Confluence then execute this command to make it
executable:

$ chmod a+x atlassian-confluence-X.X.X-x64.bin

Where X.X.X is is the Confluence version you downloaded.

2. Run the installer - we recommend using sudo to run the installer as this will create a dedicated
account to run Confluence and allow you to run Confluence as a service.

$ sudo ./atlassian-confluence-X.X.X-x64.bin

3. When prompted, choose Express Install (option 1).

4. Once installation is complete head to http://localhost:8090/ in your browser to begin the setup
process.

3. Set up Confluence

The set up wizard is the last step in getting Confluence up and running. You'll need your email address to
generate your evaluation license.
1. Select Trial, and click Next.
This will allow Confluence to set up everything it needs to run, including an H2 database.
2. Select Get an evaluation license then follow the prompts to generate your license.
3. If you want to try some Confluence apps to give you more functionality, select the ones you want and
click Next.
It will take a few minutes to get everything connected and operational.
4. Select Manage users with Confluence, and click Next.
5. Enter and confirm the details you want to use for your administrator account, and click Done.

That's it! You're ready to team up with some colleagues and start using Confluence!

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 408

Installing Confluence on Windows

In this guide we'll run you through installing On this page:
Confluence in a production environment, with an Before you begin
external database, using the Windows installer. Install Confluence
1. Download Confluence
This is the most straightforward way to get your
2. Run the installer
production site up and running on a Windows server.
Set up Confluence
3. Choose installation type
4. Enter your license
5. Connect to your
database
6. Populate your new site
with content
7. Choose where to
manage users
8. Create your administrator
account
Other ways to install Confluence: 9. Start using Confluence
Troubleshooting
Evaluation - get your free trial up and running
in no time.
Zip – install Confluence manually from a zip
file.
Linux – install Confluence on a Linux
operating system

Before you begin

Before you install Confluence, there's a few questions you need to answer.

Are you Tell me more...

using a Check the Supported Platforms page for the version of Confluence you are installing.
supported This will give you info on supported operating systems, databases and browsers.
operating
system? Good to know:
We don't support installing Confluence on OSX.
The Confluence installer includes Java (JRE) and Tomcat, so you don't need to
install these separately.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 409

Do you Tell me more...

want to run Running Confluence as a service in Windows means that Confluence will automatically
Confluence start up when Windows is started.
as a
Windows If you choose to run Confluence as a service:
Service? You must run the installer as administrator to be able to install Confluence as a
service.
The Confluence service will be run as the Windows 'SYSTEM' user account. To
change this user account see Changing the Windows user that the Confluence
service uses .
We strongly recommend creating a dedicated user account (e.g. with username
'confluence') for running Confluence. See Creating a Dedicated User Account on
the Operating System to Run Confluence to find out what directories this user will
need to be able to read and write to.
If you choose not to run Confluence as a service:
You will start and stop Confluence using the Windows Start menu, or by running a
file in your Confluence installation directory.
Confluence will be run as the Windows user account that was used to install
Confluence, or you can choose to run as a dedicated user.
Confluence will need to be restarted manually if your server is restarted.

Are ports Tell me more...

8090 and Confluence runs on port 8090 by default. If this port is already in use, the installer will
8091 prompt you to choose a different port.
available?
Synchrony, which is required for collaborative editing, runs on port 8091 by default. If
this port is already in use, you will need to change the port that Synchrony runs on after
your Confluence installation is complete. See Administering Collaborative Editing to
find out how to change the port Synchrony runs on. You won't be able to edit pages
until Synchrony has an available port.
See Ports used by Atlassian Applications for a summary of all the ports used.

Is your Tell me more...

database To run Confluence in production you'll need an external database. Check the Supporte
set up and d Platforms page for the version you're installing for the list of databases we currently
ready to support. If you don't already have a database, PostgreSQL is free and easy to set up.
use?
Good to know:
Set up your database before you begin. Step-by-step guides are available for Postg
reSQL, Oracle, MySQL, and SQL Server.
If you're using Oracle or MySQL you'll need to download the driver for your
database.
To use a datasource see Configuring a datasource connection as there are some
steps you need to perform before running the setup wizard.
The embedded H2 database can be used for evaluating Confluence, but you'll
need to migrate to another database before running in production. You may find it
easier to use external database from the start.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 410

Do you Tell me more...

have a You'll need a valid Confluence Server license to use Confluence.
Confluence
license? Good to know:
If you have not yet purchased a Confluence license you'll be able to create an
evaluation license during setup.
If you already have a license key you'll be prompted to log in to my.atlassian.com to
retrieve it, or you can enter the key manually during setup.
If you're migrating from Confluence Cloud, you'll need a new license.

Install Confluence

1. Download Confluence

Download the installer for your operating system - https://www.atlassian.com/software/confluence/download

2. Run the installer

1. Run the installer. We recommend using a Windows administrator account.

2. Follow the prompts to install Confluence. You'll be asked for the following info:

a. Destination directory – this is where Confluence will be installed.

b. H ome directory – this is where Confluence data like logs, search indexes and files will be
stored.
c. TCP ports – these are the HTTP connector port and control port Confluence will run on. Stick
with the default unless you're running another application on the same port.
d. Install as service – this option is only available if you ran the installer as administrator.
3. Confluence will start up in your browser once installation is complete.

Set up Confluence

3. Choose installation type

1. Choose Production installation.

2. Choose any apps you'd also like to install.

4. Enter your license

Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.

5. Connect to your database

1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of
this page for details and connection options.

2. Choose My own database then select your particular database from the Database type dropdown
menu.

3. For MySQL and Oracle, follow the prompts to download and install the required driver.

4. Enter your database details. Use test connection to check your database is set up correctly.
Advanced setup options...
If you want to specify particular parameters, you can choose to connect By connection string.
You'll be prompted to enter:
Database URL – the JDBC URL for your database. If you're not sure, check the
documentation for your database.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 411

Username and Password – A valid username and password that Confluence can use to
access your database.

6. Populate your new site with content

Choose whether you'd like Confluence to populate your site with content:

Demonstration space...
This option will create a space that you and your users can use to get to know Confluence. You can
delete this space at any time.
Import data from an existing site...
Use this option if you have a full site export of an existing Confluence site. This is useful when you’re
migrating to another database or setting up a test site.
Good to know:
You can only import sites from the same or earlier Confluence version.
The system administrator account and all other user data and content will be imported from your
previous installation.
In the setup wizard:
Upload a backup file – use this option if your site export file is small (25mb or less).
Restore a backup file from the file system – use this option if your backup file is large. Drop the
file into your <confluence-home>/restore directory then follow the prompts to restore the
backup.
Build Index – we’ll need to build an index before your imported content is searchable. This can
take a long time for large sites, so deselect this option if you would rather build the index
later. Your content won't be searchable until the index is built.

7. Choose where to manage users

Choose to manage Confluence's users and groups inside Confluence or in a Jira application, such as Jira
Software or Jira Service Desk:

Manage users and groups in Confluence...

Choose this option if you're happy to manage users in Confluence, or don't have a Jira application
installed.
Good to know:
If you do plan to manage users in a Jira application, but have not yet installed it, we recommend
installing Jira first, and then returning to the Confluence setup.
You can add external user management (for example LDAP, Crowd or Jira) later if you choose.
Connect to Jira...
Choose this option if you have a Jira application installed and want to manage users across both
applications.
Good to know:
This is a quick way of setting up your Jira integration with the most common options.
It will configure a Jira user directory for Confluence, and set up application links between Jira and
Confluence for easy sharing of data.
You'll be able to specify exactly which groups in your Jira app should also be allowed to log in to
Confluence. Your license tiers do not need to be the same for each application.
You'll need either Jira 4.3 or later, Jira Core 7.0 or later, Jira Software 7.0 or later, or Jira Service
Desk 3.0 or later.
In the setup wizard:
Jira Base URL – the address of your Jira server, such as http://www.example.com:8080/ji
ra/ or http://jira.example.com/
Jira Administrator Login – this is the username and password of a user account that has the Jira
System Administrator global permission in your Jira application. Confluence will also use this

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 412

username and password to create a local administrator account which will let you access
Confluence if Jira is unavailable. Note that this single account is stored in Confluence's internal
user directory, so if you change the password in Jira, it will not automatically update in Confluence.
Confluence Base URL – this is the URL Jira will use to access your Confluence server. The URL
you give here overrides the base URL specified in Confluence, for the purposes of connecting to
the Jira application.
User Groups – these are the Jira groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in
your Confluence license. The default user group name differs depending on your Jira version:
Jira 6.4 and earlier: jira-users.
Jira Software 7.x and later: jira-software-users
Jira Core 7.x and later: jira-core-users
Jira Service Desk 3.x and later: jira-servicedesk-users
Admin Groups – provide one or more Jira groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.

8. Create your administrator account

Enter details for the administrator account.

Skip this step if you chose to manage users in a Jira application or you imported data from an existing site.

9. Start using Confluence

That's it! Your Confluence site is accessible from a URL like this:
http://<computer_name_or_IP_address>:<port>
If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go
any further.
Here's a few things that will help you get your team up and running:
Set the server base URL – this is the URL people will use to access Confluence.
Set up a mail server – this allows Confluence to send people notification about content.
Add and invite users – get your team on board!
Start and stop Confluence – find out how to start and stop Confluence.

Troubleshooting
Running into problems installing Confluence?
Some anti-virus or other Internet security tools may interfere with the Confluence installation
process and prevent the process from completing successfully. If you experience or anticipate
experiencing such an issue with your anti-virus/Internet security tool, disable this tool first before
proceeding with the Confluence installation.
Can't start Confluence? See Confluence does not start due to Spring Application context has not
been set .

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 413

Collaborative editing errors? See Troubleshooting Collaborative Editing.

Head to Installation Troubleshooting in our Knowledge Base for more help.

Installing Confluence on Windows from Zip File

In this guide we'll run you through installing On this page:
Confluence in a production environment, with an
external database, manually using a zip file. Before you begin
Install Confluence
This method gives you the most control of the 1. Download Confluence
installation process. 2. Create the installation
directory
3. Create the home
directory
4. Check the ports
5. Start Confluence
Set up Confluence
6. Choose installation type
7. Enter your license
8. Connect to your
database
Other ways to install Confluence: 9. Populate your new site
with content
Evaluation - get your free trial up and running 10. Choose where to
in no time. manage users
Installer – install Confluence using the 11. Create your
Windows installer. administrator account
Linux – install Confluence on a Linux 12. Start using Confluence
operating system. Troubleshooting

Before you begin

Before you install Confluence, there's a few questions you need to answer.

Are you Tell me more about this...

using a Check the Supported Platforms page for the version of Confluence you are installing.
supported This will give you info on supported operating systems, databases and browsers.
operating
system and Good to know:
Java We don't support installing Confluence on OS X or mac OS for production
version? environments.
You'll need to install either AdoptOpenJDK or Oracle JDK. We don't support other
OpenJDK binaries.
You can use either the JDK (Java Development Kit) or JRE (Java Runtime
Environment).
We only support the version of Apache Tomcat that is bundled with Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 414

Do you want Tell me more about this...

to run Running Confluence as a service in Windows means that Confluence will
Confluence automatically start up when Windows is started.
as a
Windows You should use the Windows installer if you want to run Confluence as a Service.
Service? If you choose not to run Confluence as a service:
You will start and stop Confluence by running the start-confluence.bat file
in your Confluence installation directory.
Confluence will be run as the Windows user account that was used to install
Confluence, or you can choose to run as a dedicated user (this user must have
full read and write access to the installation directory and home directory).
Confluence will need to be restarted manually if your server is restarted.

Are ports Tell me more...

8090 and Confluence runs on port 8090 by default. If this port is already in use, the installer will
8091 prompt you to choose a different port.
available?
Synchrony, which is required for collaborative editing, runs on port 8091 by default. If
this port is already in use, you will need to change the port that Synchrony runs on
after your Confluence installation is complete. See Administering Collaborative
Editing to find out how to change the port Synchrony runs on. You won't be able to
edit pages until Synchrony has an available port.
See Ports used by Atlassian Applications for a summary of all the ports used.

What Tell me more about this...

database do To run Confluence in production you'll need an external database. Check the Support
you plan to ed Platforms page for the version you're installing for the list of databases we
use? currently support. If you don't already have a database, PostgreSQL is free and easy
to set up.
Good to know:
Set up your database before you begin. Step-by-step guides are available for Pos
tgreSQL, Oracle, MySQL, and SQL Server.
If you're using Oracle or MySQL you'll need to download the driver for your
database.
To use a datasource see Configuring a datasource connection as there are some
steps you need to perform before running the setup wizard.
The embedded H2 database can be used for evaluating Confluence, but you'll
need to migrate to another database before running in production. You may find it
easier to use external database from the start.

Do you have Tell me more about this...

a You'll need a valid Confluence Server license to use Confluence.
Confluence
license? Good to know:
If you have not yet purchased a Confluence license you'll be able to create an
evaluation license during setup.
If you already have a license key you'll be prompted to log in to my.atlassian.com
to retrieve it, or you can enter the key manually during setup.
If you're migrating from Confluence Cloud, you'll need a new license.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 415

Is your Tell me more about this...

JRE_HOME Before you install Confluence, check that you're running a supported Java version
variable set and that the JRE_HOME (or JAVA_HOME) environment variable is set correctly.
correctly?
To check the JRE_HOME variable:
Open a command prompt and type echo %JRE_HOME% and hit Enter.

If you see a path to your Java installation directory, the JRE_Home environment
variable has been set correctly.
If nothing is displayed, or only %JRE_HOME% is returned, you'll need to set the JRE
_HOME environment variable manually. See Setting the JAVA_HOME Variable in
Windows for a step by step guide.

Install Confluence

1. Download Confluence

Download the zip file for your operating system – https://www.atlassian.com/software/confluence/download.

2. Create the installation directory

1. Create your installation directory (with full control permission) – this is where Confluence will be
installed. Avoid using spaces or special characters in the path. We'll refer to this directory as your <in
stallation-directory>.
2. Extract the Confluence zip file to your <installation-directory>. We recommend using 7zip or
Winzip.

3. Create the home directory

1. Create your home directory (with full control permission) – this is where Confluence data like logs,
search indexes and files will be stored. This should be seperate to your installation directory. We'll
refer to this directory as your <home-directory>.
2. Edit <installation-directory>\confluence\WEB-INF\classes\confluence-init.pro
perties.
3. At the bottom of the file, enter the path to your <home directory>.
Show me how to do this...
You can edit the confluence-init.properties file in Notepad or any other text editor.
a. Scroll to the bottom of the text and find this line:

# confluence.home=c:/confluence/data

b. Remove the '#' and the space at the beginning of this line (so Confluence doesn't regard the
line as a comment)

confluence.home=c:/data/confluence-home

c. If you decide to use a different directory as the home directory you should:
Avoid spaces in the directory path or file name.
Use forward slashes '/' to define the path in this file.

4. Check the ports

By default Confluence listens on port 8090. If you have another application running on your server that uses
the same ports, you'll need to tell Confluence to use a different port.
Show me how to do this...
To change the ports:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 416

1. Edit <installation-directory>\conf\server.xml
2. Change the Server port (8000) and the Connector port (8090) to free ports on your server.

In the example below we've changed the Server port to 5000 and the Connector port to 5050.

Server port="5000" shutdown="SHUTDOWN" debug="0">

<Service name="Tomcat-Standalone">
<Connector port="5050" connectionTimeout="20000"
redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"
/>

5. Start Confluence

1. Run <installation-directory>/bin/start-confluence.bat to start the install process.

A command prompt will open. Closing this window will stop Confluence.

2. Go to http://localhost:8090/ to launch Confluence in your browser (change the port if you've

updated the Connector port).

Trouble starting Confluence?

If the command prompt window closes immediately, your JAVA_HOME variable may not be set
correctly. See Setting the JAVA_HOME Variable in Windows.
If you see an error, see Confluence does not start due to Spring Application context has not been
set for troubleshooting options.

Set up Confluence

6. Choose installation type

1. Choose Production installation.

2. Choose any apps you'd also like to install.

7. Enter your license

Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.

8. Connect to your database

1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of
this page for details and connection options.

2. Choose My own database then select your particular database from the Database type dropdown
menu.

3. For MySQL and Oracle, follow the prompts to download and install the required driver.

4. Enter your database details. Use test connection to check your database is set up correctly.
Advanced setup options...
If you want to specify particular parameters, you can choose to connect By connection string.
You'll be prompted to enter:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 417

Database URL – the JDBC URL for your database. If you're not sure, check the
documentation for your database.
Username and Password – A valid username and password that Confluence can use to
access your database.

9. Populate your new site with content

Choose whether you'd like Confluence to populate your site with content:

Demonstration space...
This option will create a space that you and your users can use to get to know Confluence. You can
delete this space at any time.
Import data from an existing site...
Use this option if you have a full site export of an existing Confluence site. This is useful when you’re
migrating to another database or setting up a test site.
Good to know:
You can only import sites from the same or earlier Confluence version.
The system administrator account and all other user data and content will be imported from your
previous installation.
In the setup wizard:
Upload a backup file – use this option if your site export file is small (25mb or less).
Restore a backup file from the file system – use this option if your backup file is large. Drop the
file into your <confluence-home>/restore directory then follow the prompts to restore the
backup.
Build Index – we’ll need to build an index before your imported content is searchable. This can
take a long time for large sites, so deselect this option if you would rather build the index
later. Your content won't be searchable until the index is built.

10. Choose where to manage users

Choose to manage Confluence's users and groups inside Confluence or in a Jira application, such as Jira
Software or Jira Service Desk:

Manage users and groups in Confluence...

Choose this option if you're happy to manage users in Confluence, or don't have a Jira application
installed.
Good to know:
If you do plan to manage users in a Jira application, but have not yet installed it, we recommend
installing Jira first, and then returning to the Confluence setup.
You can add external user management (for example LDAP, Crowd or Jira) later if you choose.
Connect to Jira...
Choose this option if you have a Jira application installed and want to manage users across both
applications.
Good to know:
This is a quick way of setting up your Jira integration with the most common options.
It will configure a Jira user directory for Confluence, and set up application links between Jira and
Confluence for easy sharing of data.
You'll be able to specify exactly which groups in your Jira app should also be allowed to log in to
Confluence. Your license tiers do not need to be the same for each application.
You'll need either Jira 4.3 or later, Jira Core 7.0 or later, Jira Software 7.0 or later, or Jira Service
Desk 3.0 or later.
In the setup wizard:
Jira Base URL – the address of your Jira server, such as http://www.example.com:8080/ji
ra/ or http://jira.example.com/

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 418

Jira Administrator Login – this is the username and password of a user account that has the Jira
System Administrator global permission in your Jira application. Confluence will also use this
username and password to create a local administrator account which will let you access
Confluence if Jira is unavailable. Note that this single account is stored in Confluence's internal
user directory, so if you change the password in Jira, it will not automatically update in Confluence.
Confluence Base URL – this is the URL Jira will use to access your Confluence server. The URL
you give here overrides the base URL specified in Confluence, for the purposes of connecting to
the Jira application.
User Groups – these are the Jira groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in
your Confluence license. The default user group name differs depending on your Jira version:
Jira 6.4 and earlier: jira-users.
Jira Software 7.x and later: jira-software-users
Jira Core 7.x and later: jira-core-users
Jira Service Desk 3.x and later: jira-servicedesk-users
Admin Groups – provide one or more Jira groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.

11. Create your administrator account

Enter details for the administrator account.

Skip this step if you chose to manage users in a Jira application or you imported data from an existing site.

12. Start using Confluence

That's it! Your Confluence site is accessible from a URL like this:
http://<computer_name_or_IP_address>:<port>
If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go
any further.
Here's a few things that will help you get your team up and running:
Set the server base URL – this is the URL people will use to access Confluence.
Set up a mail server – this allows Confluence to send people notification about content.
Add and invite users – get your team on board!
Start and stop Confluence – find out how to start and stop Confluence.

Troubleshooting
Running into problems installing Confluence?
If your web browser window shows an error the first time you try to access Confluence, wait for 30
seconds or so and then refresh the page.
If the command prompt window closes immediately, your JAVA_HOME variable may not be set
correctly. See Setting the JAVA_HOME Variable in Windows.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 419

If you see an error, see Confluence does not start due to Spring Application context has not been
set for troubleshooting options.
Collaborative editing errors? See Troubleshooting Collaborative Editing.
Head to Installation Troubleshooting in our Knowledge Base for more help.

Uninstalling Confluence from Windows

This page describes the procedure for uninstalling an instance of Confluence which has been installed using the
Windows Installer.
To uninstall Confluence from Windows:
1. Log in to Windows as the same user that was used to install Confluence with the Windows Installer.
2. Start the uninstaller by doing either of the following:
Click the Windows Start Menu > All Programs > Confluence > Uninstall Confluence
OR
Open the Windows Control Panel, choose Add or Remove Programs (on Windows XP) or Progr
ams and Features on (Windows 7, Vista) and then select Confluence X.Y from the list of
applications and click Uninstall/Change.
OR
Open the Windows command prompt and do the following:
a. Change directory to your Confluence installation directory
b. Run the uninstall.exe file
3. Follow the prompts to uninstall Confluence from your computer.
Please note:
The uninstaller will not delete the Confluence Home Directory.
All log files that were generated while Confluence was running will not be deleted.
All files within the Confluence Installation Directory will be deleted (with the exception of the Tomcat log f
older located in the Confluence Installation Directory).
The uninstaller can be made to operate in unattended mode by specifying the -q option at the Windows
command prompt — i.e. uninstall -q
If you wish to re-install Confluence in 'unattended mode', do not uninstall your previous installation of
Confluence just yet. See Using the Silent Installation Feature for more information.
Installing Confluence on Linux
In this guide we'll run you through installing On this page:
Confluence in a production environment, with an
external database, using the Linux installer. Before you begin
Install Confluence
This is the most straightforward way to get your 1. Download Confluence
production site up and running on a Linux server. 2. Run the installer
Set up Confluence
3. Choose installation type
4. Enter your license
5. Connect to your
database
6. Populate your new site
with content
7. Choose where to
manage users
8. Create your administrator
Other ways to install Confluence: account
9. Start using Confluence
Evaluation - get your free trial up and running Troubleshooting
in no time.
TAR.GZ – install Confluence manually from
an archive file.
Windows – install Confluence on a Windows
server.

Before you begin

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 420

Before you install Confluence, there are a few questions you need to answer.

Are you Tell me more...

using a Check the Supported Platforms page for the version of Confluence you are installing.
supported This will give you info on supported operating systems, databases and browsers.
operating
system? Good to know:
We don't support installing Confluence on OSX for production sites.
The Confluence installer includes Java (JRE) and Tomcat, so you don't need to
install these separately.
Confluence can only run on Oracle JDK or AdoptOpenJDK.

Does your Tell me more...

Linux server Many Linux distributions don't include a suitable font config package by default, so
have a font you will need to install one before you can run the Confluence installer.
config
package See Confluence Server 6.13 or later fails with FontConfiguration error when installing
installed? on Linux operating systems for commands to install a suitable package on several
popular Linux distributions.

Do you want Tell me more...

to run Running Confluence as a service means that Confluence will automatically start up
Confluence when Linux is started.
as a
service? If you choose to run Confluence as a service:
You must use sudo to run the installer to be able to install Confluence as a
service.
The installer will create a dedicated user account, confluence, that will run the
service.
If you choose not to run Confluence as a service:
You will start and stop Confluence by running the start-confluence.sh file in
your Confluence installation directory.
Confluence will be run as the user account that was used to install Confluence, or
you can choose to run as a dedicated user.
Confluence will need to be restarted manually if your server is restarted.

Are ports Tell me more...

8090 and Confluence runs on port 8090 by default. If this port is already in use, the installer will
8091 prompt you to choose a different port.
available?
Synchrony, which is required for collaborative editing, runs on port 8091 by default. If
this port is already in use, you will need to change the port that Synchrony runs on
after your Confluence installation is complete. See Administering Collaborative Editing
to find out how to change the port Synchrony runs on. You won't be able to edit pages
until Synchrony has an available port.
See Ports used by Atlassian Applications for a summary of all the ports used.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 421

Is your Tell me more...

database To run Confluence in production you'll need an external database. Check the Support
set up and ed Platforms page for the version you're installing for the list of databases we
ready to currently support. If you don't already have a database, PostgreSQL is free and easy
use? to set up.
Good to know:
Set up your database before you begin. Step-by-step guides are available for Post
greSQL, Oracle, MySQL, and SQL Server.
If you're using Oracle or MySQL you'll need to download the driver for your
database.
To use a datasource see Configuring a datasource connection as there are some
steps you need to perform before running the setup wizard.
The embedded H2 database can be used for evaluating Confluence, but you'll
need to migrate to another database before running in production. You may find it
easier to use external database from the start.

Do you have Tell me more...

a You'll need a valid Confluence Server license to use Confluence.
Confluence
license? Good to know:
If you have not yet purchased a Confluence license you'll be able to create an
evaluation license during setup.
If you already have a license key you'll be prompted to log in to my.atlassian.com t
o retrieve it, or you can enter the key manually during setup.
If you're migrating from Confluence Cloud, you'll need a new license.

Install Confluence

1. Download Confluence

Download the installer for your operating system – https://www.atlassian.com/software/confluence/download

2. Run the installer

1. Make the installer executable.

Show me how to do this...

Change to the directory where you downloaded Confluence then execute this command:

$ chmod a+x atlassian-confluence-X.X.X-x64.bin

Where X.X.X is is the Confluence version you downloaded.

2. Run the installer – we recommend using sudo to run the installer as this will create a dedicated
account to run Confluence and allow you to run Confluence as a service.

Show me how to do this...

To use sudo to run the installer execute this command:

$ sudo ./atlassian-confluence-X.X.X-x64.bin

Where X.X.X is is the Confluence version you downloaded.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 422

You can also choose to run the installer as with root user privileges.
3. Follow the prompts to install Confluence. You'll be asked for the following info:

Install type – choose option 2 (custom) for the most control.

Destination directory – this is where Confluence will be installed.
Home directory – this is where Confluence data like logs, search indexes and files will be
stored.
TCP ports – these are the HTTP connector port and control port Confluence will run on. Stick
with the default unless you're running another application on the same port.
Install as service – this option is only available if you ran the installer as sudo.
4. Once installation is complete head to http://localhost:8090/ in your browser to begin the setup
process.
(Replace 8090 if you chose a different port during installation).

Trouble installing Confluence?

If you're installing Confluence on a fresh Linux installation see Confluence throws a Confluence is vacant
error on install for troubleshooting options.
FontConfiguration error? See Confluence Server 6.13 or later fails with FontConfiguration error when
installing on Linux operating systems to find out how to install a suitable font configuration package.

Set up Confluence

3. Choose installation type

1. Choose Production installation.

2. Choose any apps you'd also like to install.

4. Enter your license

Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.

5. Connect to your database

1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of
this page for details and connection options.

2. Choose My own database then select your particular database from the Database type dropdown
menu.

3. For MySQL and Oracle, follow the prompts to download and install the required driver.

4. Enter your database details. Use test connection to check your database is set up correctly.
Advanced setup options...
If you want to specify particular parameters, you can choose to connect By connection string.
You'll be prompted to enter:
Database URL – the JDBC URL for your database. If you're not sure, check the
documentation for your database.
Username and Password – A valid username and password that Confluence can use to
access your database.

6. Populate your new site with content

Choose whether you'd like Confluence to populate your site with content:

Demonstration space...
This option will create a space that you and your users can use to get to know Confluence. You can
delete this space at any time.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 423

Import data from an existing site...

Use this option if you have a full site export of an existing Confluence site. This is useful when you’re
migrating to another database or setting up a test site.
Good to know:
You can only import sites from the same or earlier Confluence version.
The system administrator account and all other user data and content will be imported from your
previous installation.
In the setup wizard:
Upload a backup file – use this option if your site export file is small (25mb or less).
Restore a backup file from the file system – use this option if your backup file is large. Drop the
file into your <confluence-home>/restore directory then follow the prompts to restore the
backup.
Build Index – we’ll need to build an index before your imported content is searchable. This can
take a long time for large sites, so deselect this option if you would rather build the index
later. Your content won't be searchable until the index is built.

7. Choose where to manage users

Choose to manage Confluence's users and groups inside Confluence or in a Jira application, such as Jira
Software or Jira Service Desk:

Manage users and groups in Confluence...

Choose this option if you're happy to manage users in Confluence, or don't have a Jira application
installed.
Good to know:
If you do plan to manage users in a Jira application, but have not yet installed it, we recommend
installing Jira first, and then returning to the Confluence setup.
You can add external user management (for example LDAP, Crowd or Jira) later if you choose.
Connect to Jira...
Choose this option if you have a Jira application installed and want to manage users across both
applications.
Good to know:
This is a quick way of setting up your Jira integration with the most common options.
It will configure a Jira user directory for Confluence, and set up application links between Jira and
Confluence for easy sharing of data.
You'll be able to specify exactly which groups in your Jira app should also be allowed to log in to
Confluence. Your license tiers do not need to be the same for each application.
You'll need either Jira 4.3 or later, Jira Core 7.0 or later, Jira Software 7.0 or later, or Jira Service
Desk 3.0 or later.
In the setup wizard:
Jira Base URL – the address of your Jira server, such as http://www.example.com:8080/ji
ra/ or http://jira.example.com/
Jira Administrator Login – this is the username and password of a user account that has the Jira
System Administrator global permission in your Jira application. Confluence will also use this
username and password to create a local administrator account which will let you access
Confluence if Jira is unavailable. Note that this single account is stored in Confluence's internal
user directory, so if you change the password in Jira, it will not automatically update in Confluence.
Confluence Base URL – this is the URL Jira will use to access your Confluence server. The URL
you give here overrides the base URL specified in Confluence, for the purposes of connecting to
the Jira application.
User Groups – these are the Jira groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in
your Confluence license. The default user group name differs depending on your Jira version:
Jira 6.4 and earlier: jira-users.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 424

Jira Software 7.x and later: jira-software-users

Jira Core 7.x and later: jira-core-users
Jira Service Desk 3.x and later: jira-servicedesk-users
Admin Groups – provide one or more Jira groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.

8. Create your administrator account

Enter details for the administrator account.

Skip this step if you chose to manage users in a Jira application or you imported data from an existing site.

9. Start using Confluence

That's it! Your Confluence site is accessible from a URL like this:
http://<computer_name_or_IP_address>:<port>
If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go
any further.
Here's a few things that will help you get your team up and running:
Set the server base URL – this is the URL people will use to access Confluence.
Set up a mail server – this allows Confluence to send people notification about content.
Add and invite users – get your team on board!
Start and stop Confluence – find out how to start and stop Confluence.

Troubleshooting
Running into problems installing Confluence?
If the installer fails with a FontConfiguration error, you'll need to install a font package. See Conflue
nce Server 6.13 or later fails with FontConfiguration error when installing on Linux operating
systems for info on how to do this.
Some anti-virus or other Internet security tools may interfere with the Confluence installation
process and prevent the process from completing successfully. If you experience or anticipate
experiencing such an issue with your anti-virus/Internet security tool, disable this tool first before
proceeding with the Confluence installation.
The Linux OOM Killer can sometimes kill Confluence processes when memory on the server
becomes too low. See How to Configure the Linux Out-of-Memory Killer.
Collaborative editing errors? See Troubleshooting Collaborative Editing.
Head to Installation Troubleshooting in our Knowledge Base for more help.

Installing Confluence on Linux from Archive File

In this guide we'll run you through installing
Confluence in a production environment, with an

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 425

external database, manually using a zip file. On this page:

This method gives you the most control over the Before you begin
installation process. Install Confluence
1. Download Confluence
2. Create the installation
directory
3. Create the home
directory
4. Check the ports
5. Start Confluence
Set up Confluence
6. Choose installation type
7. Enter your license
Other ways to install Confluence: 8. Connect to your
database
Evaluation - get your free trial up and running 9. Populate your new site
in no time. with content
Installer – install Confluence using the Linux 10. Choose where to
installer. manage users
Windows – install Confluence on a Windows 11. Create your
server. administrator account
12. Start using Confluence
Troubleshooting

Before you begin

Before you install Confluence, there are a few questions you need to answer.

Are you Tell me more...

using a Check the Supported Platforms page for the version of Confluence you are installing.
supported This will give you info on supported operating systems, databases and browsers.
operating
system and Good to know:
Java We don't support installing Confluence on OS X or mac OS for production
version? environments.
You'll need to install either AdoptOpenJDK or Oracle JDK. We don't support
other OpenJDK binaries.
You can use either the JDK (Java Development Kit) or JRE (Java Runtime
Environment).
We only support the version of Apache Tomcat that is bundled with Confluence.

Do you want Tell me more...

to run Running Confluence as a service means that Confluence will automatically start up
Confluence when your Linux server is started.
as a service?
You should use the Linux installer if you want to run Confluence as a service.
If you choose not to run Confluence as a service:
You will start Confluence by running the start-confluence.sh file in your
Confluence installation directory.
We recommend creating a dedicated user to run Confluence. This user must
have full read, write and execute access to the installation directory and home
directory.
Confluence will need to be restarted manually if your server is restarted.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 426

Are ports Tell me more...

8090 and Confluence runs on port 8090 by default. If this port is already in use, the installer will
8091 prompt you to choose a different port.
available?
Synchrony, which is required for collaborative editing, runs on port 8091 by default. If
this port is already in use, you will need to change the port that Synchrony runs on
after your Confluence installation is complete. See Administering Collaborative
Editing to find out how to change the port Synchrony runs on. You won't be able to
edit pages until Synchrony has an available port.
See Ports used by Atlassian Applications for a summary of all the ports used.

What Tell me more...

database do To run Confluence in production you'll need an external database. Check the Suppor
you plan to ted Platforms page for the version you're installing for the list of databases we
use? currently support. If you don't already have a database, PostgreSQL is free and easy
to set up.
Good to know:
Set up your database before you begin. Step-by-step guides are available for Po
stgreSQL, Oracle, MySQL, and SQL Server.
If you're using Oracle or MySQL you'll need to download the driver for your
database.
To use a datasource see Configuring a datasource connection as there are some
steps you need to perform before running the setup wizard.
The embedded H2 database can be used for evaluating Confluence, but you'll
need to migrate to another database before running in production. You may find
it easier to use external database from the start.

Do you have Tell me more...

a Confluence You'll need a valid Confluence Server license to use Confluence.
license?
Good to know:
If you have not yet purchased a Confluence license you'll be able to create an
evaluation license during setup.
If you already have a license key you'll be prompted to log in to my.atlassian.com
to retrieve it, or you can enter the key manually during setup.
If you're migrating from Confluence Cloud, you'll need a new license.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 427

Is your Tell me more...

JAVA_HOME Before you install Confluence, check that you're running a supported Java version
variable set and that the JAVA_HOME environment variable is set correctly.
correctly?
Confluence can only run with Oracle JDK or JRE.
To check your Java version:

$ java -version

To check your JAVA_HOME variable is set correctly:

$ echo $JAVA_HOME

If you see a path to your Java installation directory, the JAVA_Home environment
variable has been set correctly. If a path is not returned you'll need to set your JAVA
_HOME environment variable manually before installing Confluence.

Have you Tell me more...

created a We strongly recommend running Confluence as a dedicated user.
dedicated
user to run You should create this user before you begin, so that when creating the installation
Confluence? and home directories, you can give this user appropriate read and write permissions.
In this example, we'll create a user called confluence:

$ sudo /usr/sbin/useradd --create-home --comment

"Account for running Confluence" --shell /bin/bash
confluence

See Creating a Dedicated User Account on the Operating System to Run Confluence
for more information.

Install Confluence

1. Download Confluence

Download the tar.gz file for your operating system - https://www.atlassian.com/software/confluence/downlo

ad.

2. Create the installation directory

1. Create your installation directory – this is where Confluence will be installed. Avoid using spaces or
special characters in the path. We'll refer to this directory as your <installation-directory>.

Show me how to do this...

In this example we'll call our installation directory confluence:

$ mkdir confluence

2. Extract the Confluence tar.gz file to your <installation-directory>. We recommend using a

GNU version of the archive utility, especially on Solaris.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 2.
Confluence 6.15 Documentation 428

Show me how to do this...

Change to the directory where you downloaded Confluence then execute these commands:

$ tar -xzf atlassian-confluence-X.X.X.tar.gz -C

<installation-directory>
$ cd <installation-directory>
$ tar -xf atlassian-confluence-X.X.X.tar

Replace x.x.x with your Confluence version and <installation-directory> with the full
path to the directory you created in the last step.
3. Give your dedicated Confluence user read, write and execute permission to your <installation-d
irectory>.

Show me how to do this...

In this example we're changing ownership of the installation directory and giving the user conflue
nce read, write and execute permissions.

$ chown -R confluence <installation-directory>

$ chmod -R u=rwx,go-rwx <installation-directory>

3. Create the home directory

1. Create your home directory – this is where Confluence application data like logs, search indexes and
files will be stored. This should be separate to your installation directory, with no spaces or special
characters in the path. We'll refer to this directory as your <home-directory>.

Show me how to do this...

In this example we'll call our home directory confluence-home:

$ mkdir confluence-home

2. Give your dedicated Confluence user read, write and execute permissions to the <home-directory
>.

Show me how to do this...

In this example we're changing ownership of the home directory and giving the user confluence r
ead, write and execute permissions.

$ chown -R confluence <home-directory>

$ chmod -R u=rwx,go-rwx <home-directory>

3. Edit <installation-directory>\confluence\WEB-INF\classes\confluence-init.pro
perties.
4. At the bottom of the file, enter the absolute path to your <home-directory>. This tells Confluence
where to find your <home-directory> when it starts up.

Show me how to do this...

You can edit the confluence.init.properties file any text editor.

a. Scroll to the bottom of the text and find this line:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 a.
Confluence 6.15 Documentation 429

# confluence.home=c:/confluence/data

b. Remove the # and the space at the beginning of this line (so Confluence doesn't read the
line as a comment) and add the absolute path to your home directory (not a symlink). For
example:

confluence.home=/var/confluence-home

4. Check the ports

By default Confluence listens on port 8090. If you have another application running on your server that uses
the same ports, you'll need to tell Confluence to use a different port.

Show me how to do this...

To change the ports:
1. Edit <installation-directory>\conf\server.xml
2. Change the Server port (8000) and the Connector port (8090) to free ports on your server.

In the example below we've changed the Server port to 5000 and the Connector port to 5050.

Server port="5000" shutdown="SHUTDOWN" debug="0">

<Service name="Tomcat-Standalone">
<Connector port="5050" connectionTimeout="20000"
redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0"
URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"
/>

Linux won't allow you to bind to ports less than 1024. If you want to run Confluence on port 80, for
example, you could use a reverse proxy to redirect traffic from port 80. See Using Apache with
mod_proxy.

5. Start Confluence

1. Run <installation-directory>/bin/start-confluence.sh to start the setup process.

Show me how to do this...

We recommend running Confluence as your dedicated user.

$ su -u <user>
$ ./start-confluence.sh

If you're using Ubuntu the command is a little different:

$ sudo su <user>
$ ./start-confluence.sh

2. Go to http://localhost:8090/ to launch Confluence in your browser (change the port if you've

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 430
2.
updated the Connector port).

Trouble starting Confluence?

Check your JAVA_HOME variable is set correctly.
If you see an error, see Confluence does not start due to Spring Application context has not been
set for troubleshooting options.

Set up Confluence

6. Choose installation type

1. Choose Production installation.

2. Choose any apps you'd also like to install.

7. Enter your license

Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.

8. Connect to your database

1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of
this page for details and connection options.

2. Choose My own database then select your particular database from the Database type dropdown
menu.

3. For MySQL and Oracle, follow the prompts to download and install the required driver.

4. Enter your database details. Use test connection to check your database is set up correctly.
Advanced setup options...
If you want to specify particular parameters, you can choose to connect By connection string.
You'll be prompted to enter:
Database URL – the JDBC URL for your database. If you're not sure, check the
documentation for your database.
Username and Password – A valid username and password that Confluence can use to
access your database.

9. Populate your new site with content

Choose whether you'd like Confluence to populate your site with content:

Demonstration space...
This option will create a space that you and your users can use to get to know Confluence. You can
delete this space at any time.
Import data from an existing site...
Use this option if you have a full site export of an existing Confluence site. This is useful when you’re
migrating to another database or setting up a test site.
Good to know:
You can only import sites from the same or earlier Confluence version.
The system administrator account and all other user data and content will be imported from your
previous installation.
In the setup wizard:
Upload a backup file – use this option if your site export file is small (25mb or less).
Restore a backup file from the file system – use this option if your backup file is large. Drop the
file into your <confluence-home>/restore directory then follow the prompts to restore the
backup.
Build Index – we’ll need to build an index before your imported content is searchable. This can
take a long time for large sites, so deselect this option if you would rather build the index

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 431

later. Your content won't be searchable until the index is built.

10. Choose where to manage users

Choose to manage Confluence's users and groups inside Confluence or in a Jira application, such as Jira
Software or Jira Service Desk:

Manage users and groups in Confluence...

Choose this option if you're happy to manage users in Confluence, or don't have a Jira application
installed.
Good to know:
If you do plan to manage users in a Jira application, but have not yet installed it, we recommend
installing Jira first, and then returning to the Confluence setup.
You can add external user management (for example LDAP, Crowd or Jira) later if you choose.
Connect to Jira...
Choose this option if you have a Jira application installed and want to manage users across both
applications.
Good to know:
This is a quick way of setting up your Jira integration with the most common options.
It will configure a Jira user directory for Confluence, and set up application links between Jira and
Confluence for easy sharing of data.
You'll be able to specify exactly which groups in your Jira app should also be allowed to log in to
Confluence. Your license tiers do not need to be the same for each application.
You'll need either Jira 4.3 or later, Jira Core 7.0 or later, Jira Software 7.0 or later, or Jira Service
Desk 3.0 or later.
In the setup wizard:
Jira Base URL – the address of your Jira server, such as http://www.example.com:8080/ji
ra/ or http://jira.example.com/
Jira Administrator Login – this is the username and password of a user account that has the Jira
System Administrator global permission in your Jira application. Confluence will also use this
username and password to create a local administrator account which will let you access
Confluence if Jira is unavailable. Note that this single account is stored in Confluence's internal
user directory, so if you change the password in Jira, it will not automatically update in Confluence.
Confluence Base URL – this is the URL Jira will use to access your Confluence server. The URL
you give here overrides the base URL specified in Confluence, for the purposes of connecting to
the Jira application.
User Groups – these are the Jira groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in
your Confluence license. The default user group name differs depending on your Jira version:
Jira 6.4 and earlier: jira-users.
Jira Software 7.x and later: jira-software-users
Jira Core 7.x and later: jira-core-users
Jira Service Desk 3.x and later: jira-servicedesk-users
Admin Groups – provide one or more Jira groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.

11. Create your administrator account

Enter details for the administrator account.

Skip this step if you chose to manage users in a Jira application or you imported data from an existing site.

12. Start using Confluence

That's it! Your Confluence site is accessible from a URL like this:
http://<computer_name_or_IP_address>:<port>
If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 432

any further.
Here's a few things that will help you get your team up and running:
Set the server base URL – this is the URL people will use to access Confluence.
Set up a mail server – this allows Confluence to send people notification about content.
Add and invite users – get your team on board!
Start and stop Confluence – find out how to start and stop Confluence.

Troubleshooting
Running into problems installing Confluence?
Check your JAVA_HOME is set correctly.
If you see an error, see Confluence does not start due to Spring Application context has not been
set for troubleshooting options.
Use a GNU version of the unzip utility. There are known issues extracting the tar.gz file on
Solaris and AIX. See 'extractBundledPlugins Couldn't find atlassian-bundled-plugins.zip on
classpath' Due to Solaris TAR Utility.
Collaborative editing errors? See Troubleshooting Collaborative Editing.
Head to Installation Troubleshooting in our Knowledge Base for more help.

Uninstalling Confluence from Linux

This page describes the procedure for uninstalling Confluence, which had been installed using the Linux Installer
.
To uninstall Confluence from Linux:
1. Open a Linux console.
2. Change directory (cd) to your Confluence installation directory.
3. Execute the command uninstall. This command must be executed as the same user account that was
used to install Confluence with the Linux Installer.
4. Follow the prompts to uninstall Confluence from your computer.
Please note:
The uninstaller will not delete the Confluence Home Directory.
All log files that were generated while Confluence was running will not be deleted.
All files within the Confluence Installation Directory will be deleted (with the exception of the Tomcat log f
older located in the Confluence Installation Directory).
The uninstaller can be made to operate in unattended mode by specifying the -q option — i.e. uninstal
l -q
If you wish to re-install Confluence in 'unattended mode', do not uninstall your previous installation of
Confluence just yet. See Using the Silent Installation Feature for more information.
Unattended installation
If you've previously installed Confluence using the

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 433

Windows or Linux installer, you can use a

configuration file from your existing Confluence
installation (response.varfile) to re-install
Confluence in unattended mode, no user input
required.
This can be useful when you have installed
Confluence on a test server and are ready to install
on your production server with the same
configuration.

Good to know

The response.varfile file contains the options specified during the installation wizard steps of
your previous Confluence installation. Don't uninstall your previous Confluence installation until after
you've copied this file to your new install location.
If you decide to modify the response.varfile file, make sure all directory paths specified are
absolute, for example, sys.installationDir=C\:\\Program
Files\\Atlassian\\Confluence
(Windows) or sys.installationDir=/opt/atlassian/confluence (Linux).

Unattended installations will fail the file contains relative directory paths.

Install Confluence in unattended mode

1. Download the appropriate installer for your operating system.

2. Copy <installation-directory>/.install4j/response.varfile from your existing

Confluence installation to where you downloaded the installer.

3. In command prompt or terminal change directory (cd) to where you downloaded the installer.

4. Run the following command to install Confluence:

Windows
> atlassian-confluence-X.X.X-x64.exe -q -varfile
response.varfile

Linux
$ atlassian-confluence-X.X.X-x64.bin -q -varfile
response.varfile

Where X.X.X is the Confluence version you downloaded.

-q instructs the installer to run in unattended mode (quietly). -varfile specifies the location and
name of the configuration file containing the options used by the installer.

5. Confluence will start automatically once the silent installation finishes.

Once Confluence is installed, you will still need to head to http://localhost:<port> to finish setting up
Confluence.
See the Set up Confluence section on Installing Confluence on Windows or Installing Confluence on Linux f
or more info.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 434

Change listen port for Confluence

Problem

This page tells you what to do if you get errors like the following when starting Confluence, when you can't
access Confluence on port 8090.
If you see this error:

java.net.BindException: Address already in use: JVM_Bind:8090

This means you are running other software on Confluence's default port of 8090. This may be another other
process running on the same port. It may also be a previous instance of Confluence that hasn't been shut down
cleanly.
To find out what process is listening on that port, load a command prompt and type: netstat -an

-a : Displays all active TCP connections and the TCP and UDP ports on
which the computer is listening.
-n : Displays active TCP connections, however, addresses and port
numbers are expressed numerically and no attempt is made to determine
names.

There is also Process Explorer tool available to determine what is binding port 8090.

Solution: Change the Ports which Confluence Listens On

To change the ports for Confluence, open the file conf/server.xml under your Confluence Installation
directory. The first four lines of the file look like this:

Default conf/server.xml
<Server port="8000" shutdown="SHUTDOWN" debug="0">
<Service name="Tomcat-Standalone">
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8090" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443" acceptCount="10"
debug="0" connectionTimeout="20000" useURIValidationHack="false"/>
...

You need to modify both the server port (default is 8000) and the connector port (default is 8090) to ports that
are free on your machine. The server port is required by Tomcat but is not user facing in any way. The connector
port is what your users will use to access Confluence, eg in the snippet above, the URL would be http://exam
ple.com:8090.

Hint: You can use netstat to identify free ports on your machine. See more information on using netstat on
Windows or on Linux.
For example, here are the first four lines of a modified server.xml file, using ports '8020' and '8099':

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 435

Modified conf/server.xml using ports 8020 and 8099

<Server debug="0" shutdown="SHUTDOWN" port="8020">
<Service name="Tomcat-Standalone">
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8099" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443" acceptCount="10"
debug="0" connectionTimeout="20000" useURIValidationHack="false"/>
...

To access Confluence in this configuration, point your web browser to http://localhost:8099/.

Final Configuration

If this is the URL your users will use to access Confluence, update your Base URL to point to the new
URL.
You should also ensure at this point that if you are using a firewall, it is configured to allow http/https
traffic over the port you have chosen.

NOTES

[1] For more information on netstat, see using netstat on Windows, or netstat man page (Linux).
[2] The Jira distribution runs on port 8080 by default. If you're looking to change the port of your Jira application's
distribution, see Changing JIRA application TCP ports.
[3] You will need to restart Confluence after editing server.xml for the changes to take effect.
Start and Stop Confluence

How you start and stop Confluence depends on whether you are running Confluence as a Service.
To check whether Confluence is already running you can go to http://<base-url>/status.

Windows
When installed as a service...
If you installed Confluence as a service, you can Start Confluence Server and Stop Confluence Server fro
m the Windows Start menu.
You can't start or stop Confluence manually using the start-confluence.bat and stop-confluence.
bat file.

When not installed as a service...

If you didn't install Confluence as a service you'll need to start and stop Confluence manually. The way you
do this depends on how Confluence was originally installed.
If you installed Confluence manually, and have Java installed on your server:
To start Confluence run <installation-directory>\bin\start-confluence.bat
To stop Confluence run <installation-directory>\bin\stop-confluence.bat

We recommend running Confluence with a dedicated user account. To do this, use use the runas command
to execute start-confluence.bat.

> runas /env /user:<DOMAIN>\<confluence> start-confluence.bat

Where <DOMAIN> is your Windows domain or computer name and <confluence> is the name of your
dedicated user.
If you installed Confluence using the installer, and don't have Java installed, use the Start and Stop
Confluence options in the Start menu, or:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 436

To start Confluence run <installation-directory>\startup-bundled-jre.bat

To stop Confluence run <installation-directory>\shutdown-bundled-jre.bat

With add-ons disabled (for troubleshooting)...

It is possible to start Confluence Server with user installed apps temporarily disabled. This is useful if you
need to troubleshoot problems with your site, particularly if an app may be preventing Confluence from
starting up successfully.
To start Confluence with all user installed apps temporarily disabled:

> cd <installation-directory>/bin
> start-confluence.bat /disablealladdons

To start Confluence with a particular app temporarily disabled:

> cd <installation-directory>/bin
> start-confluence.bat /disableaddon=com.atlassian.test.plugin

where com.atlassian.test.plugin is the app key. To disable multiple apps, use a colon separated list.
Regex/wildcards are not permitted, the full key of the plugin must be provided.
These parameters are applied at startup only, they do not persist. If you want to permanently disable an app,
go to

> Manage apps

to do this via UPM.
Notes
If the app key contains a space, disabling the app using this method will not work, you need to manuall
y deal with that app.
This feature does not work for Confluence Data Center.
replace /bin/start-confluence.bat with startup-bundled-jre.bat if you installed
Confluence using the installer, and are using the bundled JRE (Java Runtime Engine).

Linux
When installed as a service...
If you installed Confluence as a service, use one of the following commands to start, stop or restart Conflue
nce.

$ sudo /etc/init.d/confluence start

$ sudo /etc/init.d/confluence stop
$ sudo /etc/init.d/confluence restart

You can't start or stop Confluence manually using the start-confluence.sh and stop-confluence.s
h files.

When not installed as a service...

If you didn't install Confluence as a service you'll need to start and stop Confluence manually.
To start Confluence run <installation-directory>\bin\start-confluence.sh
To stop Confluence run <installation-directory>\bin\stop-confluence.sh

We recommend running Confluence with a dedicated user account:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 437

$ su -u <user>
$ ./start-confluence.sh

Where <user> is the name of your dedicated user.

If you're using Ubuntu the command is a little different:

$ sudo su <user>
$ ./start-confluence.sh

With add-ons disabled (for troubleshooting)...

It is possible to start Confluence with user installed apps temporarily disabled. This is useful if you need to
troubleshoot problems with your site, particularly if an app may be preventing Confluence from starting up
successfully.
To start Confluence with all user installed apps temporarily disabled:

$ cd <installation-directory>/bin
$ ./start-confluence.sh --disable-all-addons

To start Confluence with a particular app temporarily disabled:

$ cd <installation-directory>/bin
$ ./start-confluence.sh --disable-addons=com.atlassian.test.plugin

where com.atlassian.test.plugin is the app key.

To disable multiple apps, use a colon separated list, for example, com.atlassian.test.plugin:com.at
lassian.another.plugin. Regex/wildcards are not permitted, the full key of the plugin must be provided.

These parameters are applied at startup only, they do not persist. If you want to permanently disable an app,
go to

> Manage apps

to do this via UPM.
Notes
If the app key contains a space, disabling the app using this method will not work, you need to manuall
y deal with that app.
This feature does not work for Confluence Data Center.

Installing Confluence Data Center

In this guide we'll run you through installing
Confluence Data Center, which is a clustered
solution, in a Windows or Linux Environment.
This guide covers installing for the first time, with no
existing data. If you already have a Confluence
Server instance, see Moving to Confluence Data
Center.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 438

On this page:
Before you begin
Clustering requirements
Supported platforms
Terminology
Install and set up Confluence
1. Install Confluence on the
first node
Add more Confluence nodes
2. Copy Confluence to
Other ways to install Confluence Data Center: second node
AWS Quick Start - hassle free deployment in 3. Configure load balancer
AWS 4. Start Confluence one
Move to Data Center - for existing Confluence node at a time
Server sites 5. Test your Confluence
cluster
6. Set up your Synchrony
cluster (optional)
Interested in learning more about Data Security
Center? Find out more about the benefits Troubleshooting
of Confluence Data Center. Upgrading a cluster

Before you begin

Clustering requirements

To run Confluence in a cluster you must:

Have a Data Center license (you can purchase a Data Center license or create an evaluation license
at my.atlassian.com)
Use a supported external database, operating system and Java version
Use a load balancer with session affinity and WebSockets support in front of the Confluence cluster
Have a shared directory accessible to all cluster nodes in the same path (this will be your shared
home directory)
Use OAuth authentication if you have application links to other Atlassian products (such as Jira)

Supported platforms

See our Supported Platforms page for information on the database, Java, and operating systems you'll be
able to use. These requirements are the same for Server and Data Center deployments. See Confluence
Data Center Technical Overview for important hardware and infrastructure considerations.
We also have specific guides and deployment templates to help you running Confluence Data Center in AWS
or Azure. Check them out to find out what's required.

Terminology

In this guide we'll use the following terminology:

Installation directory – The directory where you installed Confluence on a node.
Local home directory – The home or data directory on each node (in non-clustered Confluence this is
simply known as the home directory).
Shared home directory – The directory you created that is accessible to all nodes in the cluster via the
same path.
Synchrony home directory - The directory where you configure and run Synchrony from (this may be
on a confluence node, or on its own node)
At the end of the installation process, you'll have an installation and local home directory on each node, and a
single shared home directory (a total of 5 directories in a two node cluster) for Confluence plus directories for
Synchrony.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 439

Install and set up Confluence

1. Install Confluence on the first node

1. Install Confluence on node 1

See Installing Confluence on Windows from Zip File or Installing Confluence on Linux from Archive
File for more information.
2. Start Confluence on Node 1
3. The setup wizard will prompt you to complete the migration, by entering:
A name for your cluster
The path to the shared home directory you created earlier
The network interface Confluence will use to communicate between nodes
A multicast address (automatically generated or enter your own) or the IP addresses of each
cluster node
How you want Confluence to discover cluster nodes:
Multicast - enter your own multicast address or automatically generate one.
TCP/IP - enter the IP address of each cluster node
AWS - enter your IAM Role or secret key, and region.

AWS node discovery...

We recommend using our Quick Start or Cloud Formation Template to deploy
Confluence Data Center in AWS, as it will automatically provision, configure and
connect everything you need.
If you do decide to do your own custom deployment, you can provide the following
information to allow Confluence to auto-discover cluster nodes:

Field Description

IAM This is your authentication method. You can choose to authenticate

Role or by IAM Role or Secret Key.
Secret
Key

Region This is the region your cluster nodes (EC2 instances) will be running
in.

Host Optional. This is the AWS endpoint for Confluence to use (the
header address where the EC2 API can be found, for example 'ec2.amazona
ws.com'). Leave blank to use the default endpoint.

Security Optional. Use to narrow the members of your cluster to only

group resources in a particular security group (specified in the EC2
name console).

Tag key Optional. Use to narrow the members of your cluster to only
and Tag resources with particular tags (specified in the EC2 console).
value

4. Stop Confluence on Node 1

Add more Confluence nodes

2. Copy Confluence to second node

To copy Confluence to the second node:

1. Shut down Confluence on node 1
2. Shut down your application server on node 2, or stop it automatically loading web applications
3. Copy the installation directory from node 1 to node 2
4. Copy the local home directory from node 1 to node 2

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 440
4.

If the file path of the local home directory is not the same on nodes 1 and 2 you'll need to update the <
installation
directory>/confluence/WEB-INF/classes/confluence-init.properties file on node 2
to point to the correct location.
Copying the local home directory ensures the Confluence search index, the database and cluster
configuration, and any other settings are copied to node 2.

3. Configure load balancer

Configure your load balancer for Confluence. You can use the load balancer of your choice, but it needs to
support session affinity and WebSockets.
You can verify that your load balancer is sending requests correctly to your existing Confluence server by
accessing Confluence through the load balancer and creating a page, then checking that this page can be
viewed/edited by another machine through the load balancer.

4. Start Confluence one node at a time

You must only start Confluence one node at a time. The first node must be up and available before starting
the next one.
1. Start Confluence on node 1
2. Wait for Confluence to become available on node 1
3. Start Confluence on node 2
4. Wait for Confluence to become available on node 2.
The Cluster monitoring console (

> General Configuration > Clustering) shows information about the active cluster.
When the cluster is running properly, this page displays the details of each node, including system usage and
uptime. Use the

menu to see more information about each node in the cluster.

5. Test your Confluence cluster

Remember, to test creating content you'll need to access Confluence via your load balancer. You can't
create or edit pages when accessing a node directly.
A simple process to ensure your cluster is working correctly is:
1. Access a node via your load balancer, and create a new document on this node
2. Ensure the new document is visible by accessing it directly on a different node
3. Search for the new document on the original node, and ensure it appears
4. Search for the new document on another node, and ensure it appears

If Confluence detects more than one instance accessing the database, but not in a working cluster, it
will shut itself down in a cluster panic. This can be fixed by troubleshooting the network connectivity
of the cluster.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 441

6. Set up your Synchrony cluster (optional)

Synchrony is required for collaborative editing. You have two options for running Synchrony with a Data
Center license:
managed by Confluence (recommended)
This is the default setup. Confluence will automatically launch a Synchrony process on the same
node, and manage it for you. No manual steps are required.
Standalone Synchrony cluster (managed by you)
You deploy and manage Synchrony standalone in its own cluster with as many nodes as you need.
Significant setup is required. See Set up a Synchrony cluster for Confluence Data Center for a
step-by-step guide.
Head to Administering Collaborative Editing to find out more about collaborative editing.

Security

Ensure that only permitted cluster nodes are allowed to connect to a Confluence Data Center instance's Haz
elcast port (which defaults to 5801) or Synchrony's Hazelcast port (which defaults to 5701) through the use
of a firewall and or network segregation.

Troubleshooting

If you have problems with the above procedure, please see our Cluster Troubleshooting guide.
If you're testing Confluence Data Center by running the cluster on a single machine, please refer to our
developer instructions on Starting a Confluence cluster on a single machine.

Upgrading a cluster

It's important that upgrades follow the procedure for Upgrading Confluence Data Center.

Moving to Confluence Data Center

This page outlines the process for migrating an
existing Confluence Server (non-clustered) site to
Confluence Data Center (clustered).
If you're installing Confluence for the first time (you
don't have any existing Confluence data to migrate),
see Installing Confluence Data Center.
If you're wanting to switch back to a non-clustered
solution, see Moving from Data Center to Server.

Your Confluence license determines the

type of Confluence you have: Server or Data
Center. Confluence will auto-detect the
license type when you enter your license
key, and automatically prompt you to begin
the migration.

Not sure if you should upgrade from Confluence

Server to Data Center? Learn more about the benefit
s of Confluence Data Center.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 442

On this page:
Before you begin
Clustering requirements
Supported platforms
Terminology
Set up Data Center
1. Upgrade Confluence
Server
2. Apply Data Center
license
3. Create a shared home
directory
4. Start Confluence
Add more Confluence nodes
5. Copy Confluence to
second node
6. Configure load balancer
7. Start Confluence one
node at a time
8. Test your Confluence
cluster
9. Set up a Synchrony
cluster (optional)
Security
Troubleshooting

Before you begin

Clustering requirements

To run Confluence in a cluster you must:

Have a Data Center license (you can purchase a Data Center license or create an evaluation license
at my.atlassian.com)
Use a supported external database, operating system and Java version
Use a load balancer with session affinity and WebSockets support in front of the Confluence cluster
Have a shared directory accessible to all cluster nodes in the same path (this will be your shared
home directory)
Use OAuth authentication if you have application links to other Atlassian products (such as Jira)

Supported platforms

See our Supported Platforms page for information on the database, Java, and operating systems you'll be
able to use. These requirements are the same for Server and Data Center deployments. See Confluence
Data Center Technical Overview for important hardware and infrastructure considerations.
We also have specific guides and deployment templates to help you running Confluence Data Center in AWS
or Azure. Check them out to find out what's required.

Terminology

In this guide we'll use the following terminology:

Installation directory – The directory where you installed Confluence on a node.
Local home directory – The home or data directory on each node (in non-clustered Confluence this is
simply known as the home directory).
Shared home directory – The directory you created that is accessible to all nodes in the cluster via the
same path.
Synchrony home directory - The directory where you configure and run Synchrony from (this may be
on a confluence node, or on its own node)
At the end of the installation process, you'll have an installation and local home directory on each node, and a

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 443

single shared home directory (a total of 5 directories in a two node cluster) for Confluence plus directories for
Synchrony.

Set up Data Center

1. Upgrade Confluence Server

If you plan to upgrade Confluence as part of your migration to Data Center, you should upgrade your existing
Confluence Server site as the first step.

2. Apply Data Center license

1. Go to

> General Configuration > License Details

2. Enter your new Confluence Data Center license key.
3. You'll be prompted to stop Confluence to begin the migration.

At this stage your home directory (configured in confluence\WEB-INF\classes\confluence-init

.properties) should still be pointing to your existing (local) home directory.

3. Create a shared home directory

1. Create a directory that's accessible to all cluster nodes via the same path. The directory should be
empty. This will be your shared home directory.
2. In your existing Confluence home directory, move the contents of <confluence
home>/shared-home to the new shared home directory you just created.

To prevent confusion, we recommend deleting the empty <confluence home>/shared-home direc

tory once you've moved its contents.
3. Move your attachments directory to the new shared home directory (skip this step if you currently store
attachments in the database).

4. Start Confluence

The setup wizard will prompt you to complete the migration, by entering:
A name for your cluster
The path to the shared home directory you created earlier
The network interface Confluence will use to communicate between nodes
A multicast address (automatically generated or enter your own) or the IP addresses of each cluster
node
How you want Confluence to discover cluster nodes:
Multicast - enter your own multicast address or automatically generate one.
TCP/IP - enter the IP address of each cluster node
AWS - enter your IAM Role or secret key, and region.

AWS node discovery...

We recommend using our Quick Start or Cloud Formation Template to deploy Confluence
Data Center in AWS, as it will automatically provision, configure and connect everything you
need.
If you do decide to do your own custom deployment, you can provide the following
information to allow Confluence to auto-discover cluster nodes:

Field Description

IAM This is your authentication method. You can choose to authenticate by IAM
Role or Role or Secret Key.
Secret
Key

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 444

Region This is the region your cluster nodes (EC2 instances) will be running in.

Host Optional. This is the AWS endpoint for Confluence to use (the address
header where the EC2 API can be found, for example 'ec2.amazonaws.com').
Leave blank to use the default endpoint.

Security Optional. Use to narrow the members of your cluster to only resources in a
group particular security group (specified in the EC2 console).
name

Tag key Optional. Use to narrow the members of your cluster to only resources with
and Tag particular tags (specified in the EC2 console).
value

Add more Confluence nodes

5. Copy Confluence to second node

To copy Confluence to the second node:

1. Shut down Confluence on node 1
2. Shut down your application server on node 2, or stop it automatically loading web applications
3. Copy the installation directory from node 1 to node 2
4. Copy the local home directory from node 1 to node 2
If the file path of the local home directory is not the same on nodes 1 and 2 you'll need to update the <
installation
directory>/confluence/WEB-INF/classes/confluence-init.properties file on node 2
to point to the correct location.
Copying the local home directory ensures the Confluence search index, the database and cluster
configuration, and any other settings are copied to node 2.

6. Configure load balancer

Configure your load balancer for Confluence. You can use the load balancer of your choice, but it needs to
support session affinity and WebSockets.
You can verify that your load balancer is sending requests correctly to your existing Confluence server by
accessing Confluence through the load balancer and creating a page, then checking that this page can be
viewed/edited by another machine through the load balancer.

7. Start Confluence one node at a time

You must only start Confluence one node at a time. The first node must be up and available before starting
the next one.
1. Start Confluence on node 1
2. Wait for Confluence to become available on node 1
3. Start Confluence on node 2
4. Wait for Confluence to become available on node 2.
The Cluster monitoring console (

> General Configuration > Clustering) shows information about the active cluster.
When the cluster is running properly, this page displays the details of each node, including system usage and
uptime. Use the

menu to see more information about each node in the cluster.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 445

8. Test your Confluence cluster

Remember, to test creating content you'll need to access Confluence via your load balancer. You can't
create or edit pages when accessing a node directly.
A simple process to ensure your cluster is working correctly is:
1. Access a node via your load balancer, and create a new document on this node
2. Ensure the new document is visible by accessing it directly on a different node
3. Search for the new document on the original node, and ensure it appears
4. Search for the new document on another node, and ensure it appears

If Confluence detects more than one instance accessing the database, but not in a working cluster, it
will shut itself down in a cluster panic. This can be fixed by troubleshooting the network connectivity
of the cluster.

9. Set up a Synchrony cluster (optional)

Synchrony is required for collaborative editing. You have two options for running Synchrony with a Data
Center license:
managed by Confluence (recommended)
This is the default setup. Confluence will automatically launch a Synchrony process on the same
node, and manage it for you. No manual steps are required.
Standalone Synchrony cluster (managed by you)
You deploy and manage Synchrony standalone in its own cluster with as many nodes as you need.
Significant setup is required. See Set up a Synchrony cluster for Confluence Data Center for a
step-by-step guide.
Head to Administering Collaborative Editing to find out more about collaborative editing.

Security

Ensure that only permitted cluster nodes are allowed to connect to a Confluence Data Center instance's Haz
elcast port (which defaults to 5801) or Synchrony's Hazelcast port (which defaults to 5701) through the use
of a firewall and / or network segregation.

Troubleshooting

If you have problems with the above procedure, please see our Cluster Troubleshooting guide.
If you're testing Confluence Data Center by running the cluster on a single machine, please refer to our
developer instructions on Starting a Confluence cluster on a single machine.

Upgrading Confluence Data Center

This page contains instructions for upgrading an
existing Confluence cluster.
If you are not yet running a clustered instance of

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 446

Confluence, see Moving to Confluence Data Center. On this page:

In this guide we'll use the following terminology: 1. Back up
2. Stop the cluster
installation directory - this is the directory
3. Upgrade the first node
where you installed Confluence on each
4. Upgrade Synchrony (optional)
node.
5. Copy Confluence to remaining
local home directory - this is the home or data
nodes
directory on each node (in non-clustered
6. Start Confluence and check
Confluence this is simply known as the home
cluster connectivity
directory).
shared home directory - this is a directory that
is accessible to all nodes in the cluster via the
same path.

Currently using Confluence Server?

Learn more about the benefits of
Confluence Data Center.

1. Back up

We strongly recommend that you backup your Confluence home and install directories and your database
before proceeding.
More information on specific files and directories to backup can be found in Upgrading Confluence.

2. Stop the cluster

You must stop all the nodes in the cluster before upgrading.
We recommend configuring your load balancer to redirect traffic away from Confluence until the upgrade is
complete on all nodes.

3. Upgrade the first node

To upgrade the first node:

1. Extract (unzip) the files to a directory (this will be your new installation directory, and must be different
to your existing installation directory)
2. Update the following line in the <Installation-Directory>\confluence\WEB-INF\classes\
confluence-init.properties file to point to the existing local home directory on that node.
3. Copy the jdbc driver jar file from your existing Confluence installation directory to confluence/WEB-
INF/lib in your new installation directory.
The jdbc driver will be located in either the <Install-Directory>/common/lib or <Installati
on-Directory>/confluence/WEB-INF/lib directories.
4. Copy any other immediately required customizations from the old version to the new one (for example
if you are not running Confluence on the default ports or if you manage users externally, you'll need to
update / copy the relevant files - find out more in Upgrading Confluence Manually)
5. Start Confluence, and and confirm that you can log in and view pages before continuing to the next
step.
You should now stop Confluence, and reapply any additional customizations from the old version to the new
version, before upgrading the remaining nodes.

4. Upgrade Synchrony (optional)

If you've chosen to let Confluence manage Synchrony for you (recommended), you don't need to do
anything. Synchrony was automatically upgraded with Confluence.
If you're running your own Synchrony cluster, you should:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 447

1. Grab the new synchrony-standalone.jar from the <local-home> directory on your upgraded
Confluence node.
2. Copy the new synchrony-standalone.jar to each of your Synchrony nodes, and start Synchrony
as normal.

5. Copy Confluence to remaining nodes

The next step is to replicate your upgraded Confluence directories to other nodes in the cluster.
1. Stop Confluence on the first node.
2. Copy the installation directory and local home directory from the first node to the next node.
If the path to the local home directory is different on this node, edit the confluence-init.propert
ies to point to the correct location.
3. Start Confluence, and and confirm that you can log in and view pages on this node.
4. Stop Confluence on this node before continuing with the next node.
Repeat this process for each remaining node.

6. Start Confluence and check cluster connectivity

Once all nodes have been upgraded you can start Confluence Data Center on each node, one at a time (sta
rting up multiple nodes simultaneously can lead to serious failures).
The Cluster monitoring console (

> General Configuration > Clustering) includes information about the active cluster nodes. When the
cluster is running properly, you should be able to see the details of each node.

Adding and Removing Data Center Nodes

Your Data Center license is based on the number of users in your cluster, rather than the number of nodes. This
means you can add and remove nodes from your Data Center cluster at any time.
If you deployed Confluence Data Center on AWS using the Quick Start, your Confluence and Synchrony nodes
will be in auto-scaling groups. You will add and remove nodes in the AWS console either by changing the
minimum and maximum size of each group or using a scaling plan.

Adding a node

To add a node:
1. Copy the installation directory and local home directory from the stopped node to your new node.
2. Start Confluence on your new node.
During the startup process Confluence will recover indexes from a running node to bring the new node up
to date.
3. Go to

> General Configuration > Clustering and check that the new node is visible.
You should only start one node at a time. Starting up multiple nodes simultaneously can cause serious failures.

Removing a node

To remove a node, stop Confluence on that node. You can then remove the installation and local home
directory as required.
To see the number of nodes remaining go to

> General Configuration > Clustering.

Changing the node identifier

Confluence generates an identifier for each node in your cluster. You can use the confluence.cluster.nod
e.name system property to set the node identifier on each node so that it's easier for your users and

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 448

administrators to read.
See Configuring System Properties for more information on how to set the system property.
Change Node Discovery from Multicast to TCP/IP

If you're setting up Confluence Data Center for the first time, it'll step you through the process of choosing your
discovery mode and adding cluster nodes. If you decide to change node discovery for the cluster, you'll need to
edit the confluence.cfg.xml file in the local home directory of each cluster node.

Before you make any changes, shut down all nodes in your cluster
Make sure the discovery configuration is exactly the same for each node (make the same
changes to the confluence.cfg.xml file in each local home directory)
Always back up your site before making changes to these files.

The changes you need to make may differ slightly, depending on whether you've upgraded from an older version
of Confluence Data Center or if you've started with version 5.9. We've detailed both methods, below.

To change from multicast to TCP/IP

Look for the following two lines in the confluence.cfg.xml file:

<property name="confluence.cluster.address">[multicast IP]</property>

<property name="confluence.cluster.join.type">multicast</property>

If both lines exist in the file, change them to the lines below; where the confluence.cluster.address prope
rty exists, but there's no reference to the confluence.cluster.join.type property, update the first line and
add the second line as shown below.

<property name="confluence.cluster.peers">[node 1 IP],[node 2 IP],[node

3 IP]</property> <!-- A comma-separated list of node IP addresses,
without spaces -->
<property name="confluence.cluster.join.type">tcp_ip</property> <!--
accepted values are multicast or tcp_ip -->

Enter the address of each node, and separate each address with a comma. Make sure you remove the square
brackets from around the IP addresses.
You can now restart your cluster nodes.

To change from TCP/IP to multicast

To switch from TCP/IP to multicast, just perform the reverse of the changes outlined above.

Reference of properties in the confluence.cfg.xml file

key valid values notes

confluence.cluster.join.t 'multicast' or 'tcp_ip' Pre-5.9 Data Center installations

ype won't have this key. By default, if
the key is missing, Confluence will
choose multicast

confluence.cluster.addres a single multicast IP address This key is only used by

s confluence if confluence.clus
ter.join.type is set to multi
cast

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 449

confluence.cluster.peers a comma-separated string of IP There must be at least one

addresses (no spaces) address here. The addresses are
the IP address of each node in
the cluster. This key is only used
by confluence if confluence.cl
uster.join.type is set to tcp
_ip

Running Confluence Data Center in AWS

Confluence Data Center is an excellent fit for the On this page:
Amazon Web Services (AWS) environment. Not only
does AWS allow you to scale your deployment Deploying Confluence Data Center
elastically by resizing and quickly launching using the AWS Quick Start
additional nodes, it also provides a number of EC2 sizing recommendations
managed services that work out of the box with Supported AWS regions
Confluence Data Center instances and handle all Setting up an internal facing site
their configuration and maintenance automatically. with your own DNS server
Scaling up and down
Interested in learning more about the Connecting to your nodes over
benefits of Data Center? Check out our o SSH
verview of Confluence Data Center. Upgrading
Backing up
Migrating your existing Confluence
site to AWS

Deploying Confluence Data Center using the AWS Quick Start

The simplest way to deploy your entire Data Center cluster in AWS is by using the Quick Start. The Quick
Start launches, configures, and runs the AWS compute, network, storage, and other services required to
deploy a specific workload on AWS, using AWS best practices for security and availability.
The Quick Start provides two deployment options, each with its own template. The first option deploys the
Atlassian Standard Infrastructure (ASI) and then provisions Confluence Data Center into this ASI. The
second option only provisions Confluence Data Center on an existing ASI.

Atlassian Standard Infrastructure (ASI)

The ASI is a virtual private cloud (VPC) that contains the components required by all Atlassian Data
Center applications. For more information, see Atlassian Standard Infrastructure (ASI) on AWS.

Here's an overview of the architecture for the Confluence Data Center Quick Start:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 450

The deployment consists of the following components:

One or more Amazon Elastic Compute Cloud (EC2) instances as cluster nodes, running Confluence,
in an auto scaling group.
One or more Amazon Elastic Compute Cloud (EC2) instances as cluster nodes, running Synchrony
(which is required for collaborative editing), in an auto scaling group.
An Amazon Application Load Balancer (ALB), both as load balancer and SSL-terminating reverse
proxy.
Amazon Elastic File System (EFS) server for the shared home directory which contains attachments
and other files accessible to all Confluence nodes.
An Amazon Relational Database (RDS) PostgreSQL instance as the shared database.
For more information on the architecture, components and deployment process, see our Quick Start Guide.

Confluence will use the Java Runtime Engine (JRE) that is bundled with Confluence
(/opt/atlassian/confluence/jre/), and not the JRE that is installed on the EC2 instances
(/usr/lib/jvm/jre/).

Use the Quick Start as is or develop your own

To get you up and running as quickly as possible, the Quick Start doesn't allow the same level of
customization as a manual installation. You can use our templates either as is, or as a reference for creating
your own template.

EC2 sizing recommendations

The Quick Start uses c3.xlarge instances by default for Confluence and Synchrony nodes. The instance type
is up to you, but it must meet Confluence's system requirements. Smaller instance types (micro, small,
medium) are generally not adequate for running Confluence.

Supported AWS regions

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 451

Not all regions offer the services required to run Confluence. You'll need to choose a region that supports
Amazon Elastic File System (EFS). You can currently deploy Confluence using the Quick Start in the
following regions:
Asia Pacific (Sydney)
EU (Frankfurt)
EU (Ireland)
US East (North Virginia)
US West (Oregon)
The services offered in each region change from time to time, so check the Regional Product Services table
in the AWS documentation to see if your preferred region is supported yet.

If you are deploying Confluence 6.3.1 or earlier....

There is an additional dependency for Confluence versions earlier than 6.3.2. Synchrony (which is
required for collaborative editing) uses a third party library to interact with the Amazon API, and the
correct endpoints are not available in all regions. This means you can't run Synchrony in the following
regions:
US East (Ohio)
EU (London)1
Asia Pacific (Mumbai)1
Asia Pacific (Seoul)1
Canada (Central)1

1 At the time of writing, these regions did not yet support EFS, so also can't be used to run Confluence.

Setting up an internal facing site with your own DNS server

If you want to deploy an internal facing Confluence site, using your own DNS server, you can use Amazon
Route 53 to create a link between the public DNS and internal DNS.
1. In Route 53, create a Private hosted zone. For the VPC, you can use the existing Atlassian Services
VPC. The domain name is your preferred domain.
2. If you've already set up Confluence, go to Services > CloudFormation in the AWS console, select
the stack, and click Update Stack. (If you're setting up Confluence for the first time, follow the Quick
Start template as below).
3. Under Other Parameters, enter the name of your hosted zone in the Route 53 Hosted Zone field.
4. Enter your preferred sub-domain or leave the Sub-domain for Hosted Zone field blank and we'll use
your stack name as the sub-domain.
5. Follow the prompts to update the stack. We'll then generate the load balancer and EFS url, and create
a record in Route 53 for each.
6. In Confluence go to

> General Configuration and update the Confluence base URL to your Route 53 domain.
7. Set up DNS resolution between your on-premises network and the VPC with the private hosted zone.
You can do this with:
a. an Active Directory (either Amazon Directory Service or Microsoft Active Directory)
b. a DNS forwarder on EC2 using bind9 or Unbound.
8. Finally, terminate and re-provision each Confluence and Synchrony node to pick up the changes.

Scaling up and down

To increase or decrease the number of Confluence or Synchrony cluster nodes:

1. Go to Services > CloudFormation in the AWS console, select the stack, and click Update Stack.
2. Change the Minimum number of cluster nodes and Maximum number of cluster nodes paramete
rs as desired.
It may take several minutes for the Auto Scaling Group to detect and apply changes to these parameters.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 452

Unless you specify the same number for Minimum and Maximum number of cluster nodes, the Auto
Scaling Group will launch new cluster nodes and terminate existing ones automatically to achieve the optimal
desired number of nodes between these two limits. By default, this target number is determined by the
following CloudWatch metrics:
If the average CPU utilization across the Auto Scaling Group exceeds 60% for 5 minutes, the target
number of nodes increases by one (up to the Maximum).
If the average CPU utilization across the Auto Scaling Group is lower than 40% for 30 minutes, the
target number of nodes decreases by one (down to the Minimum).
A default "cooldown" period of 10 minutes between scaling events is also applied. See Scaling Based on
Metrics for more information.

Note: Adding new cluster nodes, especially automatically in response to load spikes, is a great
way to increase capacity of a cluster temporarily. Beyond a certain point, adding large numbers of
cluster nodes will bring diminishing returns. In general, increasing the size of each node (i.e.,
"vertical" scaling) will be able to handle a greater sustained capacity than increasing the number
of nodes (i.e., "horizontal" scaling), especially if the nodes themselves are small.

See the AWS documentation for more information on auto scaling groups.

Connecting to your nodes over SSH

It is possible to SSH to your cluster nodes and file server to perform configuration or maintenance tasks.
Note that you must keep your SSH private key file (the PEM file you downloaded from Amazon and specified
as the Key Name parameter) in a safe place. This is the key to all the nodes in your instance, and if you lose
it you may find yourself locked out.

Note: the ConfluenceDataCenter.template deploys all EC2 instances in the Subnets specified
by the Internal subnets parameter. If you have specified Internal subnets that are completely
unreachable from outside, then you may need to launch an EC2 instance with SSH running and
accessible in one of the the External subnets, and use this as a "jump box" to SSH to any
instances in your Internal subnets. That is, you SSH first to your "jump box", and from there to
any instance deployed in the Internal subnets.

When connecting to your instance over SSH, use ec2-user as the user name, for example:

ssh -i keyfile.pem [email protected]

The ec2-user has sudo access. SSH access is by root is not allowed.

Upgrading

To upgrade a Confluence Data Center instance launched from ConfluenceDataCenter.template:

1. In the AWS console, Update Stack
2. Change the size of the Confluence and Synchrony auto scaling groups (maximum and minimum) to 0.
This will terminate all running nodes.
3. Once the update is complete, check that all EC2 nodes have been terminated.
4. In the AWS console, Update Stack.
5. Change the Confluence Version to the version you want to upgrade to.
6. Change the size of the Confluence and Synchrony auto scaling groups (maximum and minimum) to 1.
Do not add more than one node until after the upgrade is complete.
7. Access Confluence in your browser. Any upgrade tasks will run at this point.
8. Confirm that Confluence and Synchrony are both running successfully, and that you are running the
new version (check the footer).
9. In the AWS console, Update Stack.
10. Change the maximum Confluence nodes and Maximum Synchrony nodes to your usual auto scaling
group size.
11. Confirm that your new nodes have joined the cluster.
Confluence Data Center in AWS currently doesn't allow upgrading an instance without some downtime in
between the last cluster node of the old version shutting down and the first cluster node on the new version

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 453

starting up.
You must make sure all existing nodes are terminated before launching new nodes on the new version.

Backing up

We recommend you use the AWS native backup facility, which utilizes snap-shots to back up your
Confluence Data Center.

Migrating your existing Confluence site to AWS

To migrate an existing Confluence instance to AWS:

1. Upgrade your existing site to the version you have deployed to AWS (Confluence 6.1 or later).
2. Migrate your database to PostgreSQL (if you're not already using Postgres). See Migrating to Another
Database.
3. Back up your PostgreSQL database and your existing <shared-home>/attachments directory.
4. Copy your backup files to /media/atl/confluence/shared-home in your EC2 instance.
5. Restore your PostgreSQL database dump to your RDS instance with pg_restore.
See Importing Data into PostgreSQL on Amazon RDS in Amazon documentation for more information
on how to do this.
Notes:
When you create a cluster using the CloudFormation template, the database name is confluence.
You must maintain this database name when you restore, or there will be problems when new
nodes are provisioned. You will need to drop the new database and replace it with your backup.
You don't need to copy indexes or anything from your existing local home or installation directories,
just the attachments from your existing shared home directory.
If you've modified the <shared-home>/config/cache-settings-overrides.properties file
you may want to reapply your changes in your new environment.
The _copy method described in this AWS page, Importing Data into PostgreSQL on Amazon RDS, is
not suitable for migrating Confluence.

Getting started with Confluence Data Center on Azure

Confluence Data Center is an excellent fit for the Microsoft Azure environment. We provide a reference template
that lets you deploy Confluence Data Center in Microsoft Azure, and you can then configure it depending on
your organization's Azure best practices. It's the fastest way to get everything you need to run Confluence Data
Center up and running in Azure.
We strongly recommend you set up user management, central logging storage, a backup strategy, and
monitoring, just as you would for a Confluence Data Center installation running on your own hardware.

How it works

Here's an architectural overview of what you'll get when deploying Confluence Data Center using the template:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 454

The deployment consists of the following components:

One or more Azure standard Linux VM instances as cluster nodes, running Confluence, in a scale set
Azure SQL Server or PostgreSQL database
a storage account for the shared home directory which contains attachments and other files accessible to
all Confluence nodes (local redundant storage)
an application gateway (multiple instances for high availability)
a small Azure Linux VM to use as a bastion host (to access cluster nodes via SSH).
The Azure SQL database is private and only accessible via a database service endpoint from the Confluence
application nodes.
The application gateway acts as load balancer for your scale set of Confluence nodes and web application
firewall.
We use a storage account for Confluence's shared home directory. It's mounted on each Confluence node, and
treated as any other file store would be.
Synchrony will be managed by Confluence (on Confluence nodes). This means you don't need to provision or
configure anything to be able to enable collaborative editing.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 455

Limitations

There are some limitations you should be aware of before deciding to deploy to Azure:
Autoscaling is not yet available, due to a problem with Hazelcast, which Confluence uses to discover
nodes.
You can't use the deployment template to upgrade an existing Confluence deployment, or to provision
new nodes running a different version to the rest of your cluster.
If a node is deleted manually, it can't be redeployed without first removing the cluster. The existing
database, and the existing shared home directory won't be removed when redeploying.

Deploying Confluence Data Center to Azure via Azure marketplace

This method uses the Azure Marketplace to deploy Confluence Data Center using our deployment templates as
a reference.
To deploy Confluence Data Center to Azure using our Marketplace app:
1. Log in to Azure Portal
2. Choose Create a resource to start a new deployment
3. Search for Atlassian then select Confluence Data Center from the list of Marketplace apps
4. Choose Create to start configuring the deployment
5. Follow the prompts in the wizard to configure your deployment. Refer to the parameters table below for
more information.
6. Confirm all the details are correct then click Create to purchase the subscription. Deployment will take
about 30 minutes.
7. Once deployment is complete, go to the Confluence URL (APPENDPOINT) listed in the deployment
outputs to complete onboarding and start using Confluence.

Parameters

Parameters Description

Subscription Your Microsoft Azure subscription type.

Resource group If you have an existing resource group, you can use
it, or create a new one.

Location This is the region where Azure will house your

deployment.

Confluence Version Specify the version of Confluence you'd like to install

in full. For example 6.14.0. Head to Confluence
Release Notes for a list of all releases.

Confluence admin credentials Provide a name and password for the initial
Confluence administrator on your instance.

Confluence Cluster Select the expected size of your site - trial, small,
medium, large, extra large. This will determine the
number of Confluence application nodes, and the
size of VMs to be provisioned. Choose Change Size
to override the defaults.

Database type Choose either a SQL Server or PostgreSQL

database.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 456

Database credentials Provide a username and password for the database

admin user.
If you have an existing database in the same
location and resource group, you can choose to use
your existing database, and enter its details here.

SSH Access Provide an SSH public key to be used to SSH into

the instance that will act as bastion host, and a
username and password for SSH access to the
Confluence nodes.
See Create and use an SSH public-private key pair
for Linux VMs in Azure in the Microsoft Azure
documentation.

CNAME This is the Canonical Name record (CNAME) for

your organization. If you don't provide one, Azure
will generate a random sub domain for your
instance.

HTTP/SSL Provide the certificate and password to be used for

SSL termination on the Azure Application Gateway.

Monitoring Choose the monitoring and analytics services that

you would like to enable. Subject to availability in
your location.

Deploying Confluence Data Center to Azure using the CLI

This method uses the Azure command line interface to deploy Confluence Data Center using our deployment
templates as a reference. You'll need to install the Azure CLI to do this.
Using the deployment templates directly allows for greater configuration granularity. All hardware choices such
as the number of cluster nodes, size, disk size, and OS type are configurable as parameters. Check out the Dev
eloping guide in the template repository to learn more about developing the templates.
To deploy Confluence Data Center to Azure using the command line interface:
1. Download the azuredeploy.json template file and azuredeploy.parameters.json parameters
file from the Confluence directory on https://bitbucket.org/atlassian/atlassian-azure-deployment.
2. Edit the azuredeploy.parameters.json parameters file, and insert values for the following
required parameters:
Cluster size
SSH password (for the cluster nodes)
Database password
Confluence administrator account password
See the table below for more information on each of these required values.

The template applies sensible defaults for a number of other parameters, including the size of your VMs
and database instance. You can choose to override these defaults if you want to specify particular
values.
3. Log in to Azure via the command line interface.
4. Create a resource group. This will be the container for the Confluence resources you deploy.

az group create --name ConfluenceDataCenter --location "Central US"

5. Create a new deployment, and specify the Confluence Data Center template file and parameters file.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
5. 6.15 Documentation 457

az group deployment create \

--name ConfluenceDataCenterDeployment \
--resource-group ConfluenceDataCenter \
--template-file azuredeploy.json \
--parameters azuredeploy.parameters.json

6. Log in to the Azure Portal to see the deployment outputs. The Application URL is the URL for your new
Confluence site.
7. Go to the Application URL in your browser to complete onboarding and start using Confluence.

Required parameters

The deployment template requires a number of values to be provided in order to deploy your Confluence Data
Center instance.

Parameter Description

confClusterSize To use recommended hardware options for the

Confluence installation choose a size. Allowed
values:
trial
small
medium
large
enterprise
If set, all further Gateway, VM, DB size parameters
will be ignored.

clusterSshPassword This is the SSH password you'll use to access your

Confluence nodes.

dbPassword This the password for your dedicated database user.

The password must meet a strong password
requirement (imposed by AzureSQL Server): it must
be between 16 and 41 characters long, and must
contain at least one uppercase letter, one lowercase
letter, one number (0-9), and one non-alphanumeric
character (., !, $, #, %, etc). See the Azure SQL
password documentation for details.

confAdminUserPassword This is the password for your Confluence

administrator's account.

Optional parameters

The following parameters are optional. If you don't provide a value in the parameter file, we'll use the default
values listed below.

Parameter Default value Description

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 458

confluenceVersion Latest This is the version of Confluence

you want to install on your cluster
nodes. Enter the Confluence
version number in full, for
example "6.14.0".
We don't recommend using
versions prior to 6.12, as they
don't support managed
Synchrony.

customDownloadUrl empty Use this URL to override standard

Atlassian download url, for
example to specify beta, release
candidate or EAP versions. Used
in conjunction with the
confluenceVersion parameter.

dbCreateNew true Create a new database or attempt

to use an existing specified
database. Note that this has to be
in same resource group and
location as the target deployment.

dbType Azure SQL DB Choose between Azure SQL

Server and Azure DB for
PostgreSQL.

dbHost auto-generated The hostname of database server

to be used if an external database
is being used. This will be
autogenerated if a new database
is to be created.

dbPort 1433 The database port to use if an

external database is being used.
This will be autogenerated if a
new database is to be created.

dbDatabase confdatabase The database name to use if an

external database is being used.
This will be autogenerated if a
new database is to be created.

dbSchema auto-generated The database schema to use if an

external database is being used.
This will be autogenerated if a
new database is to be created.

dbUsername confluencedbuser The username for the dedicated

database user.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 459

cname auto-generated This is the Canonical Name

record (CNAME) for your
organization. If you don't provide
one, Azure will generate a
random domain.
If you do use a custom domain,
you must also update your
Domain Registrar's settings to
add the Azure DNS Name
Servers. Consult your domain
registry's documentation on how
to configure cname records.

sslBase64EncodedPfxCertificate The certificate to be used for SSL

termination on the Azure
Application Gateway.

sslPfxCertificatePassword The certificate password to be

used for SSL termination on the
Azure Application Gateway.

jumpboxSshKey The SSH public key to use to

access the bastion host (jumpbox)

confAdminUserName admin The username for the Confluence

Administrator's account. Must be
lowercase.

confAdminUserFullName Admin Admin The full name of the Confluence

Administrator's account.

confAdminUserEmail [email protected] The email address of the

Confluence Administrator user.

confAppTitle Atlassian Confluence The name of your Confluence

site.

jumpboxSshUser confluenceadmin This is the SSH user you'll use to

access the bastion host
(jumpbox).

clusterSshUser confluenceadmin The SSH username to use to

access the Confluence nodes
from the bastion host (jumpbox).
This is the only way you can
access Confluence nodes.

enableEmailAlerts true Enable email alerts.

enableApplicationInsights true Enable Azure Application Insights.

enableAnalytics true Enable Azure Operational

Insights.

Overriding the recommended hardware options

The confClusterSize parameter allows you to select the size of your deployment, and then use our
recommendations for all resources to be created.
If you choose not to set the confClusterSize parameter, you can choose to define your own values for things
like dbTier, dbTierSize, clusterVmSize, LinuxOsType, and appGtwyTier.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 460

These parameters are all listed in the azuredeploy.json template file, with a description and allowed values.
You should also check out the Developing guide in the template repository to learn more about developing your
own template.

Monitoring

As a number of the resources we provision are managed by Azure, a number of options are available for
monitoring. For example:
A number of default alerts are available, such as cluster nodes going offline, CPU, or Db DTU exceeding
80%. These alerts will be emailed to the Confluence Administrator email address specified in the
deployment.
Application Insights can be used to see the overall system health, and dig into particular areas of interest
Application Insights in the Azure documentation.
Azure SQL Analytics is available for more granular monitoring of your SQL Server database. Monitor
Azure SQL Database using Azure SQL Analytics in the Microsoft Azure documentation.
Note that some of these resources are still in Preview, so may not be available in your location yet.
Administering Confluence Data Center on Azure

Once you've deployed Confluence Data Center to Azure using the deployment template, administering the
application is similar to managing an application on your own hardware, with the exception that you'll need to go
via the bastion host (jumpbox) to access your nodes.
To access your jumpbox and nodes you'll need:
the SSH credentials you provided during setup,
the Confluence node credentials you provided during setup
the public DNS name or IP address of your jumpbox (you can obtain this through the Azure portal via Me
nu > Resource groups > <your resource group> > confluencenat), and
the node IP addresses, listed against the confluencecluster (instance n) row in Connected
devices. (You can obtain this through the Azure portal via Menu > Resource groups > <your resource
group> > confluencevnet).

Connecting to your Azure jumpbox over SSH

You can SSH into your Confluence cluster nodes, Synchrony nodes and shared home directory to perform
configuration or maintenance tasks. Note that you must keep your SSH public key file in a safe place. This is the
key to your jumpbox, and therefore all the nodes in your instance.
Access the jumpbox via a terminal or command line using:

$ ssh JUMPBOX_USERNAME@DNS_NAME_OR_IP_ADDRESS

You can find the SSH URL in the outputs section of your deployment.
Once you've accessed the jumpbox, we can jump to any of the nodes in the cluster, using:

$ ssh NODE_USERNAME@NODE_IP_ADDRESS

You'll then be asked for your node password - after providing this, you should be connected to the node.

Accessing your configuration files

For your Azure deployment, you may need to make changes to some configuration files, just as you would for a
deployment on your own hardware:
your server.xml lives in /opt/atlassian/confluence/conf
your setenv.sh lives in /opt/atlassian/confluence/bin
your local home confluence.cfg.xml lives in /var/atlassian/application-data/confluenc
e

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 461

your shared home confluence.cfg.xml lives in /media/atl/confluence/shared

These files are only accessible from the existing nodes. The shared home is mounted (think of it as a network
hard disk) on each node under /media/atl/confluence/shared. So from an existing node (when you're
logged in through SSH), you can go to /media/atl/confluence/shared.

If modifications to these files are made manually, new nodes will not pick up those modifications. You can either
repeat the modifications on each node, or change the templates in the /media/atl/confluence/shared dir
ectory from which those files are derived. The mappings are:
the server.xml file is derived from /media/atl/confluence/shared/server.xml
the setenv.sh file is derived from /media/atl/confluence/shared/setenv.sh
the local home confluence.cfg.xml is derived from /media/atl/confluence/shared/home-co
nfluence.cfg.xml
the shared home confluence.cfg.xml is derived from /media/atl/confluence/shared/shared
-confluence.cfg.xml
These template files contain placeholders for values that are injected via the deployment script. Removing or
changing them may cause breakages with the deployment. In most cases, these files should not be modified, as
a lot of these settings are produced from the Azure Resource Manager templates automatically.

Backing up

We recommend you use the Azure native backup facility, which utilizes snapshots to back up
your Confluence Data Center instance.

Migrating your existing content into Azure

To migrate content from an existing site into your Confluence Data Center site on Azure you will need to take a
full site export, and then import it into your new Confluence site.
See Manually Backing Up the Site for information on how to export your site, and Restoring a Site for information
on how to import it into your new site on Azure.
Make sure you have the Administrator account credentials for your existing site, as the administrator account
you created during Azure deployment process will be overwritten by the export, and you may be locked out of
your site.

Upgrading Confluence in Azure

The process of upgrading Confluence is the same as if you were running the cluster on your own hardware. You
will stop Confluence on all nodes, upgrade one node, stop that node then copy the installation directory across
to each remaining node in the cluster, before restarting each node, one at a time.
See Upgrading Confluence Data Center for more details.

You can't use the confluenceVersion parameter in the deployment template to upgrade an existing
Confluence deployment, or to provision new nodes running a different version to the rest of your cluster.
You also can't do a rolling upgrade. You will need to bring all nodes down before upgrading.

Upgrading your operating system

If you need to upgrade the operating system running on your Confluence nodes, you will need to SSH into each
node, perform a sudo apt dist-upgrade (Ubuntu) and reboot each node.

As Confluence is running as a service it will be automatically restarted on reboot.

You can't simply reimage an instance, as you might do in Jira, due to the way Hazelcast discovers cluster
nodes.

Moving from Data Center to Server

This page outlines how to switch from Confluence Data Center (clustered) to Confluence Server (non-clustered).

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 462

In these instructions we'll assume that you'll use one of your existing cluster nodes as your new, non-clustered
installation.
You'll need a Confluence Server license to switch back to Server.

Before you begin, you must:

stop Confluence on all nodes except one (run as a single node)
turn off read-only mode (if it has been turned on).

1. Enter your Confluence server license

Your home directory (configured in confluence\WEB-INF\classes\confluence-init.properties)

should point to your local home directory.

1. Go to

> General Configuration

2. Choose License Details from the sidebar under the Administration heading
3. Enter your Confluence Server license key

2. Shut down Confluence

Stop any cluster nodes that are still running before proceeding. We also recommend configuring your load
balancer to redirect traffic away from Confluence.

3. Move items in the cluster shared home back to local home

1. Create a directory called /shared-home in the <local home> directory on one node (if you removed
this directory when installing Data Center)
2. Move the entire config directory from your <shared home> directory to the <local
home>/shared-home directory
3. Move the remaining contents of your <shared home> directory to the root of your <local home> direct
ory
Your cluster's shared home directory should now be empty.

4. Start Confluence

The setup wizard will guide you through the migration process.

To confirm you're now running the non-clustered edition, go to

> General Configuration. The 'Cluster Configuration' page should not appear. Instead you'll see
information about Confluence Data Center.

Installing Java for Confluence

This page contains instructions for installing the Java Development Kit (JDK). This is a manual step that's only
required if you're installing Confluence from a zip or archive file.
If you're using the Confluence installer, you don't need to install Java manually, but you can choose to use a
different Java vendor.
Check the Supported Platforms page to find out which Java versions and vendors can be used with Confluence.

Installing Java

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 463

The JDK (Java Development Kit) needs to be installed on the same server that will have Confluence installed.
We support running Confluence with the JDK or JRE (Java Runtime Environment). These instructions will just
cover installing the JDK.
Installing the JDK on Windows...
Before you start, go to Control Panel > Programs and Features to check whether a JDK is already
installed.
To install the JDK on Windows:
1. Download the appropriate AdoptOpenJDK or Oracle JDK version.
Check the Supported Platforms page to find out which JDK / JRE versions and vendors are supported
for your version of Confluence. Be sure to download the right one for your operating system.
2. Run the Java installer. Make a note of the installation directory, as you'll need this later.
3. Once the Java installation is complete, check that the JAVA_HOME environment variable has been set
correctly.
Open a command prompt and type echo %JAVA_HOME% and hit Enter.
If you see a path to your Java installation directory, the JAVA_Home environment variable has
been set correctly.
If nothing is displayed, or only %JAVA_HOME% is returned, you'll need to set the JAVA_HOME env
ironment variable manually. See Setting the JAVA_HOME Variable in Windows for a step by
step guide.

Installing the JDK on Linux...

Before you start, check whether a JDK is already installed. Open a shell console and type echo
$JAVA_HOME and hit Enter.

If it returns something like/opt/JDK8 or /usr/lib/jvm/java8, then your JDK is installed and

properly configured.
If nothing is displayed, you'll need to install the JDK or set the $JAVA_HOME environment variable.
You can set this environment variable in your user account's 'profile' file. Alternatively, you can set this
after installing Confluence, by defining this path in your Confluence installation's setenv.sh file,
usually located in the Confluence bin directory.

To install the JDK on Linux:

1. Download the appropriate AdoptOpenJDK or Oracle JDK version.
Check the Supported Platforms page to find out which JDK / JRE versions are supported for your
version of Confluence. Be sure to download the right one for your operating system.
2. Run the Java installer.
3. Open a shell console and type echo $JAVA_HOME and hit Enter to check that it has installed correctly
(see notes above).
Note: Any Java or JDK version numbers on this page are examples only. Please refer to the Supported
Platforms page for supported versions of Java.
Setting the JAVA_HOME Variable in Windows
To install Confluence manually on Windows, you will need to set an Related pages
environment variable to point Confluence to the your Java installation
directory. Starting
Tomcat as
a Windows
This information is only relevant if you're installing Confluence Service
manually on a Windows server. If you're using the installer, you
don't need to do this. Installing
Confluenc
e in Linux
In most cases you should set the JRE_HOME environment variable, but if it
is not set, Confluence will use JAVA_HOME.

Set the JAVA_HOME Variable

To set the JRE_HOME or JAVA_HOME variable:

1. Locate your Java installation directory

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 464
1.

If you didn't change the path during installation, it'll be something like C:\Program
Files\Java\jdk1.8.0_65
You can also type where java at the command prompt.

2. Do one of the following:

Windows 7 – Right click My Computer and select Properties > Advanced
Windows 8 – Go to Control Panel > System > Advanced System Settings
Windows 10 – Search for Environment Variables then select Edit the system environment
variables
3. Click the Environment Variables button.
4. Under System Variables, click New.
5. In the Variable Name field, enter either:
JAVA_HOME if you installed the JDK (Java Development Kit)
or
JRE_HOME if you installed the JRE (Java Runtime Environment)
6. In the Variable Value field, enter your JDK or JRE installation path .

If the path contains spaces, use the shortened path name. For example, C:\Progra~1\Jav
a\jdk1.8.0_65

Note for Windows users on 64-bit systems

Progra~1 = 'Program Files'
Progra~2 = 'Program Files(x86)'

7. Click OK and Apply Changes as prompted

You'll need to close and re-open any command windows that were open before you made these changes, as
there's no way to reload environment variables from an active command prompt. If the changes don't take
effect after reopening the command window, restart Windows.

Set the JAVA_HOME variable via the command line

If you would prefer to set the JAVA_HOME (or JRE_HOME) variable via the command line:
1. Open Command Prompt (make sure you Run as administrator so you're able to add a system
environment variable).
2. Set the value of the environment variable to your JDK (or JRE) installation path as follows:

setx -m JAVA_HOME "C:\Progra~1\Java\jdk1.8.0_XX"

If the path contains spaces, use the shortened path name.

3. Restart Command Prompt to reload the environment variables then use the following command to
check the it's been added correctly.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 3.
Confluence 6.15 Documentation 465

echo %JAVA_HOME%

You should see the path to your JDK (or JRE) installation.

Change the Java vendor or version Confluence uses

When you install Confluence Server using the installer, it will run Confluence with the Java Runtime Engine
(JRE) that was bundled with that Confluence release.
If you want to use a different Java vendor, version, or you want to install the full JDK, you can tell Confluence to
use the version of Java installed on your server.
Not all vendors and versions are supported, and some versions have known issues, so always check the Suppor
ted Platforms page, as using an unsupported version can cause problems in Confluence.

On this page:
Check your current setup
Installer method - Windows
Installer method - Linux
Environment variable method - Windows and Linux
How Confluence determines which Java to use
Which Java vendor can I use with my Confluence version?
Known issues
Upgrading Java

Check your current setup

How you change Confluence's Java path depends on whether you originally installed Confluence using the
installer, or manually from a .zip or .tar.gz file.
The easiest way to check how Confluence is currently finding your Java is to:
1. Go to <install-directory>/bin/setjre.sh file (Linux) or setjre.bat (Windows) file.
2. Scroll to the bottom of the file and look for a line similar to the following. The file path may be different in
your file.
In Linux:

JRE_HOME="/opt/atlassian/confluence/jre/"; export JRE_HOME

In Windows:

SET "JRE_HOME=C:\Program Files\Atlassian\Confluence\jre"

If a line similar to the one above is present, then JRE_HOME is set in this file by the installer, and you should
use the installer method for Windows or Linux below.
If this line isn't present, JRE_HOME is not set in this file (because Confluence was installed manually), and you
should use the environment variable method below.

Installer method - Windows

The way you do this depends on whether you run Confluence manually using the start-confluence.bat file
, or as a Windows service.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 466

In these examples we're going to point Confluence to the AdoptOpenJDK JRE, which is installed on our
Windows server at C:\Program Files\AdoptOpenJDK\jdk8u192-b12\jre. The location of your JRE will be
different, but the steps are the same for any supported Java vendor and version.

If you start Confluence manually

To change the Java that Confluence uses if you start Confluence manually in Windows:
1. In Command Prompt, use the following command to check that Java is installed and has been added to
your path correctly.

> java -version

This will return your Java version. If nothing is returned, or it returns the wrong version, check the
installation instructions for your Java vendor.
2. Stop Confluence.
3. In the Confluence installation directory edit the <install-directory>/bin/setjre.bat file
and change the last line to point to your local Java installation, as in the example below.

SET "JRE_HOME=C:\Progra~1\AdoptOpenJDK\jdk8u192-b12\jre"

If this line isn't present, exit this file and use the environment variable method below.
4. Start Confluence.
5. Go to

> General Configuration > System Information and check that Confluence is using the expected Java
version.
Remember, when you next upgrade Confluence this file will be overwritten, so you will need to re-apply this
change to the new setjre.bat file.

If you run Confluence as a Windows service

To change the Java that Confluence uses if you run Confluence as a Windows service:
1. Open the Tomcat properties dialog. See How to set system properties for Confluence running as a
service on Windows for a step-by-step guide to locating your service and launching the Tomcat dialog.
2. Choose the Java tab.
3. Update the Java Virtual Machine line to point to the AdoptOpenJDK jvm.dll, as in the example
below. The path to your Java installation will be different to our example.

C:\Program Files\AdoptOpenJDK\jdk8u192-b12\jre\bin\server\jvm.dll

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 467

4. Restart the Confluence Windows Service.

5. Go to

> General Configuration > System Information and check that Confluence is using the expected Java
version.
Remember, when you next upgrade Confluence this file will be overwritten, so you will need to re-apply this
change to the service.

Installer method - Linux

In this example we're going to point Confluence to the AdoptOpenJDK JRE, which is installed on our Linus
server at /opt/java/adoptopenjdk/jdk8u192-b12/. The location of your JRE will be different, but the steps are the
same for any supported Java vendor and version.
To change the Java that Confluence uses in Linux:
1. In Terminal, use the following command to check that Java is installed and added to your path correctly.

$ java -version

This will return your Java version. If nothing is returned, or it returns the wrong version, see Installing Java
for Confluence or check the installation instructions for your Java vendor.
2. Stop Confluence.
3. In the Confluence installation directory edit the <install-directory>/bin/setjre.sh file
and change the last line to point to your local Java installation, as in the example below.

The path to your Java installation will be different to our example.

JRE_HOME="/opt/java/adoptopenjdk/jdk8u192-b12/"; export JRE_HOME

If this line isn't present, exit this file and use the environment variable method below.
4. Start Confluence.
5. Go to

> General Configuration > System Information and check that Confluence is using the expected Java
version.
Remember, when you next upgrade Confluence this file will be overwritten, so you will need to re-apply this
change to the new setjre.sh file.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 468

Environment variable method - Windows and Linux

If you installed Confluence manually (the path to the bundled JRE was not automatically set in the setjre file),
Confluence will use the path set in the JRE_HOME environment variable. If JRE_HOME is not set, it will use the
path set in JAVA_HOME.
See Setting JAVA_HOME variable for Confluence to find out how to set this environment variable in Windows.
Refer to the documentation for your Linux distribution to find out how to set an environment variable in Linux.
You won't need to update the JRE_HOME environment variable when you upgrade Confluence, but you will
need to update the path if you upgrade Java.

How Confluence determines which Java to use

The JRE_HOME set in the setjre file takes precedence. If you installed Confluence using the installer, this will
be automatically set to the Java version bundled with Confluence.
If JRE_HOME is not set in the setjre.bat or setjre.sh file, Confluence will use the JRE_HOME defined in
your environment or service. If it can't find JRE_HOME, it will use the JAVA_HOME environment variable.

Which Java vendor can I use with my Confluence version?

The following table lists the supported Java vendors, and whether Oracle or AdoptOpenJDK is bundled with
Confluence.

Confluence version Supported Java vendors Bundled Java vendor

6.6.12 and earlier Oracle JRE Oracle JRE

6.7.0 to 6.13.1, and Oracle JRE Oracle JRE

6.14.0

6.13.2 to 6.13.x, and Oracle JDK/JRE AdoptOpenJDK

6.14.1 and later AdoptOpenJDK

Known issues

You may find that Oracle is still listed as the vendor in System Information. This is a known issue in
Confluence which we hope to have resolved soon. The Java version will be reported correctly, so you can
use that to make sure Confluence is pointing to the right version.
AdoptOpenJDK does not include a required font configuration package, which may cause issues when
installing in Linux. See Confluence Server 6.13 or later fails with FontConfiguration error when installing
on Linux operating systems for information on how to install the required package manually.

Upgrading Java

If you choose not to use the bundled Java version, you will need to manually update Java from time to time, to
get access to new security fixes and other improvements.
Always check the Supported Platforms page before upgrading, for any known issues affecting particular Java
versions.
Creating a Dedicated User Account on the Operating System to Run Confluence
This step is optional if you are evaluating Confluence, but should be mandatory for Confluence installations
used in production. If you have used the Confluence installer on Linux, this user will be created automatically.
A dedicated user should be created to run Confluence, because Confluence runs as the user it is invoked under
and therefore can potentially be abused. For example:
If your operating system is *nix-based (for example, Linux or Solaris), type the following in a console:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 469

$ sudo /usr/sbin/useradd --create-home --comment "Account for running

Confluence" --shell /bin/bash confluence
If your operating system is Windows:
1. Create the dedicated user account by either:
Typing the following at the Windows command line:
> net user confluence mypassword /add /comment:"Account for running
Confluence"
(This creates a user account with user name 'confluence' and password 'mypassword'. You
should choose your own password.)
Opening the Windows 'Computer Management' console to add your 'confluence' user with
its own password.
2. (Optional) Use the Windows 'Computer Management' console to remove the 'confluence' user's
membership of all unnecessary Windows groups, such as the default 'Users' group.
If Windows is operating under Microsoft Active Directory, ask your Active Directory
administrator to create your 'confluence' account (with no prior privileges).
Ensure that the following directories can be read and written to by this dedicated user account (e.g.
'confluence'):
The Confluence Installation Directory, particularly these sub-directories:
logs
temp
work
Your Confluence Home directory.
See also Best Practices for Configuring Confluence Security.

Confluence Setup Guide

Before running the Confluence Setup Wizard, as On this page:
described below, you should have already 1. Start the setup wizard
completed installing Confluence. 2. Choose your installation type
and apps
When you access Confluence in your web browser
3. Enter your license key
for the first time, you will see the Confluence Setup
4. Production installation:
Wizard. This is a series of screens which will prompt
database configuration
you to supply some default values for your
5. Production installation: external
Confluence site. It will also offer some more
database
advanced options for setting up data connections
6. Production installation: load
and restoring data from a previous installation.
content
7. Production Installation: restore
1. Start the setup wizard data from backup
8. Set up user management
1. Start Confluence (if it is not already running) 9. Connect to your Jira application
For Windows, go to Start > Programs > Conf 10. Set up system administrator
luence > Start Confluence Server. account
Or, run the start-up script found in the bin fol 11. Setup is Complete
der of your installation directory:
start-confluence.bat for
Windows.
start-confluence.sh for
Linux-based systems.
2. Go http://localhost:8090/ in your browser
If you chose a different port during
installation, change '8090' to the port you
specified
If you see an error, check you are using the
port you specified during installation.

2. Choose your installation type and apps

In this step, you'll choose whether you want a trial or a production installation.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 470

Trial installation
Set up Confluence with the embedded H2 database, default settings and sample content to get you
started.
You'll need to migrate to a supported external database before using Confluence as a production
system. This option is recommended if you're just taking Confluence for a test drive.

Production installation
Set up Confluence with your own external database. This option is recommended for setting up
Confluence in a production environment.
If you've purchased a license bundle that includes Questions or Team Calendars for Confluence (or if you're
keen to try these apps) you can get the setup wizard to install these apps automatically.

3. Enter your license key

Follow the prompts to generate an evaluation license, or enter an existing license key. To retrieve an existing
license key head to my.atlassian.com, or to purchase a new commercial license go to my.atlassian.com/purc
hase.
If you selected a Trial installation in the previous step, Confluence will generate your license and then
create the embedded database. This will take a few minutes. Once complete, go to step 8 below.
If you selected a Production installation, go to the next step to set up your external database.

4. Production installation: database configuration

Next it's time to set up your database. Some things to consider:

Check the supported platforms list to confirm that your chosen database and version is supported.
See database configuration for information on setting up your database, including UTF-8 character
encoding requirements.
If you are using Confluence as a production system you must use an external database.
The embedded H2 database option is available for evaluating or demonstrating Confluence, but
should not be used for production use. If you choose this option, you'll need to migrate to an external
database later on.
Screenshot: Database configuration

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 471

5. Production installation: external database

Before you Start

Character encoding:
We strongly recommend that character encoding is consistent across your database,
application server and web application, and that you use UTF-8 encoding.
Before setting up your database, please read about configuring character encoding.
Database name: When creating a new external database, give it the name 'confluence'.

Choose how you want Confluence to connect to your database either via a direct JDBC connection or via a
server-managed datasource connection.
Screenshot: Connection options

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 472

Direct JDBC

This uses a standard JDBC database connection. Connection pooling is handled within Confluence.
Driver Class Name – The Java class name for the appropriate database driver. This will depend on
the JDBC driver, and will be found in the documentation for your database. Note that Confluence
bundles some database drivers, but you'll need to install the driver yourself if it is not bundled. See Dat
abase JDBC Drivers for details.
Database URL – The JDBC URL for the database you will be connecting to. This will depend on the
JDBC driver, and will be found in the documentation for your database.
User Name and Password – A valid username and password that Confluence can use to access your
database.
You will also need to know:
The size of the connection pool Confluence should maintain. If in doubt, just go with the default
provided.
What kind of database you're connecting to, so you can tell Confluence which dialect it needs to
use.

Datasource

This asks your application server (Tomcat) for a database connection. You will need to have configured a
datasource in your application server. For information about configuring an external database, see Database
Configuration.
Datasource Name - The JNDI name of the datasource, as configured in the application server.
Note: Some servers will have JNDI names like jdbc/datasourcename; others will be like java:co
mp/env/jdbc/datasourcename. Check your application server documentation.

You will also need to know:

What kind of database you're connecting to, so you can tell Confluence which dialect it needs to use.

6. Production installation: load content

We can help you get your new Confluence site started with some demonstration content (which you can
remove once you're up and running), or you can choose to proceed with an empty site. You'll need to create
a space in your new site before you can start adding content.
If you're migrating from another Confluence installation choose Restore from backup to import your existing
Confluence data.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 473

7. Production Installation: restore data from backup

This option allows you to import data from an existing Confluence installation as part of the setup process.
You'll need a manual backup file from your existing Confluence installation to do this (go to Backup and
Restore in the administration console of your existing Confluence site).
Screenshot: restore data options

There are two ways to restore your data - upload the file, or restore from a location on your file system.
Upload a backup file
This option will load the data from a zipped backup file. If your backup file is very large, restoring from
the file system is a better option. Follow the prompts to browse for your backup file. Ensure select Buil
d Index is selected so the search index is generated.
Restore a backup file from the file system
This option is recommended if your backup file is very large (100mb or more), or your backup file is
already on the same server.
Copy your XML backup file into the <confluence-home>/restore directory. Your backup file will
appear in the list. Follow the prompts to restore the backup. Ensure select Build Index is selected so
the search index is generated.
When the restore process has you'll be ready to log in to Confluence. The system administrator account and
all other user data and content has been imported from your previous installation.

8. Set up user management

You can choose to manage Confluence's users and groups inside Confluence or in a Jira application, such
as Jira Software or Jira Service Desk.
If you do not have a Jira application installed, or if you would prefer to set up external user
management later, choose Manage users and groups within Confluence.
If you have a Jira application installed, the setup wizard gives you the opportunity to configure the Jira
connection automatically. This is a quick way of setting up your Jira integration with the most common
options. It will configure a Jira user directory for Confluence, and set up application links between Jira
and Confluence for easy sharing of data. Choose Connect to Jira.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 474

9. Connect to your Jira application

Enter the following information:

Jira Base URL - the address of your Jira server, such as http://www.example.com:8080/jira/
or http://jira.example.com
Jira Administrator Login - this is the username and password of a user account that has the Jira
System Administrator global permission in your Jira application.

Confluence will also use this username and password to create a local administrator account which
will let you access Confluence if Jira is unavailable. Note that this single account is stored in
Confluence's internal user directory, so if you change the password in Jira, it will not automatically
update in Confluence.
Confluence Base URL - this is the URL Jira will use to access your Confluence server. The URL you
give here overrides the base URL specified in Confluence, for the purposes of connecting to the Jira
application.
User Groups - these are the Jira groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in your
Confluence license. The default user group name differs depending on your Jira version:
Jira 6.4 and earlier: jira-users.
Jira Software 7.x and later: jira-software-users
Jira Core 7.x and later: jira-core-users
Jira Service Desk 3.x and later: jira-servicedesk-users
Admin Groups – Specify one or more Jira groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 475

For full details and a troubleshooting guide, see Configuring Jira Integration in the Setup Wizard.

10. Set up system administrator account

The system administrator has full administrative power over your Confluence instance. This person will be
able to add more users, create spaces, and set further Confluence options. Please refer to the overview of
global permissions for more information.

Hint: If you are evaluating Confluence, set yourself as the administrator.

If you've delegated user management to a Jira application, we'll use the Jira system administrator account
you specified as Confluence's system administrator account.

11. Setup is Complete

That's it, Confluence is ready to go. Click Start to jump straight in to Confluence.
Choose Further Configuration if you want to go directly to the Administration Console and complete
administrator's tasks including configuring a mail server, adding users, changing the base URL and more.

Configuring Jira Integration in the Setup Wizard

This page describes the Connect to Jira step in the On this page:
Confluence setup wizard.
Connecting to a Jira application in
If you are already using a Jira application, you can the Setup Wizard
choose to delegate user management to Jira, Troubleshooting
instead of separately maintaining your users in
Confluence. Related pages:

You'll be able to specify exactly which groups in your User Management Limitations and
Jira app should also be allowed to log in to Recommendations
Confluence. Your license tiers do not need to be the Connecting to Crowd or Jira for
same for each application. User Management

It's possible to connect Confluence to Jira after Confluence Setup Guide

completing the setup process, but it's much quicker
and easier to set it up at this stage.
You can delegate Confluence's user management
to:
Jira 4.3 or later
Jira Core 7.0 or later
Jira Software 7.0 or later
Jira Service Desk 3.0 or later.

Connecting to a Jira application in the Setup Wizard

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 476

Enter the following information:

Jira Base URL - the address of your Jira server, such as http://www.example.com:8080/jira/
or http://jira.example.com
Jira Administrator Login - this is the username and password of a user account that has the Jira
System Administrator global permission in your Jira application.

Confluence will also use this username and password to create a local administrator account which
will let you access Confluence if Jira is unavailable. Note that this single account is stored in
Confluence's internal user directory, so if you change the password in Jira, it will not automatically
update in Confluence.
Confluence Base URL - this is the URL Jira will use to access your Confluence server. The URL you
give here overrides the base URL specified in Confluence, for the purposes of connecting to the Jira
application.
User Groups - these are the Jira groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in your
Confluence license. The default user group name differs depending on your Jira version:
Jira 6.4 and earlier: jira-users.
Jira Software 7.x and later: jira-software-users
Jira Core 7.x and later: jira-core-users
Jira Service Desk 3.x and later: jira-servicedesk-users
Admin Groups – Specify one or more Jira groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 477

Troubleshooting

If you have trouble connecting Confluence to Jira, the following troubleshooting information should help you
get up and running.
If no users can log in to Confluence after you've completed the setup process, check that the people are
members of the Jira groups you specified. Only members of these groups will get the 'Can Use' Confluence
permission.

Error in the setup wizard Cause Solution

Failed to create application The setup wizard failed to complete Follow the steps below to rem
link, or registration of the peer-to-peer ove the partial configuration t
application link with Jira. Jira hen try the Connect to Jira
Failed to authenticate integration is only partially step again.
application link configured.

Failed to register Confluence The setup wizard failed to complete Follow the steps below to rem
configuration in Jira for shared registration of the client-server link ove the partial configuration th
user management with Jira for user management. The en try the Connect to Jira step
peer-to-peer link was successfully again.
created, but integration is only
partially configured.

Error setting Crowd The setup wizard successfully Fix the problem that prevented
authentication established the peer-to-peer link with the application from saving
Jira, but could not persist the the configuration file to disk
client-server link for user then follow the steps below to
management in your config.xml fil remove the partial
e. This may be caused by a problem configuration before trying the
in your environment, such as a full Connect to Jira step again.
disk.

Error reloading Crowd The setup wizard has completed the Restart Confluence. You
authentication integration of your application with should be able to continue
Jira, but is unable to start with the setup wizard. If this
synchronizing the Jira users with your does not work, contact Atlassi
application. an Support for help.

java.lang.IllegalStateException: The setup wizard has not completed Follow the steps below to rem
Could not create the the integration of your application ove the partial configuration a
application in Jira/Crowd with Jira. The links are only partially nd resolve any conflict with
(code: 500) configured. The problem occurred existing links then try the
because there is already a user Connect to Jira step again.
management configuration in Jira for
this <application> URL.

Removing a partial configuration

If you hit a roadblock, you'll need to log in to Jira and remove the partial integration before you can try again.
The specific steps will differ depending on your Jira application and version, but the essentials are the same
for all versions:
Log in to Jira as a user with system administrator permissions.
In the Administrator screens, go to Application Links.
Remove the application link that matches the base URL of your Confluence server.
In the User Management screens, go to Jira User Server.
Remove the link that matches the name and base URL of your Confluence server from the list of
applications that can use Jira for user management.
If you have multiple servers running on the same host...
If you're unable to tell which link matches your Confluence server because you have multiple
servers of the same type running on the same host you can check the application ID, which is

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 478

listed beside each server.

To find out the application ID of your new Confluence site, go to <baseUrl>/rest/applinks/1
.0/manifest (where <baseurl>is the base URL of your Confluence site). The application ID
will be listed in the <ID> element.

Return to the Confluence setup wizard and try the Connect to Jira step again.
If you're still unable to connect Jira and Confluence using the setup wizard, you may need to skip this step
and set up the links between Jira and Confluence manually once you've completed the Confluence setup
process. See Connecting to Crowd or Jira for User Management.

Upgrading Confluence
In this guide we'll run you through using the installer On this page:
to upgrade your Confluence site to the latest Before you begin
Confluence version on Windows or Linux. Plan your upgrade
1. Determine your upgrade
Upgrading to any later version is free if you have
path
current software maintenance. See our Licensing
2. Complete the
FAQ to find out more.
pre-upgrade checks
3. Upgrade Confluence in a
test environment
Upgrade Confluence
4. Back up
5. Download Confluence
6. Run the installer
After the upgrade
7. Copy your database
driver
8. Reinstall the service
(Windows only)
9. Re-apply any
Other ways to upgrade Confluence:
modifications
Manually – upgrade without using the 10. Update your reverse
installer. proxy and check you can
Data Center – upgrade your Data Center access Confluence
cluster. Troubleshooting

XML backups should not be used to upgrade

Confluence.

Before you begin

Before you upgrade Confluence, there's a few questions you need to answer.

Is installer the Tell me more...

right upgrade You can choose to upgrade using the installer, or manually using a zip or tar.gz
method for you? file. In most cases the installer is the easiest way to upgrade your Confluence
instance.
You will need to upgrade manually if:
you are moving to another operating system or file location as part of this
upgrade.
you are upgrading from Confluence 3.5 or earlier
you are upgrading from Confluence 5.6 or earlier and previously used the E
AR/WAR distribution to deploy Confluence into an existing application
server.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 479

Are you eligible to Tell me more...

upgrade? To check if software maintenance is current for your license, go to

> General Configuration > Troubleshooting and support tools and make
sure the license support period has not expired.

1. Software maintenance: upgrade at any time during this period.

If your support period has expired, follow the prompts to renew your license and
reapply it before upgrading.

Have our Tell me more...

supported Check the Supported Platforms page for the version of Confluence you are
platforms upgrading to. This will give you info on supported operating systems, databases
changed? and browsers.
Good to know:
The Confluence installer includes Java (JRE) and Tomcat, so you won't
need to upgrade these separately.
If you need to upgrade your database, be sure to read the upgrade notes for
the Confluence version you plan to upgrade to (and any in-between) to
check for any database configuration changes that you may need to make.

Do you need to Tell me more...

make changes to Newer Confluence versions sometimes require changes to your environment,
your such as providing more memory or adjusting your reverse proxy settings.
environment?
Good to know:
We use Upgrade Notes to communicate changes that will impact you, such as:
Changes to supported databases, memory requirements or other changes
that will impact your environment.
Features that have significantly changed or been removed in this release.
Actions you may need to take in your instance or environment immediately
after the upgrade.
It's important to read the notes for the version you're upgrading to and those
in-between. For example, if you are upgrading from 5.8 to 5.10 you should read
the upgrade notes for 5.9 and 5.10.

Plan your upgrade

1. Determine your upgrade path

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 480

Use the table below to determine the most efficient upgrade path from your current version to the latest
versions of Confluence.

Your Version Recommended upgrade path to Confluence 6

2.7 or earlier Upgrade to 2.7.4 then upgrade to 3.5.17, and follow paths below.

2.8 to 3.4 Upgrade to 3.5.17, and follow paths below.

3.5 Upgrade to 5.0.3 then upgrade to the latest version of Confluence 6.

4.0 to 4.3 Upgrade to 5.10.x then upgrade to the latest version of Confluence 6.

5.0 to 6.x Upgrade directly to the latest version of Confluence 6.

Confluence 6 is a major upgrade

Be sure to read the Confluence 6.0 Upgrade Notes, take a full backup, and test your upgrade in a
non-production environment before upgrading your production site.

Enterprise releases

An Atlassian Enterprise release is a feature release that gets backported security updates and critical bug
fixes during its entire two-year support window. If you can only upgrade once a year, consider upgrading to
an Enterprise release. Learn more

2. Complete the pre-upgrade checks

1. Check the Upgrade Notes for the version you plan to upgrade to (and any in between).

2. Go to

> General Configuration > Troubleshooting and support tools to run the health check (available
in Confluence 5.5 or later).

License expired?
If the software maintenance period included in your license has expired you can keep using
Confluence, but you'll need to renew before you can upgrade.
Go to

> General Configuration > License Details and follow the prompts to renew your license.
Still using the embedded database?
If you are using the embedded (trial) database you should migrate to a different database before
upgrading.
This database is supplied for evaluation purposes only and is not recommended for production
environments. See Embedded H2 Database for more information.
Database character encoding incorrect?
Database character encoding must be set to UTF+8 (or AL32UTF8 for Oracle databases). You will
not be able to upgrade to current Confluence versions unless you have the correct character
encoding.

3. Go to

> Manage apps and scroll down to the Confluence Update Check to check the compatibility of your
Marketplace apps.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 3.

Confluence 6.15 Documentation 481

4. Choose the version you plan to upgrade to then hit Check.

If you have incompatible add-ons...

If your users rely on particular Marketplace apps, you may want to wait until they are compatible
before upgrading Confluence. Vendors generally update their apps very soon after a major
release.
Good to know:
You can disable an app temporarily while you upgrade if it is not yet compatible.
Compatibility information for Atlassian Labs and other free apps is often not available
immediatley after a new release. In many cases the app will still work, so give it a try in a
test site before upgrading your production site.

3. Upgrade Confluence in a test environment

1. Create a staging copy of your current production environment.

See Create a staging environment for upgrading Confluence for help creating an environment to test
your upgrade in.

2. Follow the steps below to upgrade your test environment.

3. Test any unsupported user-installed apps, customizations (such as custom theme or layouts) and
proxy configuration (if possible) before upgrading your production environment.

Upgrade Confluence

4. Back up

1. Back up your database and confirm the backup was created properly.
If your database does not support online backups you'll need to stop Confluence first.

2. Back up your installation directory

The installer will completley replace this directory, so any files you've added (such as a keystore or
SSL certificate) won't be retained. The installation wizard will back up this directory before starting the
upgrade, but you should also back it up manually first.

3. Back up your home directory.

The installation wizard gives you the option to also back up your home directory as part of the
installation process, but you should also back up this directory manually before starting the upgrade.

Where is my home directory?

You can find the location of your home directory in the <installation-directory>/conflue
nce/WEB-INF/classes/confluence-init.properties file.

This is where your search indexes and attachments are stored. If you store attachments outside
the Confluence Home directory, you should also backup your attachments directory.

5. Download Confluence

Download the installer for your operating system.

Latest version https://www.atlassian.com/software/confluence/download
Older versions https://www.atlassian.com/software/confluence/download-archives

6. Run the installer

1. Run the installer.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
1. 6.15 Documentation 482

Show me how to do this in Windows...

Run the .exe file. We recommend using a Windows administrator account.
If prompted to allow the upgrade wizard to make changes to your computer, choose ' Yes'. If you do
not, the installation wizard will have restricted access to your operating system and any
subsequent installation options will be limited.
Show me how to do this in Linux...
Change to the directory where you downloaded Confluence then execute this command to make
the installer executable:

$ chmod a+x atlassian-confluence-X.X.X-x64.bin

Where X.X.X is is the Confluence version you downloaded.

Next, run the installer – we recommend using sudo to run the installer:

$ sudo ./atlassian-confluence-X.X.X-x64.bin

You can also choose to run the installer with root user privileges.

2. Follow the prompts to upgrade Confluence:

a. When prompted choose Upgrade an existing Confluence installation (for Linux users this is
option 3).

b. Make sure the Existing Confluence installation directory suggested by the wizard is correct
(especially important if you have multiple Confluence installations on the same machine).

c. Back up Confluence home is strongly recommended. This will create a .zip backup of the
Confluence home and installation directories.

d. The installation wizard notifies you of customizations in the Confluence Installation directory.
Make a note of these as you'll need to reapply them later.
There are some limitations...
The installation wizard's ability to notify you about customizations will depend on how your
existing Confluence instance was installed:
If your current Confluence instance was installed using the installer, the wizard will
check the entire Confluence Installation directory.
If your current Confluence instance was installed manually it will only check the conf
luence subdirectory of the Confluence Installation directory. The installation wizard
will not notify you of modifications in any other directory, for example modifications to
start-up scripts under the bin directory or modifications to the server.xml file
(such as an SSL configuration).
You won't be notified about files you've added to the installation directory, so be sure to
back them up first.
3. The wizard will shut down your Confluence instance and proceed with the upgrade. Once complete, it
will restart Confluence and you can then launch Confluence in your browser to confirm the upgrade
was successful.

Depending on the size of your instance and the number of upgrade tasks to be run, this step may take
a few minutes or several hours.

After the upgrade

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 483

7. Copy your database driver

If you're using an Oracle or MySQL database, you'll need to copy the jdbc driver jar file from your existing
Confluence installation directory to confluence/WEB-INF/lib in your new installation directory.

Microsoft SQL and Postgres users can skip this step.

8. Reinstall the service (Windows only)

If you run Confluence as a service on Windows you should delete the existing service then re-install the
service by running <install-directory>/bin/service.bat.

This makes sure the service gets the most recent JVM options.

9. Re-apply any modifications

During the upgrade the wizard migrated the following from your existing Confluence installation:
TCP port values in your <install-directory>/conf/server.xml file.
Location of your Confluence home directory in <install-directory>/confluence/WEB-INF/c
lasses/confluence-init.properties.

All other customizations, including CATALINA_OPTS parameters in your <install-directory>/bin/se

tenv.sh / setenv.bat files, need to be reapplied manually.
Show me how to do this...
Any other configurations, customizations (including any other modifications in the <install-directo
ry>/conf/server.xml file), the path to your own Java installation in <install-directory>/bin/s
etjre.sh, or setjre.bat, or additional files added to the installation directory are not migrated durin
g the upgrade and need to be reapplied manually.
1. Stop your upgraded Confluence instance.
2. Edit each file, and reapply the customizations in your upgraded Confluence Installation directory.
3. Copy over any additional files (such as keystore or SSL certificate)
4. Restart the upgraded Confluence instance.
We strongly recommend you test your customizations in a test instance prior to upgrading your
production instance as changes may have been made to Confluence that make your customizations
unusable.

10. Update your reverse proxy and check you can access Confluence

If you are upgrading from Confluence 5.x to Confluence 6.x you will need to modify your reverse proxy (if
used) to add Synchrony, which is required for collaborative editing. See Proxy and SSL considerations for
more information on the changes you'll need to make to your proxy config.
Once your upgrade is complete, you should access Confluence (via your reverse proxy, not directly) and:
Head to

> General Configuration > Collaborative editing and check the Synchrony status is running.
Edit any page to check that your browser can connect to Synchrony.
See Troubleshooting Collaborative Editing for suggested next steps if Synchrony is not running or you see an
error in the editor, as you may have a misconfigured reverse proxy.

Troubleshooting

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 484

Did something go wrong?

If you need to retry the upgrade, you must restore your pre-upgrade backups first. Do not
attempt to run an upgrade again, or start the older version of Confluence again after an upgrade
has failed.

Some common issues while upgrading...

Can't proceed with upgrade because license has expired
If your license has expired and was not renewed and reapplied before upgrading you will receive
errors during the upgrade process. See upgrading beyond current license period for information on
how to resolve this problem.
Can't proceed with upgrade because of a conflict with anti virus
Some anti-virus or other Internet security tools may interfere with the Confluence upgrade process
and prevent the process from completing successfully, particularly if you run Confluence as a
Windows service. If you experience or anticipate experiencing such an issue with your anti-virus /
Internet security tool, disable this tool first before proceeding with the Confluence upgrade.
Database does not support online backups
The upgrade wizard will prompt you to backup your database using your database's backup
utilities. If your database does not support online backups, stop the upgrade process, shut down
Confluence, perform your database backup and then run the installer again to continue with the
upgrade.
Upgrade is taking a very long time
If you have a very large database (i.e. database backups take a very long time to complete),
setting the confluence.upgrade.recovery.file.enabled system property to false will
speed up the upgrade process. It should be used only when there is a process to back up
database and verify the backup before performing an upgrade.
Confluence doesn't start
Incompatible Marketplace apps can occasionally prevent Confluence from starting successfully.
You can troubleshoot the problem by starting Confluence with all user installed apps temporarily
disabled. See Start and Stop Confluence for more info.
Collaborative editing errors
If Synchrony is not running or you see an error, head to Troubleshooting Collaborative Editing for
info on how to get collaborative editing up and running in your environment. The most common
problems are a misconfigured reverse proxy or port 8091 not being available for Synchrony.
You can also refer to the Upgrade Troubleshooting guide in the Confluence Knowledge Base, or check for
answers from the community at Atlassian Answers.

Upgrading Beyond Current Licensed Period

This page covers what to do if you have upgraded Related pages:
Confluence to a version beyond your current license
entitlement. Upgrading Confluence
Working with Confluence Logs

License warnings

During the upgrade you will see an error similar to

the following in your application log file.

ERROR [confluence.upgrade.impl.DefaultUpgradeManager]
runUpgradePrerequisites
Current license is not valid: SUPPORT_EXPIRED

When you try to access Confluence in your browser, you'll see this warning:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 485

Updating the Confluence license

1. Head to my.atlassian.com to renew your license or purchase a new license.

2. Follow the prompts on the warning screen to enter your new license key.

3. Restart Confluence to pick up the license change. You should now be able to log in to Confluence as
normal.

Confluence Post-Upgrade Checks

This article provides a list of items for Confluence Administrators to check after a Confluence upgrade to ensure
that it has completed successfully. This list is not exhaustive, but it does cover common upgrade mistakes.

Before You Begin

After you have completed an upgrade, you should see the following message in the atlassian-confluence.
log file:

2010-03-08 08:03:58,899 INFO [main]

[atlassian.confluence.upgrade.AbstractUpgradeManager] entireupgradeFinished Upgrade
completed successfully

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 486

If you do not see the line in your log similar to the one above, this means that your upgrade may not have
completed successfully. Please check our Upgrade Troubleshooting documentation to check for a suitable
recommendation or fix.

Upgrade Checklist

Here's a recommended list of things to check after completing an upgrade

1. The editor

Edit a page to check your browser can connect to Synchrony, which is required for collaborative editing. See Tro
ubleshooting Collaborative Editing if you are not able to edit a page.

2. Layout and Menu

Visit the Confluence dashboard and check that it is accessible and displays as expected. Test the different
Internet browsers that you have in use in your environment. In addition, confirm that the layout appears as
expected and that the menus are clickable and functioning.

3. Search

Try searching for content, for example pages, attachments or user names. Check that the expected results are
returned.

4. Permissions

Confirm that you can visit a page that has view restrictions, but you have permission to view. Confirm that you
can edit a page that has edit restrictions but you have permission to edit. Make sure that the permissions of child
pages are functioning as well. Involve as many space administrators as possible to confirm they are working.
Confirm that anonymous or forbidden users cannot access or modify restricted pages.

5. Attachments

Confirm that attachments are accessible and searchable.

6. Marketplace apps

Outdated third-party apps can cause upgrade failure. Quite often, they will just be incompatible and simply do
not work anymore. If you discover that your app is no longer working, please check for the latest version for your
app in the The Atlassian Marketplace or check for compatibility in the Universal Plugin Manager.
Migration from Wiki Markup to XHTML-Based Storage Format
If you are upgrading to Confluence 4.0 or later from an older version (From Confluence 3.5.x or earler) then as
part of the upgrade an automatic migration of your content will take place. This is a non-destructive process.
Your existing content is not overwritten. Instead, the migration process will create a new version of each wiki
markup page. The new version will use the new XHTML-based storage format, so that you can edit the page in
the Confluence rich text editor.
In addition, if you are upgrading to Confluence 4.3 or later from an older version then as part of the upgrade
an automatic migration of your page templates will take place. See Migration of Templates from Wiki Markup to
XHTML-Based Storage Format.
Note: Even though the process is non-destructive, you must be sure to perform a backup of your database and
home directory prior to starting the new version of Confluence, as we recommend for any Confluence upgrade.

Migration process

Depending on the size of your Confluence installation, the migration from wiki markup to the new XHTML-based
storage format could prove time consuming. The duration of the migration is difficult to estimate; this is due to a

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 487

number of site specific factors. As a rough guide, a test dataset we migrated was 130,000 pages, totalling
approximately 700Mb, which took six minutes.
On this page:
Migration process
Watching the migration logs during the upgrade
Re-running the migration – for content that
completely failed the migration
Re-attempting the migration – for content in
'unmigrated-wiki-markup' macro
Notes
Related pages:
Migration of Templates from Wiki Markup to
XHTML-Based Storage Format
Upgrading Confluence

The following properties that can be modified to allow finer control over the migration process:

Property Purpose Default

confluence.wiki.migration.threads The number of concurrent worker 4

threads migrating content

confluence.wiki.migration.batch.si The number of items migrated in 500

ze each batch of work

confluence.wiki.migration.version The comment associated with the "Migrated to Confluence 4.0"

comment newly migrated version of each
piece of content

(For instructions on setting Confluence system properties see this document.)

Again, due to the large variability in Confluence installations it is hard to give specific recommendations for the
above settings. One point to note though that both increasing batch size and the number of threads (or both) will
increase the peak memory required for migration. If memory is an issue then as you increase one of these
settings consider decreasing the other.
Another factor to be aware of if modifying these defaults is that of the cache settings employed in your site. The
migration will quickly populate certain Confluence caches so be sure that if you have customized caches as desc
ribed here that there is enough memory on the server for these caches should they reach maximum capacity.

Watching the migration logs during the upgrade

To monitor the progress of a site migration you should watch the output in the application log.
Typical logging progress will be shown by multiple log entries at the INFO level of the following format:

WikiToXhtmlMigrationThread-n - Migrated 2500 of 158432 pages, this batch

migrated 500/500 without error

There may be a wide array of messages logged from each individual page but any errors are also collected for
display in a single migration report once all content has been processed. Here is a typical example of such a
report:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 488

Wiki to XHTML Exception Report:

Summary:
0 settings values failed.
0 PageTemplates failed.
2 ContentEntityObjects failed.
Content Exceptions:
1) Type: page, Id: 332, Title: Release Notes 1.0b3, Space: DOC -
Confluence 4.0 Beta. Cause:
com.atlassian.confluence.content.render.xhtml.migration.exceptions.Unkno
wnMacroMigrationException: The macro link is unknown.. Message: The
macro link is unknown.
2) Type: comment, Id: 6919, Title: null, Global Scope. Cause:
com.atlassian.confluence.content.render.xhtml.migration.exceptions.Unkno
wnMacroMigrationException: The macro mymacro is unknown.. Message: The
macro mymacro is unknown.

Each entry in the report will identify the content that caused migration exceptions as well as displaying the
exceptions themselves.
In almost all cases any content reported as errored will have been migrated to the new XHTML-based storage
format, but will actually consist of wiki markup content wrapped within an XML 'unmigrated-wiki-markup' macro.
This content will still be viewable in Confluence and editable within the new Confluence Editor.
However, in some cases a batch of content may actually have completely failed to migrated. This is most
typically due to an unhandled exception causing a database transaction rollback. This would be reported in the
log with a message like this:

Unable to start up Confluence. Fatal error during startup sequence:

confluence.lifecycle.core:pluginframeworkdependentupgrades (Run all the
upgrades that require the plugin framework to be available) -
com.atlassian.confluence.content.render.xhtml.migration.exceptions.Migra
tionException: java.util.concurrent.ExecutionException:
org.springframework.transaction.UnexpectedRollbackException: Transaction
rolled back because it has been marked as rollback-only

Confluence provides no further report about this scenario and will also allow Confluence to restart as normal
without retrying a migration. If a user tries to view any such unmigrated content they will see an exception similar
to this:

java.lang.UnsupportedOperationException: The body of this

ContentEntityObject ('Page Title') was 'WIKI' but was expected to be
'XHTML'

The solution is to ensure you manually re-run the site migration after the restart.

Re-running the migration – for content that completely failed the migration

A Confluence Administrator can restart the site migration if there was any content that failed migration (see
previous section). Only the content that is still formatted in wiki markup will be migrated, so typically a
re-migration will take less time than the original migration.
To manually re-run migration:
1. Open this URL in your browser: <Confluence Address>/admin/force-upgrade.action
2. Select wikiToXhtmlMigrationUpgradeTask in the Upgrade task to run dropdown list.
3.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 489

3. Choose Force Upgrade.

Re-attempting the migration – for content in 'unmigrated-wiki-markup' macro

The previous section was about dealing with the exceptional circumstance where certain content was left
completely unmigrated. The most common migration problem is that the content was migrated but remains
formatted as wiki markup on the page, within the body of an 'unmigrated-wiki-markup' macro. Any content which
is referenced in the migration report will be found in this state. This content is still viewable and editable but
since it is wiki markup it cannot be edited using the full feature set of the rich text editor.
The most common reason for content to be in this state is that the page contains an unknown macro, or a macro
that is not compatible with Confluence 4.x.
There are two possible fixes for this situation:
1. Install a version of the macro that is compatible with Confluence 4.x. See Plugin Development Upgrade
FAQ for 4.0 .
2. Edit the page and remove the problematic macro.
Regardless of the solution you choose, you can then force a re-migration of all the content (including content in
templates) that was left wrapped in an 'unmigrated-wiki-markup' macro. This feature is found at <Confluence
Address>/admin/unmigratedcontent.action

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 490

Notes

We refer to the Confluence storage format as 'XHTML-based'. To be correct, we should call it XML, because the
Confluence storage format does not comply with the XHTML definition. In particular, Confluence includes
custom elements for macros and more. We're using the term 'XHTML-based' to indicate that there is a large
proportion of HTML in the storage format.
Migration of Templates from Wiki Markup to XHTML-Based Storage Format
If you are upgrading to Confluence 4.3 or later from an older version (from Confluence 4.2.x or earlier) then
as part of the upgrade an automatic migration of your page templates will take place. This is a non-destructive
process. Your existing content is not overwritten. Instead, the migration process will create a new version of
each space template and each global template on your Confluence site. The new version will use the new
XHTML-based storage format, so that you can edit the template in the Confluence rich text editor.
Note: Nevertheless, you must be sure to perform a backup of your database and home directory prior to starting
the new version of Confluence, as we recommend for any Confluence upgrade.

Watching the migration logs during the upgrade

To monitor the progress of a site migration you should watch the output in the application log.
A typical logging progress will be shown by multiple log entries at the INFO level of the following format:

WikiToXhtmlMigrationThread-n - Migrated 22 of 29 PageTemplates.

On this page:
Watching the migration logs during the upgrade
Re-running the migration
Notes
Related pages:
Migration from Wiki Markup to XHTML-Based
Storage Format
Page Templates
Upgrading Confluence

There may be a wide array of messages logged from each individual template, but any errors are also collected
for display in a single migration report once all content has been processed. Here is a typical example of such a
report:

Wiki to XHTML Exception Report:

Summary:
0 settings values failed.
2 PageTemplates failed.
0 ContentEntityObjects failed.
Content Exceptions:
1) Type: page, Id: 332, Title: Release Notes 1.0b3, Space: DOC -
Confluence 4.0 Beta. Cause:
com.atlassian.confluence.content.render.xhtml.migration.exceptions.Unkno
wnMacroMigrationException: The macro link is unknown.. Message: The
macro link is unknown.
2) Type: comment, Id: 6919, Title: null, Global Scope. Cause:
com.atlassian.confluence.content.render.xhtml.migration.exceptions.Unkno
wnMacroMigrationException: The macro mymacro is unknown.. Message: The
macro mymacro is unknown.

Each entry in the report will identify the content that caused migration exceptions as well as displaying the

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 491

exceptions themselves.
In almost all cases any content reported as errored will have been migrated to the new XHTML-based storage
format, but will actually consist of wiki markup content wrapped within an XML 'unmigrated-wiki-markup' macro.
This content will still be viewable in Confluence and editable within the Confluence rich text editor.
However, in some cases a batch of content may actually have completely failed to migrate. This is most typically
due to an unhandled exception causing a database transaction rollback. This would be reported in the log with a
message like this:

Unable to start up Confluence. Fatal error during startup sequence:

confluence.lifecycle.core:pluginframeworkdependentupgrades (Run all the
upgrades that require the plugin framework to be available) -
com.atlassian.confluence.content.render.xhtml.migration.exceptions.Migra
tionException: java.util.concurrent.ExecutionException:
org.springframework.transaction.UnexpectedRollbackException: Transaction
rolled back because it has been marked as rollback-only

Confluence provides no further report about this scenario and will also allow Confluence to restart as normal
without retrying a migration. If a user tries to view or edit an unmigrated template, the wiki template editor will be
used.
The solution is to manually re-run the site migration after the restart, as described below.

Re-running the migration

A Confluence administrator can restart the template migration if any templates have failed the migration (see
previous section). Only the templates that are still formatted in wiki markup will be migrated again. Typically, a
re-migration will take less time than the original migration.
To manually re-run the migration:
1. Open this URL in your browser: <Confluence Address>/admin/force-upgrade.action
2. Select pageTemplateWikiToXhtmlMigrationUpgradeTask in the Upgrade task to run dropdown list.
3. Choose Force Upgrade.
Screenshot: The 'Force Upgrade' screen in the Confluence administration console

Notes

We refer to the Confluence storage format as 'XHTML-based'. To be correct, we should call it XML, because the
Confluence storage format does not comply with the XHTML definition. In particular, Confluence includes
custom elements for macros and more. We're using the term 'XHTML-based' to indicate that there is a large
proportion of HTML in the storage format.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 492

Upgrading Confluence Manually

In this guide we'll run you through upgrading your On this page:
Confluence site to the latest Confluence version on Before you begin
Windows or Linux using the zip / tar.gz file. Plan your upgrade
1. Determine your upgrade
Upgrading to any later version is free if you have
path
current software maintenance. See our Licensing
2. Complete the
FAQ to find out more.
pre-upgrade checks
3. Upgrade Confluence in a
test environment
Upgrade Confluence
4. Back up
5. Download Confluence
6. Extract the file and
upgrade Confluence
After the upgrade
7. Reinstall the service
(Windows only)
Other ways to upgrade Confluence: 8. Re-apply any
modifications
Installer – the simplest way to upgrade 9. Update your reverse
Confluence. proxy and check you can
Data Center – upgrade your Data Center access Confluence
cluster. Troubleshooting
XML backups should not be used to upgrade
Confluence.

Before you begin

Before you upgrade Confluence, there's a few questions you need to answer.

Is manual the Tell me more...

right upgrade You can choose to upgrade using the installer, or manually using a zip or tar.gz
method for you? file. In most cases the installer is the easiest way to upgrade your Confluence
instance.
You will need to upgrade manually if:
you are moving to another operating system or file location as part of this
upgrade.
you are upgrading from Confluence 3.5 or earlier
you are upgrading from Confluence 5.6 or earlier and previously used the E
AR/WAR distribution to deploy Confluence into an existing application
server.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 493

Are you eligible to Tell me more...

upgrade? To check if software maintenance is current for your license, go to

> General Configuration > Troubleshooting and support tools and make
sure the license support period has not expired.

1. Software maintenance: upgrade at any time during this period.

If your support period has expired, follow the prompts to renew your license and
reapply it before upgrading.

Have our Tell me more...

supported Check the Supported Platforms page for the version of Confluence you are
platforms upgrading to. This will give you info on supported operating systems, databases
changed? and browsers.
Good to know:
If you need to upgrade Java, remember to update your JAVA_HOME
variable to the new version.
The Confluence installer includes Tomcat, so you won't need to upgrade it
separately.
If you need to upgrade your database, be sure to read the upgrade notes for
the Confluence version you plan to upgrade to (and any in-between) to
check for any database configuration changes that you may need to make.

Do you need to Tell me more...

make changes to Newer Confluence versions sometimes require changes to your environment,
your such as providing more memory or adjusting your reverse proxy settings.
environment?
Good to know:
We use Upgrade Notes to communicate changes that will impact you, such as:
Changes to supported databases, memory requirements or other changes
that will impact your environment.
Features that have significantly changed or been removed in this release.
Actions you may need to take in your instance or environment immediately
after the upgrade.
It's important to read the notes for the version you're upgrading to and those
in-between. For example, if you are upgrading from 5.8 to 5.10 you should read
the upgrade notes for 5.9 and 5.10.

Plan your upgrade

1. Determine your upgrade path

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 494

Use the table below to determine the most efficient upgrade path from your current version to the latest
versions of Confluence.

Your Version Recommended upgrade path to Confluence 6

2.7 or earlier Upgrade to 2.7.4 then upgrade to 3.5.17, and follow paths below.

2.8 to 3.4 Upgrade to 3.5.17, and follow paths below.

3.5 Upgrade to 5.0.3 then upgrade to the latest version of Confluence 6.

4.0 to 4.3 Upgrade to 5.10.x then upgrade to the latest version of Confluence 6.

5.0 to 6.x Upgrade directly to the latest version of Confluence 6.

Confluence 6 is a major upgrade

Be sure to read the Confluence 6.0 Upgrade Notes, take a full backup, and test your upgrade in a
non-production environment before upgrading your production site.

2. Complete the pre-upgrade checks

1. Check the Upgrade Notes for the version you plan to upgrade to (and any in between).

2. Go to

> General Configuration > Troubleshooting and support tools to run the health check (available
in Confluence 5.5 or later).

License expired?
If the software maintenance period included in your license has expired you can keep using
Confluence, but you'll need to renew before you can upgrade.
Go to

> General Configuration > License Details and follow the prompts to renew your license.
Still using the embedded database?
If you are using the embedded (trial) database you should migrate to a different database before
upgrading.
This database is supplied for evaluation purposes only and is not recommended for production
environments. See Embedded H2 Database for more information.
Database character encoding incorrect?
Database character encoding must be set to UTF+8 (or AL32UTF8 for Oracle databases). You will
not be able to upgrade to current Confluence versions unless you have the correct character
encoding.

3. Go to

> Manage apps and scroll down to the Confluence Update Check to check the compatibility of your
Marketplace apps.

4. Choose the version you plan to upgrade to then hit Check.

If you have incompatible add-ons...

If your users rely on particular Marketplace apps, you may want to wait until they are compatible
before upgrading Confluence. Vendors generally update their apps very soon after a major
release.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 495

Good to know:
You can disable an app temporarily while you upgrade if it is not yet compatible.
Compatibility information for Atlassian Labs and other free apps is often not available
immediatley after a new release. In many cases the app will still work, so give it a try in a
test site before upgrading your production site.

3. Upgrade Confluence in a test environment

1. Create a staging copy of your current production environment.

See Create a staging environment for upgrading Confluence for help creating an environment to test
your upgrade in.

2. Follow the steps below to upgrade your test environment.

3. Test any unsupported user-installed apps, customizations (such as custom theme or layouts) and
proxy configuration (if possible) before upgrading your production environment.

Upgrade Confluence

4. Back up

1. Back up your database and confirm the backup was created properly.
If your database does not support online backups you'll need to stop Confluence first.

2. Back up your installation directory and home directory.

Where is my home directory?

You can find the location of your home directory in the <installation-directory>/conflue
nce/WEB-INF/classes/confluence-init.properties file.

This is where your search indexes and attachments are stored. If you store attachments outside
the Confluence Home directory, you should also backup your attachments directory.

5. Download Confluence

Download the appropriate file for your operating system - https://www.atlassian.com/software/confluence/do

wnload

6. Extract the file and upgrade Confluence

1. Stop Confluence.
See Using read-only mode for site maintenance if you need to provide uninterrupted access.

2. Extract (unzip) the files to a directory (this is your new installation directory, and must be different to
your existing installation directory)
Note: There are some known issues with unzipping the archive on Windows. We recommend using
7Zip or Winzip.

3. Edit <Installation-Directory>\confluence\WEB-INF\classes\confluence-init.pro
perties file to point to your existing Confluence home directory.

4. If you're using an Oracle or MySQL database, you'll need to copy your jdbc driver jar file from your
existing Confluence installation directory to confluence/WEB-INF/lib in your new installation
directory.

5. There are some additional steps you make need to take if:
you are running Confluence as a Windows Service
Click here to expand...

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
 5.
Confluence 6.15 Documentation 496

If you are running Confluence as a Windows service, go to the command prompt and type:

<Installation-Directory>\bin\service.bat remove
Confluence

It is vital that you stop and remove the existing service prior to uninstalling the old instance
of Confluence. For more information on running Confluence as Windows service, please
refer to Start Confluence Automatically on Windows as a Service.
To remove the service installed by the Confluence installer, you'll need to run <conflue
nce auto installer installation folder>\UninstallService.bat.

you use a Jira application or LDAP for user management

Click here to expand...
If you use Jira or LDAP for user management, copy the following files from your existing
installation directory to your new installation directory:
<Installation-Directory>/confluence/WEB-INF/classes/osuser.xml
<Installation-Directory>/confluence/WEB-INF/classes/atlassian-
user.xml
you use Crowd for user management
Click here to expand...
If you are using Crowd for user management, copy the following files from your existing
installation directory to your new installation directory:
<Installation-Directory>/confluence/WEB-INF/classes/osuser.xml
<Installation-Directory>/confluence/WEB-INF/classes/atlassian-
user.xml (if you are upgrading from Confluence 2.2 or later).
<Installation-Directory>/confluence/WEB-INF/classes/crowd.prop
erties
You are running Confluence on a different port (not the default 8090)

Click here to expand...

If you are not running Confluence on port 8090 update <Installation-Directory>\co
nf\server.xml file to include your ports.

6. Start your new Confluence. You should not see the setup wizard.

After the upgrade

7. Reinstall the service (Windows only)

If you run Confluence as a service on Windows you should delete the existing service then re-install the
service by running <install-directory>/bin/service.bat.

This makes sure the service gets the most recent JVM options.

8. Re-apply any modifications

If you have customized Confluence (such as an SSL configuration in the server.xml file, or CATALINA_OP
TS or JAVA_OPTS parameters in your confluence-init.properties file), you'll need to perform the
following steps after the upgrade is complete:
1. Stop your upgraded Confluence instance.
2. Reapply the customizations to the relevant files in the newly upgraded Confluence Installation
directory.
3. Restart the upgraded Confluence instance.
We strongly recommend you test your customizations in a test instance prior to upgrading your production

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 497

instance as changes may have been made to Confluence that make your customizations unsuable.

9. Update your reverse proxy and check you can access Confluence

If you are upgrading from Confluence 5.x to Confluence 6.x you will need to modify your reverse proxy (if
used) to add Synchrony, which is required for collaborative editing. See Proxy and SSL considerations for
more information on the changes you'll need to make to your proxy config.
Once your upgrade is complete, you should access Confluence (via your reverse proxy, not directly) and:
Head to

> General Configuration > Collaborative editing and check the Synchrony status is running.
Edit any page to check that your browser can connect to Synchrony.
See Troubleshooting Collaborative Editing for suggested next steps if Synchrony is not running or you see an
error in the editor, as you may have a misconfigured reverse proxy.

Troubleshooting

Did something go wrong?

If you need to retry the upgrade, you must restore your pre-upgrade backups first. Do not
attempt to run an upgrade again, or start the older version of Confluence again after an upgrade
has failed.

Some common issues while upgrading...

Can't proceed with upgrade because license has expired

If your license has expired and was not renewed and reapplied before upgrading you will receive
errors during the upgrade process. See upgrading beyond current license period for information on
how to resolve this problem.
Collaborative editing errors
If Synchrony is not running or you see an error, head to Troubleshooting Collaborative Editing for
info on how to get collaborative editing up and running in your environment. The most common
problems are a misconfigured reverse proxy or port 8091 not being available for Synchrony.
You can also refer to the Upgrade Troubleshooting guide in the Confluence Knowledge Base, or check for
answers from the community at Atlassian Answers.

Create a staging environment for upgrading Confluence

When you upgrade Confluence we strongly On this page:
recommend performing the upgrade in a test
environment before upgrading your production site. Create a staging environment
In this guide we'll refer to this test environment as st Additional configuration options
aging. Upgrade your staging environment

Most Confluence licenses include a free developer

license for use in a staging environment. See How to
get a Confluence Developer license to find out how
to access your license.

Create a staging environment

1. Replicate your environment

Your staging environment should closely replicate your real-live environment (production), including any
reverse proxies, SSL configuration, or load balancer (for Data Center). You may decide to use a different
physical server or a virtualized solution. The main thing is to make sure it is an appropriate replica of your
production environment.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 498

For the purposes of these instructions, we assume your staging environment is physically separate from your
production environment, and has the same operating system (and Java version if you've installed Confluence
manually).

2. Replicate your database

To replicate your database:

1. Back up your production database. Refer to the documentation for your database for more info on the
best way to do this.
2. Install your database on the staging server and restore the backup.
The steps for restoring your database backup will differ depending on your chosen database and backup
tool. Make sure:
Your new staging database has a different name from your production database.
Your staging database user account has the same username and password as your production
database user account.
Character encoding and other configurations are the same as your production database (for example
character encoding should be Unicode UTF-8 (or AL32UTF8 for Oracle databases).

3. Replicate Confluence

To replicate Confluence, make a copy of your Confluence installation and point it to your staging database.
These instructions are for Confluence Server (for Data Center there are some additional steps before you
start Confluence).
1. Copy your entire production installation directory to your staging server.
2. Copy your entire production home directory to your staging server.
3. Edit <installation-directory>/confluence/WEB-INF/classes/confluence-init.pro
perties to point to your staging home directory.
4. Edit <home-directory>/confluence.cfg.xml or <installation-directory>/server.xm
l to point to your staging database.

If you're using a direct JDBC connection, the line you need to update in confluence.cfg.xml will look
something like this...

<property
name="hibernate.connection.url">jdbc:postgresql://localhost:54
32/confluencestaging</property>

If you're using a datasource connection, the lines you need to update in server.xml will look
something like this...

<Resource name="jdbc/confluence" auth="Container"

type="javax.sql.DataSource"
username="postgres"
password="postgres"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://localhost:5432/confluencestaging"
maxTotal="60"
maxIdle="20"
validationQuery="select 1" />

5. Start Confluence with the following System Properties to make sure your staging site does not send
notifications to real users.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 499

-Datlassian.notifications.disabled=true
-Datlassian.mail.senddisabled=true

6. Head to http://localhost:<port> and log in to Confluence on your staging server.

7. Go to

> General Configuration and change the base URL of your staging site (for example mysite.stag
ing.com)
8. Go to

> General Configuration > License Details and apply your development license.
9. Go to

> General Configuration > System Information and check that Confluence is correctly pointing to
your staging database, and staging home directory.

It's essential to check that you are not still connected to your production database.

Additional steps for Data Center

If you have Confluence Data Center, the process is much the same as for Confluence Server described
above. You will copy each local home and installation directory to each staging node, and then:
1. Copy the production shared home directory to the staging server.
2. Edit<local-home-directory>/confluence.cfg.xml to point to your staging shared home
directory. This change must be made on every staging node.
Changes to the <installation-directory>/confluence/WEB-INF/classes/confluence-init.
properties and <home-directory>/confluence.cfg.xml must be made on every staging node.

When it comes time to start Confluence, start one node at a time, as usual.

4. Replicate external user management (optional)

If you're managing users in Jira, Crowd, or in an external LDAP directory you can:
replicate Jira, Crowd, or your external directory in your staging environment and point your Confluence
staging site to your staging external directory (recommended).
provide your staging server with network or local access to the same hosts as your production server.

Additional configuration options

There are a number of additional things you may want to change in your staging environment, to make sure it
does not interact with your production environment, or to clearly differentiate it for users.

Modify application links (recommended)

If you have application links between Confluence and other Atlassian applications you should change the
server ID on each staging application. See How to change the server ID of Confluence and Changing Server
ID for Test Installations for Jira.
If you don't change the server ID and update your application links there is a chance that when you create a
new application link in production it will point to your staging server instead.
To review the Application Links manually in the database, use the following following SQL query:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 500

select * from bandana where bandanakey like 'applinks%';

Modify external gadgets

If you have external gadgets configured, you can update these from the database, using the following SQL
query:

select * from bandana where bandanakey =

'confluence.ExternalGadgetSpecStore.specs'

Change the global color scheme

If can be helpful to use a different color scheme on your staging site, to differentiate it from your production
site. See Customizing Color Schemes for how to do this.
You can also find this data in the database using the following SQL query:

select * from bandana where bandanakey =

'atlassian.confluence.colour.scheme';

Change the instance name (recommended)

It is a good idea to change the name of your staging site, to differentiate it from your production site. Head to

> General Configuration and update the Site Title if Confluence is running.
If Confluence is not running, you can do this from the database. You can find the site title using the following
SQL query:

select * from bandana where bandanakey =

'atlassian.confluence.settings';

The attribute you are looking for is setTitle.

Add a banner

It can be useful to add a banner to your staging site, to provide useful information like the date of the last
refresh, or who to contact if you want to make changes.
If you have a Confluence Data Center license, you can do this by enabling the banner that is used by read-on
ly mode (you don't need to enable read-only mode to use the banner).
If you have a Confluence Server license, you can manually add a banner using HTML. Head to

> General Configuration > Custom HTML. Remember to close your tags properly, or Confluence may not
display correctly.
If you want to add a banner before starting Confluence, you can do it in the database. You can find the
custom HTML using the following SQL query:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 501

select * from bandana where bandanakey =

'atlassian.confluence.settings';

The attribute you are looking for is customHtmlSettings afterBodyStart

Disable specific plugins

You might want to disable specific plugins or check whether these plugins are already disabled or not. See
the How to reset all Confluence plugins back to their default state through the database knowledge base
article to find how to do this.
You can also disable plugins in Confluence in 6.1+ using Java system properties.

Upgrade your staging environment

Once you have created your staging environment, you can upgrade it in the same way you would your
production environment.
Make a note of how long the upgrade takes, as this information will help you plan your production system
outage and communicate with your users.
You can also use your staging environment to test any customizations or essential Marketplace apps in your
site.

Supported Platforms
This page describes the additional software and infrastructure you'll need to On this page:
run Confluence. Please review this info before installing Confluence. The
information on this page applies to Confluence 6.15. Browsers
Operating
You should only use Confluence with a supported platform. Any systems
platforms and versions not listed on this page are unsupported, which Databases
means we don't test, fix bugs or provide assistance. Java
See End of Support Announcements for Confluence for upcoming Infrastruct
changes to supported platforms. ure
Go to

Related pages:
> General Configuration > Troubleshooting and support tools to
check your instance health. It looks at things like your license validity, Confluenc
Tomcat version, basic database setup and more. e
Installation
Definitions:
Guide
Supported - you can use Confluence 6.15 with this platform. Confluenc
e Setup
Limited - you can evaluate Confluence on this platform, but you can't use Guide
it to run a production Confluence site.
Server
Deprecated - support for this platform will end in an upcoming release. Hardware
Requireme
nts Guide
Supported
Platforms
FAQ

Browsers
Desktop browsers: Good to know:
Internet Explorer 11 We test Confluence in Internet Explorer 11 using standards-compliant
rendering mode, not compatibility mode. You may experience

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 502

Microsoft Edge problems in compatibility mode.

The Confluence setup wizard requires Javascript to be enabled while
Chrome installing Confluence. Learn more
Firefox Parts of Confluence won't display correctly if your browser window
size is less than 1024x768.
Safari (Mac only)
Mobile browsers:
Chrome
Firefox
Safari (iOS only)
Android 4.4 (KitKat) or
later
Mobile operating system:
(required for mobile app)
iOS 11 or later
Android 4.4 (KitKat) or
later

Operating systems
Operating systems: Known issues:
Microsoft Windows The following operating system variants can't be used with
Confluence:
Linux (most distributions) Windows Nano
MacOS / OSX (evaluation Alpine Linux - see CONFSERVER-52400
only) Good to know:
You can run Confluence on 32bit or 64bit operating systems, but we
only provide installers for 64bit operating systems.
You can evaluate Confluence on MacOS / OSX, but you can't install
and run your production Confluence site on a Mac.

Databases
PostgreSQL: Known issues:
PostgreSQL 9.4 Confluence will not work on MySQL 5.6 versions earlier than 5.6.16.
See MySQL bug 69005.
PostgreSQL 9.5 Confluence will not work on MySQL variants such as:
PostgreSQL 9.6 MariaDB - see CONFSERVER-29060
Percona Server - see CONFSERVER-36471
MySQL:
Good to know:
MySQL 5.6
You must use the InnoDB storage engine in MySQL.
MySQL 5.7 The embedded H2 database is for evaluation only. For production
sites, you'll need to use one of the supported external databases
Oracle: listed on this page.
Oracle 12c Release 1
Oracle 12c Release 2
Microsoft SQL Server:
SQL Server 2012
SQL Server 2014
SQL Server 2016

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 503

SQL Server 2017

Azure SQL
Embedded database:
H2 (evaluation only)

Java
Oracle JRE / JDK: Known issues:
Java 1.8 You can only run Confluence with AdoptOpenJDK or Oracle
JRE/JDK.
AdoptOpenJDK: Some Oracle Java versions have bugs that impact Confluence. You
Java 8 can't run Confluence on Java 1.8.0_25 and 1.8.0_31 (see JDK-80592
99) or Java 1.8.0_45 (see JDK-8068400).
Some AdoptOpenJDK versions have bugs that impact Confluence.
We recommend version jdk8u192 or later.
Good to know:
You don't need to install Java if you plan to use the installer to install
Confluence, as a JRE is bundled with Confluence (provided by
AdoptOpenJDK).

Infrastructure
Hardware:
You can't run Confluence on SPARC based hardware. You'll need to use x86 hardware or 64bit
derivatives of x86 hardware.
You can't use an NFS mount for your installation or home directory due to Lucene requirements. If
you're installing Confluence Data Center, an NFS mount is fine for the shared home directory, but not
for the local home directories.
Virtualization:
You can run Confluence and Confluence Data Center in a virtualized environment (including Docker),
but our support team can't assist you with problems related to the environment itself. See Running
Confluence in a Virtualized Environment
Our support team can assist you with deploying Confluence Data Center in AWS using the Cloud
Formation Template or Quick Start. We won't be able to assist you if you have significantly customised
the Cloud Formation Template.
Application server:
We only support the Tomcat version that is bundled with your Confluence version. You can't run
Confluence in your own application server.
Internet protocols:
You can run Confluence in both IPv4 and IPv6 environments.
Raw IPv6 addresses are not always recognized. See the Confluence 6.9 Upgrade Notes for limitations
and known issues.
For more information see our Server Hardware Requirements Guide and System Requirements.

End of Support Announcements for Confluence

This page is where we announce end of support for various platforms, browsers, and information on features
that will be discontinued in Confluence Server.
The table below summarizes the end of support announcements for upcoming Confluence releases. If a
platform (or version) has already reached its end of support date, it is not listed in the table.

Platform Confluence end of support

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 504

IM Presence macro With the release of Confluence 7.0 (announcement)

Network macro With the release of Confluence 7.0 (announcement)

Search Results macro With the release of Confluence 7.0 (announcement)

Space Details macro With the release of Confluence 7.0 (announcement)

Confluence gadgets With the release of Confluence 7.0 (announcement)

Shortcut Links With the release of Confluence 7.0 (announcement)

Trackback and Referrers With the release of Confluence 7.0 (announcement)

Orphaned Pages With the release of Confluence 7.0 (announcement)

View File macros These macros are now fully supported (updated announcement)

See the full list of announcements...

Most recent announcements first:
Deprecated macros for Confluence (12 March 2019)
Deprecated Gadgets in Confluence (12 March 2019)
Changes to features in Confluence (12 March 2019)
Deprecated databases for Confluence (2 October 2018)
Deprecated databases for Confluence (30 January 2017)
Deprecated macro for Confluence (31 October 2017)
Deprecated driver for Microsoft SQL Server
Deprecated operating system for Confluence (15 May 2017)
Deprecated mobile browser for Confluence (3 November 2016)
Changes to Confluence distributions (8 June 2016)
Deprecated browsers for Confluence (8 June 2016)
Deprecated databases for Confluence (8 June 2016)
Deprecated macros for Confluence (13 November 2015)
Discontinued features for Confluence (10 July 2015)
Deprecated databases for Confluence (19 May 2015)
Deprecated Tomcat platform for Confluence (1 May 2015)
Deprecated Web Browsers for Confluence (20 April 2015)
Deprecated Java platform for Confluence (27 January 2015)
Deprecated distribution for Confluence (2 September 2014)
Deprecated databases for Confluence (12 June 2014)
Deprecated Tomcat platform for Confluence (22 April 2014)
Deprecated Databases for Confluence (2 December 2013)
Deprecated Web Browsers for Confluence (24 September 2013)
Deprecated Databases for Confluence (13 August 2013)
Deprecated Tomcat platform for Confluence (29 August 2012)
Deprecated Java platform for Confluence (6 August 2012)
Deprecated Databases for Confluence (1 May 2012)
Deprecated Databases for Confluence (13 March 2012)
Deprecated Operating Systems for Confluence (21 July 2011)
Deprecated Databases for Confluence (7 January 2011)
Deprecated Web Browsers for Confluence (7 January 2011)
Deprecated Databases for Confluence (12 October 2010)
Deprecated Web Browsers for Confluence (12 October 2010)
Deprecated Databases for Confluence (6 July 2010)
Deprecated Web Browsers for Confluence (6 July 2010)
Deprecated Databases for Confluence (24 March 2010)
Deprecated Application Servers for Confluence (27 January 2010)
Deprecated Java Platforms for Confluence (27 January 2010)
Deprecated Web Browsers for Confluence (14 December 2009)

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 505

Deprecated macros for Confluence (12 March 2019)

We will end support for the following macros in Confluence 7.0, and hide them from the macro browser. Any
existing instances of these macros will still work, but you won't be able to insert these macros into the editor
using the macro browser:
IM Presence macro
Netwok macro
Search results macro
Space details macro
End of support means Atlassian will not fix bugs related to these macros in Confluence 7.0 or later versions. We
will remove these macro entirely in a future Confluence release, and will provide more information at that time.
To check whether a macro is used in your site, go to

> General Configuration > Macro Usage. Some macros will be listed under the system app that provides
them.

IM Presence macro

The IM Presence Macro shows when a given user is online in a selected chat service. The macro only supports
a small number of chat services, and we feel that most modern chat tools provide better ways to see this
information.
If you have questions or concerns, please comment on this issue
CONFSERVER-57596
WAITING FOR RELEASE .

Network macro

The Network Macro allows you display the people a particular user is following, or people who are following that
user. Following someone is a useful way to get notifications about their activity, and this network information is
also available on each user's profile page.
If you have questions or concerns, please comment on this issue
CONFSERVER-57597
WAITING FOR RELEASE .

Search results macro

The Search Results Macro allows you to display the results of a keyword search on a page. We are making
some great changes to Search over the next few releases, and have observed that this macro is rarely used.
If you have questions or concerns, please comment on this issue
CONFSERVER-57598
WAITING FOR RELEASE .

Space details macro

The Space Details Macro allows you to display basic information about the current space on a page. This
information is available at all times from Space Tools > Overview.
If you have questions or concerns, please comment on this issue
CONFSERVER-57599
WAITING FOR RELEASE .

Deprecated Gadgets in Confluence (12 March 2019)

We will end support for the following Gadgets in Confluence 7.0, and hide them from the macro browser. Any

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 506

existing instances of these gadgets will still work, but you won't be able to insert these gadgets into the editor
using the macro browser:
Activity Stream
Confluence Page Gadget
Confluence Quick Nav Gadget
News gadget
End of support means Atlassian will not fix bugs related to these gadgets in Confluence 7.0 or later versions. We
will remove these gadgets entirely in a future Confluence release, and will provide more information at that time.
Gadgets were designed to allow you to display information dynamically from sources like iGoogle or Jira, for
example, in Confluence. The first gadgets were introduced in Confluence 3.1, and much of the technology they
were based on is now superseded or obsolete. Since then we have also implemented a number of better ways
to display dynamic information using macros and other integration points.

Activity Stream gadget

The Activity stream gadget shows a list of recently changed content in your site. We recommend using the Rece
ntly Updated macro as an alternative in Confluence.

Confluence Page Gadget

This gadget displays the contents of a Confluence page. We recommend using the Include Page macro as an
alternative in Confluence.

Confluence Quick Nav Gadget

This gadget provides a search field that can be used to search for page titles in Confluence. We recommend
using the Livesearch macro as an alternative in Confluence.

News gadget

This gadget previously displayed blogs and other news from Atlassian. It has not been displaying content for
some time. We will remove this gadget completley in 7.0.
If you have questions or concerns, please comment on this issue
CONFSERVER-57614
WAITING FOR RELEASE .

Changes to features in Confluence (12 March 2019)

Shortcut links

We will end support for shortcut links in Confluence 7.0, and will remove the feature completley in a future
Confluence release.
Shortcut Links were introduced in Confluence 2.3 and provided a quick way to add links to websites in wiki
markup. Shortcut links can only be configured by an administrator, are not easily discoverable, and seldom used
by end users.
End of support means that Atlassian will not fix bugs related to shortcut links in Confluence 7.0 or later versions.
If you have questions or concerns, please comment on this issue
CONFSERVER-57610
WAITING FOR RELEASE .

Trackback and external referrers

We will remove the trackback and referrers features completley in Confluence 7.0.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 507

Trackback enables Confluence to send and receive trackback pings when pages are linked to. External
Referrers appear on the Page Information view of a page, and list clicks from external websites to the page.
Trackback is no longer widely used in modern websites, and because it relies on accepting unauthenticated
requests to a particular URL, is a spam vector.
If you have questions or concerns, please comment on this issue
CONFSERVER-57611
WAITING FOR RELEASE .

Orphaned pages screen

We will remove the Orphaned pages screen in the default theme in Confluence 7.0.
The Orphaned pages screen provided a list of all pages that Confluence considers orphaned pages (not a child
of a space homepage, and not linked to by any other page). Since the introduction of the Confluence 5 default
theme, the orphaned pages screen has been less useful because it's always possible to see all pages in a space
via Space Tools > Reorder pages.
If you have questions or concerns, please comment on this issue
CONFSERVER-57601
WAITING FOR RELEASE .

Hipchat integration

We have discontinued development on all chat products. Hipchat Cloud services were shut down in February
2019, and Hipchat Data Center and Server will both reach end of life within the next year.
We will end support for all bundled Hipchat plugins in Confluence 7.0. These will be disabled by default for new
installations. This will have no impact on existing installations, and can be easily enabled if required.
End of support means that Atlassian will not fix bugs related to Hipchat integration in Confluence 7.0 or later
versions.
If you have questions or concerns, please comment on this issue
CONFSERVER-57602
WAITING FOR RELEASE .

Deprecated databases for Confluence (2 October 2018)

Atlassian will end support for PostgreSQL 9.3 in Confluence 6.13. End of support means that Atlassian will not
offer support for, or fix bugs related to, running Confluence 6.13 or later with this database.
Confluence 6.12 is the last version that will support PostgreSQL 9.3.
Confluence 6.12 and earlier versions will continue to work with PostgreSQL 9.3, however we will not fix
bugs affecting these databases after the end-of-life date for your version of Confluence.
Confluence 6.13 and later will not be tested with PostgreSQL 9.3.
Check out the Supported Platforms page for the full list of supported databases.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.

Deprecated databases for Confluence (30 January 2017)

Atlassian will end support for PostgreSQL 9.2 in Confluence 6.8. End of support means that Atlassian will not
offer support for, or fix bugs related to, running Confluence 6.8 or later with this database.
Confluence 6.7 is the last version that will support PostgreSQL 9.2.
Confluence 6.7 and earlier versions will continue to work with PostgreSQL 9.2, however we will not fix
bugs affecting these databases after the end-of-life date for your version of Confluence.
Confluence 6.8 and later will not be tested with PostgreSQL 9.2.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 508

Check out the Supported Platforms page for the full list of supported databases.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.

Deprecated macro for Confluence (31 October 2017)

We will end support for the JUnit Report macro with the release of Confluence 6.6. This macro is used to
display the results of JUnit tests on a Confluence page and, based on our research, is rarely used.
End of support means that Atlassian will not fix bugs related to this macro past the support end date for your
version of Confluence. We will remove this macro entirely in a future Confluence release, and will provide more
information at that time.
To check whether this macro is used in your site, go to

> General Configuration > Macro Usage. The JUnit Report macro will be listed under Advanced Macros if it's
used.
If you have questions or concerns, please comment on this issue
CONFSERVER-53942 - Plans to remove JUnit macro
WAITING FOR RELEASE .

Deprecated driver for Microsoft SQL Server

We are replacing the open source jTDS driver for SQL Server with the official Microsoft JDBC Driver for SQL
Server. This new driver is bundled with Confluence 6.4 and later.
Atlassian will end support for the jTDS driver in Confluence 6.6. End of support means that Atlassian will not
offer support for, or fix bugs related to, installing and running Confluence 6.6 or later with this driver.
Confluence 6.5.x will be the last major release to bundle the jTDS driver.
Confluence 6.5.x and earlier versions will continue to be supported with the jTDS driver, until their support
end date.
Confluence 6.6.x will not bundle or support the jTDS driver. We'll provide plenty of information on how to
migrate to the new driver at that time.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.

Deprecated operating system for Confluence (15 May 2017)

Atlassian will end support for the Oracle Solaris operating system in Confluence 6.3. End of support means
that Atlassian will not offer support for, or fix bugs related to, installing and running Confluence 6.3 or later on
this operating system.
Confluence 6.2.x will be the last major release that can be installed on Solaris.
Confluence 6.2.x and earlier versions will continue to be supported on Solaris, until their support end
date.
Check out the Supported Platforms page for the full list of supported operating systems.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.

Deprecated mobile browser for Confluence (3 November 2016)

Atlassian will end support for the default browser provided with Android 4.0.3 (Ice Cream Sandwich) in
Confluence 6.0. End of support means that Atlassian will not fix bugs related to this browser past the support
end date, except for security related issues. This means:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 509

Confluence 5.10 will be the last major release that supports the default browser provided with
Android 4.0.3 (Ice Cream Sandwich).
Confluence 5.10.x and earlier versions will continue to work on the default browser provided with
Android 4.0.3 (Ice Cream Sandwich).
With the release of Confluence 6.0 we have added support for the default browser provided with current Android
versions from 4.4 (KitKat) and later. Check out the Supported Platforms page for the full list of supported
browsers.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.

Changes to Confluence distributions (8 June 2016)

To help us bring you new Confluence Server releases faster, we are considering only providing 64-bit installers.
Confluence 5.10 would be the last Confluence release to provide a 32-bit installer.
Q: Can I upgrade using the 64-bit installer?
Yes. If you installed Confluence using the 32-bit installer on a 64-bit operating system, you will be able to
upgrade using the 64-bit installer.
Q: What if I am not able to use the 64-bit installer?
We'd love to hear from you to better understand how this change would impact you. Comment on this issue
CONFSERVER-42817 - Planned deprecation of 32-bit installers
RESOLVED or contact us directly at eol-announc
ement at atlassian dot com.

Deprecated browsers for Confluence (8 June 2016)

Atlassian will end support for Internet Explorer 10 in Confluence 6.0. End of support means that Atlassian will not
fix bugs related to Internet Explorer 10 past the support end date, except for security related issues.
This change allows us to use more modern browser technologies to give you the best user experience in
Confluence. Check out the Supported Platforms page for the full list of supported browsers.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.

Internet Explorer 10 (IE10) end of support notes

Confluence 5.10 will be the last major release that supports Internet Explorer 10.
Confluence 5.10.x and earlier versions will continue to work on Internet Explorer 10.
No Confluence releases after 5.10.x will be tested with Internet Explorer 10.

Deprecated databases for Confluence (8 June 2016)

This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcement
at atlassian dot com.

End of life announcement for database support

Database Support End Date

MySQL 5.5 After Confluence 5.10.x

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 510

Notes:

Confluence 5.10 is the last version that will support MySQL 5.5.
Confluence 5.10 and previously-released versions will continue to work with the database version listed
above, however we will not fix bugs affecting these databases after the end-of-life date for your version of
Confluence.
No Confluence releases after 5.10.x will be tested with the database listed above.

Deprecated macros for Confluence (13 November 2015)

Update 22 January 2019

We know from your feedback that the existing View File macros provide important functionality that the
newer file upload and preview experience does not. For this reason, we've decided to reverse the
decision to stop supporting these macros.
This means from Confluence 6.14, we will fix bugs relating to these macros, and will not remove the
macros from Confluence.

With the release of Confluence 5.9 we will be ending support for the following macros, known collectively as the
'View File' macros:
Office Excel
Office Word
Office PowerPoint
PDF
End of support means that Atlassian will not fix bugs related to these macros past the support end date for your
version of Confluence. We plan to remove these macros in a future Confluence release, and will provide plenty
of information to help you make the transition when the time comes.
The View File macros will still be available in future Confluence releases (including Confluence 5.9, 5.10 and
later), but we recommend inserting Office and PDF files as a thumbnail or link, and using the preview to view the
file in full, as it provides a much better way to display Office and PDF files on your pages. See Display Files and
Images for more info.
If you have any questions or concerns, please comment on this issue
CONFSERVER-39829 - Plans to remove the view file macros
RESOLVED

Discontinued features for Confluence (10 July 2015)

Status updates

As part of our work to make Confluence simpler and easier to use we've decided to remove the Status Updates
feature in Confluence 5.9. This includes the ability to:
update your status
see other people's status via their profile or the User Status List macro.
Our research tells us that this feature isn't widely used, and we believe that HipChat gives your team much
better ways to share their status.
We'll provide more information at the time of the Confluence 5.9 release. If you have questions or concerns,
CONFSERVER-38253 - Plans to remove status updates
please comment on this issue RESOLVED .

Documentation theme

In order to better focus our development efforts on a single theme, we plan to remove the Documentation theme
in Confluence 6.0.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 511

We know that many customers use the Documentation theme because they like to have a page tree in their
space sidebar. This has been available in the default theme for some time now, plus other great features like
sidebar shortcuts, JIRA links, and sticky table headers.
To help you switch to the more modern default theme, we've added some of your favorite documentation theme
features, including the ability to add:
a header and footer
custom content to the sidebar.
These new additions to the default theme are available in Confluence 5.9. As these fields will continue to use
wiki markup, you will be able to drop your existing wiki markup straight from the Documentation theme into the
default theme.
To help you switch themes we've put together a FAQ and step-by-step guide which covers everything from how
to turn on the default theme, find out which spaces are using the theme, and what to do if the Documentation
theme is the global theme for your whole site.
If you have any questions or concerns please comment on this issue
CONFSERVER-38256 - Plans to remove the documentation theme
RESOLVED .

Deprecated databases for Confluence (19 May 2015)

This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Database Support End Date

Microsoft SQL 2008

Oracle 11.1 After Confluence 5.8.x

Oracle 11.2

Notes:
Confluence 5.8 is the last version that will support the database versions listed above.
Confluence 5.8 and previously-released versions will continue to work with the database versions listed
above, however we will not fix bugs affecting these databases after the end-of-life date for your version of
Confluence.
No Confluence releases after 5.8.x will be tested with the databases listed above.

Deprecated Tomcat platform for Confluence (1 May 2015)

This section announces the end of Atlassian support for Tomcat 7.0.x for Confluence. As previously announced,
we now only support the version of Tomcat that is bundled with your version of Confluence.
End of support means that Atlassian will not fix bugs related to the specified version of Tomcat, past the support
end date for your version of Confluence. If you have questions or concerns regarding this announcement, please
email eol-announcement at atlassian dot com.

End of Life Announcement for Tomcat 7.0.x Support

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 512

Platform Support End Date

Tomcat 7.0.x When Confluence 5.8 is released

Tomcat 7.0.x notes:

Confluence 5.7 is the last major version that will support Tomcat 7.0.x. The Confluence 5.7.x bug-fix
releases will also continue to support Tomcat 7.0.x.
Confluence 5.7.x and previously-released versions will continue to work with Tomcat 7.0.x. However, we
will not fix bugs affecting Tomcat 7.0.x after the end-of-life date for your version of Confluence.
Confluence 5.8 will not be tested with Tomcat 7.0.x.

Deprecated Web Browsers for Confluence (20 April 2015)

Atlassian will end support for Internet Explorer 9 in the next major release after Confluence 5.8.x. End of support
means that Atlassian will not fix bugs related to Internet Explorer 9 past the support end date, except for security
related issues.
This change allows us to use more modern browser technologies to give you the best user experience in
Confluence. Check out the Supported Platforms page for the full list of supported browsers.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.

Internet Explorer 9 (IE9) End of Support Notes

Confluence 5.8 will be the last major release that supports Internet Explorer 9
Confluence 5.8.x and earlier versions will continue to work on Internet Explorer 9
No Confluence releases after 5.8.x will be tested with Internet Explorer 9

Deprecated Java platform for Confluence (27 January 2015)

This section announces the end of Atlassian support for Java 7 for Confluence. Please note that Oracle is
planning to stop providing public updates for JRE 7 in April 2015.
End of support means that Atlassian will not fix bugs related to the specified version of Java, past the support
end date for your version of Confluence. The details are below. Please refer to the list of supported platforms fo
r details of platform support for Confluence. If you have questions or concerns regarding this announcement,
please email eol-announcement at atlassian dot com.

End of Life Announcement for Java 7 Support

Platform Support End Date

Java 7 (JRE and JDK 1.7) When Confluence 5.8 is released

Java 7 notes:
Confluence 5.7 is the last major version that will support Java 7. The Confluence 5.7.x bug-fix releases
will also continue to support Java 7.
Java 7 (JRE and JDK 1.7) will still be supported in Confluence 5.7.
Confluence 5.7.x and previously-released versions will continue to work with Java 7, but we will not fix
bugs affecting Java 7 after the end-of-life date for your version of Confluence.
Confluence 5.8 will not be tested with Java 7.

Deprecated distribution for Confluence (2 September 2014)

To help us to make Confluence a more robust and scalable application, we have decided to stop providing an
EAR/WAR distribution. This means that the only supported application server will be will be the version of
Tomcat that is bundled with each release.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 513

Confluence 5.6 will be the last Confluence release to provide an EAR/WAR edition.
Q: Do I need to use the installer?
No, the removal of the EAR/WAR distribution does not force you to use the installer. You can still use the
standalone distribution, which doesn't have an install script - it's just a copy of Tomcat with Confluence
configured inside it. Essentially it's a directory that you unpack and then run yourself.
Q: What if a security problem is found in the bundled version of Tomcat?
Our security team monitors vulnerabilities in all our dependencies, including Tomcat, and fixes continue to follow
our Security Bugfix Policy. If at any time you become aware of a vulnerability we've missed, please report it as
described in How to report a security issue.
If you have more questions or concerns regarding this announcement, please contact us at eol-announcemen
t at atlassian dot com.

Deprecated databases for Confluence (12 June 2014)

This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Database Support End Date

PostgreSQL 8.4

PostgreSQL 9.0
With the release of Confluence 5.7
PostgreSQL 9.1

MySQL 5.1

Notes:
Confluence 5.6 is the last version that will support the database versions listed above.
Confluence 5.6 and previously-released versions will continue to work with the database versions listed
above, however we will not fix bugs affecting these databases after the end-of-life date for your version
of Confluence.
Confluence 5.7 has not been tested with the databases listed above.

Deprecated Tomcat platform for Confluence (22 April 2014)

This section announces the end of Atlassian support for Tomcat 6.0.x for Confluence.
End of support means that Atlassian will not fix bugs related to the specified version of Tomcat, past the
support end date for your version of Confluence. The details are below. Please refer to the list of supported
platforms for details of platform support for Confluence. If you have questions or concerns regarding this
announcement, please email eol-announcement at atlassian dot com.

End of Life Announcement for Tomcat 6.0.x Support

Platform Support End Date

Tomcat 6.0.x When Confluence 5.6 is released, due in mid 2014

Tomcat 6.0.x notes:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 514

Confluence 5.5 is the last major version that will support Tomcat 6.0.x. The Confluence 5.5.x bug-fix
releases will also continue to support Tomcat 6.0.x.
Confluence 5.5.x and previously-released versions will continue to work with Tomcat 6.0.x. However, we
will not fix bugs affecting Tomcat 6.0.x after the end-of-life date for your version of Confluence.
Confluence 5.6 will not be tested with Tomcat 6.0.x.

Deprecated Databases for Confluence (2 December 2013)

This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Database Support End Date

PostgreSQL 8.3 When Confluence 5.5 is released, due in early 2014

PostgreSQL 8.3 notes:

Confluence 5.4 is the last version that will support PostgreSQL 8.3.
Confluence 5.4 and previously-released versions will continue to work with PostgreSQL 8.3. However,
we will not fix bugs affecting PostgreSQL 8.3 after the end-of-life date for your version of Confluence.
Confluence 5.5 will not be tested with PostgreSQL 8.3.

Deprecated Web Browsers for Confluence (24 September 2013)

To allow us to dedicate resources to providing the best experience on modern browsers, Confluence 5.5
will be the last release that supports Internet Explorer 8 (IE8). The reasons behind this decision are to
enable us to provide the best user experience to our customers, accelerate our pace of innovation and give
us the ability to utilize modern browser technologies.
End of support means that Atlassian will not perform any maintenance on Confluence related to IE8 after
the final release of Confluence 5.5.x, except for security related issues. In order to minimize the impact on
you and the way your company uses Confluence, we have provided this announcement as early as
possible, and hope that the subsequent 6 month period will give you adequate time to prepare for this
change without disruption.
Atlassian will continue to support Internet Explorer 9 (IE9) and Internet Explorer 10 (IE10) as well as the
latest versions of Chrome, Firefox and Safari. For further information, please refer to the Supported
Platforms page. If you have questions or concerns regarding this announcement, please email
eol-announcement at atlassian dot com.

Deprecated Databases for Confluence (13 August 2013)

This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 515

Database Support End Date

MS SQL 2005 When Confluence 5.3 is released, due in late 2013

MS SQL 2005 notes:

Confluence 5.2 is the last version that will support MS SQL 2005.
Confluence 5.2 and previously-released versions will continue to work with MS SQL 2005. However, we
will not fix bugs affecting MS SQL 2005 after the end-of-life date for your version of Confluence.
Confluence 5.3 will not be tested with MS SQL 2005.

Deprecated Tomcat platform for Confluence (29 August 2012)

This section announces the end of Atlassian support for Tomcat 5.5.x for Confluence. Please note: Apache
have announced that support for Apache Tomcat 5.5.x will end on 30 September 2012: End of life for Apache
Tomcat 5.5.x.
End of support means that Atlassian will not fix bugs related to the specified version of Tomcat, past the
support end date for your version of Confluence. The details are below. Please refer to the list of supported
platforms for details of platform support for Confluence. If you have questions or concerns regarding this
announcement, please email eol-announcement at atlassian dot com.

End of Life Announcement for Tomcat 5.5.x Support

Platform Support End Date

Tomcat 5.5.x When Confluence 5.0 is released, due in early 2013

Tomcat 5.5.x notes:

Confluence 4.3 is the last major version that will support Tomcat 5.5.x. The Confluence 4.3.x bug-fix
releases will also continue to support Tomcat 5.5.x.
Tomcat 6.0.x will still be supported in Confluence 5.0.
Confluence 4.3.x and previously-released versions will continue to work with Tomcat 5.5.x. However, we
will not fix bugs affecting Tomcat 5.5.x after the end-of-life date for your version of Confluence.
Confluence 5.0 will not be tested with Tomcat 5.5.x.

Deprecated Java platform for Confluence (6 August 2012)

This section announces the end of Atlassian support for Java 6 for Confluence. Please note that Oracle has
announced the end of public updates for Java 6: Java SE 6 End of Public Updates Notice.
End of support means that Atlassian will not fix bugs related to the specified version of Java, past the support
end date for your version of Confluence. The details are below. Please refer to the list of supported platforms fo
r details of platform support for Confluence. If you have questions or concerns regarding this announcement,
please email eol-announcement at atlassian dot com.

End of Life Announcement for Java 6 Support

Platform Support End Date

Java 6 (JRE and JDK 1.6) When Confluence 5.0 is released, due in early 2013

Java 6 notes:
Confluence 4.3 is the last major version that will support Java 6. The Confluence 4.3.x bug-fix releases
will also continue to support Java 6.
Java 7 (JRE and JDK 1.7) will still be supported in Confluence 5.0.
Confluence 4.3.x and previously-released versions will continue to work with Java 6. However, we will

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 516

not fix bugs affecting Java 6 after the end-of-life date for your version of Confluence.
Confluence 5.0 will not be tested with Java 6.

Deprecated Databases for Confluence (1 May 2012)

This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Database Support End Date

PostgreSQL 8.2 When Confluence 4.3 is released, due in mid 2012

PostgreSQL 8.2 notes:

Confluence 4.2 is the last version that will support version 8.2 of PostgreSQL.
Versions 8.3, 8.4 and 9.0 will still be supported in Confluence 4.3.
Confluence 4.2 and previously-released versions will continue to work with PostgreSQL 8.2. However,
we will not fix bugs affecting PostgreSQL 8.2 after the end-of-life date for your version of Confluence.
Confluence 4.3 will not be tested with PostgreSQL 8.2.

Deprecated Databases for Confluence (13 March 2012)

This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Database Support End Date

DB2 When Confluence 4.3 is released, due in mid 2012

DB2 notes:
Confluence 4.2 is the last version that will support DB2.
From Confluence 4.3, no versions of DB2 will be supported.
Confluence 4.2 and previously-released versions will continue to work with DB2. However, we will not fix
bugs affecting DB2 after the end-of-life date for your version of Confluence.
Confluence 4.3 will not be tested with DB2.
For help with moving from DB2 to a supported database, please refer to the list of supported databases
and the guide to migrating to another database.

Deprecated Operating Systems for Confluence (21 July 2011)

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 517

This section announces the end of Atlassian support for certain operating systems for Confluence. End of
support means that Atlassian will not fix bugs related to running Confluence server on that operating system
past the support end date.
We will stop supporting the following operating systems from Confluence 4.0, due in late 2011:
Mac OS X (as a Confluence server platform).
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Operating System Support

Operating System Support End Date

Mac OS X (as a Confluence server platform) When Confluence 4.0 releases, due in late 2011

Mac OS X Notes:
Atlassian intends to end support for Mac OS X (as a server platform) in Confluence 4.0 (due for
release in late 2011). Confluence 3.5 is the last version that will support Mac OS X.
The Sun/Oracle JDK/JRE 1.6 is the only JDK platform officially supported by Atlassian. This
means that Apple Mac OS X is not a supported operating system for the Confluence server, as
the Sun/Oracle JDK does not run on Mac OS X.
Accessing Confluence as a user from Mac OS X via a compatible web browser will still be
supported for the forseeable future.

Deprecated Databases for Confluence (7 January 2011)

This section announces the end of Atlassian support for certain database versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain database versions past the support end date.
We will stop supporting the following database versions from Confluence 4.0, due in late 2011:
MySQL 5.0.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Database Support End Date

MySQL (version 5.0 only) When Confluence 4.0 releases, due in late 2011

MySQL Notes:
Atlassian intends to end support for MySQL 5.0 in Confluence 4.0 (due for release in the middle
of 2011). Confluence 3.5 is the last version that will support MySQL 5.0.
MySQL 5.1 will still be supported.
'Support End Date' means that Confluence 3.5 and previously released versions will continue to
work with MySQL 5.0. However, we will not fix bugs affecting MySQL 5.0 past the support end
date.
Confluence 4.0 will not be tested with MySQL 5.0.

Deprecated Web Browsers for Confluence (7 January 2011)

This section announces the end of Atlassian support for certain web browser versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain web browser versions past the support end
date.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 518

We will stop supporting the following web browser versions from Confluence 4.0, late middle of 2011:
Microsoft Internet Explorer 7 (IE7).
Safari 4.
Firefox 3.5.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Web Browser Support

Web Browser Support End Date

Microsoft Internet Explorer (version 7 only) When Confluence 4.0 releases, late the middle of
2011

Safari (version 4 only) When Confluence 4.0 releases, due in late of 2011

Firefox (version 3.5 only) When Confluence 4.0 releases, due in late of 2011

Internet Explorer Notes:

Atlassian intends to end support for IE7 in Confluence 4.0 (due for release in the middle of 2011).
Confluence 3.5 is the last version that will support IE7.
IE8 will still be supported.
'Support End Date' means that Confluence 3.5 and previously released versions will continue to
work with IE7. However, we will not fix bugs affecting IE7 past the support end date.
Confluence 4.0 will not be tested with IE7.
Safari Notes:
Atlassian will introduce support for Safari 5 in Confluence 3.5.
We intend to end support for Safari 4 in Confluence 4.0 (due for release in the middle of 2011).
Confluence 3.5 is the last version that will support Safari 4.
'Support End Date' means that Confluence 3.5 and previously released versions will continue to
work with Safari 4. However, we will not fix bugs affecting Safari 4 past the support end date.
Confluence 4.0 will not be tested with Safari 4.
Firefox Notes:
Atlassian will end support for Firefox 3.0 in Confluence 3.5, as previously announced.
We intend to end support for Firefox 3.5 in Confluence 4.0 (due for release in the middle of 2011).
Confluence 3.5 is the last version that will support Firefox 3.5.
Firefox 3.6 will still be supported.
'Support End Date' means that Confluence 3.5 and previously released versions will continue to
work with Firefox 3.5. However, we will not fix bugs affecting Firefox 3.5 past the support end
date.
Confluence 4.0 will not be tested with Firefox 3.5.

Deprecated Databases for Confluence (12 October 2010)

This section announces the end of Atlassian support for certain database versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain database versions past the support end date.
We will stop supporting the following database versions:
From Confluence 3.5, due in the first half of 2011, Confluence will no longer support PostgreSQL 8.1.
Note, PostgreSQL 8.2 and PostgreSQL 8.4 will still be supported.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 519

Database Support End Date

PostgreSQL (version 8.1 only) When Confluence 3.5 releases, due in the first half
of 2011

PostgreSQL (version 8.1 only) End of Support Notes:

Atlassian intends to end support for PostgreSQL 8.1 in Confluence 3.5 (due to release in the first
half of 2011), with the final support for these platforms in Confluence 3.4. PostgreSQL 8.2 and
PostgreSQL 8.4 will still be supported.
'Support End Date' means that Confluence 3.4 and previous released versions will continue to
work with the PostgreSQL 8.1 However, we will not fix bugs affecting PostgreSQL 8.1 past the
support end date.
Confluence 3.5 (due to release in the first half of 2011) will not be tested with PostgreSQL 8.1.

Deprecated Web Browsers for Confluence (12 October 2010)

This section announces the end of Atlassian support for certain web browser versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain web browser versions past the support end
date.
We will stop supporting the following web browser versions:
From Confluence 3.5, due in the first half of 2011, Confluence will no longer support Firefox 3.0.
Note, Firefox 3.5 and Firefox 3.6 will still be supported.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Web Browser Support

Web Browser Support End Date

Firefox (version 3.0 only) When Confluence 3.5 releases, due in the first half
of 2011

Firefox (version 3.0 only) End of Support Notes:

Atlassian intends to end support for Firefox 3.0 in Confluence 3.5 (due to release in the first half of
2011), with the final support for these platforms in Confluence 3.4. Firefox 3.5 and Firefox 3.6 will
still be supported.
'Support End Date' means that Confluence 3.4 and previous released versions will continue to
work with Firefox 3.0. However, we will not fix bugs affecting Firefox 3.0 past the support end
date.
Confluence 3.5 (due to release in the first half of 2011) will not be tested with Firefox 3.0.

Deprecated Databases for Confluence (6 July 2010)

This section announces the end of Atlassian support for certain database versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain database versions past the support end date.
We will stop supporting the following database versions:
From Confluence 3.4, due in the second half of 2010, Confluence will no longer support Oracle 10g (i.e.
Oracle 10.1 and Oracle 10.2).
Note, Oracle 11g (i.e. Oracle 11.1 and Oracle 11.2) will still be supported.
We have made these decisions in line with Oracle's decision to stop support for Oracle 10g, as per the "Oracle
Database (RDBMS) Releases Support Status Summary [ID 161818.1]" article on the Oracle Support site (note,
you will need an Oracle Support account to find and view the article). This also will reduce the testing time
required for each release and help us speed up our ability to deliver market-driven features. We are committed
to helping our customers understand this decision and assist them in upgrading to Oracle 11g if needed.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 520

The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Database Support End Date

Oracle (version 10.1 and 10.2 only) When Confluence 3.4 releases, due in the second
half of 2010

Oracle (version 10.1 and 10.2 only) End of Support Notes:

Atlassian intends to end support for Oracle 10.1 and Oracle 10.2 in Confluence 3.4 (due to
release in the second half of 2010), with the final support for these platforms in Confluence 3.3
. Oracle 11.1 and Oracle 11.2 will still be supported.
'Support End Date' means that Confluence 3.3 and previous released versions will continue to
work with the Oracle 10.1 and Oracle 10.2. However, we will not fix bugs affecting Oracle 10.1 or
Oracle 10.2 past the support end date.
Confluence 3.4 (due to release in the second half of 2010) will not be tested with Oracle 10.1 and
Oracle 10.2.

Deprecated Web Browsers for Confluence (6 July 2010)

This section announces the end of Atlassian support for certain web browser versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain web browser versions past the support end
date.
We will stop supporting the following web browser versions:
From Confluence 3.4, due in the second half of 2010, Confluence will no longer support Safari 3 or
Safari 3.1.
Note, Safari 4 will still be supported.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Web Browser Support

Web Browser Support End Date

Safari (version 3 and 3.1 only) When Confluence 3.4 releases, due in the second
half of 2010

Safari (version 3 and 3.1 only) End of Support Notes:

Atlassian intends to end support for Safari 3 and Safari 3.1 in Confluence 3.4 (due to release in
the second half of 2010), with the final support for these platforms in Confluence 3.3. Safari 4 will
still be supported.
'Support End Date' means that Confluence 3.3 and previous released versions will continue to
work with the Safari 3 and Safari 3.1. However, we will not fix bugs affecting Safari 3 and Safari
3.1 past the support end date.
Confluence 3.4 (due to release in the second half of 2010) will not be tested with Safari 3 and
Safari 3.1.

Deprecated Databases for Confluence (24 March 2010)

This section announces the end of Atlassian support for certain database versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain database versions past the support end date.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 521

We will stop supporting the following database versions:

From Confluence 3.3, due in Q3 2010, Confluence will no longer support DB2 8.2.
Note, DB2 9.7 will still be supported.
We are reducing our database support to reduce the amount of testing time and help us speed up our ability to
deliver market-driven features. We are committed to helping our customers understand this decision and assist
them in upgrading to DB2 9.7 if needed.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Database Support

Database Support End Date

DB2 (version 8.2 only) When Confluence 3.3 releases, due Q3 2010

DB2 (version 8.2 only) End of Support Notes:

Atlassian intends to end support for DB2 8.2 in Q3 2010, with the final support for these platforms
in Confluence 3.2. DB2 9.7 will still be supported.
'Support End Date' means that Confluence 3.2 and previous released versions will continue to
work with the DB2 8.2. However, we will not fix bugs affecting DB2 8.2 past the support end date.
Confluence 3.3 (due to release in Q3 2010) will not be tested with DB2 8.2.

Deprecated Application Servers for Confluence (27 January 2010)

This section announces the end of Atlassian support for certain application servers for Confluence. End of
support means that Atlassian will not fix bugs related to certain application servers past the support end date.
We will stop supporting the following application servers:
From Confluence 3.2, due late Q1 2010, Confluence will no longer support JBoss application servers.
From Confluence 3.3, due in Q3 2010, Confluence will no longer support Oracle WebLogic, IBM
WebSphere or Caucho Resin.
We are reducing our application server platform support to reduce the amount of testing time and help us
speed up our ability to deliver market-driven features. We are committed to helping our customers understand
this decision and assist them in migrating to Tomcat, our supported application server.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Application Server Support

Application Servers Support End Date

JBoss 4.2.2 When Confluence 3.2 releases, due late Q1 2010

Oracle WebLogic 9.2 When Confluence 3.3 releases, due Q3 2010

IBM WebSphere 6.1 When Confluence 3.3 releases, due Q3 2010

Caucho Resin 3.0, 3.1.6, 3.1.7 When Confluence 3.3 releases, due Q3 2010

JBoss End of Support Notes:

'Support End Date' means that Confluence 3.1 and previous released versions will continue to
work with stated application servers. However, we will not fix bugs affecting JBoss application
servers.
Confluence 3.2 will not support JBoss application servers.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 522

WebLogic, WebSphere and Resin End of Support Notes:

Atlassian intends to end support for Oracle WebLogic, IBM WebSphere, and Caucho Resin in Q3
2010, with the final support for these platforms in Confluence 3.2.
'Support End Date' means that Confluence 3.2 and previous released versions will continue to
work with the stated application servers. However, we will not fix bugs affecting Oracle WebLogic,
IBM WebSphere, and Caucho Resin application servers past the support end date.
Confluence 3.3 (due to release in Q3 2010) will only be tested with and support Tomcat 5.5.20+
and 6.0.
If you have concerns with this end of support announcement, please email eol-announcement
at atlassian dot com.

Why is Atlassian doing this?

We have chosen to standardize on Tomcat, because it is the most widely used application server in our user
population. It is fast, robust, secure, well-documented, easy to operate, open source, and has a huge
community driving improvements. It is the de facto industry standard, with several companies available that
specialize in providing enterprise grade support contracts for it, ranging from customizations to 24/7 support.

Deprecated Java Platforms for Confluence (27 January 2010)

This section announces the end of Atlassian support for certain Java Platforms for Confluence.
We will stop supporting the following Java Platforms:
From Confluence 3.3, due Q3 2010, support for Java Platform 5 (JDK/JRE 1.5) will end.
We are ending support for Java Platform 5, in line with the Java SE Support Roadmap (i.e. "End of Service
Life" for Java Platform 5 dated October 30, 2009). We are committed to helping our customers understand this
decision and assist them in updating to Java Platform 6, our supported Java Platform.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

End of Life Announcement for Java Platform Support

Java Platform Support End Date

Java Platform 5 (JDK/JRE 1.5) When Confluence 3.3 releases, due Q3 2010

Java Platform 5 End of Support Notes:

Atlassian intends to end support for Java Platform 5 in Q3 2010.
'Support End Date' means that Confluence 3.2.x and previous released versions will continue to
work with Java Platform 5 (JDK/JRE 1.5), however we will not fix bugs related to Java Platform 5
past the support end date.
Confluence 3.3 will only be tested with and support Java Platform 6 (JDK/JRE 1.6).
If you have concerns with this end of support announcement, please email eol-announcement
at atlassian dot com.

Deprecated Web Browsers for Confluence (14 December 2009)

This section announces the end of Atlassian support for certain web browsers for Confluence.
We will stop supporting older versions of web browsers as follows:
From Confluence 3.2, due late Q1 2010, support for Firefox 2 and Safari 2 will end.
From 13 July 2010, in line with Microsoft's Support Lifecycle policy, support for IE6 will end.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 523

End of Life Announcement for Web Browser Support

Web Browsers Support End Date

Firefox 2 When Confluence 3.2 releases, late Q1 2010

Safari 2 When Confluence 3.2 releases, late Q1 2010

Internet Explorer 6 When Confluence 3.3 releases (target Q3 2010) or

13 July 2010, whichever is sooner

Firefox 2 and Safari 2 Notes:

Confluence 3.1 is the last version to officially support Firefox 2 and Safari 2.
You may be able to use these older browser for the most common use cases like viewing and
editing content, but official support for these browsers will end once you upgrade to Confluence
3.2.
Confluence 3.2 is currently targeted to release late Q1 2010 and will not be tested with Firefox 2
and Safari 2. After the Confluence 3.2 release, Atlassian will not provide fixes in older versions of
Confluence for bugs affecting Firefox 2 and Safari 2.
Internet Explorer 6 Notes:
Confluence 3.2 (due late Q1 2010) will be the last version to officially support Internet Explorer 6.
Confluence 3.3 is currently targeted to release Q3 2010 and will not support IE6.
Atlassian will support IE6 in Confluence until the 13th of July 2010, in line with Microsoft's Support
Lifecycle policy. Beyond that date, released versions of Confluence will continue working with IE6
just as they did before, but we will not fix bugs affecting Internet Explorer 6.
You may be able to use Internet Explorer 6 for the most common use cases like viewing and
editing content, but official support for this browser will end once you upgrade to Confluence 3.3.
Supported Platforms FAQ
Q: How does Atlassian choose which JRE versions, application servers and databases to support?
For application servers and databases, we try to pick a good cross-section of open source options and popular
commercial platforms. We then choose which JRE versions to support based on the recommended
environments for these servers.
Q: What is a supported platform?
A supported platform is one that:
Confluence is regularly tested on during the development cycle
One that is available within Atlassian for support technicians and developers to reproduce problems
Bugs raised against it will be given a high priority
Supporting a platform means we know how to get Confluence running in that environment and can troubleshoot
Confluence issues within it. It does not mean we have any particular expertise beyond that. As such, we may not
be able to provide assistance with customizing or tuning that application server or database. (Atlassian support
is not a substitute for a good database administrator.)
Q: Can I get assistance with running Confluence on a platform that is not supported?
If you are running Confluence on an unsupported platform, then we can not guarantee providing any support for
it. Furthermore, we will recommend that you switch to a platform which is supported.
Q: If you write your application to standards like J2EE, JDBC and SQL, doesn't that mean it should run
on any compliant server?
Confluence is a complicated application and we commonly encounter interesting edge-cases where different
servers have interpreted the specifications differently. Then again, each server has its own different collection of
bugs.
Q: How can I get Atlassian to support Confluence on a new platform?
Supporting a new platform involves a significant investment of time by Atlassian, both up-front costs to set up
new testing environments and fix any issues we might encounter and the ongoing costs involved in maintaining
the application against this new environment in the future. As such, supporting a new platform is not something

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 524

we will do unless we know there is significant demand for it.

Please be aware that your interest alone will not be enough for us to add support for your application server or
database. We would need to see a significant number of votes on the issue raised in our public Jira site or a
significant level of interest in our forums, before considering supporting that platform.
Q: My organization has standardized on an operating environment that Confluence does not support.
What can I do?
In this situation, you have the following two options:
1. Run Confluence in the unsupported environment, with the caveats mentioned above.
2. Make an exception to your standardized operating environment and set up Confluence based on its
supported platforms.

Migrating Confluence Between Servers

This page describes how to move Confluence On this page:
between physical servers using the same or a
different operating system. Transferring Confluence to
another server
It doesn't cover database migration or upgrading you
r Confluence version. We suggest you do each of
these steps separately.

Transferring Confluence to another server

To transfer Confluence to another server you will copy the home and install folders straight into an identical
external database and user management setup. If your new server is using a different operating system there
may be some additional changes at step 4.
1. Run the Confluence installer on your new server
2. Shut down Confluence on both your old and new servers
3. If you're using Oracle or MySQL, copy the drivers from your old server to the new one
4. Delete the contents of the home directory on your new Confluence server, then copy in the contents of
the home directory from your old Confluence server.
5. Make any additional changes required for your environment.

If you're changing the location of the home directory...

If the path to your home directory is different on the new server open the Confluence_install_
directory/confluence/WEB-INF/classes directory and edit confluence-init.propert
ies by changing the line starting with 'confluence.home='.

If you're moving your database...

If you have also moved your database from one server to another you can change the JDBC URL
in <confluence.home>/confluence.cfg.xml if you are using a direct JDBC connection or in
the definition of your datasource (if you are connecting via a datasource).
If your new server has a different operating system...
If you're migrating from Windows to Linux, you'll need to replace the backslashes with forward
slashes in the following lines in confluence.cfg.xml:

<property
name="attachments.dir">${confluenceHome}/attachments</property
>
<property
name="lucene.index.dir">${localHome}/index</property>
<property
name="webwork.multipart.saveDir">${localHome}/temp</property>

If you're migrating from Linux to Windows, you'll need to replace the forward slashes with

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 525

backslashes in the following lines in confluence.cfg.xml:

<property
name="attachments.dir">${confluenceHome}\attachments</property
>
<property
name="lucene.index.dir">${localHome}\index</property>
<property
name="webwork.multipart.saveDir">${localHome}\temp</property>

6. Copy the <confluence-install>/conf/server.xml file from your old server to the same
location on your new server
7. If you use a data source, ensure the data source points to the new database. See Configuring a
datasource connection.
8. Start Confluence, then head to General configuration > License Details to add your license key
We strongly recommend you perform a rebuild of your content indices after performing a migration, to
ensure Confluence search works as expected.

From Confluence Evaluation through to Production Installation

So, you want to try Confluence on an evaluation On this page:
installation, then move to a production installation Step 1. Set up your evaluation
when you are ready? This page gives an overview of Confluence site
the steps to follow. Step 2. Add users and content to
your evaluation site
Assumptions:
Step 3. Look for interesting
This page starts with telling you how to install Marketplace apps as part of your
an evaluation Confluence site. If you have evaluation
already finished evaluating Confluence, you Step 4. Set up your production
can safely skip steps 1 to 3. Confluence site
Your production installation will be an
Related pages:
installed version of Confluence, not a
Confluence Cloud site. Supported Platforms
You will evaluate Confluence on an installed Add and Invite Users
version too, not a Confluence Cloud site. Getting Started as Confluence
Administrator
If you are using Confluence Cloud to evaluate
Confluence installation and
Confluence, please refer to the following guide when
upgrade guide
you want to move to an installed version: Migrate
from Confluence Cloud to Server.

Step 1. Set up your evaluation Confluence site

If you have already set up an evaluation Confluence site, you can skip this step.
Below is a summary of the installation and setup procedure, focusing on the choice of database.
To install Confluence:
1. Download the installer from the Confluence download site.
Note: If you are using a Mac or another unsupported platform for your evaluation, you will need to
install from a zip file. Details are in the full installation guide.
2. Run the installer and choose the express or custom installation. If you are not sure, choose Express
Install.
The express option will install Confluence with default settings.
The custom option allows you to choose the Confluence installation directory, home (data)
directory, ports and other options.
3. When prompted, choose the option to open Confluence in your browser, where you can complete

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 526
3.

the setup.
To set up Confluence, including the database:
1. Follow the prompts in the browser-based setup wizard, to get your Confluence license.
2. Choose the Trial or Production installation type. If you are not sure, choose Trial Installation.
The Trial option will install Confluence with default settings, including the embedded database
which is automatically set up for you. You'll need to migrate to an external database before
running Confluence in a production environment (more info below).

Step 2. Add users and content to your evaluation site

If you have finished evaluating Confluence, you can skip this step.
Depending on your choices during the Confluence setup, your evaluation site may include sample content.
The example pages, blog posts and attachments are in the 'Demonstration space'. This space is present if:
You chose the 'Trial Installation' during setup.
Or you chose the 'Production Installation', then chose to include the 'Example Site'.
You can update the sample content, and create more of your own. You can also invite people to join you on
the site.
When you move to a production site, you can choose to copy the content and users to the new site.
To create content in your evaluation site:
Choose Spaces > Create Space to add a space, which is like a library of pages.
Choose Create to add pages and blog posts.
To add users: Go to

> User management.

Step 3. Look for interesting Marketplace apps as part of your evaluation

If you have finished evaluating Confluence, you can skip this step.
Apps, also called plugins or add-ons, provide additional features that you can install into your Confluence
site. Some of them are provided free of charge. Many of the commercial apps are available free for an
evaluation period.
You can browse and download app on the Atlassian Marketplace. You can also find apps via the Confluence
user interface, which interacts with the Atlassian Marketplace for you.
To find useful apps via the Confluence user interface:
1. Go to

> Manage apps.

2. Choose Find new add-ons.

Step 4. Set up your production Confluence site

When you are ready to move from an evaluation site to a production site, you need to migrate to a
production-ready database. This involves installing a new Confluence site with a new database, and
instructing Confluence to copy the data from your evaluation site to the new site. You will also need to check
some important configuration settings, and define your backup strategy. The instructions below lead you
through all the steps required.
Migrating your data to a production database:
1. Choose a database carefully, with a focus on reliability and backups. See our list of supported
databases. If you are unsure which one to choose, we recommend PostgreSQL.
2. Install a new database and a new Confluence site, by following our guide to migrating to another

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 527
2.

database. The guide will lead you through the following steps:
Setting up your database server.
Adding a Confluence database (schema) to your database server.
Installing a new, production-ready Confluence site.
Copying your Confluence data from your evaluation site to your new production site.
Setting important configuration options on your production site:
Set the base URL. See Configuring the Server Base URL.
Make sure you have configured an email server. See Configuring a Server for Outgoing Mail.
Decide on proxy setup and other settings that determine where Confluence fits into your network. See
Web Server Configuration.
Consider setting up a secure connection via SSL. See Running Confluence Over SSL or HTTPS.
Read our guidelines on security. See Best Practices for Configuring Confluence Security.
Decide whether you will manage your users in Confluence or connect to an external LDAP directory.
See Configuring User Directories.
Decide whether you want to allow public (anonymous) access to your site. See Setting Up Public
Access.
Set up your permission scheme. See Permissions and restrictions.
Connect Confluence to Jira applications such as Jira Software or Jira Service Desk or other
applications. See Linking to Another Application.
Defining your backup strategy:
By default, Confluence will create daily XML backups of your content and user data. This is suitable when
you are evaluating Confluence. When you move to a production site, you need more robust backup
procedures and technologies. See Production Backup Strategy.

Migrate from Confluence Server to Cloud

Overview On this page:

Overview
This guide provides a high-level plan for migrating a self-hosted Confluence Pre-migrati
Server site to Confluence Cloud. It covers enlisting your project team, on
evaluating technology options, ensuring that the current Confluence Server Migration
site is ready for migration, and executing the migration. Post-migra
tion
Not sure if you should migrate from Confluence Server to cloud? Learn more
about the benefits of Atlassian Cloud or check out our Confluence migration
FAQs.

Some of the steps in this guide require advanced permissions.

Before you begin, you many want to check that you:
1. Have System Administrator global permissions in
Confluence Server.
2. Are in the site-admins group in your cloud site. This grants

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 528
2.
access to all your applications (e.g. Confluence and Jira),
their administration features and site administration, which
includes managing users and bills.

Pre-migration

Decide to migrate

1. Review your security and compliance requirements: Adhering to

your organization's security requirements is critical to a successful
migration. For more information about Atlassian's security, privacy,
and compliance policies, check out Trust at Atlassian. At this point,
you may need to engage with your procurement or security teams to
ensure Confluence Cloud meets your requirements.
2. Evaluate apps: Before deciding to migrate, review any apps and
custom integrations you may have to determine what you'll need for
your Confluence Cloud site. The Atlassian Marketplace offers a large
selection of apps and integrations that extend the functionality of
Confluence Cloud. These include free integrations with leading SaaS
productivity and collaboration products like Slack and Dropbox, and
subscription-based licensing of some of your most beloved Server
apps.

Keep in mind while you're evaluating that while Atlassian’s cloud and
server products provide the same benefits, they can differ in features
and functionality. In some cases, you may discover that the cloud
version of a product includes functionality that is fulfilled through an
app on server. You may also have in-house or custom-built apps to
consider.
a. App data is not typically included when migrating from
Confluence Server to Confluence Cloud. Some apps do have
the capability to export and import their data but you'll need to
check with the app developers or their documentation to
confirm if this is possible.
b. If you do need to map third-party apps to Confluence Cloud,
first check if there is a cloud equivalent of your server app in
our Marketplace. If there is a cloud equivalent, your next step
would be to check with the app developer to see if it stores any
data. Not all apps store data. If it does, you'll need to work with
the app vendor to understand your data migration options.
Atlassian doesn't directly handle migrating data generated
from third-party server apps to cloud apps. If there's no
equivalent and the app stores data, you should still contact the
vendor to see if there's a way to export the data.
3. Check costs: There's no cost to migrate to Confluence Cloud
besides the cost of your Confluence Cloud subscription. However,
you'll still want to assess your payment options and overall costs. A
few things to keep in mind:
a. Unlike Confluence Server, Confluence Cloud is sold as a
subscription, not a perpetual license. You can pay either
monthly or annually, with a discount for paying annually. Check
out Confluence Licensing to decide which payment schedule is
best for your team and estimate your baseline costs, or try our
Atlassian Cloud pricing calculator.
b. If you're planning on using apps from the Atlassian
Marketplace in Confluence Cloud, remember to factor these
into your cost considerations. The Atlassian Cloud pricing
calculator can help you calculate your total monthly or annual
cost including apps.
c. Note that your existing Confluence Server license and

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 529
c.

maintenance do not transfer to Confluence Cloud. These are

two separate licenses, and are paid for separately.
4. Review the FAQs: We've developed a comprehensive set of FAQs i
n the Atlassian Cloud Migration Center to assist you in planning
your Confluence migration. If you have questions that we don't cover,
let us know.
5. Try out Confluence Cloud: Sign up for a free Confluence Cloud trial
to give Confluence Cloud a spin. Keep in mind as you trial that the
design and layout aren't the same across Confluence Server and
Confluence Cloud, and you can't switch between the two. We
recommend trialing Confluence Cloud before migrating to get
comfortable with the differences and identify any communications or
training needed to help onboard your users.

Prepare to migrate

Now that you've decided to migrate, let's figure out how to get there.
1. Assemble your team: Migrating from Confluence Server to Cloud
will have an impact on your users' experience and workflows, as well
as various stakeholders throughout your organization. Depending on
the size of your organization and number of users, a migration may
require a fully fledged project with defined roles and responsibilities
across teams. As early as possible, you should communicate with
individuals and stakeholders who are interested and impacted by a
move to Confluence Cloud. Where possible, recruit and enlist these
people to be a part of the process.
2. Communicate early and often: Beyond informing your organization
about the migration schedule, share your migration plan with team
members. Determine how you'll alert users about any issues or errors
that arise. At this stage, your migration communication plan should
cover things like:
a. When will the migration occur?
b. What downtime can users expect?
c. Ask people to avoid changing anything during the transition.
d. What will happen to the old site after migrating? Will it still be
accessible or readable?
3. Prepare your Confluence Server site: Evaluate your current
environment to determine if you need to make any changes before
migrating your data.
a. To use the Cloud Migration Assistant for Confluence, you'll
need to upgrade your Confluence Server to version 5.10 or
later before migrating.
b. You may also want to take this opportunity to clean up or
remove any unnecessary data.
4. Review your anonymous access settings:
a. If you don't want to allow anonymous users to access to your
Confluence Cloud site without logging in, you'll need to check
that anonymous access isn't enabled in server before
migrating. Learn more at Setting Up Public Access.
b. If you do want to allow anonymous access to some spaces,
but not others, you need to first allow anonymous access in
the global permissions for Confluence Cloud, and then review
the space permissions for each individual space to determine
whether they allow anonymous access. Disabling anonymous
access in the Confluence Cloud global permissions will disable
anonymous access at the space level as well.
5. Back up your data: Back up your Confluence Server data before
migrating to Confluence Cloud. If data is present in your Confluence
Cloud site, back it up for safekeeping as well.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 530

Set up your cloud site

Next, you'll need to sign up for your Atlassian cloud site.

1. Sign up for cloud: Sign up for a free Confluence Cloud trial and
choose a site name (URL). Site names are chosen for an entire
Atlassian Cloud site at the time you sign up for your first Atlassian
Cloud product – for example, when you first sign up for Jira Software
Cloud or Confluence Cloud. The format for the site name is https://ex
ample.atlassian.net, where example is a unique character string that
you specify.
There are a few things to be aware of when choosing your site name:
a. Your unique character string must be at least three characters.
b. It can only contain letters, numbers, and hyphens.
c. Hyphens can't be the first or last character.
2. Set up your organization: An organization allows you to view all
Atlassian Cloud users at your company in one place, manage your
users' accounts, and set up security features like SAML SSO (with a
subscription to Atlassian Access). Organizations are particularly
helpful if your company manages more than one site and wants
insight into all your sites, products, and the users who can access
them. Learn more about how to Set up an Atlassian organization.
3. Set up SSO: If you plan to use SSO in your cloud site, you should set
this up in advance so that it will continue working seamlessly for your
users when you migrate. Before setting this up, you'll need to create
an organization and verify a domain. Learn more about setting up
SSO. Note that this requires a subscription to Atlassian Access,
which you can trial free for 30 days.

Additional considerations

1. Migrating Jira and Confluence: If you're migrating both Jira and

Confluence, we recommend migrating Jira first. Migrating Confluence
before Jira will result in your users being wiped from cloud once Jira
is imported. Learn more about migrating Jira from server to cloud.
After migrating Jira along with your users, you can use the Cloud
Migration Assistant for Confluence to migrate your Confluence
spaces from Confluence Server to Confluence Cloud.
2. Migration services: If you need assistance with your migration, we
have a wide network of partners globally that are very experienced in
Atlassian migrations. Visit our Atlassian Partners page to find one
who can help with your migration.

Migration

After you have the necessary prerequisites in place and have completed the
tasks associated with the pre-migration phase, you're ready to perform the
migration. Follow the steps outlined below to migrate.
1. Run a test migration: We recommend performing a trial run in a
testing or staging site to ensure that your site's integrations,
functionality, and performance are working as expected and the
migration runs smoothly. You can do this using a free Confluence
Cloud trial. The test migration will help you:
a. Identify possible bugs and the steps needed to resolve before
the actual migration.
b. Establish a clearer timeline for your live migration, including
any expected downtime.
c. Validate the data before moving to Confluence Cloud.
2. Build a timeline: Identifying an ideal migration window can mean the
difference between happy and frustrated users. Determine how much

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
2. 6.15 Documentation 531

time your migration will take, factoring in time for troubleshooting.

Consider scheduling the migration for overnight, on a weekend, or
when your team is less likely to need access to Confluence. This will
reduce the risk of data discrepancies between server and cloud.
3. Migrate to cloud: To perform the migration, use the Cloud Migration
Assistant for Confluence. When you migrate, the following data
is imported:
Site data, including spaces, pages and attachments.
Users and groups.
The following is not imported:
Global settings and permissions: These will need to be
configured manually in your cloud site.
Apps: You'll need to work with the app vendors to migrate or
re-install your apps in Confluence Cloud after migrating.
Application links: If you plan to use Altassian server products in
conjunction with your Confluence Cloud site, you can create
two-way links between your cloud and server products. If this
applies to you, you can set set these up after migrating.
User avatars: Users will need to update their avatars at id.atlas
sian.com after migrating.
Passwords: Users will need to reset their passwords
in Confluence Cloud after migrating.

Common scenarios

Not all migrations are quite so straightforward. Below are some of the
common migration scenarios you may encounter, and guidance on how to
approach each.
Merging server sites
If you need to merge multiple Confluence Server sites, just install the Cloud
Migration Assistant for Confluence on all server instances and move them
separately to the Confluence Cloud site.
Keep in mind that every space in your Confluence Cloud site needs to have
a unique space key. If a space key already exists in your Confluence Cloud
site, trying to migrate a space with the same space key will cause that
individual spaces' migration to fail.

Troubleshooting your migration

If you've run into a problem during your migration, we're here to help. You
can start by searching for known issues in our public issue tracker. There,
you can find information about some of the common issues we see with Con
fluence migrations, including their status and suggested workarounds.
Some known issues include the following:

CONFCLOUD-64436 - Former users after importing from Server instance

RESOLVED
CONFSERVER-57776 - Time is displaying differently after migrating from
Server to Cloud SHORT TERM BACKLOG

If you've run into a different issue or need help to move forward with your
migration, you can contact our Technical Support team or reach out to our A
tlassian Community for advice.

Post-migration

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 532

After you've successfully completed the migration, you'll need to go through

a series of post-migration tasks to ensure that everything is functioning as
smoothly and efficiently as possible.
1. Review your cloud site: When your migration is complete, you will
need to review the new Confluence Cloud site to ensure your data
and attachments have migrated successfully. We recommend:
a. Checking spaces for common things, e.g. comments,
attachments, and permissions.
b. Allowing time for different teams and users to test the
operation and functionality of the application to identify any
behavior gaps. If needed, you may want to document them for
your users.
2. Install apps: If you've identified apps that should be installed, add
them to your Confluence Cloud site.
3. Follow our cloud security best practices: Create a strong
foundation for securing your company’s most important work. Learn
more.
4. Get acquainted with cloud: To learn more about what's new in
Confluence Cloud and how to get the most of it, check out the Conflu
ence Cloud documentation. Consider sharing this resource with your
users if this is their first introduction to Confluence Cloud. You may
also find the Atlassian Cloud documentation a helpful resource as
you get started as a Confluence Cloud admin.
5. Welcome your team: Now that the migration is complete, make sure
your organization is ready. Once migrated, you'll need to send an
invitation or the link to your new site to your users so they can start
using it. They will not be automatically invited. After you invite them,
they'll also need to reset their passwords and avatars.

We recommend developing a comprehensive launch communication

plan to share the new Confluence Cloud site information with the
team. This can cover topics like:
a. What action is needed post-migration?
b. Will users need to reset their passwords and avatars?
c. What URL will they use to access the new site?
d. Who can they contact with questions, and how? For example,
can you provide a chat room or an issue tracker where people
can raise any issues or feedback?
e. Are there any notable changes they'll need to be aware of?
f. Links to any further reading or FAQs.
g. Let people know about the Confluence Cloud mobile app.

Sit back and relax

Now that you're a cloud admin, you'll have immediate access to our latest
features and bug fixes. Installs, upgrades, and patches are managed
seamlessly by Atlassian, so you can relax on your weekends.
To keep track of major changes that affect all users of the Confluence Cloud
products, follow the Atlassian Cloud Documentation blog. This includes new
features, bug fixes, and other changes across all Atlassian Cloud products,
for example, updates to the meeting notes templates or the ability to drag
and drop spaces for easy space reorganization in Confluence Cloud.

Additional support

We have a number of support channels available to help you with your

migration. For more Jira migration planning information and FAQs, visit the
Atlassian Cloud Migration Center.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 533

Need more help with strategy, best practices, or planning questions? Our mi
gration planning specialists can help with planning your migration from Jira
Server to Jira Cloud.
Technical question or issue? Get in touch with our Technical Support team.
Looking for peer advice? Ask the Atlassian Community.

Cloud Migration Assistant for Confluence

The Cloud Migration Assistant for Confluence is an app that helps you easily move content, users, and groups
from Confluence Server to Confluence Cloud. Built and maintained by Atlassian, the app is free to install and
use.
Once installed, you can choose what you want to move to the Cloud, start migrating at your convenience, and
monitor the progress of everything throughout the migration process.

When to use the Cloud Migration Assistant for Confluence

After completing the pre-migration steps in your migration plan.

After you've migrated your Jira Server instance to your Jira Cloud site, and you're ready to migrate to a
new Confluence Cloud site. Migrating Jira after Confluence may overwrite some of the migrated data.
When you want to migrate an entire Confluence Server site to a new Confluence Cloud site.
When you want to move spaces or users from Confluence Server to an existing Confluence Cloud site.
When the Atlassian Support team has recommended using the app.

Before you migrate

Check out the Cloud Migration Center and FAQs to find out everything you need to know before
migrating. You can also use our helpful guide to plan your migration from start to finish.
Pre-migration checklist
You'll need a Confluence Cloud site set up before migrating. If you haven’t already set one up,
start a free 7-day trial.
Your Confluence Server site will need to be version 5.10 or later to migrate to cloud. If you're
running an earlier version, you'll need to upgrade it first.
Check that you have System Administrator global permissions in Confluence Server, and Site
Administrator permissions in your destination cloud site.
Before you run a migration plan, we recommend backing up your current Confluence Server site.
If your destination cloud site has existing data, back up your Confluence Cloud site as well.
This tool does not migrate any app data. You'll need to check with the app developers to confirm
whether you are able to move app data across. You can check what apps you're using at my.atla
ssian.com.
If you use a third-party user management system, you'll need to check that it is compatible with At
lassian Access.
Confluence Data Center
This app is not compatible with Confluence Data Center.

Step 1: Check for possible data conflicts in your cloud site

You can reduce the risk of running into issues, or the migration failing, if you conduct some manual checks in
your server instance and cloud site.

Groups

Make sure that there are no groups already in your cloud site with the same name as groups from your
server site, unless you are intentionally trying to merge them.
If we find a group in your server instance that has the same name a group in your cloud site (either Jira or
Confluence), we will merge the users from the server group into the cloud group. The server group users will

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 534

inherit the permissions of the cloud group. This also applies to groups with Jira product access that have the
same name as a Confluence group you are migrating. This is because all users and groups are managed in a
central location in your cloud site.
If you don’t want this to happen, you will need to make sure all groups across server and cloud have unique
names before running your migration plan.

The following generic groups are blacklisted and will not be migrated at
all: "site-admins", "system-administrators", "atlassian-addons", "atlassian-addons-admin". Users from
within these groups will be migrated, you will then need to manually add them to these groups after
migration.

Space keys

Your migration could also fail if a space from your server instance has the same space key as a space in your
cloud site. This is because every space in Confluence Cloud must have a unique space key.
If the migration assistant finds a conflict, the space will not migrate. In this case some spaces may still migrate,
but the overall plan will fail.
Before migrating, check that there are no competing space keys between your Server and Cloud sites. If you
find a conflict you may need to use a workaround to change the space key, or you can choose not to migrate
that space in step 3.
If a space key conflict is caused by a previous test migration you can reset your cloud site before migrating.

Step 2: Install the Cloud Migration Assistant for Confluence app

There are a few things to check before using the app:

Set up your Confluence Cloud site. If you don't already have one, start a free 7-day trial.
Upgrade your Confluence Server instance to version 5.10 or later. You will not be able to run a migration
on an earlier version.
Check that you have System Administrator global permissions in Confluence Server, and Site
Administrator permissions in your destination Cloud site.
Back up your current Confluence Server instance. If your destination Cloud site has existing data, back up
your Confluence Cloud site as well.
Check your firewall. If your Confluence Server site is behind a firewall, you'll need to allow access to *.atla
ssian.com.
Once all of the prerequisites are complete, you can begin using the app. If your Confluence Server instance is
version 6.13 or above you won't need to install anything because it comes pre-installed, although you may be
asked to update the app. See step 3 to locate the migration assistant within your server instance.
To install the app on versions 5.10 to 6.12:
1. In Confluence Server go to

> Manage apps.

2. Choose Find new add-ons.
3. Search for the Cloud Migration Assistant for Confluence app.
4. Choose Install and you're all set.

Step 3: Use the app to prepare and run your migration

Analyze your instance

1. In Confluence Server, go to

> General Configuration > Migration Assistant.

2. Choose Create a migration plan > Run analysis

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 535

This step evaluates your Confluence Server instance. It will give you an overview of the number of users,
groups, spaces, pages, and attachments that currently exist.
It will also check for any user account errors, such as invalid or duplicate email addresses. You'll need to resolve
these errors before you can migrate.

Updating the app

You may be asked to update the Cloud Migration Assistance for Confluence. You will need to do this before
running any migrations.

Choose what you'd like to migrate

You can migrate everything together or break it up into different stages.

You can choose:
all or none of your users and groups
which individual spaces (and their attachments) you'd like to migrate

If you choose to migrate spaces and no users, some user data will be migrated along with the spaces.
This is to make sure that mentions and comments stay active. These users will appear in your cloud site
but will not be granted product access, and will not be added to your license.

If you choose to migrate users later, their product access will be updated.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 536

Migrating users and groups

There are a few things to be aware of when migrating users and groups from your server instance to a cloud
site:
Confluence Cloud is subscription-based and billed on a per-user basis. If you plan to migrate your users,
make sure you check the licensing options or calculate the cost with our pricing calculator.
If you use an external user management system, we recommend syncing it with your local directory
before migrating.
All users must have a unique and valid email address before you will be able to migrate. The process for
fixing any invalid email errors will depend on where your user data is stored.
Users with disabled status will be migrated as active but without any product access. This means they
will not be counted as active Confluence users for billing purposes.
If we find a group in your server instance that has the same name a group in your cloud site, we will
merge the users from the server group into the cloud group.
Global settings and global site permissions are not migrated with this tool. You will need to set
these manually after migration.

If your users already exist in cloud

If you have users that already exist in your destination cloud site and you choose to migrate users with this app,
you will need to consider the following:
If a user has product access in cloud, but has disabled status in your server instance, they will
continue to have product access in cloud after migration.
If a user does not have product access in cloud, but is enabled in your server instance, they will be
granted product access through the migration process.
If we find a group in your server instance that has the same name a group in your cloud site, we will
merge the users from the server group into the cloud group.

When migrating users and groups, be sure to check for the issues listed above. Some users may be
granted escalated access.

Add spaces to your plan

When you're ready to add spaces to your plan, select Continue.

Select the spaces you want to add to your migration plan. You can filter the list or search for particular spaces,
or click Select all if you want to migrate everything at once. You will not be able to migrate spaces with space

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 537

keys that already exist in your Confluence Cloud destination site. Make sure you check for conflicting space keys
in step 1.

When you've chosen all your spaces, select Add items to plan.

Give the plan a name

Add a name for your migration plan in the Migration plan name field. This name helps you keep track of your
plans, for example, differentiating between a user migration, a test migration, and a final production migration.

Choose your destination Confluence Cloud site

1. Select Choose cloud site and follow the prompts to log in to your Atlassian Cloud account as a Site
Admin (if you're not already logged in).
2. The sites associated with your Atlassian Cloud account will be listed in the Migration destination drop-d
own menu. If the current account is not correct, click Change account to log in with a different account.
3. Select your site from the Migration destination field then select Confirm.
4. When you're ready, select Review plan.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 538

Review your migration plan

If everything looks correct and you want to start your migration, click Run. If you would like to start your
migration later from your migration dashboard, click Save. If you choose to run your migration plan, it will still be
saved to your migration dashboard. There, you can view the progress and details of the migration.
The first time you run a migration plan, you will be asked to Securely share your migration data with
Atlassian to begin the cloud migration process. This allows Atlassian to securely copy data from your
Confluence Server instance to your Confluence Cloud site. You will need to confirm that you agree before the
migration plan can run.

You won't be able to run your migration until all user email errors are resolved. This is because these
errors will cause the migration to fail.

Manage your migration plans

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 539

Your saved migration plan will be listed on the migration dashboard, where you can view its details or run it. You
can also check the status of a plan, monitor the progress of a migration plan that is currently running, stop a plan
that's currently running, or create a new plan.
You can create as many plans as you need. At this time, migration plans can't be edited or deleted, so if you
create a plan that can't be used, just create a new plan to continue your migration to the Cloud.

Plan status definitions

READY Your migration plan is ready to run.

RUNNING Your migration plan is currently in progress.

FINISHED Everything in your migration plan has been migrated.

STOPPED Your migration plan has been stopped. Once stopped, it can't be resumed. Any step already in
progress will first need to finish before the plan is shown as fully stopped. Some users, groups and spaces may
already have been migrated to your Confluence Cloud site.

FAILED We were unable to complete the migration plan. This might be because a space key already
exists in the destination site, or the migration hit an unexpected error. Some users, groups and spaces may
already have been migrated to your Confluence Cloud site.

Run a saved migration plan

To run your plan:

1. In Confluence Server, go to

> General Configuration > Migration Assistant.

2. Select Run on the plan you want to run. The first time you run a migration plan, you will be asked to Secu
rely share your migration data with Atlassian to begin the cloud migration process. This allows
Atlassian to securely copy data from your Confluence Server instance to your Confluence Cloud site. You
will need to confirm that you agree before the migration plan can run.
You can check the progress of your migration in the progress column, or choose View details to see a summary
of the migration tasks.
After migrating spaces, it may take a while for them to appear in the space directory. However, you can still
access them via a direct link.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 540

Step 4: After migrating

Depending on the type of migration, there may be some things you need to do once your migration is finished.

Users and groups

To make sure your users and groups are set up correctly:

Review members of groups and approve their permissions by going to Review imported groups.
Add users to the generic groups if necessary. The generic groups are: "site-admins", "system-administrat
ors", "atlassian-addons", "atlassian-addons-admin"
If you use an external user management system, check that your users have synced correctly.
When you are ready, invite your users by using the send reminder email function. When they first login
they may be prompted to set a new password and add personal details.

Spaces

To check that your spaces have migrated successfully:

Review content and spaces, or ask your users to review their own content.
Check for any instances of Former User. This means that we were unable to match content to a user.
You can then install any apps you wish to use and onboard your users.
For a full list of post-migration recommendations, refer to the Confluence migration planning guide.

More information and support

We have a number of channels available to help you with your migration. For more Confluence migration
planning information and FAQs, visit the Atlassian Cloud Migration Center.
Need more support with strategy, best practices, or planning questions? Our migration planning specialists can
help with planning your migration from Jira Server to Jira Cloud.
If you have technical question or issues, get in touch with our Technical Support team.
Looking for peer advice? Ask the Atlassian Community.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 541

Leave a review

Your feedback is invaluable in helping us improve our products. Please take a moment to let us know what you
think by leaving a review of the Cloud Migration Assistant for Confluence on the Atlassian Marketplace.

Migrate from Confluence Cloud to Server

This page is for people who are currently using On this page:
Confluence Cloud, and wish to move to Confluence Migration steps
Server (a self-hosted Confluence site). Support, limitations, and
recommendations
For migrating from Confluence Server to Marketplace apps
Confluence Cloud, see Plan your Database considerations
Confluence Server to Cloud migration. Confluence license

You can migrate from Confluence Cloud to Confluence Server 6.0 or later only. You can't import Cloud data
(either the whole site or individual spaces) into any earlier versions of Confluence. We recommend installing
the latest version of Confluence Server.
Confluence Cloud is typically ahead of Confluence Server, which means that some features may not be
available after you've moved to Confluence Server.

Migration steps

To migrate from Confluence Cloud to Confluence Server:

1. Export the data from your Confluence Cloud site, using the Confluence backup manager.
For detailed instructions, see Exporting wiki data.
You'll now have an XML export of your Confluence data.
2. Download the latest Confluence Server release. You will only be able to import your Cloud backup into
Confluence 6.0 or later. We recommend always installing the latest release.
3. Follow the Confluence Installation Guide for your platform to install Confluence.
4. Import the data from your backup file (XML export) into your new Confluence installation - see Restori
ng a Site.
5. Follow the steps on Restore Passwords To Recover Admin User Rights to start Confluence in
recovery mode, and log in using the temporary account.
6. Create a new user account, and make it a member of the confluence-administrators group. This will be
your system administrator account.
7. Stop Confluence, remove the recovery mode system property, then restart Confluence.

Support, limitations, and recommendations

Please note the following about your new Confluence Server site.

If you're unable to remove the Jira Cloud application link from your Confluence after the
import, you'll need to remove those references directly from the Confluence database as per t
his guide.
The User Management section might be missing due to
CONFSERVER-35177 - User and Group Links Missing from Admin Console After Migrating From Cloud
to Server GATHERING IMPACT

Follow the workaround notes on the issue to enable the feature again.
If your Confluence Cloud site has macros that depend on the Application Links back to a Jira
Cloud instance, and you are migrating Jira as well, these references will need to be updated
to work properly as per
APL-1144 - Allow relocation of application links even if the target application is still accessible.
TRIAGE
You can address that by either editing the XML prior to import, or by bulk editing those
references in Confluence database as per this guide .
If you experience problems loading pages after the import, head to

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 542

> General Configuration to check your base URL as the port may have changed.
If you find that some of your users' favorites (pages saved for later) are missing due to
CONFSERVER-36348 - Favourites missing after importing
GATHERING IMPACT . See How to
restore missing favorites after import from XML for more information.
Confluence spaces are not automatically created when you create a new Jira project.
If you are unable to create or edit pages after migrating from Cloud to Confluence 5.10, follow
the workaround in this issue to disable the specified dark features
CONFSERVER-44335 - Edit/Create pages is not working when migrate from Cloud to Server
CLOSED .
This issue doesn't affect Confluence 6.x versions.

Marketplace apps

After migrating your data you will need to install any compatible apps, such as Questions and Team
Calendars.
Please note that your Questions data will not be included in the migration.
Some third party apps are only available for Cloud, and will no longer be available after you migrate. You can
check whether your essential apps are available for Confluence Server, Cloud or both on Atlassian
Marketplace.

Database considerations

If you are uncertain about which database to choose for your new Confluence installation, we recommend
PostgreSQL - see Database Setup for PostgreSQL. The Confluence Cloud site runs on PostgreSQL, so
there should be no compatibility issues.
If you choose another supported database, contact Support if you encounter any compatibility issues.

Confluence license

You will need a new license to migrate to Confluence Server. Your existing Confluence Cloud license cannot
be used. You can get a new license at https://my.atlassian.com. You may also need new licenses for any
paid Marketplace apps.

Confluence Data Center

Confluence Data Center is designed to support the unique, and complex requirements of enterprise
organizations, providing performance at scale and high availability. This page provides an overview of
options and considerations for large enterprises using Confluence. If you want to find out how to make sure
Confluence can scale with your organization, this information is for you.
Performance at scale: If your Confluence instance has a very heavy load (you have a lot of users
accessing Confluence at the same time) a clustered installation will spread the load evenly between
cluster nodes, enabling you to serve more requests.
High availability and failover: If one cluster node goes down, then the remaining cluster nodes can
continue servicing requests so that users see little or no loss of availability.
Instant scalability: You can rapidly provision extra capacity with no downtime. Licensing is based on
users, not the number of nodes in your cluster. This means you can join additional nodes to your
cluster at any time, making it very easy to adapt as your usage grows.

A look at the architecture

Confluence Data Center enables you to configure a cluster similar to the one pictured here:

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 543

Load balancer Application nodes Shared database and storage

The load balancer distributes The cluster of Data Center nodes Data Center supports the same
requests from your users to the share the workload of incoming databases that are supported for
cluster nodes. If a cluster node requests. Failure of a cluster Confluence Server. It also
goes down, the load balancer node causes virtually no loss of supports any shared file system,
immediately detects the failure availability for users, because which stores: import/export files,
and automatically directs requests are immediately directed plugins, Logos directory, shared
requests to the other nodes within to other nodes. All nodes are caches, and any data directory
seconds. You can use any load active and process requests. which includes attachments,
balancer that supports session avatars and icons.
affinity.

Get started with Confluence Data Center

Contact us to speak with an Atlassian, or learn more about the benefits of Confluence Data Center on our
website.
Want to see what's included with a Data Center license? Head to the Confluence Server and Data Center
feature comparison.
For all the technical details and considerations, see Confluence Data Center Technical Overview. For help
with installation, take a look at Installing Confluence Data Center.

Confluence Data Center Technical Overview

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 544

This page provides information on Confluence Data On this page

Center, which is designed to meet the needs of
busy, mission critical Confluence sites. How it works
Infrastructure and hardware
requirements
How it works Database
User management
Marketplace apps

The basics

Confluence Data Center enables you to set up Confluence in a cluster similar to the one pictured below with:
Multiple server nodes that run the Confluence application, and other required components.
A shared file system that stores attachments, and other shared files.
A database that all nodes read and write to.
A load balancer to evenly direct requests to each node.
All Confluence nodes are active and process requests. A user will access the same Confluence node for all
requests until their session times out, they log out, or a node is removed from the cluster.

Licensing

Your Data Center license is based on the number of users in your cluster, rather than the number of nodes.
You can monitor the available license seats in the License page.
If you wanted to automate this process (for example to send alerts when you are nearing full allocation) you
can use the REST API.
REST API...

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 545

The following GET requests require an authenticated user with system administrator permissions. The
requests return JSON.

<confluenceurl>/rest/license/1.0/license/userCount Number of active users

<confluenceurl>/rest/license/1.0/license/remainingSeats Number of users you

can add before
reaching your license
limit

<confluenceurl>/rest/license/1.0/license/maxUsers Maximum number of

users allowed by your
license

Your Confluence license determines which features and infrastructure choices are available. Head to Conflue
nce Server and Data Center feature comparison for a full run down of the differences between a Server
license and a Data Center license.

Home directories

Confluence has a concept of a local home and shared home.

Each Confluence node has a local home that contains logs, caches, Lucene indexes and configuration files.
Everything else is stored in the shared home, which is accessible to each Confluence node in the cluster.
Marketplace apps can choose whether to store data in the local or shared home, depending on the needs of
the app.
Here's a summary of what is found in the local home and shared home:

Local home Shared home

logs attachments
caches avatars / profile pictures
Lucene indexes icons
configuration files export files
plugins import files
plugins

If you are currently storing attachments in your database you can continue to do so, but this is not available
for new installations.

Caching

Confluence uses a distributed cache that is managed using Hazelcast. Data is evenly partitioned across all
the Confluence nodes in a cluster, instead of being replicated on each node. This allows for better horizontal
scalability, and requires less storage and processing power than a fully replicated cache.
Because of this caching solution, to minimize latency, your nodes should be located in the same physical
location.

Indexes

A full copy of the Confluence indexes are stored on each Confluence node individually. A journal service
keeps each index in synch.
When you first set up your cluster, you will copy the local home directory, including the indexes, from the first
node to each new node.
When adding a new Confluence node to an existing cluster, you will copy the local home directory of an
existing node to the new node. When you start the new node, Confluence will check if the index is current,
and if not, request a recovery snapshot of the index from either the shared home directory, or a running node
(with a matching build number) and extract it into the index directory before continuing the start up process. If

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 546

the snapshot can't be generated or is not received by the new node in time, existing index files will be
removed, and Confluence will perform a full re-index.
If a Confluence node is disconnected from the cluster for a short amount of time (hours), it will be able to use
the journal service to bring its copy of the index up-to-date when it rejoins the cluster. If a node is down for a
significant amount of time (days) its Lucene index will have become stale, and it will request a recovery
snapshot from an existing node as part of the node startup process.
If you suspect there is a problem with the index on all nodes, you can temporarily disable index recovery on
one node, rebuild the index on that node, then copy the new index over to each remaining node.

Cluster safety mechanism

The ClusterSafetyJob scheduled task runs every 30 seconds in Confluence. In a cluster, this job is run on
one Confluence node only. The scheduled task operates on a safety number – a randomly generated
number that is stored both in the database and in the distributed cache used across the cluster. The
ClusterSafetyJob compares the value in the database with the one in the cache, and if the value differs,
Confluence will shut the node down - this is known as cluster split-brain. This safety mechanism is used to
ensure your cluster nodes cannot get into an inconsistent state.
If cluster split-brain does occur, you need to ensure proper network connectivity between the clustered
nodes. Most likely multicast traffic is being blocked or not routed correctly.
This mechanism also exists in standalone Confluence.

Balancing uptime and data integrity

By changing how often the cluster safety scheduled job runs and the duration of the Hazelcast heartbeat
(which controls how long a node can be out of communication before it's removed from the cluster) you can
fine tune the balance between uptime and data integrity in your cluster. In most cases the default values will
be appropriate, but there are some circumstances where you may decide to trade off data integrity for
increased uptime for example.

Here's some examples...

Uptime over data integrity

Cluster Hazelcast Effect

safety heartbeat
job

1 1 minute You could have network interruptions or garbage collection pauses of up to 1

minute minute without triggering a cluster panic. However, if two nodes are no longer
communicating, conflicting data could be being written to the database for up
to 1 minute, affecting your data integrity.

10 30 You could have network interruptions or garbage collection pauses of up to

minutes seconds 30 seconds without nodes being evicted from the cluster. Evicted nodes then
have up to 10 minutes to rejoin the cluster before the Cluster Safety Job kicks
in and shuts down the problem node. Although this may result in higher
uptime for your site, conflicting data could be being written to the database for
up to 10 minutes, affecting your data integrity.

Data integrity over uptime

Cluster Hazelcast Effect

safety heartbeat
job

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 547

15 15 Network interruptions or garbage collection pauses longer than 15 seconds

seconds seconds will trigger a cluster panic. Although this may result in higher downtime for
your site, nodes can only write to the database while out of communication
with each other for a maximum of 15 seconds, ensuring greater data
integrity.

15 1 minute You could have network interruption or garbage collection pauses up to 1

seconds minute without nodes being evicted from the cluster. Once a node is evicted,
it can only write to the database for a maximum of 15 seconds, minimizing
the impact on your data integrity.

To find out how to change the cluster safety scheduled job, see Scheduled Jobs.
You can change the Hazelcast heartbeat default via the confluence.cluster.hazelcast.max.no.
heartbeat.seconds system property. See Configuring System Properties.

Cluster locks and event handling

Where an action must only run on one node, for example a scheduled job or sending daily email notifications,
Confluence uses a cluster lock to ensure the action is only performed on one node.
Similarly, some actions need to be performed on one node, and then published to others. Event handling
ensures that Confluence only publishes cluster events when the current transaction is committed and
complete. This is to ensure that any data stored in the database will be available to other instances in the
cluster when the event is received and processed. Event broadcasting is done only for certain events, like
enabling or disabling an app.

Cluster node discovery

When configuring your cluster nodes you can either supply the IP address of each cluster node, or a
multicast address.
If you're using multicast:
Confluence will broadcast a join request on the multicast network address. Confluence must be able to open
a UDP port on this multicast address, or it won't be able to find the other cluster nodes. Once the nodes are
discovered, each responds with a unicast (normal) IP address and port where it can be contacted for cache
updates. Confluence must be able to open a UDP port for regular communication with the other nodes.
A multicast address can be auto-generated from the cluster name, or you can enter your own, during the
set-up of the first node.

Infrastructure and hardware requirements

The choice of hardware and infrastructure is up to you. Below are some areas to think about when planning
your hardware and infrastructure requirements.

AWS Quick Start deployment option

If you plan to run Confluence Data Center on AWS, a Quick Start is available to help you deploy Confluence
Data Center in a new or existing Virtual Private Cloud (VPC). You'll get your Confluence and Synchrony
nodes, Amazon RDS PostgreSQL database and application load balancer all configured and ready to use in
minutes. If you're new to AWS, the step-by-step Quick Start Guide will assist you through the whole process.
Confluence can only be deployed in a region that supports Amazon Elastic File System (EFS). See Running
Confluence Data Center in AWS for more information.
It is worth noting that if you deploy Confluence using the Quick Start, it will use the Java Runtime Engine
(JRE) that is bundled with Confluence (/opt/atlassian/confluence/jre/), and not the JRE that is installed on the
EC2 instances (/usr/lib/jvm/jre/).

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 548

Server requirements

You should not run additional applications (other than core operating system services) on the same servers
as Confluence. Running Confluence, Jira and Bamboo on a dedicated Atlassian software server works well
for small installations but is discouraged when running at scale.
Confluence Data Center can be run successfully on virtual machines. If plan to use multicast, you can't run
Confluence Data Center in Amazon Web Services (AWS) environments as AWS doesn't support multicast
traffic.

Cluster nodes

Your Data Center license does not restrict the number of nodes in your cluster. We have tested the
performance and stability with up to 4 nodes.
While each node does not need to be identical, but for consistent performance we recommend they are as
close as possible. All cluster nodes must:
be located in the same data center
run the same Confluence version (for Confluence nodes) or the same Synchrony version (for
Synchrony nodes)
have the same OS, Java and application server version
have the same memory configuration (both the JVM and the physical memory) (recommended)
be configured with the same time zone (and keep the current time synchronized). Using ntpd or a
similar service is a good way to ensure this.
You must ensure the clocks on your nodes don't diverge, as it can result in a range of problems with
your cluster.

Memory requirements

Confluence nodes

We recommend that each Confluence node has a minimum of 10GB of RAM. A high number of concurrent
users means that a lot of RAM will be consumed.
Here's some examples of how memory may be allocated on different sized machines:

RAM Breakdown for each Confluence node

10GB 2GB for operating system and utilities

4GB for Confluence JVM (-Xmx 3GB)
2GB for external process pool (2 sandboxes with -Xmx 512MB each)
2GB for Synchrony

16GB 2GB for operating system and utilities

10GB for Confluence JVM (-Xmx 8GB)
2GB for external process pool (2 sandboxes with -Xmx 512MB each)
2GB for Synchrony

The maximum heap (-Xmx) for the Confluence application is set in the setenv.sh or setenv.bat file. The
default should be increased for Data Center. We recommend keeping the minimum (Xms) and maximum
(Xmx) heap the same value.
The external process pool is used to externalise memory intensive tasks, to minimise the impact on individual
Confluence nodes. The processes are managed by Confluence. The maximum heap for each process
(sandbox) (-Xmx), and number of processes in the pool, is set using system properties. In most cases the
default settings will be adequate, and you don't need to do anything.

Standalone Synchrony cluster nodes

Synchrony is required for collaborative editing. By default, it is managed by Confluence, but you can choose

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 549

to run Synchrony in its own cluster. See Possible Confluence and Synchrony Configurations for more
information on the choices available.
If you do choose to run your own Synchrony cluster, we recommend allowing 2GB memory for standalone
Synchrony. Here's an example of how memory could be allocated on a dedicated Synchrony node.

Physical RAM Breakdown for each Synchrony node

4GB 2GB for operating system and utilities

2GB for Synchrony JVM (-Xmx 1GB)

Database

The most important requirement for the cluster database is that it have sufficient connections available to
support the number of nodes.
For example, if:
each Confluence node has a maximum pool size of 20 connections
each Synchrony node has a maximum pool size of 15 connections (the default)
you plan to run 3 Confluence nodes and 3 Synchrony nodes
your database server must allow at least 105 connections to the Confluence database. In practice, you may
require more than the minimum for debugging or administrative purposes.
You should also ensure your intended database is listed in the current Supported Platforms. The load on an
average cluster solution is higher than on a standalone installation, so it is crucial to use the a supported
database.
You must also use a supported database driver. Collaborative editing will fail with an error if you're using an
unsupported or custom JDBC driver (or driverClassName in the case of a JNDI datasource connection).
See Database JDBC Drivers for the list of drivers we support.

Shared home directory and storage requirements

All Confluence cluster nodes must have access to a shared directory in the same path. NFS and SMB/CIFS
shares are supported as the locations of the shared directory. As this directory will contain large amount of
data (including attachments and backups) it should be generously sized, and you should have a plan for how
to increase the available disk space when required.

Load balancers

We suggest using the load balancer you are most familiar with. The load balancer needs to support ‘session
affinity’ and WebSockets. This is required for both Confluence and Synchrony. If you're deploying on AWS
you'll need to use an Application Load Balancer (ALB).
Here are some recommendations when configuring your load balancer:
Queue requests at the load balancer. By making sure the maximum number requests served to a
node does not exceed the total number of http threads that Tomcat can accept, you can avoid
overwhelming a node with more requests than it can handle. You can check the maxThreads in <ins
tall-directory>/conf/server.xml.
Don't replay failed idempotent requests on other nodes, as this can propagate problems across all
your nodes very quickly.
Using least connections as the load balancing method, rather than round robin, can better balance the
load when a node joins the cluster or rejoins after being removed.
Many load balancers require a URL to constantly check the health of their backends in order to automatically
remove them from the pool. It's important to use a stable and fast URL for this, but lightweight enough to not
consume unnecessary resources. The following URL returns Confluence's status and can be used for this
purpose.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 550

URL Expected content Expected HTTP Status

http://<confluenceurl>/status {"state":"RUNNING"} 200 OK

See all status codes and responses...

HTTP Response entity Description

Status
Code

200 Running normally

{"state":"RUNNING"}

500 An error state

{"state":"ERROR"}

503 Application is starting

{"state":"STARTING"}

503 Application is stopping

{"state":"STOPPING"}

200 Application is running for the first time

{"state":"FIRST_RUN"} and has not yet been configured

404 Application failed to start up in an

unexpected way (the web application
failed to deploy)

Here are some recommendations, when setting up monitoring, that can help a node survive small problems,
such as a long GC pause:
Wait for two consecutive failures before removing a node.
Allow existing connections to the node to finish, for say 30 seconds, before the node is removed from
the pool.

Network adapters

Use separate network adapters for communication between servers. Cluster nodes should have a separate
physical network (i.e. separate NICs) for inter-server communication. This is the best way to get the cluster to
run fast and reliably. Performance problems are likely to occur if you connect cluster nodes via a network that
has lots of other data streaming through it.

Additional requirements for collaborative editing

Collaborative editing in Confluence 6.0 and later is powered by Synchrony, which runs as a seperate
process.
If you have a Confluence Data Center license, two methods are available for running Synchrony:
managed by Confluence (recommended)
Confluence will automatically launch a Synchrony process on the same node, and manage it for you.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 551

No manual setup is required.

Standalone Synchrony cluster (managed by you)
You deploy and manage Synchrony standalone in its own cluster with as many nodes as you need.
Significant setup is required.
If you want simple setup and maintenance, we recommend allowing Confluence to manage Synchrony for
you. If you want full control, or if making sure the editor is highly available is essential, then managing
Synchrony in its own cluster may be the right solution for your organisation.

Additional requirements for high availability

Confluence Data Center removes the application server as a single point of failure. You can further minimize
single points of failure by ensuring your load balancer, database and shared file system are also highly
available.

User management

You can manage users in Confluence's internal directory, in an external LDAP directory, or in Atlassian
Crowd or JIRA.
You can also connect Confluence Data Center to a SAML 2.0 identity provider for authentication and single
sign-on (only available to Confluence Data Center).

Marketplace apps

The process for installing Marketplace apps (also known as add-ons or plugins) in Confluence Data Center is
the same as for a standalone instance of Confluence. You will not need to stop the cluster, or bring down
any nodes to install or update an app.
The Atlassian Marketplace indicates apps that are compatible with Confluence Data Center.
If you have developed your own plugins (apps) for Confluence you should refer to our developer
documentation on How do I ensure my app works properly in a cluster? to find out how you can confirm your
app is cluster compatible.

Ready to get started?

Learn more about Confluence Data Center and get started today.
For help with installation, take a look at Installing Confluence Data Center.

Administer your Data Center search index

Location of search indexes

A full copy of the Confluence indexes are stored on each Confluence node individually. A journal service keeps
each index in sync.
Confluence Data Center also stores a snapshot of the search index in the shared home directory, which can be
useful in a disaster recovery scenario. These snapshots are created as part of the Clean Journal Entries
scheduled job which, by default, runs once per day.

Index recovery

When you start a Confluence node it will check whether its index is current, and if not, it will request a recovery
snapshot from the shared home directory. If a snapshot is not available, it will generate a snapshot from a
running node (with a matching build number). Once the recovery snapshot is extracted into the index directory,
Confluence will continue the startup process.
If the snapshot can't be generated, or is not received in time, existing index files will be removed and Confluence
will perform a reindex on that node. If your index is very large or your file system slow, you may need to increase

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 552

the time Confluence waits for the snapshot to be generated using the confluence.cluster.index.recove
ry.generation.timeout system property.

Index recovery only happens on node startup, so if you suspect a problem with a particular cluster node's index,
restart that node to trigger index recovery.

Rebuilding the search index

If you suspect there's a problem with the index on all nodes, you'll need to rebuild the index on just one node
first, then copy it to the other nodes. We recommend backing up the local home directory and your shared home
directory before you begin.
In this example we'll rebuild the index on node 1. You may wish to use your load balancer to direct traffic away
from node 1 while the index is being rebuilt. This will prevent users from hitting a Confluence node with an
incomplete index.
1. Stop Confluence on node 1.
2. Set the confluence.cluster.index.recovery.num.attempts system property to 0.
This disables index recovery on node 1, so that when this node is restarted, it does not attempt to recover
the bad index from the remaining nodes.
3. Back up then delete the following index directories on node 1.
<local-home>/index
<local-home>/journal
4. Back up then delete the following index directory from your shared home directory.
<shared-home>/index-snapshots
5. Start Confluence on Node 1. Confluence will automatically begin building the index.
6. Once the reindex is complete stop Confluence on both node 1 and node 2.
7. Back up then delete the following index directories on node 2.
<local-home>/index
<local-home>/journal
8. Copy the <node1-local-home>/index directory to node 2 local home.
9. Start Confluence on node 2.
10. Repeat this process for any remaining nodes.
To avoid problems, both the node you are copying from and the node you are copying to should be
stopped while copying.
11. Finally, stop Confluence on Node 1.
12. Set the confluence.cluster.index.recovery.num.attempts system property back to 1.
This re-enables index recovery on node 1.
All nodes are now running the rebuilt index.
External Process Pool for Confluence Data Center
In Confluence Data Center we minimize the impact of particularly memory or CPU intensive actions by handling
them in an external process pool, which is a seperate pool of processes, managed by Confluence. These
processes (also known as sandboxes) can crash or be terminated, and will be restarted automatically by
Confluence, without affecting the Confluence application itself.
The external process pool currently handles the following actions:
Document conversion (thumbnail generation for file previews)
Exporting a space to PDF

The external process pool is only available for Confluence Data Center.
In Confluence Server, these actions are handled by Confluence, so the information on this page does
not apply.

Memory requirements

You will need to make sure that every Confluence node in the cluster has enough memory for the external
process pool. The pool contains two processes (sandboxes) by default, so we recommend allowing an additional

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 553

2 GB on top of what is already required for Confluence (1 GB per sandbox).

If you increase the size of the external process pool, make sure each node has enough free memory to cater for
the extra processes.

Configure the external process pool

In most cases the default values will be adequate, however system administrators can configure the external
process pool using system properties. For example you may want to increase the size of the pool (the number of
processes available), or increase the amount of memory a process can consume. Here are the main properties
you may need to change:
conversion.sandbox.pool.size
Use this property to increase the number of processes (sandboxes) in the pool. You'll need to allow
additional memory on each node for each additional process.
conversion.sandbox.memory.limit.megabytes
Use this property to limit the amount of memory each process (sandbox) in the pool can consume.
See Recognized System Properties for a full description of these properties, including additional properties that
can be used to fine-tune, or disable sandboxes for particular actions.

Monitor failed actions

When an external process (sandbox) is terminated, we'll write the following to the application log on that node:

2018-04-09 17:35:35 WARN [sandbox-terminator]

[impl.util.sandbox.DefaultSandbox] lambda$startTerminator$0 Request
has taken 33384ms exceeds limit 30000ms terminating sandbox

This will be followed by an Attempting to restart the sandbox message, the next time someone
performs an action that uses the external process pool.
Note that the process is not immediatley restarted after termination, as we don't re-attempt failed actions. We
wait for the next request to spin up a new sandbox process.
Document conversion for Confluence Data Center
When you insert a file into a page (for example a Word document, or Excel spreadsheet), Confluence will
generate thumbnail images of the file contents, so it can be viewed inline in the page, or in the preview. This can
be quite memory and CPU intensive, and has been known to cause out of memory errors when processing very
complex files.
In Confluence Data Center we minimize the impact by handling the conversion in an external process pool,
which is a seperate pool of processes, managed by Confluence. These processes (also known as sandboxes)
can crash or be terminated, and will be restarted automatically by Confluence, without affecting the Confluence
application itself.
If you insert a very complex file, and the process crashes or is terminated, thumbnail generation will fail. When
this happens, a placeholder thumbnail will be used on the page, and a download option will be provided in the
file preview. Confluence Data Center doesn't re-attempt to generate thumbnails for failed files. A good example
of a complex file, is a PowerPoint presentation that contains 50 embedded Excel charts. Most files will be
processed without any problems.

The external process pool is only available for Confluence Data Center.
In Confluence Server, thumbnail generation is handled by Confluence, so the information on this page
does not apply.

Configure the external process pool

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 554

In most cases the default values will be adequate, however system administrators can change the behaviour
using system properties. For example you may want to increase the size of the pool (the number of processes
available), or increase the time limit before a process is terminated. Here are the three main properties you may
need to change:
conversion.sandbox.pool.size
Use this property to increase the number of processes (sandboxes) in the pool. You'll need to allow
additional memory on each node for each additional process.
conversion.sandbox.memory.limit.megabytes
Use this property to limit the amount of memory each process (sandbox) in the pool can consume.
document.conversion.sandbox.request.time.limit.secs
Use this property to change the amount of time (in seconds) that the sandbox will wait for the document
conversion process to complete, before terminating the process, and marking thumbnail generation for
that file as failed.
See Recognized System Properties for a full description of these properties, plus a few additional properties that
can be used to fine-tune, or disable the sandboxes completley.

Re-attempt thumbnail generation for failed files

Confluence does not re-attempt to generate thumbnails for a failed attachment, and re-inserting the attached file
into the editor will not trigger the process.
If you do want to re-attempt thumbnail generation, for example after increasing the request time limit, you will
need to re-upload the file, and then re-insert it into the page.
PDF export in Confluence Data Center
When you export a space to PDF, Confluence exports the content of each page to HTML, converts that HTML to
PDF, and then finally merges all the pages together into a single PDF file. This can be quite memory and CPU
intensive, and has been known to cause out of memory errors when processing spaces with very long or
complex pages.
In Confluence Data Center we minimize the impact by handling the export in an external process pool, which is a
seperate pool of processes, managed by Confluence. These processes (also known as sandboxes) can crash or
be terminated, and will be restarted automatically by Confluence, without affecting the Confluence application
itself.

The external process pool is only available for Confluence Data Center.
In Confluence Server, PDF export is handled by Confluence, so the information on this page does not
apply.

Troubleshooting failed exports

Exporting an entire space to PDF can sometimes fail, especially if the space is very large, or has very long or
complex pages. If PDF export fails you'll see one of the following errors in your browser.

Page took too long to convert

This error occurs when the time it takes to convert the HTML of a page to PDF exceeds the set time limit. The
page title will be included in the error message.
You should take a look at the page, and see if it can be simplified. It might have a lot of complex macros, or a lot
of web images (images that are not attached to the page). If this error happens a lot, you can ask your admin to
increase the time limit.

Error converting page to HTML

This error occurs when Confluence runs out of memory, or hits another error while trying to convert the HTML of
a page to PDF. The page title will be included in the error message.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 555

As with the 'page took too long to convert' error above, you should take a look at the page, and see if it can be
simplified.
Confluence admins can get more information about the cause of these errors from the Confluence application
logs. If the failures are being caused by out of memory errors, your admin may be able to increase the amount of
memory available to each sandbox in the external process pool. See External Process Pool for Confluence Data
Center for more information.

Final PDF file wasn't merged in time

This error occurs at the last stage of the process, when the time it took to stitch together all the individual page
PDFs into one PDF file, exceeds the set time limit.
If you hit this error you could try exporting the space again, or perhaps export the space in two sections (using
the custom option on the PDF export screen). If this error happens a lot, you can ask your admin to increase the
time limit.

Error merging the final PDF file

This error occurs when Confluence runs out of memory, or hits another error, when attempting to stitch together
all the individual page PDFs into one file.
If you hit this error you could try exporting the space again, or perhaps export the space in two sections (using
the custom option on the PDF export screen).
Confluence admins can get more information about the cause of these errors from the Confluence application
logs. If the failures are being caused by out of memory errors, they may be able to increase the amount of
memory available to each sandbox in the external process pool. See External Process Pool for Confluence Data
Center for more information.

Too many concurrent exports

This error occurs when multiple people are exporting to PDF at the same time. Confluence limits the number of
PDF exports that can be processed concurrently.
If you hit this error, try exporting the space again later, after the other PDF exports have completed.
If this error happens a lot, your admin can increase the maximum number of concurrent PDF exports, or
increase the time Confluence should wait when the maximum number of concurrent PDF exports has been
reached using the following system properties:
confluence.pdfexport.permits.size
Use this property to set the maximum number of concurrent PDF exports that can be performed. This property
applies per node, not per sandbox process.
confluence.pdfexport.timeout.seconds
Use this property to set the amount of time a new PDF export request should wait before failing, if the maximum
number of concurrent PDF exports has already been reached.

Change the time limit

Processes are automatically terminated once a time limit is exceeded. You can increase the time limit for PDF
export using the following system property:
pdf.export.sandbox.request.time.limit.secs
Use this property to set the amount of time (in seconds) that a process should wait to complete, before being
terminated. This time limit applies both to the time to convert the content from HTML to PDF, and the time to
merge the final PDF file.
See Recognized System Properties for a full list of properties, including a few additional properties that can be
used to fine-tune, or disable the sandboxes for a particular action.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 556

Don't use the external process pool for PDF export

If you don't want to use the external process pool for PDF export, you can revert back to the Confluence Server
method of generating PDF exports using the following system property:
pdf.export.sandbox.disable
Set this property to true if you don't want to handle PDF exports in the external process pool.
Restricted Functions in Confluence Data Center
There are some features that are disabled or limited in Confluence Data Center. This is to ensure the integrity
and performance of your cluster.
The current restricted functions are:

Restricted function Data Center Status Explanation

Workbox plugins Available from 5.7 The workbox

provides notifications collected

from Confluence page watches,
shares, and mentions. This is
disabled in Confluence Data
Center 5.6 to ensure notifications
are correctly handled across the
cluster.
Disabled plugins included
Workbox common plugin,
Workbox Jira provider plugin,
Workbox confluence provider
plugin, Workbox host plugin. You
will not be able to enable these
plugins in the universal plugin
manager.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 557

Confluence Quick Reload Plugin Available from 5.6.3 The quick reload function notifies
users when a new comment has
been added to a page they are
currently viewing.

This is disabled in Confluence

Data Center 5.6 and 5.6.1 for
performance reasons. You will not
be able to enable the Confluence
Quick Reload Plugin in the
universal plugin manager.
See
CONFSERVER-34680 - Mak
e quick reload plugin available in
Confluence Data Center RESOLVED
for more info.

Application links authentication: RESTRICTED When creating Application links to

other applications (for example
Basic access (http) Jira) Basic HTTP and Trusted
Trusted Applications Applications authentication is not
supported for Confluence Data
Center.
All application links must use
OAuth authentication in a cluster.

Confluence Usage Stats plugin DISABLED The Confluence Usage Stats

plugin provides space activity
information for a space
(statistics). This is disabled by
default in Confluence Server and
should not be enabled in
Confluence Data Center.

Scheduled jobs history and status LIMITED On the Scheduled Jobs page in
the Confluence Data Center
administration console you will not
be able to access the last
execution time or history for each
job. The page will also only show
the configured status (scheduled
or disabled) of each job, and will
not indicate when a job is in
progress.

Remember me on by default LIMITED Remember me on the log in page

is enabled by default (and does
not appear) to allow users to
move seamlessly between nodes.
You can use the cluster.logi
n.rememberme.enabled syste
m property to override the default
and show the checkbox - users
will be prompted to log in to
another node if their current node
is unavailable.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 558

Confluence Data Center Performance

This document describes the performance tests we On this page
conducted on Confluence Data Center within
Atlassian and the results of those tests. You can Testing results summary
compare these data points to your own Testing methodology and
implementation to predict the type of results you specifications
might expect from implementing Confluence Data How we tested
Center in your own organization. What we tested
Hardware
We started our performance tests by taking a fixed Comparison to Confluence Server
load profile (read/write ratio), then tested different response times
cluster set ups against multiples of that load profile.

Testing results summary

Performance gains - Under a high load, clustered Confluence has improved performance overall.
Request responses don't diminish under increased load - Adding more nodes increases throughput,
handles higher load and decreases response times.

You might observe a different trend/behavior based on your configuration and usage. For details, please see the What we tested s
ection below.

Testing methodology and specifications

The following sections detail the testing environment and methodology we used in our performance tests.

How we tested

Our performance tests were all run on the same controlled isolated lab at Atlassian. For each test, the entire
environment was reset and rebuilt. The testing environment included the following components and
configuration:
Apache proxy_balancer
Postgres database and the required data
G1GC garbage collector
8GB Xmx settings per node
6 CPUs per node
Confluence Server on one machine or Confluence Data Center on two, or four machines as required
for the specific test.
To run the test, we used a number of machines in the lab to generate load using scripted browsers and
measuring the time taken to perform an action. An action here, means a complete user operation like
creating a page or adding comment. Each browser was scripted to perform an action from a predefined list of
actions and immediately move on the to next action (i.e. zero think time). Please note that this resulted in
each browser performing more tasks than would be possible by a real user and you should not interpret the
number of browsers to be equal to the number of real world users. Each test was run for 20 minutes, after
which statistics were collected.

What we tested

All tests used the same Postgres database containing the same number of spaces and pages.
The mix of actions we included in the tests represented a sample of the most common user actions*
representing six typical types of users (personas). The table below show the ratio of actions performed
by each of these personas. These user-based actions were repeated until the test was completed.

Persona Ratio of actions

PageReader 7

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 559

Searcher 1

Editor 1

Creator 1

Commenter 1

Liker 1

Tests were performed with differing load sizes, from 4 up to 96 browsers. For larger load sets, profiles were
scaled up, that is, doubling each amount for the 24 browser load, tripled for the 36 browser load.
* The tests did not include admin actions as these are assumed to be relatively infrequent.

Hardware

All performance tests were all run on the same controlled, isolated lab at Atlassian using the hardware listed
below.

Hardware Description How

many?

Rackform iServ CPU: 2 x Intel Xeon E5-2430L, 2.0GHz (6-Core, HT, 15MB Cache, 60W) 20
R304.v3 32nm
RAM: 48GB (6 x 8GB DDR3-1600 ECC Registered 2R DIMMs)
Operating at 1600 MT/s Max
NIC: Dual Intel 82574L Gigabit Ethernet Controllers - Integrated
Controller: 8 Ports 3Gb/s SAS, 2 Ports 6Gb/s SATA, and 4 Ports 3Gb/s
SATA via Intel C606 Chipset
PCIe 3.0 x16: Intel X540-T2 10GbE Dual-Port Server Adapter (X540)
10GBASE-T Cat 6A - RJ45
Fixed Drive: 240GB Intel 520 Series MLC (6Gb/s) 2.5" SATA SSD
Power Supply: 600W Power Supply with PFC - 80 PLUS Gold Certified

Arista 4PORT SFP+ REAR-TO-FRONT AIR 2XAC 1

DCS-7050T-36-R

HP ProCurve 1810-48G 48 Port 10/100/1000 ports Web Managed Switch 1

Switch

Hardware testing notes:

In order to quickly put more stress on the Confluence nodes with less load, cluster nodes were set to
use only 4 cores out of 6 from each CPU, thereby reducing its processing power.
For instances being tested, 6 GB of memory was allocated to the JVM consistently across all tests.
This may not be optimized for all cases but allowed for consistency and comparability between the
tests.
During the tests we did not observe high CPU or IO load on either the database or load balancer
servers.
During the tests we did not observe running out of HTTP connections in the load balancer or
connections to database.
The browser and servers are in the same location so there was very low latency between client and
server.

Comparison to Confluence Server response times

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 560

The following table shows the relative performance as the load increases for each Confluence instance
configuration: Confluence Server, two node Confluence Data Center, and four node Confluence Data Center.
The table shows the response time relative to the baseline response time which we determined to be
Confluence Server with sixteen browsers.

Browsers 16 24 36 48 60 72 84 96

Server 100.00% 125.28% 142.95% 222.76% 276.54% 334.79% 393.03% 451.28%

2 Node 93.79% 122.61% 123.50% 141.98% 168.47% 201.97% 235.47% 268.97%

4 Node 94.24% 122.22% 103.94% 123.47% 114.76% 134.61% 138.90% 160.95%

Ready to get started?

Contact us to speak with an Atlassian or get going with Data Center straight away.
For a detailed overview of Confluence's clustering solution see Confluence Data Center Technical Overview.
For help with installation, take a look at Installing Confluence Data Center.

Confluence Data Center disaster recovery

A disaster recovery strategy is a key part of any business continuity plan. It outlines the processes to follow in
the event of a disaster, to ensure that the business can recover and keep operating. For Confluence, this means
ensuring Confluence's availability in the event that your primary site becomes unavailable.
Confluence Data Center is the only Atlassian-supported high-availability solution for Confluence.

Not sure if you should upgrade from Confluence Server to Data Center? Learn more about the benefi
ts of Confluence Data Center.

This page demonstrates how you can use Confluence Data Center 5.9 or later in implementing and managing a
disaster recovery strategy for Confluence. It doesn't, however, cover the broader business practices, like setting
the key objectives (RTO, RPO & RCO1), and standard operating procedures.

What's the difference between high availability and disaster recovery?

The terms "high availability", "disaster recovery" and "failover" can often be confused. For the purposes
of this page, we've defined them as follows:
High availability – A strategy to provide a specific level of availability. In Confluence's case, acce
ss to the application and an acceptable response time. Automated correction and failover (within
the same location) are usually part of high-availability planning.
Disaster recovery – A strategy to resume operations in an alternate data center (usually in
another geographic location), if the main data center becomes unavailable (i.e. a disaster).
Failover (to another location) is a fundamental part of disaster recovery.
Failover – is when one machine takes over from another machine, when the aforementioned
machines fails. This could be within the same data center or from one data center to another.
Failover is usually part of both high availability and disaster recovery planning.

Overview

Before you start, you need Confluence Data Center 5.9 or later to implement the strategy described in this
guide.
This page describes what is generally referred to as a 'cold standby' strategy, which means the standby
Confluence instance isn't continuously running and that you need to take some administrative steps to start the
standby instance and ensure it's in a suitable state to service the business needs of your organization.

Maintaining a runbook
The detailed steps will vary from organization to organization and, as such, we recommend you keep a

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 561

full runbook of steps on file, away from the production system it references. Make your runbook detailed
enough such that anyone in the relevant team should be able to complete the steps and recover your
service, regardless of prior knowledge or experience. We expect any runbook to contain steps that cover
the following parts of the disaster recovery process:
1. Detection of the problem
2. Isolation of the current production environment and bringing it down gracefully
3. Synchronization of data between failed production and intended recovery point
4. Warm up instructions for the recovery instance
5. Documentation, communication, and escalation guidelines

The major components you need to consider in your disaster recovery plan are:

Confluence installation Your standby site should have exactly the same
version of Confluence installed as your production
site.

Database This is the primary source of truth for Confluence

and contains most of the Confluence data (except
for attachments, avatars, etc). You need to replicate
your database and continuously keep it up to date to
satisfy your RPO1

Attachments All attachments are stored in the Confluence Data

Center shared home directory, and you need to
ensure it's replicated to the standby instance.

Search Index The search index isn't a primary source of truth, and
can always be recreated from the database. For
large installations, though, this can be quite time
consuming and the functionality of Confluence will
be greatly reduced until the index is fully recovered.
Confluence Data Center stores search index
backups in the shared home directory, which are
covered by the shared home directory replication.

Plugins User installed plugins are stored in the database

and are covered by the database replication.

Other data A few other non-critical items are stored in the

Confluence Data Center shared home. Ensure
they're also replicated to your standby instance.

Set up a standby system

Step 1. Install Confluence Data Center 5.9 or higher

Install the same version of Confluence on your standby system. Configure the system to attach to the standby
database.

DO NOT start the standby Confluence system

Starting Confluence would write data to the database and shared home, which you do not want
to do.
You may want to test the installation, in which case you should temporarily connect it to a different
database and different shared home directory and start Confluence to make sure it works as expected.
Don't forget to update the database configuration to point to the standby database and the shared home
directory configuration to point to the standby shared home directory after your testing.

Step 2. Implement a data replication strategy

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 562

Replicating data to your standby location is crucial to a cold standby failover strategy. You don't want to fail over
to your standb y Confluence ins tance and find that it's out of date or that it takes many hours to re-index.

Database All of the following Confluence supported database

suppliers provide their own database replication
solutions:
Show me...
Oracle: http://www.oracle.com/technetwork/d
atabase/features/data-integration/index.html
PostgreSQL: https://wiki.postgresql.org/wiki/
Binary_Replication_Tutorial
MySQL: http://dev.mysql.com/doc/refman/5.7
/en/replication.html
Microsoft SQL Server: http://msdn.microsoft.
com/en-us/library/ms151198.aspx
You need to implement a database replication
strategy that meets your RTO, RPO and RCO1.

Files You also need to implement a file server replication

strategy for the Confluence shared home directory
that meets your RTO, RPO and RCO1.

Clustering considerations

For your clustered environment you need to be aware of the following, in addition to the information above:

Standby cluster There's no need for the configuration of the standby

cluster to reflect that of the live cluster. It may
contain more or fewer nodes, depending on your
requirements and budget. Fewer nodes may result
in lower throughput, but that may be acceptable
depending on your circumstances.

File locations Where we mention <confluencesharedhome>

as the location of files that need to be synchronized,
we're referring to the shared home for the cluster. <
confluencelocalhome> refers to the local home
of the node in the cluster.

Starting the standby cluster It's important to initially start only one node of the
cluster, allow it to recover the search index, and
check it's working correctly before starting additional
nodes.

Disaster recovery testing

You should exercise extreme care when testing any disaster recovery plan. Simple mistakes may cause your
live instance to be corrupted, for example, if testing updates are inserted into your production database. You
may detrimentally impact your ability to recover from a real disaster, while testing your disaster recovery plan.

The key is to keep the main data center as isolated as possible from the disaster recovery testing
.

This procedure will ensure that the standby environment will have all the right data, but as the testing
environment is completely separate from the standby environment, possible configuration problems on
the standby instance are not covered.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 563

Prerequisites

Before you perform any testing, you need to isolate your production data.

Database 1. Temporarily pause all replication to the standby

database
2. Replicate the data from the standby database to
another database that's isolated and with no
communication with the main database

Attachments, plugins and indexes You need to ensure that no plugin updates or index
backups occur during the test:
1. Disable index backups
2. Instruct sysadmins to not perform any updates in
Confluence
3. Temporarily pause all replication to the standby
shared home directory
4. Replicate the data from the standby shared
home directory to another directory that's
isolated and with no communication with the
main shared home directory

Installation folders 1. Clone your standby installation separate from

both the live and standby instances
2. Change the connection to the database in the <c
onfluencelocalhome>/confluence.cfg.x
ml file to avoid any conflict
3. Change the location of the shared home
directory in the <confluencelocalhome>/co
nfluence.cfg.xml file to avoid any conflict
4. If using TCP/IP for cluster setup, change the IP
addresses to that of your testing instances in <c
onfluencelocalhome>/confluence.cfg.x
ml

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 564

After this you can resume all replication to the standby instance, including the database.

Perform disaster recovery testing

Once you have isolated your production data, follow the steps below to test your disaster recovery plan:
1. Ensure that the new database is ready, with the latest snapshot and no replication
2. Ensure that the new shared home directory is ready, with the latest snapshot and no replication
3. Ensure you have a copy of Confluence on a clean server with the right database and shared home
directory settings in <confluencelocalhome>/confluence.cfg.xml
4. Ensure you have confluence.home mapped, as it was in the standby instance, in the test server
5. Disable email (See atlassian.mail.senddisabled in Configuring System Properties)
6. Start Confluence

Handling a failover

In the event your primary site is unavailable, you'll need to fail over to your standby system. The steps are as
follows:

1. Ensure your live system is shutdown and no longer updating the database
2. Ensure the contents of <confluencesharedhome> is synced to your standby instance
3. Perform whatever steps are required to activate your standby database
4. Start Confluence on one node in the standby instance
5. Wait for Confluence to start and check it is operating as expected
6. Start up other Confluence nodes
7. Update your DNS, HTTP Proxy, or other front end devices to route traffic to your standby server

Returning to the primary instance

In most cases, you'll want to return to using your primary instance after you've resolved the problems that
caused the disaster. This is easiest to achieve if you can schedule a reasonably-sized outage window.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 565

You need to:

Synchronize your primary database with the state of the secondary

Synchronize the primary shared home directory with the state of the secondary

Perform the cut over

1. Shutdown Confluence on the standby instance

2. Ensure the database is synchronized correctly and configured to as required
3. Use rsync or a similar uililty to synchronize the shared home directory to the primary server
4. Start Confluence
5. Check that Confluence is operating as expected
6. Update your DNS, HTTP Proxy, or other front end devices to route traffic to your primary server

Other resources

Atlassian Answers
Our community and staff are active on Atlassian Answers. Feel free to contribute your best practices, questions
and comments. Here are some of the answers relevant to this page:
Disaster Recovery Configuration for Jira and Confluence

Troubleshooting

If you encounter problems after failing over to your standby instance, check these FAQs for guidance:
What should I do if my database isn't synchronized correctly?
If your database doesn't have the data available that it should, then you'll need to restore the database from
a backup.
Once you've restored your database, the search index will no longer by in sync with the database. You can ei
ther do a full re-index, background or foreground, or recover from the latest index snapshot if you have one.
This includes the journal id file for each index snapshot. The index snapshot can be older than your database
backup; it'll synchronize itself as part of the recovery process.

What should I do if my search index is corrupt?

If the search index is corrupt, you can either do a full re-index, background or foreground, or recover from an
earlier index snapshot from the shared home directory if you have one.

What should I do if attachments are missing?

You may be able to recover them from backups if you have them, or recover from the primary site if you have
access to the hard drives. Tools such as rsync may be useful in these circumstances. Missing attachments
won't stop Confluence performing normally; the missing attachments won't be available, but users may be
able to upload them again.

What happens to my application links during failover?

Application links are stored in the database. If the database replica is up to date, then the application links
will be preserved.
You do, however, also need to consider how each end of the link knows the address of the other:
If you use host names to address the partners in the link and the backup Confluence server has the
same hostname, via updates to the DNS or similar, then the links should remain intact and working.
If the application links were built using IP addresses and these aren't the same, then the application
links will need to be re-established.
If you use IP addresses that are valid on the internal company network but your backup system is
remote and outside the original firewall, you'll need to re-establish your application links.

Definitions

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 566

RPO Recovery Point Objective How up-to-date you require your

Confluence instance to be after a
failure.

RTO Recovery Time Objective How quickly you require your

standby system to be available
after a failure.

RCO Recovery Cost Objective How much you are willing to

spend on your disaster recovery
solution.

Data Center Troubleshooting

This page covers troubleshooting for a Data Center installation of On this page:
Confluence.
Symptoms
If you're experiencing Cluster Panic messages in non-clustered installation Didn't find
of Confluence, visit the Knowledge Base article 'Database is being updated a solution?
by an instance which is not part of the current cluster' Error Message .
Related pages:
You must ensure the clocks on your cluster nodes don't diverge, as it can
result in a range of problems with your cluster. Troublesho
oting a
Data
Symptoms Center
cluster
Below is a list of potential problems with Confluence Data Center, and their outage
likely solutions.

Problem Likely solutions

Database is being updated by an instance 'Database is being updated by an instance

which is not part of the current cluster erro which is not part of the current cluster'
rs on a stand-alone Error Message

Database is being updated by an instance Add multicast route, Check firewall, Cluste
which is not part of the current cluster erro r Panic due to Multiple Deployments
rs on a cluster

Cannot assign requested address on startup, Prefer IPv4

featuring an IPv6 address

Error in log: The interface is not suitable for Change multicast interface, Add multicast
multicast communication route

Multicast being sent, but not received Check firewall, Check intermediate routers
, Increase multicast TTL

App is unlicensed on some nodes after updating the Disable and re-enable the app in the
license on one node. Universal Plugin Manager.

After an app update, strings appear in the UI instead of Restart the affected node.
buttons and icons on some nodes.

Hazelcast CANNOT start on this node. No See Hazelcast CANNOT start on this
matching network interface found. node. No matching network interface
found KB article

Any issue not covered here Contact support

Multicast

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 567

Which multicast address?

The multicast address and port used by Confluence can be found on the Cluster Configuration page, or in co
nfluence.cfg.xml in the Confluence home directory.

Multicast address generation.

Confluence uses a hashing algorithm to take the inputted name during setup and it is then turned into a
multicast address stored in the config file. Thus, once the initial setup is completed, Confluence will use the
address this is the reason why user can change the address if needed, without actually changing the name.
Consequently the additional nodes using the same multicast address specified in the config file are able to
join the cluster.
Each node has a multicast address configured in the confluence.cfg.xml file

name="confluence.cluster.address">xxx.xx.xxx.xxx</property>

A warning message is displayed when an user changes the address from the one that Confluence has
generated by the hashing of the name. There is no way of eliminating the message any other way other than
by returning the address to the one that matches the cluster name. Purpose of the warning message is to
remind the user that the address has been changed - as it is not the hashed version any longer -
consequently the node can not join the cluster just by using the name. It is also necessary to provide the
correct address as well.

Mapping interface to IP address.

To ensure that the interface name is mapped correctly, the following tool can be used. It shows the mapping
of the interface name to the IP address.

C:\>java -jar list-interfaces.jar

interfaces.size() = 4
networkInterface[0] = name:lo (MS TCP Loopback interface) index: 1
addresses:
/127.0.0.1;

networkInterface[1] = name:eth0 (VMware Virtual Ethernet Adapter for

VMnet8) index: 2 addresses:
/192.168.133.1;

networkInterface[2] = name:eth1 (VMware Virtual Ethernet Adapter for

VMnet1) index: 3 addresses:
/192.168.68.1;

networkInterface[3] = name:eth2 (Broadcom NetXtreme 57xx Gigabit

Controller - Packet Scheduler Miniport) index: 4 addresses:
/192.168.0.101;

Debugging tools

Listed below are some debugging tools that help determine what the status of the multicast traffic is:

Tool Information provided

netstat -gn Lists multicast groups. Does not work on Mac OS X.

netstat -rn Lists system routing table.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 568

tcpdump -i inte Captures network traffic on the given interface. Most useful on an interface that
rface only receives cluster traffic.

Add multicast route

Multicast networking requirements vary across operating systems. Some operating systems require little
configuration, while some require the multicast address to be explicitly added to a network interface before
Confluence can use it. If multicast traffic can't be sent or received correctly, adding a route for multicast traffic
on the correct interface will often fix the problem. The example below is for a Ubuntu Linux system:

route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0

To support multiple applications using multicast on different interfaces, you may need to specify a route
specific to the Confluence multicast address.

Check firewall

Ensure your firewall allows UDP traffic on the multicast address and port used by Confluence.

Prefer IPv4

There are known issues relating to IPv6. You should configure your JVM to try binding to an IPv4 address
first.

Change multicast interface

Confluence might have selected the incorrect interface for multicast traffic, which means it cannot connect to
other nodes in the cluster. To override the interface used for multicast traffic after initial setup, edit the confl
uence.cluster.interface property in <local-home>/confluence.cfg.xml and specify the
network interface. For example to tell Confluence to use eth1:

<property name="confluence.cluster.interface">eth1</property>

Overriding Hazelcast Configuration

If the solution to your problem involves changes to the Hazelcast configuration, these changes should not be
made to the Confluence configuration files. Instead, to ensure your configuration survives upgrades, make
your changes by creating a Hazelcast override file.

Increase multicast TTL

The multicast time-to-live (TTL) specifies how many hops a multicast packet should be allowed to travel
before it is discarded by a router. It should be set to the number of routers in between your clustered nodes:
0 if both are on the same machine, 1 if on two different machines linked by a switch or cable, 2 if on two
different machines with one intermediate router, and so on.
To increase the multicast TTL by edit the confluence.cluster.ttl property in the <local
home>/confluence.cfg.xml file on each node. For example to set the TTL to 3:

<property name="confluence.cluster.ttl">3</property>

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 569

Check intermediate routers

Advanced switches and routers have the ability to understand multicast traffic, and route it appropriately.
Unfortunately sometimes this functionality doesn't work correctly with the multicast management information
(IGMP) published by the operating system running Confluence.
If multicast traffic is problematic, try disabling advanced multicast features on switches and routers in
between the clustered nodes. These features can prevent multicast traffic being transmitted by certain
operating systems.

Didn't find a solution?

Check Related Articles from the Confluence Knowledge Base

Starting Confluence node fails with 'Port [5801] is already in use and auto-increment is disabled.
Hazelcast cannot start' error
"Exception bootstrapping cluster:Shared home directory is not configured correctly" Error during
Confluence Data Center startup
Recovering from a Data Center cluster split-brain
Cluster Panic due to Multicast Traffic Communication Problem
Hazelcast CANNOT start on this node. No matching network interface found.
Cannot find "external_id" column when trying to upgrade to a Confluence CDC license after upgrading
from a pre-5.5 Confluence Clustered installation
Multicast communication works only one-way
Configuration of Confluence Cluster Fails with 'Cannot assign requested address'
How to suppress cluster warning messages in the Confluence log files

Contact Atlassian support

We have dedicated staff on hand to support your installation of Confluence. Please follow the instructions for
raising a support request and mention that you're having trouble setting up your Confluence cluster.

Troubleshooting a Data Center cluster outage

Confluence Data Center cluster outages can be On this page:
difficult to troubleshoot as the environments are
complex and logging can be very verbose. Establish the originating node
Investigate common root causes
This page provides a starting point for investigating Garbage collection
outages in your cluster. Database connections
Network connectivity
Still having trouble?
Establish the originating node

The most common outage scenario is when

something, such as database connectivity issue,
network outage or a long garbage collection (GC)
process, causes a node to fail to communicate with
the cluster for 30 seconds or more and is removed
by Hazelcast. The affected node then continues to
write to the database, causing a cluster panic.
To establish the originating node:
1. Gather the atlassian-confluence.log files from each node as soon as possible after the outage.
Time is critical as the logs will roll over and you may lose the relevant time period.
2. Record identifying information about each node to help you interpret the log messages (IP address,
node ID and name of each node).
3. Make a chronological timeline of the events:
a. Record the time that users or monitoring systems started reporting problems.
b.

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation
3. 570

b. View the logs for each node side by side (Hint: we find opening three tabs in node number
order helps you always know which logs you are viewing).
c. Search the logs for 'removing member' and 'panic'. This will give you a good idea of which
nodes caused the issue and when.
d. Make a chronological timeline of events from errors to node removal to panics. You can
essentially disregard all logging that happens post-panic because once a node panics it needs
to be restarted to function effectively. There will be a lot of noise in the logs, but it won't be very
useful. The time period we're most interested in will be the minute or so leading up to the first
removal or panic event in the logs.
For example:

2:50:15 (approx) Node 3 stopped heartbeating to the cluster

for 30s
(we can estimate this from the time of node removal)
02:50:45 Node 3 was removed by Node 2
02:53:15 Node 4 panics
02:54:15 Node 1, Node 3 and Node 4 receive the panic event
and stop processing
Node 2 remains serving requests

e. When you've established when the first affected node was removed, or when the first cluster
panic occurred, look back in time in the logs on that node, to look for root causes.

Investigate common root causes

Once you know when the first affected node was removed you can start investigating root causes. From this
point on, you're only looking at events on the affected node around the time of removal (in our example
above, this is Node 3 at around 2:50). The subsequent removals and panics are usually flow-on effects of
the original node removal event, and aren't likely to provide useful root cause information.

Garbage collection

Check the GC logs for the node that was removed (Node 3 in our example). Were there any GC pauses
longer than the Hazelcast heartbeat interval (30 seconds by default)? Nodes can't heartbeat during Garbage
Collection, so they will be removed from the cluster by one of the other nodes.
If there was a cluster panic, but the node was not removed from the cluster first, check the GC logs for
pauses around the time of the panic - pauses that are relatively short (less than 30 seconds) can sometimes
still cause panics (due to a race condition) in Confluence 5.10.1 and earlier.

Database connections

Check any database monitoring tools you may have. How many connections to the database were there at
the time of the outage? Heartbeats can fail to send if a node can get a connection from its connection pool
but not from the database itself, which can lead to nodes being removed from the cluster.
You won't be able to diagnose this from the Confluence logs and will need to look at any external monitoring
tools you have for your database. If the outage happens again, check the current number of connections at
the db level during the outage.

Network connectivity

Check your network monitoring tools. If a node drops off the network for a short time and cannot
communicate with the cluster, it can be removed by the other nodes. Your load balancer logs may be useful
here.

Still having trouble?

Contact Support for help troubleshooting these outages. Provide them with as much of the information above

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 571

as possible, to help their investigation.

Confluence Server and Data Center feature comparison

If you manage your own Confluence site (it's not hosted by Atlassian), you'll have either a Confluence Server or
Confluence Data Center license.
Your Confluence license determines which features and infrastructure choices are available.

Feature comparison

Here's a summary of what you get with each license.

Core features Server license Data Center license

Create spaces
Create spaces to store your team
or project work.

Create pages
Create pages and blog posts, and
work on them with your team.

Collaborative editing
Up to 12 people can work on the
same page at the same time. Lear
n more

Browser and mobile

Use your browser, or use the iOS
or Android app. Learn more

User management

External user directories

Store users in Active Directory,
Crowd, Jira or another LDAP
directory. Learn more

SAML single sign-on

Use a SAML identity provider for
authentication and single-sign on.
Learn more

High availability and

performance at scale

Clustering
Run Confluence on multiple
nodes high availability. Learn
more

Infrastructure and Control

Read-only mode
Limit what users can do in your
site while you perform
maintenance. Learn more

Sandboxed processes
Run resource intensive tasks in
external sandboxes for greater
stability. Learn more

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 572

Deployment options

Your own hardware

Run Confluence on your own
physical servers, virtualized
servers, or in the data center of
your choice.

AWS Quick Start

Use our Cloud Formation
Templates to deploy Confluence
on AWS. Learn more

Azure template
Use our template to deploy
Confluence on Azure. Learn more

How do you decide what is included in each license?

We want all teams to get the most out of Confluence, so the core features are available for everyone - including
creating pages, working together, organising your work.
Some features are developed specifically for customers with a Data Center license. These may be specific to the
needs of larger enterprises, or may provide additional infrastructure or administrative options to help you when
Confluence is essential to getting work done in your organization.
Find out more about how we prioritize features for our Server and Data Center products in our blog.

Which license is right for your organization?

Considering switching? The following articles may help you decide if a Data Center license is right for your
organization.
Server vs. Data Center – What’s right for you? (blog)
Server to Data Center: The Tipping Point (whitepaper)

Getting Started with Confluence Data Center

This page provides an overview of the steps On this page:
involved in setting up Confluence Data Center.
1. Get to know Confluence Data
Center
2. Assess your requirements
3. Provision your infrastructure
4. Plan your deployment
5. Install and configure Confluence
Data Center
6. Maintain and scale Confluence
Data Center

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 573

1. Get to know Confluence Data Center

There are two products that allow you to run Confluence on your own servers: Confluence Server
and Confluence Data Center.
Data Center is built for enterprise organizations. It includes additional deployment options and
admin features that can help you keep Confluence highly available and performing at scale.
Learn more about Confluence Data Center features and deployment options:
Confluence Data Center
Confluence Server and Data Center feature comparison

2. Assess your requirements

To get the most out of Data Center, you need to set it up in a cluster, tailored to your
organization's needs.
We recommend assessing:
the number of users you have
the amount of data you have
your expected usage patterns
any specific requirements, such as high availability and disaster recovery
the resources your organization has allocated to maintain your Confluence site.
For more information about high availability, failover and disaster recovery for Confluence, head to
Confluence Data Center disaster recovery.
Our sizing and performance benchmarks can help you assess your expected load, and predict
performance:
Confluence Data Center load profiles
Confluence Data Center performance

3. Provision your infrastructure

Once you've identified your organization's needs, you can design and build your
environment. Read our Confluence Data Center Technical Overview for important hardware and
infrastructure considerations.
To help you get started, we've provided a Confluence Data Center sample deployment and
monitoring strategy.
We've also provided some general advice about node sizing and load balancers, to help you find
your feet if this is your first clustered environment:
Node sizing overview for Atlassian Data Center
Load balancer configuration options
Traffic distribution with Atlassian Data Center

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.15 Documentation 574

4. Plan your deployment

If you're new to Confluence, you can try out Confluence Data Center by downloading a free trial.
This can help you identify dependencies and plan your path to production.
Migrating from Confluence Server to Confluence Data Center? Read through these guides to
help minimize disruption during the switch:
Moving to Confluence Data Center
Atlassian Data Center migration plan
Atlassian Data Center migration checklist
It's also important to take an inventory of your third-party apps (also known as add-ons) to make
sure they're compatible with Data Center. Using a large number of add-ons can degrade
performance, so it's a good idea to remove any add-ons that aren't crucial to functionality.
Find out how to evaluate add-ons for Data Center migration.

5. Install and configure Confluence Data Center

Once your environment is ready, it's time to install and configure Confluence Data Center.
How you install depends on your environment:
Your own hardware – see Installing Confluence Data Center
Azure – see Getting started with Confluence Data Center on Azure
AWS (Amazon Web Services) – see Running Confluence Data Center in AWS

If you're migrating from Confluence Server to Confluence Data Center, follow the instructions
outlined in Moving to Confluence Data Center.
Before deploying Confluence Data Center to production, we recommend thoroughly testing the
installation. Head to our Data Center migration plan for detailed advice about testing and
launching to production.

6. Maintain and scale Confluence Data Center

Once you've got Confluence Data Center deployed in production, here are some resources for
monitoring the health of the cluster and scaling it up to accomodate more users:
Tools for monitoring your Data Center application
Ready to grow? Read up on scaling and adding nodes to your new Confluence Data
Center cluster:
Scaling with Atlassian Data Center
Adding or removing Confluence Data Center nodes

Created in 2019 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.