Confluence 7 7 0 CompleteGuide Compressed

Documentation for Confluence 7.
7
2
Contents
Confluence Server documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Get started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Tutorial: Navigate Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
The dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
The space directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
The space sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Complete your mission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Tutorial: Space ace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Create a project space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Create your personal space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Create the team's PR space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Delete and archive spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Create a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Create a Space From a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Space Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Navigate Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Space Permissions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Assign Space Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Make a Space Public . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Give Access to Unlicensed Users from Jira Service Desk . . . . . . . . . . . . . . . . . . . . . . . 48
Organize your Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Set up a Space Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Use Labels to Categorize Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Customize your Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Configure the Sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Edit a Space's Color Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Apply a Theme to a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Documentation theme migration FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Customize Space Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Archive a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Delete a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Export Content to Word, PDF, HTML and XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Customize Exports to PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Advanced PDF Export Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Create a PDF in Another Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Pages and blogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Create and Edit Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Blog Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
The Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Symbols, Emoticons and Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Collaborative editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Move and Reorder Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Copy a Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Delete or Restore a Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Add, Remove and Search for Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Display Pages with Label Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Drafts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Concurrent Editing and Merging Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Page Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Anchors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Add, Assign, and View Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Autocomplete for links, files, macros and mentions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Page Layouts, Columns and Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Create Beautiful and Dynamic Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
3
Page Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Create a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Create a Page from a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Blueprints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Decisions Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
File List Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Meeting Notes Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Product Requirements Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Shared Links Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Jira Report Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Retrospective Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
How-To Article Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Troubleshooting Article Blueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Create a Blueprint-Style Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Import Content Into Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Import a Word Document into Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Undefined Page Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
View Page Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Page History and Page Comparison Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Confluence Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Confluence Storage Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Confluence Wiki Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Upload Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Display Files and Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Manage Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Share and Comment on Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Edit Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Edit in Office using the Office Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Install Atlassian Companion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Confluence Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Using the Confluence Server mobile app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Using Confluence via your mobile browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Invite your team to use the app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Mobile Device Management (MDM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Anchor Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Attachments Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Blog Posts Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Change History Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Chart Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Wiki Markup Examples for Chart Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Cheese Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Children Display Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Code Block Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Column Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Content by Label Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Content by User Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Content Report Table Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Contributors Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Contributors Summary Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Create from Template Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Create Space Button Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Excerpt Include Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Excerpt Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Expand Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Favorite Pages Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Gallery Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Global Reports Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
HTML Include Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
HTML Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
IM Presence Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Include Page Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Info, Tip, Note, and Warning Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
4
Jira Chart Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Jira Issues Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Labels List Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Livesearch Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Loremipsum Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Multimedia Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Navigation Map Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Network Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Noformat Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Office Excel Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Office PowerPoint Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Office Word Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Page Index Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Page Properties Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Page Properties Report Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Page Tree Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Page Tree Search Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Panel Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
PDF Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Popular Labels Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Profile Picture Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Recently Updated Dashboard Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Recently Updated Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Recently Used Labels Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Related Labels Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Roadmap Planner Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
RSS Feed Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Search Results Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Section Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
Space Attachments Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Space Details Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Spaces List Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Status Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Table of Contents Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Table of Content Zone Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Task Report Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
User List Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
User Profile Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
View File Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Widget Connector Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Your profile and settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Your User Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Change Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Edit Your User Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Set Your Profile Picture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Choose Your Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Save for later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
View and Revoke OAuth Access Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Collaboration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Network Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Likes and Popular Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Mentions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
Share a Page or Blog Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Comment on pages and blog posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Watch Pages, Spaces and Blogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Manage Watchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Email Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
Subscribe to RSS Feeds within Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Subscribe to pre-specified RSS feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
The RSS Feed Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
Subscribe to a Network RSS Feed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Workbox Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Confluence Search Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
5
Confluence Search Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539

Search the People Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
Recently Viewed Pages and Blog Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Permissions and restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
Confluence Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
Check who can view a page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
Inspect permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Permissions best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Add-ons and integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
Use Jira applications and Confluence together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
Use Hipchat and Confluence together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Request Marketplace Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
Use a WebDAV Client to Work with Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
Mail Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
Add a Mail Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Delete and Restore Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
Import Mail from an mbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Activity Stream Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
Confluence Page Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
Confluence QuickNav Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
Confluence use-cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
Develop Technical Documentation in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
Use Confluence as a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
Use Confluence as your Intranet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
Confluence for Software Teams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
Confluence administrator's guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Getting Started as Confluence Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
Manage Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Add and Invite Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
Delete or Disable Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Restore Passwords To Recover Admin User Rights . . . . . . . . . . . . . . . . . . . . . . . . . . 627
Edit User Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
Change a Username . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
Managing Site-Wide Permissions and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Confluence Groups for Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
Adding or Removing Users in Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
Global Permissions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
Setting Up Public Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Revoking access for unlicensed users from Jira Service Desk . . . . . . . . . . . . . . . 643
Configuring User Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
Configuring the Internal Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Connecting to an LDAP Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Connecting to an Internal Directory with LDAP Authentication . . . . . . . . . . . . . . . 668
Connecting to Crowd or Jira for User Management . . . . . . . . . . . . . . . . . . . . . . . . 675
Managing Multiple Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
Managing Nested Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
Synchronizing Data from External Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
Diagrams of Possible Configurations for User Management . . . . . . . . . . . . . . . . . 697
User Management Limitations and Recommendations . . . . . . . . . . . . . . . . . . . . . 703
Requesting Support for External User Management . . . . . . . . . . . . . . . . . . . . . . . 707
Disabling the Built-In User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Single sign-on for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Managing System and Marketplace Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
Writing User Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
User Macro Template Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
Customizing your Confluence Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
Changing the Look and Feel of Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Customizing the Confluence Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
Changing the Site Logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
Customizing Color Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
Styling Confluence with CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
Working with Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
Customizing Site and Space Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
6
Customizing a Specific Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747

Customizing the Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
Modify Confluence Interface Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
Customizing Email Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
Changing the Default Behavior and Content in Confluence . . . . . . . . . . . . . . . . . . . . 751
Administering Site Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
Changing the Site Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
Choosing a Default Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
Configuring the Administrator Contact Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Configuring the Site Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
Customizing Default Space Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
Editing the Site Welcome Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
Integrating Confluence with Other Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Linking to Another Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
Configuring Workbox Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Integrating Jira and Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
Registering External Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
Configuring the Office Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
Managing Webhooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
Managing your Confluence License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
Managing Confluence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
Database JDBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
Database Setup for Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
Database Setup for PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
Database Setup for SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
Database Setup For MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
Embedded H2 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
Migrating to Another Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
Configuring Database Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
Configuring database query timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
Surviving Database Connection Closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
Configuring a datasource connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
Configuring Confluence Data Center to work with Amazon Aurora . . . . . . . . . . . . 822
Site Backup and Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
Production Backup Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
Configuring Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
Manually Backing Up the Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
Restoring a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
Restoring a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
Restoring a Test Instance from Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
Restoring Data from other Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
Retrieving File Attachments from a Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
Troubleshooting failed XML site backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846
Import a space from Confluence Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
Attachment Storage Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
Configuring Attachment Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
Hierarchical File System Attachment Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
Confluence Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
Finding Unused Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
Data Import and Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
Import a Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
Auditing in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
Audit Log Events in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
Audit Log Integrations in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
Configuring Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
Viewing System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888
Live Monitoring Using the JMX Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
Tracking Customizations Made to your Confluence Installation . . . . . . . . . . . . . . . 892
View Space Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
Viewing Site Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
Viewing System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898
Configuring the Server Base URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
Configuring the Confluence Search and Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
7
Configuring Indexing Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902

Configuring Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903
Content Index Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
Enabling OpenSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
Rebuilding the Ancestor Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
Setting Up Confluence to Index External Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
Setting Up an External Search Tool to Index Confluence . . . . . . . . . . . . . . . . . . . 912
Configuring Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
Configuring a Server for Outgoing Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
Setting Up a Mail Session for the Confluence Distribution . . . . . . . . . . . . . . . . . . . 916
Configuring the Recommended Updates Email Notification . . . . . . . . . . . . . . . . . . 917
The Mail Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
Configuring Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
Troubleshooting Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
Other Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
Configuring a WebDAV client for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
Configuring HTTP Timeout Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
Configuring Number Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
Configuring Shortcut Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
Configuring Time and Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935
Enabling the Remote API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
Enabling Threaded Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
Installing a Language Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
Installing Patched Class Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
Configuring System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
Recognized System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
Working with Confluence Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
Configuring Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
log4j Logging Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
Troubleshooting SQL Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968
Scheduled Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
Configuring the Whitelist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
Configuring the Time Interval at which Drafts are Saved . . . . . . . . . . . . . . . . . . . . . . . 976
Configuring Confluence Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
Confluence Security Overview and Advisories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
Proxy and HTTPS setup for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
Configuring Web Proxy Support for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
Connecting to LDAP or Jira applications or Other Services via SSL . . . . . . . . . . . 985
Using Apache with mod_proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
Running Confluence behind NGINX with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
Running Confluence Over SSL or HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
Using Apache to limit access to the Confluence administration interface . . . . . . 1003
Using Apache with mod_jk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
Using mod_rewrite to Modify Confluence URLs . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
Configuring Secure Administrator Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
Confluence Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
Using Fail2Ban to limit login attempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
Securing Confluence with Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
Best Practices for Configuring Confluence Security . . . . . . . . . . . . . . . . . . . . . . . . . 1014
Hiding the People Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
Configuring Captcha for Spam Prevention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
Hiding External Links From Search Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018
Configuring Captcha for Failed Logins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
Configuring XSRF Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
User Email Visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
Anonymous Access to Remote API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
Configuring RSS Feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
Preventing and Cleaning Up Spam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
Configuring a Confluence Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
Confluence Home and other important directories . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
Application Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
Managing Application Server Memory Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
Starting Confluence Automatically on System Startup . . . . . . . . . . . . . . . . . . . . . . . 1034
Start Confluence Automatically on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
8
Start Confluence Automatically on Windows as a Service . . . . . . . . . . . . . . . . . . 1039

Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042
Cache Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
Cache Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047
Memory Usage and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
Requesting Performance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
Access Log Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056
Compressing an HTTP Response within Confluence . . . . . . . . . . . . . . . . . . . . . . . . 1057
Garbage Collector Performance Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058
Troubleshooting Slow Performance Using Page Request Profiling . . . . . . . . . . . . . . 1059
Identifying Slow Performing Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
Confluence Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063
Data Collection Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065
Administering Collaborative Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066
Possible Confluence and Synchrony Configurations . . . . . . . . . . . . . . . . . . . . . . . . . 1071
Configuring Synchrony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
Set up a Synchrony cluster for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . 1080
Migrate from a standalone Synchrony cluster to managed Synchrony . . . . . . . . . . . 1087
Troubleshooting Collaborative Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
Using read-only mode for site maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092
Administering the Atlassian Companion App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
Notifications from Atlassian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
Confluence installation and upgrade guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100
Server Hardware Requirements Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
Running Confluence in a Virtualized Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
Confluence Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
Installing Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108
Installing a Confluence trial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1109
Installing Confluence on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111
Installing Confluence on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124
Unattended installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1138
Change listen port for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141
Start and Stop Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
Installing Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
Moving to Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
Upgrading Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
Adding and Removing Data Center Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155
Change Node Discovery from Multicast to TCP/IP or AWS . . . . . . . . . . . . . . . . . 1158
Running Confluence Data Center in AWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161
Getting started with Confluence Data Center on Azure . . . . . . . . . . . . . . . . . . . . 1171
Moving from Data Center to Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181
Installing Java for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1184
Setting the JAVA_HOME Variable in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 1185
Change the Java vendor or version Confluence uses . . . . . . . . . . . . . . . . . . . . . 1187
Creating a Dedicated User Account on the Operating System to Run Confluence . . 1191
Confluence Setup Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
Configuring Jira Integration in the Setup Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1199
Upgrading Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203
Upgrading Beyond Current Licensed Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
Confluence Post-Upgrade Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
Migration from Wiki Markup to XHTML-Based Storage Format . . . . . . . . . . . . . . . . . 1213
Migration of Templates from Wiki Markup to XHTML-Based Storage Format . . . . . . 1217
Upgrading Confluence Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
Create a staging environment for upgrading Confluence . . . . . . . . . . . . . . . . . . . . . 1225
Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229
End of Support Announcements for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
Bundled Tomcat and Java versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1254
Supported Platforms FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1262
Migrating Confluence Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263
From Confluence Evaluation through to Production Installation . . . . . . . . . . . . . . . . 1264
Migrate from Confluence Server to Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1267
Cloud Migration Assistant for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1272
Migrate from Confluence Cloud to Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1282
9
Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1287

Getting Started with Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289
Confluence Server and Data Center feature comparison . . . . . . . . . . . . . . . . . . . . . . . . 1291
Clustering with Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1293
External Process Pool for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
Document conversion for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
PDF export in Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305
Restricted Functions in Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
Set up a Confluence Data Center cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309
Confluence Data Center Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315
Confluence Data Center disaster recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1321
Data Center Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326
Troubleshooting a Data Center cluster outage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330
Use a CDN with Atlassian Data Center applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1332
Configure your CDN for Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336
Improving instance stability with rate limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1340
Adjusting your code for rate limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1347
Running Confluence Data Center on a single node . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1350
Confluence Server documentation
Confluence is where you create, organize, and discuss work with your team.
Get started
Kick start your Confluence journey with our navigation and space tutorials.
View guide
What’s new in 7.7
Time to upgrade? Get the low down on the latest and greatest changes in Confluence.
View release notes
Get started
Welcome to the Confluence getting started documentation. In this section, you'll find tutorials and other
information that'll be useful for evaluating Confluence, and getting to know it when you're starting out.
Teams in Space
For each tutorial in this section, we'll use a fictional organization known as 'Teams in Space'. Their mission is to:
"Perform flight research and technology integration to revolutionize aviation and pioneer
aerospace technology. Also, land the first humans on Mars by 2020."
You're an astronaut in the 'See Space EZ' team, which is working on the upcoming colonization of Mars.
Go ahead – dive into the tutorials, and let us show you around Confluence and some of its handy features.
Tutorial: Navigate Confluence

The dashboard
The space directory
The space sidebar
Keyboard shortcuts
Complete your mission
Tutorial: Space ace
Create a project space
Create your personal space
Create the team's PR space
Delete and archive spaces
Tutorial: Navigate Confluence
Confluence is pretty simple to use, once you get to know it. This tutorial aims to get you acquainted with the
Confluence user interface, and show you how and where to perform some common tasks.
Teams in Space
In this tutorial,you'll be working with some new Teams in Space recruits. Let's get to know them.
Alana Baczewski Emma Silvetti William Vladinov

Tech Lead Launch Specialist Aerospace Engineer
Now that you've met your team, let's take a look at your mission.
Mission brief
Your mission commander has thrown you a curveball: this week you'll be training new recruits at Teams in
Space HQ on your collaboration tool – Confluence. You just need to know the basics, so we'll go through the
main things you need to know to complete your mission.
Your mission is broken up into the following components:
Get to know the dashboard

Find your way in the space directory
Master the space sidebar
Impress everyone with keyboard shortcuts
Those new recruits will be here tomorrow; we better get started!

Let's go!
The dashboard
1. The dashboard
2. The space directory
3. The space sidebar
4. Keyboard shortcuts
5. Complete your
mission
The dashboard is the hub of your Confluence site, providing you with access to information and updates that
are important to you. It's also the first thing your new recruits will see, so you need to make a good
impression on this one.
You can get to the dashboard from anywhere in Confluence by choosing the site logo at the left of the
Confluence header.
The dashboard has a collapsible sidebar that helps you get around:
Discover
Watch the action unfold in real time with All updates or check out pages with lots of likes and activity
in the Popular feed.
My Work
Get lightning fast access to your recently created and edited pages in Recently worked on, get back
to that page you stumbled across yesterday in Recently viewed, and have mission critical pages on
speed dial under Saved for later.
My Spaces
This is where you can keep links to the spaces that you hop in and out of several times a day.
If you're a Confluence admin you can give the dashboard some personality by adding useful
announcements, links, or a photo from your last mission (or office party). The whole right hand column is
ready and waiting for you to customize.
1. Discover: see what's happening in your site.

2. Your work: get work done with recent and useful pages at your fingertips.
3. Customize: admins can add useful content to welcome people to the site.
Try clicking one of the spaces on the sidebar, then return to the dashboard by clicking the site logo. Even
when your shuttle is spinning out of control, the dashboard is there to orient you.
You'll discover more about the dashboard as you get to know Confluence, but, for now, let's move on to the
space directory.
Confluence 7.7 Documentation 2
Pro tips
You can choose to set any page as your personal home page
You can always get to the dashboard at https://yoursite.com/wiki/dashboard.
action
Your Confluence admin can customize the global dashboard that all users see
Next
Created in 2020 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
The space directory
1. The dashboard
5. Complete your
mission
The space directory won't let you look up ET in the intergalactic phone book, but it will let you see and filter
all the spaces in your Confluence site. Spaces are places to collect pages with a common theme – you can
create as many spaces as you like – and you can find them all in the space directory.
Here are some tasks to get you comfortable using the space directory:
1. Visit the space directory – To get to the space directory, choose Spaces > Space directory in the
Confluence header.
2. Choose the spaces you'll use the most – No doubt there'll be a space or two that you'll use on a
regular basis. Click the star to the right of a space to make it appear under My Spaces on the
dashboard.
3. Choose space categories – Once you're there, you'll see a list of all the spaces in your Confluence
site. Choose the 'My Spaces' category on the left to see only the spaces you marked with a star. Then
choose all spaces again.
4. Filter the list of spaces – Type part of a space name in the Filter field at the top right. That'll quickly
narrow down the list of spaces if there are a lot of them.
You can also categorize spaces with labels you create yourself. We're not going to cover that here,
but, if you'd like to know more, you can check out Use Labels to Categorize Spaces.
Understanding and using the space directory will make it much easier to find pages and blog posts that are
relevant to you.
You're ready to impress those new recruits with your knowledge of Confluence's space directory; now it's
time to sneak a peek at the space sidebar.
Next
The space sidebar
1. The dashboard
5. Complete your
mission
What's in the sidebar?

The sidebar is a feature of every Confluence space; it's where you'll find the page tree (a hierarchical list of
pages in the space), customizable space shortcuts, and a link to the space's blog.
The See Space EZ team will find their meeting notes, decisions, requirements, and other pages in the
sidebar. Basically any page you create in the space will appear in the sidebar by default.
When you use certain page templates, like meeting notes, Confluence will automatically add an
index page to your space shortcuts. The index page is just a place where you can view all pages of
the same type – meeting notes in this example – in one place.
The space's blog is great for announcements and what's new-type updates.
1. Space shortcuts: link to Confluence pages or other pages on the web

2. Page tree: hierarchical view of pages in this space.
The page tree in the sidebar shows the 200 pages closest to where you are. Hit Show all pages, if you want
to see all the pages in a space.
Configure the sidebar

You can expand or collapse the sidebar using the left square bracket ( [ ) on your keyboard, or by dragging it
with your mouse.
There are lots of things you can change in the sidebar, but we'll stick to the basics – just enough to train your
new recruits.
You need to be a space admin to complete this task. Take a look, but feel free to skip it if you're not
an admin of any space.
Try this out:
1. Choose Space tools > Configure sidebar from the bottom of the sidebar (or the cog menu if your
sidebar is collapsed)
2. Add a space shortcut by clicking +Add link
Shortcuts can be to Confluence pages or spaces, or to any other content on the web. Try linking to this
blog post, which mentions Teams in Space (we're always after a plug at Teams in Space HQ!)
You can also hide things – like the space's blog – in the sidebar, if they're of no use in the space.
The sidebar is pretty easy, right? You'll be schooling those recruits in no time. Next up: Impress them with
your knowledge of keyboard shortcuts.
Next
Keyboard shortcuts
1. The dashboard
5. Complete your
mission
Give a person some space food, and they'll eat for a day; teach a person to rehydrate their own space food,
and they're set for the whole mission. Or something like that. Keyboard shortcuts fall into this basket. We
could give you a list here, but then you'd need to keep referring to this page. The best way to go is to show
you how to find the list of keyboard shortcuts within Confluence.
Your recruits also need to work fast, so you'll need to pass this wisdom on to them.
Find the keyboard shortcuts

To open the list of keyboard shortcuts in Confluence, do any of the following:
Choose the help icon at top right of the screen, then choose Keyboard Shortcuts
When viewing a page, press Shift+?
While editing a page, choose the question mark icon in the editor toolbar
What you'll see is a dialog listing the available keyboard shortcuts, for your operating system, in Confluence.
The keyboard shortcuts are broken up into 3 categories:
General – Global, page and blog post shortcuts.

Editor – Text editing and formatting shortcuts.
Editor Autoformatting – Wiki markup and autoformatting shortcuts.
You can turn the 'General' keyboard shortcuts off when you visit the General tab in the keyboard
shortcuts dialog.
Take some time to open the dialog and take a look at the shortcuts, and maybe find some you'll use a lot.
Then, start practising!
Want a printable sheet of keyboard shortcuts? Keyboard shortcuts infographic - you're welcome.
Next, we'll wrap up this mission and give you some ideas about where to head from here.
Next
Complete your mission
1. The dashboard
5. Complete your
mission
Well done, astronaut, you've acquitted yourself admirably. I'm sure those new recruits will be mightily
impressed with your knowledge of Confluence.
In this tutorial, we've:
Explored the anatomy of the dashboard

Navigated using the space directory and favorited a space
Taken a look at and customized the space sidebar
Found a handy list of keyboard shortcuts to help you work faster
Just look at your team's adoring faces...
If you'd like to take things to the next level, check out our tutorial on becoming a space ace.
Tutorial: Space ace
This tutorial will take you on a journey through Confluence to create and customize spaces, and delete them
if you want to, so you can achieve the rank of 'Space Ace'!
You'll need to have the 'Create space' and 'Create personal space' permission to complete this tutorial. If
you've just set up Confluence, you won't have any trouble; if you're using an existing instance and you're not
an admin, speak to your Confluence admin to make sure you have the right permissions.
Teams in Space
In this tutorial you're a new recruit on the Teams in Space crew, but, even though you're new, you'll be given
a lot of responsibility. You need the power to go with it.
Mission brief
You're in charge of organizing information and resources for the planned mission to Mars. There's going to
be plenty of important information, and it must be readily available to the people who need it. Some
information, though, will be sensitive, and may be 'for your eyes only.' You'll use the power and flexibility of
Confluence spaces to organize information, and make sure it's visible to the right people.
Your mission is broken up into the following components:
Create a space to house all of the important information related to the mission
Create your own space to keep yourself organized
Create a public relations space, where you'll introduce your team the world
What's a space?
Well, being an astronaut, I hope you know what space is, but what's a Confluence space all about? It's really
just a place to put related things, like information pages and files. But spaces also give you a place to
collaborate with groups of people, whether that's your team, people working on a common project, or the
whole world.
Every space has its own permissions, allowing you to grant access and other privileges to the right people.
They also have a blog, so you can post important messages and updates to whoever can see the space.
You can have as many Confluence spaces as you like, and you can archive or delete spaces when you no
longer need them.
Enough about that; let's begin.

Start the mission!
Create a project space
1. Create a project space
2. Create your personal
space
3. Create the team's PR
space
4. Delete and archive
spaces
The Mars colonization crew needs a place to put all their mission-critical information and resources, and
you're charged with setting it up. This part is going to be easy, because the information needs to be viewable
by the entire Teams in Space organization. That means we can set up the project space without any special
permissions.
If you haven't done so already, open up Confluence and log in so we can get started.
Create the space

1. Choose Spaces > Create space from the Confluence header
2. Select the Blank space option and choose Next
3. Enter a Space name – for this space, we'll call it 'Mars Colony', as it's being used for the Mars
colonization project.
4. Change the Space key to 'MARS' – this step isn't absolutely necessary, but it helps people if they're
navigating to this space by name. The space key forms part of the URL, so making it a word or name
makes it much easier to associate with your project.
5. Click Create
You now have a space set up for the Mars colonization project. Because everyone at Teams in Space HQ
needs access to the information in this space, you don't need to do anything with the space's default
permissions. It's visible to everyone in your organization, but not to the general public.
Every space has a default home page, which you can customize to suit your needs. Add the following image
and text to your space's home page to get things started. Just click Edit (or press E on your keyboard) to
edit the home page, and copy and paste the text. For the image it's best to drag it to your desktop and save
it there, then drag it into your page. That'll make sure the image is attached directly to the page.
Hit Save when you're happy with the home page.
A human mission to Mars has

been the subject of science
fiction, engineering, and
scientific proposals throughout
the 20th century and into the
21st century. The plans
comprise proposals to land on
Mars, eventually settling on and
terraforming the planet, while
exploiting its moons, Phobos an
d Deimos.
Exploration of Mars has been a

goal of national space
programs for decades.
Preliminary work for missions
that would involve human explorers has been undertaken since the 1950s, with planned missions typically
being cited as taking place 10 to 30 years in the future when they are drafted. The list of manned Mars
mission plans in the 20th century shows the various mission proposals that have been put forth by multiple
organizations and space agencies in this field of space exploration.
Your 'Mars colony' space is ready for your team to add pages to. If you want to find it again, choose Spaces i
n the Confluence header, and select it from the list; to add a page to it, navigate to the space and hit Create i
n the header.
Now it's on to your personal space; a place where you can work in peace, and be sure that no one's looking
over your shoulder.
Next
space
space
spaces
As a newbie on the team, you might want to keep some work to yourself until you're ready to present it.
There's always the chance your mission commander will also send you some information that's 'for your
eyes only,' and you'll need to keep that in a safe place.
For this part of the mission, we'll be creating a special type of space: a personal space. We'll be using your
personal space like a sandbox, at least to start with – somewhere you can play around, draft pages, try out
features, and generally see what spaces are capable of.

1. Choose your profile picture at the right side of the Confluence header
2. Select Add Personal Space...
3. Hit Create
You've now got a space that you can call your own. But we still need to lock it down to make sure it's
only visible to you.
4. Choose Space tools > Permissions from the bottom of the siderbar
5. Hit Edit Permissions (enter your password if prompted)
You should see the confluence-users group listed under Groups. To the left of the list of
permissions is the View permission, which determines whether everyone in that group can see your
space.
6. Uncheck View and hit Save all at the bottom of the page
You're now the only one that can view this space. Feel free to try anything in this space, and store super
secret stuff here.
Next
Create the team's PR space
space
space
spaces
Now it's time to go public; the world needs to know about the mission and its brave participants.
In this step, we'll create a team space and open it up to everyone. That's right – you can open Confluence
spaces up to anonymous (not logged in) users.
In order to allow anonymous access to your Confluence site, a site admin needs to grant
anonymous users the 'Use Confluence' permission. Don't worry if you can't do that, or if it's not
done; it's just something to note if you're opening up your Confluence site for real.
Create a Team space

1. Choose Spaces > Create space from the header
2. Select Team Space and hit Next
3. Enter a Space name (let's call it 'Mars PR')
4. Change the Space key to 'MarsPR'
5. If there are other people using Confluence with you, feel free to add them as Team members (you
can remove them later), or just stick with yourself for now
6. Paste this in as the Description: Follow the progress of the brave Teams in Space astronauts as they
embark on their mission to colonize Mars.
Great! You now have a team space, again with its own home page. This home page is a little different to the
project space and your personal space – you'll see any team members you added, listed on the home page.
Each space you create also has its own blog, so your social media team will be able to create posts in this
space and speak directly to all those adoring fans. But none of those fans can see this space. Yet.
Allow anonymous access

It's time to let the world in by changing the permissions on this space.
1. Choose Space tools > Permissions from the bottom of the sidebar
2. Scroll down until you see Anonymous, then hit Edit Permissions
3. Tick the View permission for anonymous users and hit Save all
That's it. You can now share the space's URL, which will be http(s)://<your_confluence_site>/display
/MarsPR. Visitors to that space don't need to log in, or have a license for Confluence.
Next
Delete and archive spaces
space
space
spaces
We hope you've had a successful mission, and learned a bit about the power and versatility of Confluence
spaces. Flash forward 18 months, and just look how well the colony is coming along!
If you need to clean up old spaces (or destroy the evidence of a failed mission!), you can either archive or delete
a space. Archiving just means it won't show up in the regular search, whereas deleting is obviously a lot more
permanent.
To archive a space:
1. Choose Space tools > Overview from the bottom of the sidebar
2. Click Edit Space Details
3. Change the Status from 'Current' to 'Archived' and hit Save
To delete a space:
1. Choose Space tools > Overview from the bottom of the sidebar
2. Select the Delete Space tab
What next?
If you'd like to know more about spaces and the permissions that govern them, check out Spaces and Permissio
ns and restrictions in the Confluence documentation.
Teams in Space HQ, signing off.

Spaces
What is a space? On this page:
Spaces are Confluence's way of organizing content
into meaningful categories. Think of it like having What is a space?
different folders into which you can put your work. How do I use a space?
Related pages:
Spaces come in two main varieties:
Create a Space
Site spaces – These spaces are found in the Space Permissions Overview
Space Directory and are the areas where Navigate Spaces
you create content and collaborate with Organize your Space
others. They are sometimes called global Customize your Space
spaces. Archive a Space
Personal spaces – Every Confluence user Export Content to Word, PDF, HTML and
can set up a personal space which they can XML
keep private or make public so others can Delete a Space
view and edit. Personal spaces are listed in
the People Directory and found under your
personal profile.
How do I use a space?

Create as many spaces as you need to get things done:
Team spaces – Give each team (QA, HR, Engineering, Support, ...) their own space so they can
focus and make their information easier for everyone to find.
Project spaces – Put all the information related to your project in one place. This allows everyone to
work together in Confluence instead of emailing back and forth.
Personal space – Store everything you're working on individually, keep your to-do lists, and polish
any content before you move it into another shared space.
Stay up to date with spaces
Watch a space to stay up-to-date with any changes.

Add important spaces to your dashboard so that they're easy to find again.
Administer spaces
If you have admin permissions for a space you can:
Change the colors, logo, sidebar and homepage of that space.

Control who can view and edit your space.
Make your space public to share it with people who don't have access to Confluence.
Space Permissions
Some things we should make clear about space admin permissions:
The person who creates a space automatically has admin permissions for that space.
Space admins can grant admin permissions to others.
Space admins don't have to be Confluence admins and can have special permissions for a single
space. For example, you are the admin for your personal space, no matter what kind of access you
have anywhere else.
Want more ideas for using spaces? Check out our kickass guides on how to:
Use Confluence as a Knowledge Base

Develop Technical Documentation in Confluence
Use Confluence as your Intranet
Use Confluence for Software Teams
Create a Space
There's no limit to the number of Spaces you can create on Confluence.
You can choose to set up a space for each team, project, or a mix of both On this page:
depending on your needs.
Each space in Confluence functions autonomously, which means that each Create a personal
space: space
Create a site space
Has its own homepage, blog, pages, comments, files, and RSS Space permissions
feeds. Linking related
Can be customized with different color schemes, logo and sidebar. spaces
Has its own set of permissions, as set by the space admin. Tips
For example, an IT team can create one overarching space with all their roa Related pages:
dmaps, details of sub-teams, and a list of all the people and roles within that
team. They could then create a new space for each sub-team, such as Spaces
Quality Assurance, Developers, and Documentation, with guidelines, long Space Keys
term plans, and knowledge articles within them. Each project that these Create a Space
teams work on could also have its own space, which could be linked to the From a Template
team spaces using labels.
Create a personal space

Your personal space is always owned by you, and you can use it to store
your individual work, keep track of tasks, blog about what you've been
working on, or just use it to polish your pages before you move them into a
site space.
1. Choose your profile picture at top right of the screen, then choose Add Personal Space..
2. Choose Create.
You can change the permissions for your space at any time to determine who can and can't access the
content. So if you want it to be a private sanctuary, that's no problem.
To create a personal space you need the 'Personal Space' global permission.
Create a site space

You can create a site space for any team or project that would benefit from having a place where people can
work together and store related files. You can create these as blank spaces, or use templates, called space
blueprints , to help you create Team spaces, Knowledge Bases spaces, or Documentation spaces quickly
and easily.
1. Hit Spaces > Create space in the header.

2. Pick a type of space.
3. Enter the required details and create your space.
Choose your space key carefully as you can't change this later.
Each space you create will automatically have a home page that you can customize to display relevant
information for people viewing the space. If you use a space blueprint when creating a space, it will
customize your home page for you.
To create a site space you need the 'Create Space' global permission.
Space permissions
Each space is created with a set of default permissions. The user who created a site space is automatically
granted 'space admin' permissions for that space, which means that they can then grant permissions to
other users and groups. See Space Permissions Overview for more information.
System Administrators can edit the permissions of spaces in their Confluence site at any time.
Linking related spaces

You can link related spaces together using labels. This will create categories in the space directory for each
label, grouping all spaces with that label together.
You can also add a space description to make it easier for visitors to find the right space within each
category.
To help navigate between related spaces, you can use the Spaces List Macro on a page and filter by
category. This will let you insert a list of all the other spaces in a certain category into your space. You
can use this, for example, to keep a list in your team space of all the project spaces your team is
working on.
If you want to link to only certain pages of related content, rather than whole spaces, you can use the
Content Report Table Macro. You can use this, for example, in a space that functions as a workplace
directory, to create a list of all the team pages with everyone's roles and contact details across your
organization.
Tips
If your needs change, or your spaces grow too big, it's easy to copy or move content from one space
to another.
If the content or purpose of your space changes, you can update the space name, logo, colors and de
scription to reflect those changes.
If you no longer need a space, such as when a project has been completed, you can archive it, which
makes it less visible but retains the content on your site so that you can still refer back to it later.
Create a Space From a Template
Confluence comes with a number of templates, known as space blueprints,
Related pages:
which have a customized homepage and sidebar, and may contain page
blueprints or sample content to help you get started. Create a Space
This page is about space blueprints. You can also use Blueprints to
create individual pages.
Your Confluence administrator can customize or disable particular

blueprint templates, so they may be different to the examples shown here.
Types of space blueprints
Team space
A great building block if you are using Confluence as an intranet or to manage teams. Team spaces highlight
the members of the team, and grants permissions to those users accordingly.
Knowledge base space
This space blueprint uses search and page labels to make content easier to find, right from the space
homepage. It also contains two page blueprints for creating how-to and troubleshooting articles. The
templates used in these page blueprints are completely customizable. The Knowledge Base space blueprint
also Use Jira applications and Confluence together.
Documentation space
This space blueprint displays the full page tree in the sidebar and hides other sidebar features including
blogs and shared links. The homepage uses search and page labels to make content easy to find. Add the
'featured' label to any page you want to highlight on the homepage. This space does not include any page
blueprints but you can create and promote templates for your documentation authors to use.
Software project space
This space is designed to help you organize your software project. The purpose-built space home page lets
you view and edit your roadmap, see team members, and Use Jira applications and Confluence
together#JIRA Software. Create pages in this space for requirements, meeting notes, decisions, retros, and
more.
The software project space blueprint will only appear if you have linked Confluence to your Jira Software
instance.
Check out our guides for some more tips on how to:

Confluence for Software Teams
Space Keys
Each Confluence space has a space key, which is a short, unique identifier
that forms part of the URL for that space. Related pages:
Create a Space
Create a Space
From a Template
When you create a site space, Confluence will suggest a space key or you can enter your own key to make
it more memorable.
For example, you might give your marketing team's space a key of MARKETING. You can then navigate
directly to the space using a URL like this - http://<yoursite>/display/marketing
Personal spaces always use your username as the space key.
Choosing a space key

Each space key:
Must be unique.
Can contain any alphanumeric character (a-z, 0-9).
Can be up to 255 characters long.
You can't change the space key after you create your space, so choose your space key carefully!
Navigate Spaces
How is content arranged in spaces?
On this page:
Think of a space as the container that holds all the important stuff a team,
group, or project needs to work. These are autonomous – that means that How is content
each space has its own pages, blogs, files, comments and RSS feeds. arranged in
spaces?
Each space is automatically created with a homepage - the first page you'll View all spaces in
see when you navigate to the space. You can edit your homepage and your Confluence
sidebar to help people navigate their way around your space.
Related pages:
Spaces can't be nested – you can't have a space within a space – but you
can Use Labels to Categorize Spaces. Spaces with the same label will Organize your
appear together in the the space directory and in the recent activity area of Space
the dashboard. Watch Pages,
Spaces and Blogs
Pages and blogs
Search
Inside the space, you can nest your pages, and you can create as many levels of hierarchy as you need.
Each space also has its own blog, which lets you share news and make announcements. Blog posts are a
great way to keep people involved in what's going on in your team or project.
You can set different levels of access for each space, and the pages and blogs within it, using Space
Permissions Overview.
View all spaces in Confluence

There are two main ways to view spaces in Confluence:
The space directory – choose Spaces > Space directory in the Confluence header for a list of all
the site and personal spaces you have permission to see. Filter the list of spaces by selecting from
the categories on the left of the space directory.
The dashboard – you can make your most useful spaces appear under My spaces on the
dashboard. Choose the star icon in the space sidebar or space directory to add a space to My spaces.
The spaces menu in the header also displays a list of your recently viewed spaces, allowing you to quickly
navigate to the things you view most often.
The Spaces List Macro allows you to display a list of spaces on a Confluence page, and lets you filter them
by category.
Space Permissions Overview
Every Confluence space has its own set of permissions which determine
Related pages:
what people can do in the space.
Confluence Groups
Space permissions are set by the space administrator. The user who Assign Space
created the space is automatically a space administrator, and other users Permissions
can also be granted Space Admin permission. Page Restrictions
Global Permissions
Overview
This page is about Space Permissions. Confluence also lets you set Page Restrictions.
Edit space permissions

To change permissions for a space, choose Space tools > Permissions from the bottom of the sidebar,
then choose Edit Permissions to change permission settings.
See Assign Space Permissions for more details.
Permissions Summary
The following permissions can be assigned in a space:
Category Permission
All View gives you permission to access the content in this space, and see it in the space
directory and other places like the dashboard.
Delete own gives you permission to delete any pages, blogs, attachments and comments
you've created in this space (regardless of whether other users have subsequently edited the
content).
Pages Add page gives you permission to create new pages and edit existing pages in this space
(assuming the page is not restricted for editing).
Delete page gives you permission to delete any page in the space.
Blog Add blog gives you permission to create new blog posts and edit existing blog posts in this
space (assuming the blog post is not restricted for editing).
Delete page gives you permission to delete any blog post in the space. Delete permission is
also required to move a page or blog to a different space.
Attachmen Add attachment gives you permission to upload (attach) files to pages and blog posts in this
ts space.
Delete attachment gives you permission to remove attached files from pages or blog posts
in the space.
People with only Add page or blog permissions can still insert existing attached files in the
editor, and remove files from the editor, so they're not displayed on the page or blog post.
They can't however upload a new file, a new version of the file, or delete the attached file
itself.
Comments Add comments gives you permission to add comments to a page, blog post or attached
file.
Delete comments gives you permission to delete any comment on a page, blog post or
attached file.
Restrictions Add restrictions gives you permission to apply page-level restrictions to a page or blog
post. You can restrict a page for viewing, or just for editing.
Delete restrictions gives you permission to remove restrictions from any page or blog post.
Mail Delete mail gives you permission to delete mail items that have been archived in this
space. This is not a commonly used feature.
Space Export space gives you permission to export all the contents of the space to PDF, HTML or
XML. This is different to single page exports - anyone who can view a page can also export it.
Admin gives you permission to access all space administration tools, including things like
permissions, templates, look and feel, and the ability to delete the whole space.
Here's how it looks on the Permissions screen:
How space permissions work

Space permissions are additive. If a user is granted permissions as an individual or as a member of one or
more groups, Confluence will combine these permissions together. This is sometimes known as their
effective permissions.
Sasha is a member of the confluence-users group and the developers group. The confluence-
users group has 'export' permission, but does not have 'restrict' permission. The developers group
has 'restrict' permission but does not have 'export' permission.
By being a member of these two groups, Sasha can restrict and export content. The permissions do not
conflict, they combine to determine what Sasha is allowed to do in this space.
If you have Confluence Data Center, Inspect permissions provides space admins and Confluence
administrators a great way to view someone's effective permissions.
Who is the space admin?

The user who created the space is automatically a space administrator, and other users can also be granted
Space Admin permission.
To find out who is an administrators in your space, either:
Go to Space Tools > Overview in the space.

Go to Spaces > Space Directory on the header, then choose theSpace Details icon beside the
space.
If you accidentally deny all admin access to a space, so that nobody has access to administer the space any
more, you can ask someone with Confluence Administrator global permission to recover Space Permissions.
Space admin superpowers

Space administrators can do a lot of things in the space such as:
grant permissions to users and groups (and themselves)

create templates
change the look and feel
delete the space
manually remove page restrictions (including on pages they can't see)
manage watchers, to change who is watching a page
inspect permissions to see what users can do in the space (Data Center only)
Confluence administrators aren't necessarily space administrators. If they don't have the Space Admin
permission (as an individual or member of a group), they can recover permissions to the space, which will
grant them space admin permission.
Assign Space Permissions
If you are the administrator of a space, you control the permissions for it.
You can choose to assign/revoke permissions on either an individual user On this page:
basis, or using Confluence Groups.
Grant space
Want to know the best way to set permissions for your team's permission
needs? Check out our Permissions best practices guide. Set default space
permission for all
new spaces
To view the permissions for a space:
Revoke space
permissions
1. Go to the space and choose Space tools > Permissions from the
Inspect permissions
bottom of the sidebar
Manage and
2. Choose Edit Permissions. recover space
admin permissions
The Edit Space Permissions page is divided into the following sections:
Related pages:
Space Permissions
Overview
Global Permissions
Overview
Make a Space
Public
Give Access to
Unlicensed Users
from Jira Service
Desk
Licensed Users - this is where you grant permissions to groups and individual users.
Anonymous Access - this is where you grant permissions to users who are not logged in (essentially
making the space public). Note: allowing anonymous access in a space will allow all logged in users
to see that space, even if your site is not Public.
Grant space permission

To add a new user or group to the permissions list:
1. Search for either a group or user in their respective sections and choose Add. The group or user will
appear in the list.
2. Select the specific permissions you'd like to apply then choose Save all.
You can bulk assign or revoke permissions by selecting Select All or Deselect All.
Permissions are managed on a space by space basis. Your Confluence Administrator is able to set default
space permissions, which will apply to any new spaces.
Set default space permission for all new spaces

If you regularly need to grant permissions to the same groups each time a new space is created, you should
consider updating the default space permissions.
To set the default space permissions:
1. Go to > General Configuration > Space Permissions.

2. Choose Edit Permissions.
Default permissions are configurable for groups only, not for individual or anonymous users.
Revoke space permissions

To remove a user or group from the space permissions list, deselect all the checkboxes for that user or
group and save the changes. The user or group won't appear in the list once you save.
Inspect permissions
If you need to troubleshoot why someone can or can't do something in your space, and you have a Data
Center license, you can inspect permissions. See Inspect permissions for more information.
Manage and recover space admin permissions

If you're a Confluence Administrator you can recover permissions to a space. This is useful when the only
person with Space Admin permissions to a space leaves your organisation, for example.
To recover Space Admin permissions:

2. Locate the space in the list of individual spaces and choose Recover Permissions.
You can then choose Manage Permissions, and add any other appropriate permissions to the space.
Requests to recover permissions are recorded in the Confluence audit log.
People with System Administrator permissions are able to manage permissions for all spaces, they do not
need to first recover permissions.
Make a Space Public
If your site is public, and you want to share your space with people who are
Related pages:
not logged in to Confluence (anonymous users), you can make your space
public. Give Access to
Unlicensed Users
Making a space public does not let you choose who you want to share it from Jira Service
with – a public space can be viewed by anyone inside or outside of your Desk
organization.
In order to make a space public, your administrator must first turn on the global permission for
anonymous access.
This permission doesn't automatically grant anonymous users permission to see any of the spaces
on your site, that is done on a space by space basis.
To make your space public:
1. Go to the space and choose Space tools > Permissions from the bottom of the sidebar.
3. Scroll down to the Anonymous Access section and select the specific permissions you'd like
anonymous users to have.
4. Save All to apply the changes.
You can't grant space administration or page restriction rights to anonymous users. You can grant Delete
Own, but it will have no effect, as we have no way of knowing who an anonymous user is.
What happens when the site is not public?
If your Confluence administrator turns off anonymous access to your site, users who are not logged in will no
longer be able to see any spaces. However, all logged in users (regardless of their group membership) will
be able to see all spaces that have granted space permissions to anonymous users.
Auditing considerations
There are some additional things to be aware of if you grant the Add page 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.
Give Access to 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 Related pages:
who do not have a Confluence license) to view specific spaces. This can
only be turned on via JIRA Service Desk. Make a Space
Public
When a space is accessible to all active users, you'll see the following
message in the space permission screen.
This permission overrides all existing space permissions, so any logged in Confluence user will also be
able to see the space (regardless of their group membership).
You can edit this permission at any time to revoke access to a space, but it can only be re-enabled from Jira
Service Desk.
Active users who don't hold a Confluence license have very limited access to Confluence. They can view
pages, but can't like, comment, edit, view the dashboard, use the space directory, see user profiles or
search your full site.
See Use Jira applications and Confluence together for more information about Jira Service Desk integration.
Organize your Space
Here's a few tips that'll help you organize your
space so that everyone can find what they're On this page:
looking for and stay on top of what's important to
them.
How do I organize content within my
space?
Pages and blogs
Using labels
How do I keep my space tidy?
Create a set of guidelines
Use page blueprints
Create from template macro
Create your own page templates
How do I help my team stay on top of
what's important?
My Spaces
Save for later
Watch a page, blog or space
@mentions
How do I organize content within my space?
Pages and blogs
Everything you create in Confluence, from meeting notes to retrospectives and everything in between, takes
the form of either pages or blogs.
Your homepage will be the first thing that visitors to your site see, so to help them find relevant
content, start by curating your homepage with useful macros and including information about what is
in your space. See Set up a Space Home Page for more information.
If you're creating content that is specific mainly to the current time-frame, and isn't going to change
over time, create it as a blog post. Your blog displays as an infinite scroll, so it surfaces the latest
news and visitors just need to scroll down if they're interested in older content.
If you're creating content that you want to last, and possibly evolve over time, then create it as a page.
Pages nest, so every page can have its own child pages, which lets you organize your content into
categories and subcategories.
You can Configure the Sidebar to make it easier to navigate through your space.
The space shortcuts section of the sidebar lets you link to important content. You can use this to highlight
pertinent pages within your space, related content from other spaces, or to external content that is relevant
to your space.
The navigation display lists the pages in your space in either a page tree or child pages format. If you only
want some content to be visible in the sidebar, you can hide the navigation display and put the pages you
want to remain visible under Space shortcuts instead.
The page tree in the sidebar shows the 200 pages closest to where you are. Hit Show all pages, if you want
to see all the pages in a space.
Using labels
Labels are keywords or tags that you can add to pages, blog posts, and attachments.
Define your own labels and use them to categorize, identify, or bookmark content in Confluence. For
example, if you assign the label 'accounting' to all accounts -related pages on your site, you'll then be
able to:
Browse all pages with that label in a single space or across the site.
Display a list of pages with that label.
Search based on that label.
Use theContent by Label Macro to create a table of contents for your space that is organized by label
categories.
Labels aren't exclusive, so you can have as many labels as you want on a page. The page will then
appear under each of those categories. See Use Labels to Categorize Spaces for more information.
How do I keep my space tidy?

If you have lots of people creating in the same space, things can get messy fast. You can prevent this by
taking a few easy steps.
Create a set of guidelines
Let your collaborators know about what parent pages to create their child pages under, so no content
gets lost or misplaced.
Decide on standard labels to add to pages, blogs, and attachments so all content gets neatly
categorized.
Add a link to this in the Space Shortcuts section of the sidebar so that it's easy to find.
Use page blueprints
Blueprints are templates that come with formatting, macros and sample content. You can customize these
Blueprints for each space. Everything created from a Blueprint will have it's own index in the sidebar, so for
example if you use the Meeting Notes Blueprint, you can select 'Meeting Notes' in the sidebar to see a list of
all the meeting notes in your space.
Create from template macro
Make things simpler for other contributors by using the Create from Template Macro. The Create from
Template Macro lets you put a button on a page that links to a specific template of your choice. When the
button is clicked, the macro opens the editor, ready to add a new page, and adds content to that page based
on the given template.
Create your own page templates
Create your own templates for any content that you want formatted the same way every time. For example, if
you have to create a regular report tracking the same criteria, create a template with headings, variable
dates, tables, and spaces for any graphics, so that each time all you have to do is input the new data instead
of creating the whole report from scratch.
How do I help my team stay on top of what's important?

If you've got a lot of content on Confluence, staying on top of everything may seem a little daunting – but
these features will help your team save and track all the content they care about.
My Spaces
Add any spaces that you want to be able to navigate to easily to your list of 'My Spaces'. This list can be
found under your dashboard and in the Space Directory, and you can also use the Spaces List Macro to
display it on a page or blog.
To add a space to your list of 'My Spaces', either navigate to that space or find it under the Space Directory,
and select the star icon next to the Space Name. To remove it from the list, just select the star icon again.
Save for later
If you only want links to certain pages or blogs rather than a whole space, you can choose Save for later and
these will appear on your dashboard and under your profile. You can use the Favorite Pages Macro to
display a list of all of everything you've saved for later.
Watch a page, blog or space
If you want to keep track of all the changes made to a page, blog, or space, you can also watch them.
Watching any content means that you will receive email notifications for all edits, deletions, attachments or
comments made to that content.
To watch a page, navigate to the page you want to watch, then choose Watch > Watch page , or if
you want to watch the whole space, select Watch all content in this space.
To watch a blog, navigate to that blog and choose Watch this blog.
To stop watching something, deselect the relevant checkbox.
You can also manage watchers for your own space. This is useful when, for example, you're creating a new
project, and want the team members on that project to stay notified of its progress. Go to any page in that
space and choose Watch > Manage Watchers, then add or delete any names under 'Watching this space'.
@mentions
Use @mentions for any work where you need someone else's input or want to assign someone a task.
Mentioning someone works like a tag; they'll immediately receive a notification that they've been mentioned,
and can click through to that page or blog. If you mention someone when creating a task, it'll assign that task
to them and they'll also be able to find it under their profile.
You can use this in place of emails – if you want someone to look something over, add in additional
information, or approve anything, simply put that work on Confluence and assign it to them as a task. They'll
be able to make any changes or comments within Confluence and let you know when they're done by
mentioning you back.
Set up a Space Home Page
When you create a space, Confluence automatically
creates a home page for that space. Spaces On this page:
created with a blueprint come with a ready-made
home page populated with useful macros and
sample content specific to the blueprint's use case. Create a kick-ass home page
Top macros for common types of spaces
However, even if you've started with a blank space, Set up your personal space home page
you can still customize your home page to make it Set another page as your home page
easier for everyone using that space to navigate
their way around and find useful content. Related pages:
Organize your Space
Create a kick-ass home page

What is this space about?
Your home page is the first page visitors will see when they visit your space, so it helps to include
some information about what the space is about, and what you're working on. You can use the Info,
Tip, Note, and Warning Macros to create a colored box in which to put this information.
What is in this space?

You can use the Content Report Table Macro to create a table of contents for your space. You can
also set this macro to only display content with a particular label, so if you would like only some
content to display, you can do this by adding that label to only those pages and blogs you want listed
on your home page.
Organize your space with labels

You can organize content in your space with labels, so that for example, if you have a Learning and
Development space, you can create different labels for online learning resources, upcoming
workshops, and training strategy. You can then use the Labels List Macro to create a list of those
labels to make it easy for visitors to your space to find the content relating to each of those topics.
Add a search box so that it's easy to find content within your space
The Livesearch Macro allows you to add a search box to a Confluence page, and you can set it to
only find content within your space.
Keep everyone updated about the latest changes within your space
If it's important for your visitors to know about the latest changes to your space, you can use the Rece
ntly Updated Macro to display a list of the most recently updated content. You can set the space
parameter to show this for just your space, or, if you have related spaces, to show the most recently
updated content across all of those spaces as well.
Using Jira? Create and display your Jira issues on Confluence

If your Confluence site is connected to a Jira application, you can both create and display your Jira
issues without having to leave Confluence using the Jira Issues Macro. You can connect Confluence
to any Jira application, including Jira Software and Jira Service Desk.
Top macros for common types of spaces
Team Spaces:
Introduce the team: The User Profile Macro displays a short summary of a given Confluence user's
profile with their role, profile photo and contact details.
Share news and announcements with your team: The Blog Posts Macro displays a stream of your
latest blog posts so your team can easily see what's been going on.
Knowledge Base:
Have external content that you need on your page? Embed online videos, slideshows, photo
streams, and more, directly into your page with the Widget Connector Macro.
Put your own multimedia content onto the page: The Multimedia Macro embeds attached video,
animation, and other multimedia files on a Confluence page.
Create an index of all your content: The Page Index Macro creates a hyperlinked alphabetical
index of all page titles within the current space.
Planning/Project:
Keep track of everyone's tasks: Use the Task Report Macro to display a list of tasks on a page.
Filter the tasks by space, page, user, label, created date and more.
Is your project on track? The Status Macro displays a colored lozenge (a rounded box) that is
useful for reporting project status. You can choose the color of the lozenge and the text that appears
inside the lozenge.
Let everyone see where you're going: The Roadmap Planner Macro creates simple, visual
timelines that are useful for planning projects, software releases and much more.
Using Macros
1. From the editor toolbar, choose Insert > Other Macros

2. Find and select the required macro
Speed it up with autocomplete: Type { and the beginning of the macro name, to see a list of suggested
macros. In this example we're inserting the cheese macro.
To edit an existing macro: Click the macro placeholder and choose Edit. This will open the macro
details, so you can edit the macro parameters.
Set up your personal space home page

Whether you're using your personal space as a sandbox to draft and test content, a portfolio to show off
what you're working on, a home base to navigate to your content in other spaces, or something completely
different, these are some macros that should help you use your space more effectively.
Use the Favorite Pages Macro to create a list on your home page of all the pages you've saved for
later, so you can easily navigate back to any of them.
Use the Content by User Macro to keep track of all the current pages, comments and spaces you've
created so you can find everything you've been working on in one place.
Use the Task Report Macro to keep track of all tasks assigned to you, and tick them off as you finish
them.
Use the Recently Updated Dashboard Macro to keep track of all the content across your Confluence
site that you're interested in - the Dashboard lets you choose which spaces, users, blogs, pages or
files you would like to keep updated about.
Set another page as your home page

If at any point you decide that you would like another page within your space to be your home page, you can
easily change this from the Edit Space Details tab.
To edit a space's details:
1. Go to the space and choose Space tools > Overview from the bottom of the sidebar.
2. Choose Edit Space Details.
3. Enter the page you want use in the Home page field then choose Save.
You can change the home page, name and description of your space, but you are not able to change the
space key.
Use Labels to Categorize Spaces
If you've got lots of related spaces, you can use labels to group them
On this page:
together into categories in the Space Directory.
For example, if you're in an IT team who work on a number of projects, Categorize a space
each in a different space, you could label each space 'IT-projects-open'. View spaces in a
Then in the Space Directory you could select IT-projects-open to see all category
your current IT project spaces. Remove a space
from a category
You can add as many space categories to a space as you need, so that if, Search within a
for example, two different teams are working on a project together, you can space category
add labels for both teams and space will appear under both categories.
Related pages:
Labels are easy to add or remove, so if your needs change, you can always
recategorize your spaces. Add, Remove and
Search for Labels
Categorize a space
You need space administrator permissions to add categories to a space.
1. Go to the space and choose Space tools > Overview from the bottom of the sidebar
2. Choose Edit next to Space Categories.
3. Under Space Categories, enter your category name and choose Add.
Alternatively, choose a category in the list of Suggested Space Categories.
4. Choose Done.
Add a space description
Help make it easier to find the right space within a category by adding a description to your space:
1. Go to the space and choose Space tools > Overview from the bottom of the sidebar.
3. Under the Description field, type a short description to tell visitors what your space is about, then
choose Save.
View spaces in a category

To see what spaces are in a category, choose Spaces > Space directory in the Confluence header, then
select one of the categories from the list.
You can also view spaces by category by using the Spaces List Macro and filtering by category.
Head to My Spaces in the Space Directory to see all your favorite spaces. When viewing a space,
you can choose the star icon next to the space title in the sidebar to add it to My Spaces so that it's
easier to find later.
Remove a space from a category

1. Go to the space and choose Space tools > Overview from the bottom of the sidebar
2. Choose Edit next to Space Categories.
3. Under Space Categories, choose the x icon next to each category that you want to remove.
If you remove all spaces from a category, the category will no longer appear in the Space Directory.
There's no way to bulk remove a category, but you can choose the category in the Space Directory to find all
the spaces it appears on, and then remove it from each space.
Search within a space category

You can search for content within a specific space category using the search filter.
To search within a Confluence space category:
1. Click the search field in the top-right of Confluence to open the search panel.
2. Click the Space category filter on the left.
3. Start typing the category name and choose from the list of possible matches.
Learn more about searching Confluence.
Customize your Space
Make your space stand out from the crowd by
Related pages:
customizing its appearance.
Changing the Look and Feel of Confluence
If you have space admin privileges, you can change
the color scheme for your space, add your own Styling Confluence with CSS
space logo, choose what shows up in your space's
sidebar, or use Atlassian Marketplace themes to
change the whole look of your space.
Configure the Sidebar

Edit a Space's Color Scheme
Apply a Theme to a Space
Customize Space Layouts
Configure the Sidebar
If you have administration permissions for a space,
you can customize the space's sidebar to have its On this page:
own logo, change the way the hierarchy is
displayed, and add shortcut links to help navigate to
important content quickly. Change the space name and logo
Configure the sidebar links
To start configuring the sidebar, choose Space Change the navigation display options
tools > Configure sidebar. Adding custom content to a sidebar
Related pages:
Change the space name and logo Edit a Space's Color Scheme
Organize your Space
To change the space name:
1. Choose next to the space name.

2. Type in a new space name and Save.
1. Logo - change the space name and logo

2. Reorder - drag to reorder shortcuts
3. Hide - hide or show pages, blogs, shortcuts or navigation display options.
To change the space logo:
1. Choose the next to the space name.

2. Choose Upload an image.
3. Select an image from your computer.
4. Adjust the size of the image to fit within the highlighted circle.
5. Choose Save.
Things you should know:
Space logos are 48px x 48px. Logos smaller than these dimensions will be centred with whitespace
around them.
You can only change the space logo for a site space. For your personal space, your profile picture is
used as the space icon.
Configure the sidebar links

Choose the icons to show or hide pages, blogs, shortcuts or navigation options.
For example, if you want your space to be used primarily as a blog you can hide the 'Pages' link.
Add--ons such asTeam Calendars for Confluence Server may add other links in this section of the
sidebar and you can also show or hide these.
Choose Add link to add a shortcut link to the sidebar. This could be a link to an important page for
your team, or to an external site.
Drag links to reorder them within each section (you can't move a link from one section to another).
Change the navigation display options

Choose Child pages to see the current page and its children in the sidebar.
Choose Page tree to see the page tree for the entire space, expanded to the current page.
You can also choose to completely hide the navigation display options and instead add the pages you
want to be visible as shortcut links. Alternatively, you can remove the sidebar navigation altogether
and use a Page Tree Macro or Children Display Macro on your homepage for navigation instead.
Adding custom content to a sidebar

You can further customize a sidebar using wiki markup to add custom content.
To add custom content to your sidebar:
1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar.
2. Choose Sidebar, Header and Footer.
3. Enter your custom content in the Sidebar field.
The sidebar, header and footer fields all use wiki markup, check our guide to wiki markup for help, or check
out some common customizations below.
To add a search field to the sidebar add the following wiki markup for a search macro in the Sidebar field.
For the Livesearch Macro macro:
{livesearch}
For the Page Tree Search Macro macro:
{pagetreesearch}
To add a panel with some custom content to the sidebar add the following wiki markup for the Panel
Macro in the Sidebar field:
{panel}This is some custom content to appear in the sidebar{panel}
To hide the default page tree and add your own, with additional parameters:
1. Add the wiki markup for the Page Tree Macro in the Sidebar field.
The following example includes parameters to expand the top three levels of the page tree by
default and include an Expand All and Collapse All link above the tree.
{pagetree:root=Page Name|startDepth=3|expandCollapseAll=true}
2. Go to Space Tools > Configure sidebar.

3. Use the Show and Hide icons to hide the default page tree from the sidebar.
Edit a Space's Color Scheme
Spaces inherit the global color scheme by default, but if you have admin
Related pages:
permissions for a space, you can jazz it up with your very own customizable
color scheme. Configure the
Sidebar
To change the color scheme for a space: Apply a Theme to
a Space
1. Go to the space and choose Space tools > Look and Feel from the
2. Choose Color Scheme
3. Choose Select next to a scheme listed under Custom Color
Scheme (if not already selected)
4. Choose Edit
5. Enter standard HTML/CSS2 color codes or use the color-picker to
choose a new color from the palette provided
Customizable Elements
The color scheme allows you to edit the colors of UI elements including the top bar, tabs and backgrounds.
Some UI elements below are for specific themes, and color changes may not take effect for other themes.
Top Bar - the top navigation bar background

Top Bar Text - the text on the top navigation bar
Header Button Background - buttons on the top navigation bar (e.g. Create button)
Header Button Text - the text on buttons on the top navigation bar
Top Bar Menu Selected Background - background color of top navigation bar menu items when
selected (e.g. spaces)
Top Bar Menu Selected Text - text color of top navigation bar menu items when selected
Top Bar Menu Item Text - text on top navigation bar drop down menus (e.g. help or cog)
Menu Item Selected Background - highlight color on top navigation bar drop down menu items
Menu Item Selected Text - text color on highlighted top navigation bar drop down menu items
Search Field Background - the background color of the search field on the header
Search Field Text - the color of the text in the search field on the header
Page Menu Selected Background - the background color of the drop down page menu when
selected
Page Menu Item Text - the text of the menu items in the drop down page menu
Heading Text - all heading tags throughout the space
Links - all links throughout the space
Borders and Dividers - table borders and dividing lines
Handy Hint
If you mess things up, just choose Reset then try again.
Themes are used to change the appearance of your space. Your
Related pages:
Administrator can download and install themes from The Atlassian
Marketplace. Applying a Theme
to a Site
Once a theme is installed it can be applied to the whole site or to individual Customize your
spaces. Space
Edit a Space's
To apply a theme to a space:
Color Scheme
Configure the
1. Go to the space and choose Space tools > Look and Feel from the
Sidebar
You'll need Space Admin permissions to do this.
2. Choose Themes and select a theme option.
3. Choose Confirm.
What is the global look and feel?
When a new space is created, whichever theme is applied to the whole site will be applied by default to the
new space. This is the global look and feel, and any changes made globally will flow through to all spaces
that inherit the global look and feel.
If a space has its own theme applied, or if changes have been made to customize the look and feel of the
space, it will no longer inherit changes from the global look and feel.
If you want to go back to inheriting the global look and feel choose Global look and feel from the Themes p
age.
Documentation theme migration FAQ
As previously announced, the documentation theme is not available in Confluence 6.0. We know you'll have a
lot of specific questions, so we've created this FAQ to help you prepare for upgrading to Confluence 6.0.
If you have further questions, you can ask them at the bottom of the page and we'll do our best to provide an
answer.
What does the default theme look like?

How can I check if I am using the documentation theme in my space?
How can I check if the documentation theme is being used anywhere in my site?
What will happen to my theme customizations during the upgrade?
Will my space break after the upgrade?
Can I add custom content to the sidebar, header and footer globally?
Can I still use macros in my sidebar, header or footer?
Where should I add custom content to the sidebar, header or footer?
How do I turn off the Pages and Blogs shortcuts at the top of the sidebar?
Can I edit the default theme's sidebar globally?
I want to see the page tree, not child pages. how do I do this?
Where is Space Administration and Space Operations?
Do I have to use wiki markup in the sidebar, header, and footer?
Can I hide or change the space logo appearance?
Can I hide the built in page tree and insert my own?
How can I make my page titles wrap in the sidebar?
Can I change the order in which things appear in the sidebar?
Can I still use the space jump macro?
Why don't child pages appear below the page?
Can I restrict search to just this space?
How do I view the pages in my space alphabetically?
What will happen if I import a space that uses the documentation theme?
What does the default theme look like?
Here's an example of the documentation theme, and default theme with the same custom content side by side:
1. Documentation theme: with custom sidebar content.

2. Default theme: with the same custom content in the sidebar.
How can I check if I am using the documentation theme in my space?

The easiest way to check whether your space is using the documentation theme is to look for a Browse menu
in the header, near the Create button. (If you're using the default theme already, you'll see a Space Tools menu
at the bottom of the sidebar instead.)
How can I check if the documentation theme is being used anywhere in my site?
There's no simple way to see a list of spaces using the Documentation theme in Confluence itself, however if
you have a very large site, your Confluence Administrator can use the following query to get a list of spaces
directly from the database.
SELECT *
FROM BANDANA B, SPACES S
WHERE B.BANDANAKEY='atlassian.confluence.theme.settings'
AND S.SPACEKEY=B.BANDANACONTEXT
AND B.BANDANAVALUE LIKE ('%documentation%')
ORDER BY S.SPACENAME;
This query will only find spaces that are explicitly using the documentation theme. It doesn't include spaces
using the global look and feel (these spaces automatically change when you change the Site Theme, you wont
need to change the theme space by space).
What will happen to my theme customizations during the upgrade?
During the upgrade we'll automatically turn on the default theme for any spaces that currently use the
documentation theme. If you've customized the documentation theme (by adding wiki markup to the sidebar,
header or footer) we'll take this wiki markup and drop it into the sidebar, header and footer in the default theme.
The default theme adds some new sections to the sidebar, such as links to pages, blogs and space
shortcuts. You can choose to hide these - head to Space Tools > Configure Sidebar and use the button to
hide any items you don't want to see.
Will my space break after the upgrade?
This depends on the amount of customization you have. In most cases your space sidebar may look a little
different but the changes shouldn't be dramatic.
If you've used CSS to change the appearance of your space (either in the space stylesheet or by using the
Adaptavist Content Formatting macros like {style} and {div} in the sidebar, header, or footer of the
documentation theme), you may need to make a few changes to some class names in your CSS to get your
space looking right. For example, if you specified #splitter-sidebar in the doc theme, you'll need to use .
acs-side-bar for the default theme.
If you have customized default theme layouts through the Confluence UI, you may find that your space looks
strange or broken when the default theme is re-applied to spaces previously using the documentation theme.
If you experience problems, you'll need to reset the broken layouts.
This method will only work if you have more than one theme available in your site. You'll need System
Administrator global permission to do this.
1. Switch to another theme temporarily.

If you're unable to use the space navigation, use this URL, replacing YOURSPACEKEY with the space
key for the space.
http://<yoursite>/spaces/choosetheme.action?key=YOURSPACEKEY
2. In the space administration options go to Layouts (if available) or use the following link, replacing YO
URSPACEKEY with the space key for the space.
http://<yoursite>/spaces/listdecorators.action?key=YOURSPACEKEY
3.
3. Choose Reset Default next to any template that have been customized.
4. Return to the Themes page and try applying the default theme again.
Layouts can also be customized for the entire site - head to > General Configuration > Layouts if you
need to reset the layout for the entire site.
If you're unable to reset the layouts via the Confluence UI, you can remove the affected layouts directly in
the database. Be sure to take a full database backup before you try this.
First, use the following query to identify customized layouts:
Select *
FROM DECORATOR
ORDER BY SPACEKEY
Then, you can selectively remove records for spaces that are affected.
Can I add custom content to the sidebar, header and footer globally?
Yes. Head to > General Configuration > Sidebar, Header and Footer. All spaces that use the global look
and feel will inherit your custom content. Any custom content added to the sidebar, header and footer in a
particular space will override any custom content added globally.
Can I still use macros in my sidebar, header or footer?
Yes! If a macro worked correctly in the documentation theme it'll work in the default theme too.
Where should I add custom content to the sidebar, header or footer?
You can add custom content to the sidebar, header and footer in each space individually (Space Tools > Look
and Feel > Sidebar, Header and Footer) or globally ( > General Configuration > Sidebar, Header and
Footer).
Confluence displays global custom content in all spaces, except where a space has its own custom content
defined (space custom content overrides global custom content). This behavior applies field by field, so a space
can display a combination of custom content. For example you could define the content of a footer globally, and
content of a header in each space individually, or only in some spaces.
How do I turn off the Pages and Blogs shortcuts at the top of the sidebar?
Go to Space Tools > Configure Sidebar and use the icons to hide any items you don't want to see.
Can I edit the default theme's sidebar globally?
No. You can add custom content to the sidebar globally, but showing and hiding sections of the sidebar, setting
space logos, and adding shortcut links are done on a space by space basis.
I want to see the page tree, not child pages. how do I do this?
Head to Space Tools > Configure Sidebar and select Page Tree in the navigation options. The default for all
new spaces is Page Tree.
Where is Space Administration and Space Operations?

Instead of choosing between Space Operations and Space Administration, the documentation theme has a
single Space Tools menu that lets you jump right to Permissions, Content Tools, Look and Feel, or
Integrations.
Old Space Operations location New Location in the sidebar
Browse > Pages Pages on the sidebar or Space Tools > Reorder pages
Browse > Blogs Blogs on the sidebar
Browse > Labels

Click a label on any page, then use the menu to see all
labels, popular labels or pages from other spaces
Browse > Space Operations > Space Tools > Overview

Space Details
Browse > Space Operations > Space Tools > Content Tools > Orphaned Pages
Orphaned Pages
Browse > Space Operations > Space Tools > Content Tools > Undefined Pages
Undefined Pages
Browse > Space Operations > Space Tools > Content Tools > Attachments
Attachments
Browse > Space Operations > Space Tools > Content Tools > Export
PDF, HTML, XML Export
Browse > Space Operations > Space Tools > Content Tools > RSS Feeds
RSS Feeds
Browse > Space Operations > Pages > Watch this space (or use the Watch button on any page)
Watch this space
Browse > Space Operations > Blogs > Watch this blog (or use the Watch button on any blog post)
Watch this blog
Browse > Space Operations > Use the icon in the sidebar (or in the space directory)
Remove from My Spaces
Browse > Space Admin > Space Space Tools > Overview
Details
Browse > Space Admin > Space Space Tools > Overview
Categories
Browse > Space Admin > Space Tools > Content Tools > Templates
Templates
Browse > Space Admin > Delete Space Tools > Overview > Delete Space
Space
Browse > Space Admin > Trash Space Tools > Content Tools > Trash
Browse > Space Admin > Space Tools > Permissions

Permissions
Browse > Space Admin > Space Tools > Permissions > Restricted Pages
Restricted Pages
Browse > Space Admin > Space Tools > Integrations > Application Links
Application links
Browse > Space Admin > Themes Space Tools > Look and Feel > Themes
Browse > Space Admin > Color Space Tools > Look and Feel > Color Scheme
Scheme
Browse > Space Admin > PDF Space Tools > Look and Feel > PDF Layout
Layout
Browse > Space Admin > PDF Space Tools > Look and Feel > PDF Stylesheet
Stylesheet
Browse > Space Admin > Space Tools > Configure Sidebar then choose the edit icon on the
Change Space Logo space logo
Browse > Space Admin > Hipchat Space Tools > Integrations > Hipchat
Integration
Do I have to use wiki markup in the sidebar, header, and footer?
Yes. Our main focus when adding this feature was to help people move from the documentation theme to the
default theme with a minimum of effort. Keeping these fields as wiki markup means that your existing
customizations can be pasted straight in.
Can I hide or change the space logo appearance?
You can upload any image to use as your space logo, but you can't change how it appears in the sidebar (it's
always round and always at the top).
Can I hide the built in page tree and insert my own?
Yes! If you want to have complete control over how the page tree appears in your sidebar you can hide the built
in page tree, and then add a Page Tree macro {pagetree} in the sidebar custom content.
How can I make my page titles wrap in the sidebar?
Page titles do not wrap in the sidebar of the default theme (regardless of whether you're using the built in page
tree or have added a {{pagetree}} macro as custom content). There's no way to change this.
Can I change the order in which things appear in the sidebar?
You can change the order of some items in the sidebar, such as the shortcuts, but the order of the sections
themselves can't be changed. Anything that has a icon can be moved.
Custom content appears above the page tree. You have the option to hide the built in page tree, and then add it
back in the custom content area using wiki markup. This can be useful if you want more control over the order of
the page tree and your custom content.
Can I still use the space jump macro?
No, the space jump macro was provided by the documentation theme and will not be available once the
documentation theme is removed. If you've used this macro on a page or in the header or footer of a space, it
will show the following error after the upgrade unknown macro: {spacejump}.
To find out whether the Space Jump macro is used on any pages in your site, enter macroName:spacejump
into the search bar. All pages containing the macro will be returned (it won't search the sidebar, header or
footer unfortunately).
Why don't child pages appear below the page?
The default theme does not list child pages below the sidebar, but you can achieve a similar result by adding a C
hildren Display macro to the footer.
Can I restrict search to just this space?
No, that is one of the features we removed with the documentation theme.
One workaround is to add a Livesearch macro to the sidebar or space homepage. Use @self in the spaces
parameter to restrict the search to the current space.
How do I view the pages in my space alphabetically?
The default theme does not have an option to view all pages in your space alphabetically.
What will happen if I import a space that uses the documentation theme?
You should have no problems importing the space, but it will have the default theme applied and any wiki
markup customization in the theme will not be automatically migrated to the default theme. Before exporting the
space you should copy the wiki markup contents of the sidebar, header, and footer fields and keep it so that you
can add it back in manually after you've successfully imported your space.
Customize Space Layouts
You can modify Confluence's look and feel by
editing the layout files. This page tells you how to Related pages:
customize the layout files for a space. You'll need
the system administrator global permission plus spa Customize your Space
ce administrator permission for that space. Apply a Theme to a Space
Styling Confluence with CSS
People with system administrator permissions can
also customize the layout of the entire Confluence
site. For more information, see Customizing Site
and Space Layouts. Site layout customizations
modify the default layout of all spaces in the
Confluence site.
Any space layout customizations will override the

equivalent site customizations.
If you modify the look and feel of Confluence by following these instructions, you'll need to update
your customizations when you upgrade Confluence. The more dramatic the customizations are, the
harder it'll be to reapply your changes when upgrading. Please take this into account before
proceeding with any customizations.
For more information on updating your customizations, please refer to Upgrading Customized Site
and Space Layouts .
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.
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 a very simple programming language called Velocity. Learn more about Velocity. Once you
become 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,
if you want to make changes to the header and the footer, you will need to modify these layouts.
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 they allow you to alter the way the
surrounding comments or attachments are shown.
Export layouts: These control the appearance of spaces and pages when they are exported to
HTML. If you are using Confluence to generate a static website, for example, you will need to modify
these layouts.
Learn more about using decorators.
To edit a decorator file:
1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
2. Choose Layout (Layout is displayed only if you are a Confluence system administrator.)
You'll see a list of the layouts for the space
3. Click Create Custom to edit the default vmd file
This will open up the vmd file in edit mode. If you only want to view the vmd file, click View Default.
4. Make any changes and click Update
Archive a Space
Archiving a space is useful when you have content that is no longer
On this page:
relevant, but you still want the option of accessing it at a later date. Archived
spaces are less visible, but still available on your site. Archiving a space is
easy to undo — you can make a space current again at any time. Archive a space
The effect of
Archive a space archiving a space
Spaces
1. Go to the space and choose Space tools > Overview from the Pages
bottom of the sidebar Change a space
2. Choose Edit Space Details. from archived to
3. Select Archived in the Status dropdown menu. current
4. Choose Save.
Related pages:
Delete a Space
Export Content to
Word, PDF, HTML
and XML
The effect of archiving a space
Spaces
If a space is archived, that space:
Won't appear in the Recent spaces section of the search panel.

Won't appear in search results, unless you select Search archived spaces.
Won't appear in advanced search results unless you select Search archived spaces.
Won't appear on the Spaces dropdown menu.
Won't appear in the general spaces lists in the Space Directory, but will instead appear under the Arc
hived Spaces list. It will, however, still appear under any categories it was labeled with.
Won't show up in activity streams when updated.
Won't appear on your dashboard.
Pages
Pages within an archived space will appear in a few places.
If you view a page within an archived space, that page will appear in:
The Recently visited section of the search panel.

The Recently viewed pages menu.
If you edit a page within an archived space, that page will appear in:
Activity streams
The Recently updated macro.
Pages within an archived space won't appear in search results, unless you select Search archived spaces.
These functions remain available for archived spaces:
You can view the content as usual, by following a link or typing in a URL belonging to the archived
space.
You can edit the content as usual, as determined by the space permissions.
RSS feeds, watches and notifications remain active.
Archiving a space has no effect on search results of external search engines. For example, a public space
will still appear in Google search results.
Change a space from archived to current

Through the space directory:
1. Go to Spaces > Space directory in the header.

2. Choose Archived Spaces on the left.
3. Find your space and click the on the right.
5. Change the Status from 'Archived' to 'Current' and hit Save.
Through the archived space:
1. If you know the space key, you can navigate straight to the archived space - http://yoursite
/display/SPACEKEY
2. Choose Space tools > Overview from the bottom of the sidebar.
4. Change the Status from 'Archived' to 'Current' and hit Save.
Delete a Space
Deleting a space permanently removes the space and all of its contents,
including any calendars and questions linked to that space. Only someone Related pages:
with space admin permissions can delete that space.
Archive a Space
Deleting a space is permanent – it does not go to the trash and cannot Export Content to
be undone. Word, PDF, HTML
and XML
If you're unsure about deleting a space, create an XML export of the space
as a backup before proceeding. You can then restore the space from the
XML export file if you need to.
To delete a space:
1. Go to the space and choose Space Tools > Overview from the
bottom of the sidebar.
2. Choose Delete Space.
3. Choose OK.
Members of the confluence-administrators group can also delete spaces, including personal
spaces.
Export Content to Word, PDF, HTML and XML
You can export all or part of a Confluence space to various formats,
On this page:
including Microsoft Word, HTML, PDF and XML.
To use the space export functionality, you need the 'Export Space' Export single
permission. See the guide to space permissions. pages to PDF
Export single
Export single pages to PDF pages to Word
Export multiple
If you need to send content to people who don't have access to Confluence, pages to HTML,
you can export a single page or blog post as a PDF. XML, or PDF
Customizing the
If you've got permission to view the page in Confluence, you'll be able to appearance of
export it in this way; go to the page and choose (Tools) > Export to PDF exports
PDF. Migrating content
to Confluence
Only published content is exported. This means you can create PDF Cloud
exports even while people are still working on the page.
Related pages:
When you export a single page to PDF, the PDF stylesheet customizations
Customize Exports
are applied, but any PDF layout customizations are not. To make your PDF
to PDF
layout customizations apply to a single page exported to PDF, you'll need to
Restoring a Space
use the 'multiple page' method described below to export the single page.
See Customize Exports to PDF.
Export single pages to Word

You can also choose to export single pages to a .doc file that can be opened in Microsoft Word.
If you've got permission to view the page in Confluence, you'll be able to export it in this way; go to the page
and choose Tools > Export to Word.
Only published content is exported. This means you can create Word exports even while people are still
working on the page. Also, only the first 50 attached images will be included in the export. See the notes
below for more information.
Note that due to the format of this file, it can only be opened in Microsoft Word and is not compatible with
other applications such as Open Office, Libre Office or Google Docs.
Export multiple pages to HTML, XML, or PDF

If you want to export a space – or selected pages in a space – to HTML, XML, or PDF, Confluence can
create a zipped archive of the HTML or XML files, or a single, downloadable PDF file.
PDF export is useful you're producing a printable user manual from your documentation space for example.
The HTML export can be used to convert your site content to a static website, and finally the XML export can
be used to import your space content into another Confluence space (running the same or later version of
Confluence).
To export pages to HTML, XML, or PDF:
1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Export
3. Select either HTML, XML, or PDF, then choose Next
4. Select the type of export:
Normal Export (HTML and PDF) – to produce an HTML or PDF file containing ONLY the
pages that you have permission to view.
Full Export (XML) – to produce an XML file containing all the pages in the space, including
those that you do not have permission to view.
Custom Export – if you want to export selected pages only, or if you want to exclude
comments from the export.
5.
5. Choose whether to Include Page Numbers (PDF only)

6. Choose Export.
When the export process has finished, you can download the zipped archive or PDF.
What's included in the export?
The following content is included in space exports.
PDF export XML export HTML export
Pages Yes Yes Yes
Blogs No Yes No
Comments No Optional Optional
Attachments Images only Yes Yes
Unpublished changes No Yes No
Page numbers Optional N/A N/A
Restricted pages Only those Yes, they Only those

and blog posts you can view remain you can view
restricted
Customizing the appearance of PDF exports

You can add a title page, table of contents, and customized headers and footers to the PDF output. For
more advanced customizations, you can apply Cascading Style Sheet (CSS) modifications. These
customizations are specific to each space, and you need the 'Space Administrator' permission to apply these
customizations. For more information, see Customize Exports to PDF.
Notes on PDF exporting
To export a PDF containing international text, see Create a PDF in Another Language
Confluence's PDF export feature is designed to handle a wide variety of content, but on rare
occasions the PDF Export process may fail due to an unrecognized customization. If that happens,
the PDF export screen will indicate the title of the page in which the problem occurred, to help you
diagnose the cause of the failure.
Tables that exceed the width of a page, particularly those with images in them, might be cut off in the
PDF. See Wide tables are cut off in PDF exports for some suggested workarounds.
In Confluence Data Center, PDF exports are handled by the external process pool.
Notes on Word exporting
Only the first 50 images attached to the page are exported to your Word document. This is to prevent
out of memory errors affecting your whole Confluence site. See
CONFSERVER-34211 - If a page with big number of images Exported to Word, some images
are invisible GATHERING IMPACT
for more information, and to find out how you can temporarily increase this limit using a system
property.
Notes on HTML exporting
In the zip file, page attachments are placed in individual folders with names in the following format:
...\download\attachments\xxxxxx
where 'xxxxxx' is the page ID of the page containing the attachments.
To customize the HTML output, you'll need to modify the file confluence-x.y.z-jar/com
/atlassian/confluence/pages/Page.htmlexport.vm. To learn how to repackage this file,
see How to Edit Files in Confluence JAR Files
Notes on XML exporting
You can only import a space into the same or later Confluence version. You can't import a space
into an earlier version.
Team Calendars aren't included in XML exports.
If you're doing the export for backup purposes, consider another means of backup. See Production
Backup Strategy.
If you are running Confluence behind Apache HTTP Server and are facing timeout errors, please
consider creating the export directly from Tomcat, instead of going through Apache. This will speed
up the process and prevent timeouts.
See Restoring a Space for notes on restrictions when importing a space into Confluence Server.
Migrating content to Confluence Cloud

If you're migrating from Confluence Server to Confluence Cloud, you can use the Confluence Cloud
Migration Assistant to migrate your content and spaces.
Customize Exports to PDF
Confluence provides a basic PDF export that you
On this page:
can customize and style to suit your needs.
You need Space Admin permissions to customize How it works

PDF exports in a space, and Confluence Limitations
Administrator global permissions to customize PDF Change the PDF layout
exports for the whole site. PDF Layout examples
Title page
Header or footer
Change the PDF stylesheet
PDF Stylesheet examples
Page size
Page orientation
Page margins
Page breaks
Word wrapping
Title page
Table of contents
Tables
Page numbers
Headings
Other formatting
Related pages:
Advanced PDF Export Customizations
How it works
When someone exports a space to PDF, Confluence will apply any layout and styling directions it finds in the
current space or set globally for the whole site.
The PDF Layout allows you to add a title page to your PDF, and add a header and footer to all
pages.
The PDF Stylesheet allows you to change the look of the PDF. You can change just about anything,
including the paper size, fonts and colours, spacing, and control behaviours like page breaks.
Both the PDF Layout and PDF Stylesheet can be customized on a space by space basis, or globally for the
whole site. Space customizations will always completley override any global customizations. This means
you can't mix and match and set some items globally and others at the space level.
Limitations
There are a few limitations to be aware of:
Changes to the PDF layout only apply to space exports, not to single page exports (via > Export
to PDF).
Confluence Server and Data Center process space exports slightly differently. This means that some
options, like adding page numbers via CSS, aren't available in PDFs created with Data Center. We
recommend selecting Include page numbers on the export screen if you need to number your
pages.
We provide a number of example customizations to get you started, however Atlassian Support can't
help you with styling your PDFs or problems introduced by your customizations. If you're new to CSS,
you might want to get help from an Atlassian Solution Partner, or check out a Marketplace app like Scr
oll PDF Exporter which has a WYSIWYG editor to help you produce beautifully styled PDFs.
Change the PDF layout

The PDF Layout is where you add a title page, header, or footer to your PDF exports. The PDF layout fields
accept HTML. You can include inline CSS in the HTML too.
To change the PDF layout for the whole site:
Go to > General Configuration > PDF Layout.

You need Confluence Administrator global permissions to do this.
You need
Choose Edit, then add your customizations in the Title, Header, or Footer fields.
To change the PDF layout for a specific space:
Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar You'll need
Space Admin permissions to do this.
Choose PDF Layout.
Choose Edit, then add your customizations in the Title, Header or Footer fields
PDF Layout examples

Here are some examples of things you can do in the PDF Layout. The PDF layout can accept HTML and
inline CSS.
Title page
In this example we've added the title "Documentation for Confluence", a logo, and an additional title
"Contents" above the table of contents.
<div class="fsTitlePage">
<img src="/download/attachments/169118009/atlassian_logo.png" />
<div class="fsDocTitle">Documentation for Confluence</div>
</div>
<div class="tocTitle">Contents</div>
The logo image we've used is attached to a Confluence page in the same site. You can find out the
attachment ID by right clicking the image on the page, and copying its location.
Header or footer
In this example we've added plain text to the footer with some copyright information, and included a link.
Created in 2018 by Atlassian. Licensed under a <a href="http://creativecommons.org/licenses/by/2.5/au/"

>Creative Commons Attribution 2.5 Australia License</a>.
Change the PDF stylesheet

The PDF Stylesheet allows you to change the appearance of your PDF. This includes things like paper size,
fonts, colours, spacing, and other styling.
To change the PDF stylesheet for the whole site:
Go to > General Configuration > PDF Stylesheet.

You need Confluence Administrator global permissions to do this.
You need
Choose Edit, then add your CSS.
To change the PDF stylesheet for a specific space:
Go to the space and choose Space tools > Look and Feel from the bottom of the sidebarYou'll need
Space Admin permissions to do this.
Choose PDF Stylesheet.
Choose Edit, then add your CSS.
PDF Stylesheet examples

Here are some examples of common CSS overrides that you can use in your PDF Stylesheet.
The default CSS rules will apply unless you have specified an override in the PDF Stylesheet.
Page size
The default page size is US Letter (8.5 inches wide by 11 inches long). To override this behaviour and
specify a particular size, add a size property to the CSS @page rule.
For example to export your space in A4 size:
@page
{
/*The A4 paper size is 210 mm wide by 297 mm long*/
size: 210mm 297mm;
}
Page orientation
To change the page orientation of your PDF document, reverse the order of the values declared in the @page
rule's size property. The first and second values of this property represent the width and height of the
page, respectively.
For example, to generate an A4 PDF in landscape, your @page rule might look like this:
@page
{
/*A4-sized pages in landscape orientation are 297 mm wide by 210 mm long*/
size: 297mm 210mm;
}
Page margins
The default margins are 0.5". To set all margins to 15 mm, with a paper size of A4, edit the CSS @page rule
in the PDF Stylesheet, like this:
@page
{
size: 210mm 297mm;
margin: 15mm;
}
To set the margins independently, edit the @page rule like this:
@page
{
margin-top: 2.54cm;
margin-bottom: 2.54cm;
margin-left: 1.27cm;
margin-right: 1.27cm;
}
To set margins to include a gutter for binding a printed document, you can use the :left and :right pseud
o-classes, as follows:
@page :left
{
margin-left: 4cm;
margin-right: 3cm;
}
@page :right
{
margin-left: 3cm;
margin-right: 4cm;
}
@page :first
{
margin-top: 10cm /* Top margin on first page 10cm */
}
In the example above we've also used the :first pseudo-class to define different margins for the title page.
Page breaks
By default, each Confluence page will start on a new page in the PDF. If you don't want each Confluence
page to start on a new page, you can override the default page breaks using the following CSS:
.pagetitle {
page-break-before: auto;
}
This behaviour changed in Confluence 6.13. If you're using Confluence 6.12 or earlier, page breaks are not
added before each page title.
If you're using Confluence Data Center, you won't be able to change this behavior, as PDFs are
generated page by page in the external process pool, and then combined together once all pages
are complete.
Word wrapping
Long, unbreakable words or strings (such as a URL) will automatically wrap to fit the page width, or cell
width if in a table.
If you don't want words or long strings to break you can use the following CSS:
div {
word-wrap: normal !important;
}
This may mean that the table formatting in your PDF is problematic, and very long content may overflow,
and be cut off the page.
Title page
If you have added a title page in the PDF layout, you can use the following rules to change the appearance
of the title page and title text.
.fsTitlePage
{
margin-left: auto;
margin-top: 50mm;
margin-right: auto;
page-break-after:always
}
.fsTitle
{
font-size: 42px;
font-weight: bold;
margin: 72px 0 4px 0;
text-align:center;
}
Table of contents
A table of contents is included by default when you export a space to PDF. It will appear at the start of the
document, or after the title page, if you've configured a title page in the PDF layout.
To omit the table of contents, use the following override:
div.toc
{
display: none;
}
The table of contents uses a leader character to visually connect the page title with it's page number. By
default this is a dot. Allowed values are dotted, solid and space. You can also use a string, for example
leader(". . . ").
The example below uses solid line, instead of dots.
span.toclead:before
{
content: leader(solid);
}
Tables
When you export a page that contains a table, we'll reduce the width of the table columns as much as
possible, so that the whole table fits comfortably on the page. Individual columns are resized to fit the
contents of each column.
If you prefer table columns to always be of equal width, you can use the following CSS:
table.fixedTableLayout {
table-layout: fixed !important;
width: 98% !important;
}
Any images in a table will be exported using the size set in the editor. If your table contains large images,
part of the table may be cut off when exported to PDF. To ensure that nothing is cut off, we recommend
resizing images in the editor, so that the total width does not exceed about 600px (for an A4 page in portrait
orientation).
Alternatively you can use the following CSS to fit images to the available width:
table img.confluence-embedded-image {
-fs-fit-images-to-width: 100% !important;
}
Page numbers
The best way to add page numbers to your document is to select Include page numbers on the export
screen. If you're using Confluence Server, and want more control over where page numbers appear, you
can use CSS to add numbers instead.
If you're using Confluence Data Center, you can't add page numbers using these methods, as PDFs
are generated page by page in the external process pool, and then combined together once all
pages are complete. Use the Include page numbers option on the export screen instead.
To add page numbers in the format "Page x of y" to the bottom of your page, add the following CSS to the
PDF stylesheet:
@page
{
@bottom-center
{
content: "Page " counter(page) " of " counter(pages);
font-family: ConfluenceInstalledFont, Helvetica, Arial, sans-serif;
font-size: 8pt;
}
}
Alternatively you can add page numbers into the footer. This requires making a change in the PDF layout
and the stylesheet.
First, add an element in the PDF layout. In this example we'll call it pageNum:
<span id="pageNum"/>
Then, in the PDF stylesheet, style the pageNum element as follows:
#pageNum:before
{
content: counter(page);
}
Headings
Heading sizes in the PDF export roughly match the sizes used on Confluence pages. You can easily
override them as follows:
h1 {
/* Custom styling */
}
h2 {
/* Custom styling */
}
This behaviour changed in Confluence 6.13. In Confluence 6.12 and earlier, headings were demoted based
on the position of the page in the page tree. Now headings are a consistent size on every page.
Other formatting
You can use the stylesheet to customize the output of just about anything on the page, including fonts,
tables, line spacing, macros, etc. The export engine works directly from the HTML output produced by
Confluence. Therefore, the first step in customizing something is to find a selector for the HTML element
produced by Confluence or the Confluence macro. Then add a CSS rule to the PDF stylesheet.
Advanced PDF Export Customizations
This page provides information about 'advanced'
PDF export customizations. These expand upon the On this page:
regular customizations described in Customize
Exports to PDF.
Header and Footer
Adding Headers and Footers to
The information below is for advanced users. Be
Single Page Exports
aware that the advanced customizations described
Adding Images to Headers and
below require knowledge of certain parts of
Footers
Confluence, and of CSS and HTML. Customizations
Incorporating Other Fonts
are not supported by Atlassian, so our support
Adding a Dynamic Title to the Title Page
engineers won't be able to help you with these
Hiding Text from the PDF Output
modifications.
Indexing
Notes
Related pages:
Customize Exports to PDF

Create a PDF in Another Language
Header and Footer
Adding Headers and Footers to Single Page Exports
Single page exports don't support adding HTML headers and footers via the PDF Layout page, but you can
use CSS rules in the PDF Stylesheet page (Space tools > Look and Feel > PDF Stylesheet) to produce
headers and/or footers for a single page export.
For custom headers, define any of the following rules within your @page rule: @top-left, @top-center, a
nd @top-right. These rules allow you to define the content of the left-hand side, centre and right-hand
side of your page's header area, respectively.
For custom footers, define @bottom-left, @bottom-center and @bottom-right rules within your @page
rule.
For example, the following rules add a document title at the centre of the header and a page number at the
centre of the footer:
CSS - PDF Stylesheet
@page
{
@top-center
{
content: "Document Title Goes Here"; /* This is the content that will appear in the header */
font-size: 8pt;
}
@bottom-center
{
content: "Page " counter(page); /* This is the content that will appear in the footer */
font-size: 8pt;
}
/* Any other page-specific rules */
}
Notes:
The font-family and font-size properties ensure that the header and footer text is rendered in
the same default font style used for the body text, based on the default CSS rules.
It is not possible to use this method to insert images (stored as attachments within your Confluence
instance) into the headers and footers of single page exports.
Adding Images to Headers and Footers
To insert an image into the header or footer, add HTML to the Header or Footer section of the PDF Layout
screen.
The following example uses an HTML img element with src attribute to add an image to the left of the
header. The src attribute refers to an image attached to a Confluence page. The image element is usually
placed within a div element container.
HTML - PDF Layout: Header Section
<div style="margin-top: 10.0mm;">

<img src="https://confluence.atlassian.com/download/attachments/12346/header-image.png" />
</div>
In the example above, the header includes an image called 'header-image.png'. The "12346" in the src
attribute is the ID number of the page to which the image is attached.
Follow these instructions to include an image on your page:
1. Attach the image to a Confluence page.

2. View the list of attachments on that page, then right-click the image and copy its location.
3. Paste the link into the appropriate src="" attribute in your PDF Stylesheet, as shown above.
4. Edit the image URL so that it is relative, by removing the first part of the URL before /download/....
Notes:
This example uses an inline CSS property margin-top in the style attribute to force the image
away from the top of the page by 10mm. This comes in handy when your header image is large
enough to touch or spill over the top of the page.
Likewise, for footers, you can use the margin-bottom:XXmm property to force an image away from
the bottom of the page by 'XX' mm.
Very large images can spill over into the body of a page or alter the position of text or other elements
used within a header or footer. In such situations, it is recommended that you reduce the size of the
image and then attach it to your Confluence page again. If you prefer to keep the image size and want
to move the content lower instead, you can do so by configuring the margin-top properties in the @p
age CSS rule.
By default, a header or footer image is aligned to the left-hand side of the page. However, you can
align this image to the centre or right-hand side of a page by adding either the text-align:center
or text-align:right properties to your style attribute. For example, to align the header image to
the right-hand side of the page, your style attribute would look similar to this: style="margin-
top:10mm; text-align:right".
Incorporating Other Fonts

By default, Confluence provides Times New Roman, Helvetica or Courier fonts for use in PDF exports. You
can use your own fonts for PDF exports by declaring them in a @font-face CSS rule in your PDF
Stylesheet.
The following CSS rule example shows how to declare the Consolas font and apply it to some elements for
your PDF export:
@font-face { src: url(file:///usr/share/fonts/Consolas.ttf); -fs-pdf-font-embed: embed; } .code pre, .

preformatted pre, tt, kbd, code, samp { font-family: Consolas, monospace; font-size: 9pt; }
The font path specified in the CSS must be the path to the font on the Confluence server.
Adding a Dynamic Title to the Title Page

When you export an arbitrary set of pages from Confluence, you may like to have a corresponding title
added to the cover (or title) page automatically. This can be done (in a somewhat irregular way) by using the
top level item from the default table of contents as the title. This method relies on having the exported pages
structured as sub-pages of the top-level page. In other words, the pages to be exported should consist of a
page (at the top-level) and all of its child pages. The result is that the title that appears on the cover page
changes depending on the top-level page that is used for the export.
The CSS below moves, and styles, the top-level TOC item for use as the title on the cover page, and turns
off the leader and page number normally associated with this item in the TOC.
.fsTitlePage { position:relative; left:0px; } /* Turn off the default section numbering for this TOC
item */ .toclvl0:before { content: " "; counter-reset: chapter 0; } /* Hide the default page
numbering for this TOC item */ .toclvl0 .tocnum { display: none; } /* Move and style this TOC item */ .
toclvl0 { position:absolute; top:250px; font-size: 42px; font-weight: bold; margin: 72px 0 4px 0; text-
align:center; }
Hiding Text from the PDF Output

This section describes a way to hide text from your PDF export. In other words, you can have text on the
Confluence page that will not appear in the PDF export.
There are three steps:
1. Follow the instructions to define the NoPrint user macro.

2. Use the NoPrint macro to mark some text on a Confluence page.
3. Add the following CSS to your PDF stylesheet to make the PDF export recognize the NoPrint macro:
.noprint { display: none ; }
Indexing
To obtain an index at the end of the exported PDF file, consider using the Scroll Wiki PDF Exporter plugin tha
t is produced by K15t Software GmbH.
Notes
If styling is not working as expected, it is useful to look at the intermediary HTML source to which the CSS is
applied. This intermediary HTML is created whenever you create an HTML export that contains multiple
pages, and is stored in the temp directory in Confluence's home directory. For example:
/temp/htmlexport-20110308-154047-1/export-intermediate-154047-2.html
Create a PDF in Another Language
To export a Confluence page written in a language
other than English, you'll need the necessary font Related pages:
for that language.
Export Content to Word, PDF, HTML and
XML
Upload a Font File to Confluence

1. Find the appropriate font file:
Windows users:All font files in Windows are stored in a directory called:
C:\WINDOWS\Fonts
Unix users:All font files in Unix are stored in:
/usr/share/fonts
Microsoft True Type core fonts such as Verdana can be downloaded from this page: http://coref
onts.sourceforge.net/
2. Copy the font file into a temporary folder, for example a folder on your desktop.
3. Choose the cog icon , then choose General Configuration then choose PDF Export Language
Support.
4. Upload the file you copied in step 2.
5. Choose Install.
Notes
The only font files supported are true type fonts and true type collections. The accepted file
extensions are *.ttf and *.ttc.
Confluence can only store one font file at any one time. Please create a collection to install more than
one *.ttf files.
We recommend that you use Unicode font Verdana for correct character encoding and exporting to
PDF.
For symbols, if the other fonts do not work, try Seguisym
If the font file size is bigger than your current attachment size limit, you will not be able to upload it.
Please increase the attachment size limit temporarily and re-upload again. An improvement of the
error messaging is tracked at CONFSERVER-24706 CLOSED
To make use of an installed font in your PDF Export style sheet (CSS) refer to it by the font-family
ConfluenceInstalledFont.
Pages and blogs
Pages and blog posts allow you to capture and share information in
Related pages:
Confluence.
Create and Edit
Whether it's taking down some quick notes from a meeting, writing a require Pages
ments page, or letting your teammates know about the company's latest Blog Posts
marketing push – you can create it as a Confluence page or blog post. The Editor
Page Templates
Pages are great for when you want the information to last and evolve over Delete or Restore
time. If it's a point-in-time update or one-time communication then a blog a Page
post is the way to go. These aren't hard-and-fast rules; they're just pointers Spaces
to give you a place to start.
Each Confluence space, including your personal space, allows you to

create pages in it, and has its own blog where you can create posts. If
you're not sure what a space is, or what you can do with spaces, check out
our page on Spaces.
Take a look at the below pages to learn more about pages and blog posts in Confluence.
Create and Edit Pages

Blog Posts
The Editor
Move and Reorder Pages
Copy a Page
Delete or Restore a Page
Add, Remove and Search for Labels
Drafts
Page Restrictions
Links
Anchors
Tables
Add, Assign, and View Tasks
Autocomplete for links, files, macros and mentions
Page Layouts, Columns and Sections
Create Beautiful and Dynamic Pages
Page Templates
Blueprints
Import Content Into Confluence
Undefined Page Links
View Page Information
Page History and Page Comparison Views
Confluence Markup
Create and Edit Pages
Create a page On this page:
You can create a page from anywhere in Confluence; just choose Create in
the header and you're ready to go. Pages are the place to capture all your Create a page
important (and unimportant) information; start with a blank page and add Edit together
rich text, tasks, images, macros and links, or use one of the useful blueprints Collaborate or
to capture meeting notes, decisions, and more. restrict
Organize and move
Other page actions
Notes
If you want to quickly create a blank page, hit the Create button in the header; if you want to create
a page from a template, hit the Create from template button.
1. Create blank page

2. Create from template
1. Select space: choose the space where you'll create the content.
2. Page templates: create a page from a template or create other types of content.
3. Parent page: your page will be a child of this page.
Once you decide on a blank page or blueprint, you'll be taken straight into the Confluence editor. The editor
is where you'll name or rename your page, add the content, and format it to look great. When you've added
some content, choose > Preview to take a peek at what your finished page will look like, and Publish when
you're ready to make it appear in the space.
After you save you'll see the page in 'view' mode. You can re-enter the editor any time by choosing Edit or
pressing E on your keyboard.
1. Confluence header: create blank pages, pages from templates and visit spaces or your profile.
2. Space sidebar: access pages, blogs and administer the space.
3. Page tools: edit or share the page, watch it to get updates and perform more actions.
Another useful way to create a page is to use the Create from Template Macro. This macro allows
you to choose a page template, and adds a button to the page allowing one-click page creation. If
you want others to create pages using this template, this is a great option.
Edit together
Need input from your team members? Multiple people can edit your page at the same time.
Hit the Invite button in the editor and either grab the link, or enter some people or groups to invite by email (t
hey need the appropriate Confluence and space permissions of course).
See Collaborative editing for all the ins and outs.
Collaborate or restrict
Once you've created a page, you can decide if you want to keep it private, using restrictions, or collaborate
on it with others using @mentions, sharing, and comments.
Organize and move

You can also organize pages in a hierarchy, with child and/or parent pages for closely related content. When
you navigate to a Confluence page and choose the Create button in the header, the page you're creating will
by default be a child of the page you're viewing. Have as many child pages and levels in the hierarchy as
you need to, and move pages if you want to change their location.
If you want to view all pages in a Confluence space, choose Pages in the sidebar.
Each time you create a page, you're creating it in a space . Spaces are containers used to contain
pages with related content, so you can set them up for each team in your organization, for projects,
a combination of both, or for any reason you want to group pages together. See Spaces for more
information.
Other page actions
Copy a page and its child pages

Delete a page or remove a specific version of a page
Monitor page updates and other activity through page notifications
View page history, and manage and compare versions of a page
Search page content, including attachments
Export pages to Word, PDF, HTML or XML
Like a page
We recommend you don't use special characters in page or attachment names, as the page or
attachment may not be found by Confluence search, and may cause some Confluence functions to behave
unexpectedly.
If you rename a page, Confluence will automatically update all relative links to the page, except in
some macros . Links from external sites will be broken, unless they use the permanent URL. See Lin
ks for more information.
Notes
You may experience problems saving extremely large pages. Confluence can accept approximately 5mb of
content (not including attached files) which is roughly equivalent to 800,000 words. If you do experience
errors that indicate the page is too large to save, you should break up the page into several smaller pages.
Blog Posts
Blog posts are an easy way to share announcements, journal entries, status
On this page:
reports, or any other timely information. Others can join in by commenting on
and/or liking your blog post and, if you get enough of either, your post Create a blog post
might make it to the popular feed on the dashboard! Move a blog post
Restrict a blog post
Each space in Confluence, including your personal space, has it's own blog. Delete a blog post
To view a space's blog, go to a space and choose Blog in the sidebar. You'll Export a blog post
see a list of the latest blog posts, and you can click through to earlier posts
via the navigation area in the sidebar. Related pages:
Subscribe to RSS
Create a blog post Feeds within
Confluence
You can follow the same process to create a blog post as when you create
Blog Posts Macro
a Confluence page.
Collaboration
Export Content to
1. Navigate to the space where you want to create your blog post
Word, PDF, HTML
2. Choose Create in the Confluence header and select Blog post
and XML
3. Add your content and choose Publish
You can create blog posts from the Dashboard, but you'll need to make
sure you choose the space it's going to appear in in the create dialog.
Blog posts can be attractive and engaging in the same way a page can be, so go ahead and add images,
YouTube clips (preferably of cats), and tables to your post to really grab your audience.
To create a blog post, you need the 'Add Blog' permission. See Space Permissions.
Move a blog post

If you create a blog post in the wrong space, or want to reorganize your spaces, you can move an individual
blog post to another space.
To move a blog post, go to the post and choose > Move and select the new destination space.
You'll need the 'Delete blog' permission in the current space, and 'Add blog' permission in the new
(destination) space to do this.
Restrict a blog post

You can restrict a blog post so that it is only available to specific users or groups. Blog post restrictions work
in the same way as page restrictions.
To restrict a blog post prior to publishing it, choose the Unrestricted button in the footer and apply your
restrictions. To restrict a blog post after publishing, choose > Restrictions and apply your restrictions.
Notes:
Notifications are sent at the point a blog post is created - removing restrictions does not trigger a new
notification.
As a blog post has no parent, restrictions aren't inherited.
Delete a blog post

To delete a blog post, choose > Delete. Deleting a blog post follows the same rules as deleting a page.
Export a blog post

You can export individual blog posts to PDF. This is useful, for example, if you want to email an internal blog
post to people outside your organization.
See Export Content to Word, PDF, HTML and XML for more information on exporting blog pages to PDF.
The Editor
The Confluence editor is what you'll use to create and edit Confluence
On this page:
pages, blog posts, and comments. You can enter content as you would in a
Word document, apply formatting, and embed other content and files on the
page. Edit a page or blog
post
Note: To edit a page, you need the 'Add Pages' permission for the space. The editor
See space permissions. Someone may also apply page restrictions that Editor toolbar
prevent you from editing the page. Restrictions,
labels, and
Edit a page or blog post notifications
Things to help you
You'll be taken to the editor whenever you create a new page or blog post, work faster
or add a comment. To edit an existing page or blog post, choose Edit at the Find and replace
top of a page or press E on your keyboard. text
Invite people to
Confluence automatically saves changes as you type. Changes are only edit with you
visible when viewing the page after you publish or update. See Collaborative Record change
editing for more information on how this works. comments and
notify watchers
Related pages:
Tables
Page Layouts,
Columns and
Sections
Display Files and
Images
Links
Symbols,
Emoticons and
Special Characters
The editor
The editor allows you to enter or change the title of your page; insert content including text, images, and
links; and format your content using the toolbar.
If you're renaming your page, there are some things you should take into account.
1. Page content: add your page title and body text.

2. Page tools: add labels or restrict the page.
3. Insert: add files, links, images, tables and macros
4. Notify: notify others and leave a comment when you change a page.
5. Preview or revert: preview your page, view changes since last published, or revert back to last
published version (or delete the draft page, if it has never been published).
Editor toolbar
The editor toolbar is where you format your page layout and text, and add links, tables, images, attachments
and macros. You can also perform a find and replace, or get help using the editor by choosing the help icon
.
The Insert menu

The Insert menu is particularly useful. Use the Insert menu to include any of the following content types on
your page:
An image
A link to another Confluence page or external URL, or a link to an attachment or image
An emoticon or symbol, or a horizontal line
A macro (choose a specific macro, or Other Macros, from the Insert menu)
You can also use keyboard shortcuts to insert links, images, and macros. Try out the shortcuts listed below:
Type [ (square bracket) to insert a link.

Type ! (exclamation mark) to insert an image or other media.
Type { (curly bracket) to insert a macro.
Typing any of the above shortcuts will trigger the autocomplete functionality, prompting you with a list of
suggestions to finish off the entry. For more shortcuts, click the help icon on the editor toolbar.
Restrictions, labels, and notifications

When editing a page, you may want to set restrictions on who can view or edit the page, or add labels to the
page to make it easily searchable.
Once you're ready to save, you can enter change comments to let others know what you've changed, and, if
you like, send an email notification to anyone watching the page.
Things to help you work faster
Auto-formatting
You can type Confluence wiki markup directly into the editor to have Confluence auto-format your text as
you type. To learn more, choose help icon in the toolbar, then choose Editor Autoformatting.
Autoconvert for pasted links
When you paste certain URLs into Confluence, the editor will analyze what you're pasting and automatically
convert it into something that will display well in Confluence. Examples include:
YouTube videos
Jira issue queries
Google Maps
Confluence pages, blog posts, comments, user statuses, user profiles.
Shared screenshot links from Skitch
And more.
Drag-and-drop for external images and files
You can drag files, like images, multimedia, Office files and PDFs, from your computer and drop them
directly into the editor. The contents of the file will be embedded into the page or blog post.
Drag-and-drop within the editor
In the editor panel, you can drag an image or a macro from one location to another on the page. Hover your
cursor over the image or the macro placeholder and your cursor changes to a drag-and-drop icon. Click the
image or macro and drag it to a new location.
Keyboard shortcuts
To view the available keyboard shortcuts, choose the help icon in the editor toolbar.
Find and replace text
Click the icon on the toolbar, or use the keyboard shortcut Ctrl+F (Windows) or Cmd+F (Mac OS).
Search matches are highlighted in yellow. You can step through the results one by one, replace the
matching text strings one by one, or replace all matching strings at once. Find and replace works only within
the current page.
Invite people to edit with you

Speed up your draft and review cycles and get input from the right people by inviting them to edit the page
with you. The page does not need to be published.
Hit the button in the editor and either grab the link, or add people, groups or email addresses to invite,
just like sharing a page.
Sharing or inviting someone to edit a page or blog post does not automatically grant any permissions - they
will still need the appropriate Confluence permissions to access Confluence and view or edit the page.
Up to 12 people can edit the same page at the same time (your administrator can change this limit).
Record change comments and notify watchers

When you finish editing a page, you can add a comment to let others know what you changed. Type a short
message in the change comments field in the footer. The comment will be visible in the page history.
If you want to send a notification to people watching the page, select Notify watchers. The change
comment will be included in the notification email.
The Notify watchers checkbox remembers your last selection for each page, so if you choose not to notify
people, the checkbox will be deselected for you next time you edit that page.
Symbols, Emoticons and Special Characters
You can add various symbols and special characters to Confluence pages.
On this page:
You can also use them in other places that display content, such as blog
posts, comments, and the dashboard welcome message.
Insert symbols and
special characters
Insert symbols and special characters Insert emoticons
Prevent emoticons
1. Edit the page (if you're viewing the page, press E on your keyboard) from appearing
2. Choose Insert > Symbol
3. Choose a symbol to insert it Related pages:
The Editor
Insert emoticons
There are two ways to add an emoticon, or smiley, to your page.
By choosing an emoticon from those available:
1. Choose Insert > Emoticon

2. Choose an emoticon to insert it
By typing a character combination:
You can also type the following characters to insert emoticons. This can be useful when the Insert menu is
not available, for example in an inline comment.
Prevent emoticons from appearing

To undo the conversion of a character combination into an emoticon, press Ctrl+Z (Windows) or Cmd+Z
(Mac).
To prevent Confluence from converting text to emoticons automatically, disable 'Autoformatting' in your user
profile. See Edit Your User Settings.
Collaborative editing
Collaborative editing takes teamwork to the
On this page:
next level by letting you and your team work
together in real time on software requirements,
meeting notes, retros, and any other Confluence Drafts and unpublished changes
page. See who's editing the page with you, and see Things you should know
changes as they happen. Hit to invite more
people to edit with you.
Changes save and sync automatically, so everyone

editing sees the same thing. And, because we're
saving all the time, there's no need to manually
save. Publish now or keep the draft and publish it
later—you're in control.
Up to 12 people can edit the same page at the

same time. Your administrator can change this limit
using a system property.
Once you and your team are done editing you can:
publish (or update if the page has previously been published) to make everyone's changes visible
close the editor and keep everyone's work to finish later
revert to the published version of the page, discarding everyone's unpublished changes
delete the draft page entirely, if it has never been published.
We'll warn you if you're about to publish (or discard) other peoples' changes along with your own.
1. Invite more people: see who is editing the page and invite others to edit with you.
2. See what they're doing: watch others edit the page in real time.
Drafts and unpublished changes
What is a draft?
A draft is a page that has never been published before. Draft pages have a lozenge that says draft, and are
only visible to their author, and to anyone that author shares their draft with. Nobody else will be able to see
your draft, as it is only accessible from the Recently worked on list of each of the people who've contributed
to it.
What are unpublished changes?

A page with unpublished changes is a page that has been published, and has then had edits made to it,
but which has not yet been republished. Anyone who has unpublished edits will see the page in their Recentl
y worked on list, with a lozenge saying unpublished changes. People who haven't contributed to the
unpublished changes won't see this lozenge.
Those unpublished changes, however, are visible in the editor, and anyone can access them by editing that
page. Therefore, if you have unpublished changes and do not want someone else making additional
changes before they can be published, you might want to temporarily restrict editing on that page (leaving
the published version of the page visible).
Things you should know
Limited content auditing
We don’t yet have the same auditing capabilities with collaborative editing. All page changes are currently
attributed to the person that publishes the page, rather than the person who made each specific change.
Changes in drafts aren't versioned
We’re saving all the time in collaborative editing, but we don’t save versions in a draft. When restoring an
earlier page version, you can only roll back to published versions (the page draft is deleted when you restore
a previous version)
No more personal drafts
Collaborative editing introduces a new type of draft, a shared draft. Previously, when you edited a page but
didn't save it, Confluence would create a draft that was only visible to you (a personal draft). Now,
Confluence creates a shared draft whenever anyone edits a page. All page editors work on this same shared
draft, and it exists until someone publishes the page.
When you publish a shared draft, you're publishing all the changes you have made and changes made by
others. Publishing creates a version in the page history.
If you discard a shared draft, you're discarding all changes, including changes made by others. Because
shared drafts aren't versioned, there's no way to get a discarded draft back.
Any existing personal drafts are still available, but are no longer editable. If you edit a page, you'll see the
shared draft of the page, not your personal draft (if one exists).
If you need to get content out of your previous personal drafts head to Profile > Drafts, locate your page
and copy the contents.
Move and Reorder Pages
The easiest way to set a page's location in Confluence is to navigate to the
On this page:
space where you want the page to live and, if necessary, find its parent
page and choose Create. Sometimes though, you'll want to change a
page's location either while you're creating it, or after it's been created. Set page location
or move a page
You can also move and reorder pages in the page tree (hierarchy). Reorder pages
within a space
Notes about
Set page location or move a page permissions
1. Do either of the following: Related pages:

While creating a page – choose the location icon at the Create and Edit
top of the page Pages
Once a page is created – choose > Move Copy a Page
2. Use the tabs on the left of the 'Set Page Location' dialog to help you Delete or Restore
find the new space and/or parent page for your page (the Current a Page
location and New location breadcrumbs at the bottom of the dialog
indicate the current parent page and new parent page)
3. Select Reorder if you want to move the page to a different position
amongst the child pages (when you choose Move in the next step,
you'll be able to reorder the page)
4. Choose Move (If you're reordering the child pages, choose the new
position for the page and choose Reorder)
The page – along with any attachments, comments, and child pages – is moved to your chosen location.
Confluence will automatically adjust all links to the moved pages, to point to the page(s) in its new location.
When completing the New parent page field, you need to select the page suggested by
Confluence's autocomplete. Typing or pasting the page name (or using your browser's
autocomplete) won't work.
Screenshot: Setting the location or moving a page
Reorder pages within a space

You can change the location of a page within its space, and reorder pages in the hierarchy. This allows you
to:
Move a single page, or a family of pages, to a different parent within the space.
Reorder pages that are children of the same parent.
All links to the page are maintained. When you move a parent page, the entire hierarchy of child pages will
move too.
To move or reorder a page:
1. Go to the space and choose Space tools > Reorder pages from the bottom of the sidebar
2. Expand the branches to locate the page you want to move.
3. Drag the page to a new position in the tree.
Alternatively, you can choose to order a group of child pages alphabetically by choosing the Sort
Alphabetically (A-Z) icon. The Sort Alphabetically (A-Z) icon only appears next to the parent page if the
page family is currently sorted manually.
If you change your mind, you can use the Undo Sorting icon to revert back to the previous manual page
order. This option is only available immediately after sorting the page, while you're still on the Reorder
Pages tab, and haven't performed any other action.
1. Alphabetical: sort all child pages alphabetically.

2. Undo: undo sorting.
Notes about permissions

To move a page, you need the following permissions:
'Add' permission on the page you're moving, and

'View' permission on the page's parent page. If you're moving the page to a different parent, you need
'View' permission on the new parent.
To move a page into a different space, you also need:
'Delete' permission on the space you're moving from, and

'Add' permission on the space you're moving to.
If the page has restrictions, and you want to keep the page restrictions in the new location, you'll also need
'Restrict' permission on the space you're moving to. Alternatively, remove the page restrictions before
performing the move.
Copy a Page
If you need to duplicate the contents of a page, the easiest way is to copy
On this page:
the page. You can copy pages into the same space or to a different space.
When you copy pages into the same space, you'll need to rename them, as Copy pages
two pages with the same name can't live in the same space. We give you Copy the contents
some handy tools to help rename your pages during the copy process. of an entire space
You need the 'Create Page' permission to copy pages. See space
permissions for more information.
Related pages:
Create and Edit
Pages
Move and Reorder
Pages
Copy pages
Single page
To copy a single page:
1. Go to the page and choose > Copy.

2. Choose a Location for the new page.
3. Choose whether to include attached files and images.
4. Hit Copy.
Confluence will open the copy of the page in the editor and name it 'Copy of [original page title]'. You can
then rename the page and work in the editor like any ordinary page.
Any restrictions are not copied over. If the page contains private information, click the padlock icon in the
editor to apply restrictions before you publish.
Page hierarchy
To copy a page and all its child pages:
1. Go to the page and choose > Copy.

2. Choose a Location for the new pages.
3. Select Include child pages.
4. Use the options provided to customize your new page titles.

You can add a prefix, replace a keyword or phrase in existing titles, or both. The preview will give you
a good idea of what your new page hierarchy will look like, and warn you if there are any problems.
5. Deselect any items you do not want to copy over (attached files, labels, restrictions)
6. Hit Copy.
You'll find a link to your newly copied pages in the copy complete message.
Note: It's not possible to selectively copy multiple pages. You will be copying the entire hierarchy.
What's included when you copy a page?
Here's some more info on what's included when you copy a page.
Single Page and its child pages

page
Page contents (text, Yes Yes

macros)
Attached files and Optional - if you choose not to include attachments, you may see 'unknown-
images attachment' errors on the copied pages.
Comments No No
Labels Yes Optional
Restrictions No Optional - you may not be able to change this option if you don't have
appropriate 'Restrict' space permissions.
Watchers No No
Saved for later info No No
History No No
Child pages with - Yes - if you have permission to see the child pages.
view restrictions
No - if you do not have permission to see the child pages.
Space permissions and page restrictions
Your space permissions and any existing page restrictions have an impact on what you can copy:
To copy pages you need the 'Create' page permission in the destination space.
To copy pages with restrictions intact, you need the 'Restrict' page permission in the destination
space.
When copying a page and its child pages, you also have a choice to copy over any existing page
restrictions. This is useful if you need to maintain the current view or edit restrictions. If you don't have
'Restrict' page permission in the destination space, you won't be able to choose this option.
Limitations
You can copy hierarchies containing up to 2000 pages. Administrators can increase or decrease this limit by
setting the confluence.cph.max.entries system property.
Copy the contents of an entire space

Confluence does not provide an option to copy a space, however if your space has less than 1000 pages,
you can use copy page to copy all the pages in an existing space to a new space.
To copy the contents of a space to a new space:
1. Create a new space.

2. Go the homepage of the space you want to copy, and choose > Copy.
3. Set your new space as the Location.
4. Select Copy child pages then hit Copy.
5. In the new space, go to Space Tools > Reorder pages and drag your copied homepage to the root
of the space (so it is no longer a child of the current space homepage).
6. Go to Space tools > Overview > Edit space details.
7. Enter the copied space homepage title in the Home page field and Save.
That's it. You can now delete the homepage that was automatically added when you created the space.
Note that this is a new space, and no space settings (permissions, color schemes, templates etc) will be
copied. See these instructions on copying a space for some other workarounds.
Delete or Restore a Page
When you delete a Confluence page, we'll move it to the space's trash. It's
On this page:
not permanently deleted, and can be restored by a space admin, until the
page is permanently deleted from the trash. Delete a single
page
Don't see a delete option? Delete only appears if you are allowed to Delete a page
delete the page. Both space permissions and page restrictions can prevent hierarchy
you from deleting. Delete an
unpublished page
Delete a single page Delete a page
version
When you delete a page in Confluence, you're deleting its page history too. Restore deleted
If you only want to delete a specific version of a page, take a look at the pages
instructions below for deleting a specific version. Empty the trash
or permanently
To delete a page: delete a page
1. Go to the page and choose > Delete. Related pages:

2. We'll warn you of any issues, such as incoming links that will
Cannot edit page:
break. Choose Delete to proceed.
Editing or Deleting
a Page That Won't
The page will be sent to the trash, where it can be restored by a space
Render
admin.
Copy a Page
Any child pages (including any restricted pages that you are not allowed to
see) will move up to the nearest parent page.
Delete a page hierarchy
Only users with Delete Page permission in a space can delete hierarchies.
When deleting a page that has child pages you have the option to delete the entire page hierarchy.
To delete a page hierarchy:
1. Navigate to the parent page and choose > Delete.

2. Choose Also delete child pages then hit Next.
3. We'll warn you of any issues, such as incoming links that will break. Choose Delete to proceed.
The pages will be sent to the trash, where they can be restored by a space admin.
Any pages that are restricted (that you are not allowed to see or delete) will not be deleted and will move up
to the nearest parent page.
Users who only have Delete Own permission can’t delete hierarchies, even if they created all of the pages in
the hierarchy.
Delete an unpublished page

To delete a page that has never been published (a draft), in the editor go to > Delete unpublished page.
Deleted drafts are not sent to the trash, so cannot be restored. If other people have contributed to the draft,
you will be deleting their work as well as your own.
Delete a page version

Space admins can delete specific versions from the page history. This is useful if you need to prevent older
versions of a page being restored in future. Deleting a page version is permanent and cannot be undone.
To delete a specific version of a page:
1.
1. Go to the page and choose > Page History

2. Choose Delete next to the version you want to delete.
Once you've deleted a version, the other versions are re-numbered where necessary.
Restore deleted pages

If you're a space admin you can restore deleted pages back into a space. This is useful if someone
accidentally deletes a page and needs to get it back.
To restore a deleted page:
2. Choose Trash.
3. Choose > Restore next to the page you wish to restore.
Pages are restored to the root of the space. Head to Space Tools > Reorder Pages to drag your restored
page back into the page hierarchy.
Empty the trash or permanently delete a page

If you're a space admin you can permanently delete a page (and all its attached files) by purging it from the
trash. Once purged, the page and all its versions and attached files will be gone for good.
To purge deleted pages:
2. Choose Trash.
3. Choose > Purge next to a specific page or you can Purge all to completely empty the trash.
Add, Remove and Search for Labels
Labels are key words or tags that you can add to pages, blog posts and
On this page:
attachments. You can define your own labels and use them to categorize,
identify or bookmark content in Confluence.
Label a page or
For example, you could assign the label 'accounting' to all accounts-related blog post
pages on your site. You can then browse all pages with that label in a single Label an
space or across the site, display a list of pages with that label, or search attachment
based on the label. The Labeled
content page
Because labels are user-defined, you can add any word that helps you Search by label
identify the content in your site. Search for labeled
pages using a URL
You can also apply labels (known as categories) to spaces, to help organize Remove labels
your Confluence spaces. See Use Labels to Categorize Spaces.
Related pages:
Label a page or blog post
Use Labels to
Categorize Spaces
Any user with permission to edit a page can add labels to it. Any existing
Display Pages with
labels appear at the bottom-right of the page, below the page content.
Label Macros
To add a label to a page or blog post:
1. At the bottom of the page, choose Edit labels or hit L on your keyboard
2. Type in a new label (existing labels are suggested as you type)
3. Choose Add
If you're editing or creating a page, and you want to add labels, choose the Edit label icon at the
top of the page.
Labels can't contain spaces, and are lower case. You can add multiple labels by adding a space between
each label, any capitals will be automatically converted to lower case. If you want a label to include more
than one word, use an underscore or hyphen (the only two special characters that labels accept). For
example this_is_a_label or this-is-a-label.
Label an attachment
1. Do either of the following:
Go to the page that contains the attachment and choose Go to > Attachments
Go to the space and choose Space tools > Content Tools from the bottom of the sidebar,
then choose Attachments
You'll see a list of attachments, with any existing labels listed in the Labels column.
2. Choose the Edit label icon beside the list of labels and type in a new label (existing labels are
suggested as you type)
3. Choose Add
You can also add labels in a list of attachments displayed by the Attachments macro, by choosing the edit
icon beside each label.
If you add one or more labels to a template, that label will be copied to the page when someone adds a
page based on that template. See Creating a Template.
The Labeled content page
If you're viewing a page or post that has labels or displays the Attachments macro, you can choose any label
to go to the Labeled content page for the space. Choose Popular Labels or All Labels from the cog at the
top-right – to view the most-used labels or all labels in the space – or choose See content from all spaces
from the cog to view labeled content from all spaces in your Confluence site.
Screenshot: The Labeled content page
The Popular Labels option displays a word cloud, where the bigger a label is displayed, the more popular it
is. Choose any label to view content tagged with that label.
You can also navigate to the labels view for a space by entering the following URL (replace SPACEKEY with
the space's key):
<your.Confluence.site>/labels/listlabels-alphaview.action?key=SPACEKEY
Search by label
You can use the ' labelText: ' prefix to search specifically for content that has a specific label. For
example, if you're looking for pages with the label 'chocolate', type labelText:chocolate into the search
field in the Confluence header. For more examples of searching by label, see Confluence Search Syntax.
Search for labeled pages using a URL

Entering a URL with an appended label or labels is another way to search for pages with particular labels.
In your browser's address bar, enter the following URL and press enter: http://<your.Confluence.
site>/label/foo+bar
The Labeled content page will load, showing search results for pages with the both labels, 'foo' and 'bar'.
Replace 'foo' and 'bar' with the label(s) you want to search for, and separate multiple labels with a + symbol.
Adding a label to your results:
Once you're on the Labeled content page, you can add more labels to your search by choosing them from
the Related Labels list at the top-right of the page. Each label is listed with a plus (+) sign.
If you want to remove labels from your search, locate the included labels at the top of the page and choose
the label(s) you want to remove. Each included label will be listed with a minus (–) sign.
Remove labels
When viewing page, blog post, or attachment labels, an x appears alongside each label. Choose the x to
remove the label.
You can't remove, consolidate or manage labels directly. A label is created by adding it to a page for
the first time, and ceases to exist once its been removed from all pages it was added to.
If you have deleted pages that contain a label, you may need to purge the deleted pages from the
space's trash to ensure that the label disappears too.
Display Pages with Label Macros
Using labels and macros, you can categorize pages and then display them
Related pages:
in Confluence in a number of ways.
Add, Remove and
As an example, you could label all pages relevant to the marketing team Search for Labels
with 'marketing', and then add more specific labels like 'online', 'mobile', and Macros
'physical' to different pages where required. Use Labels to
Categorize Spaces
You could then use the Content by Label Macro to display different
combinations of pages with the marketing label. Some combinations you
could use would be:
All pages with the label 'marketing'.

Pages with all of the following labels: 'marketing', 'mobile', and
'online'.
Pages with either the 'mobile' or 'online' labels, in the Marketing
space.
There are a lot of ways you can filter the content, making it easier for you to find content that's relevant to
you.
Other label macros

Here are some other macros that use labels, and can help you categorize and display your content.
Navigation Map macro
The Navigation Map macro renders the list of pages associated with a specified label as a navigation map.
Related Labels macro
The Related Labels macro lists labels commonly associated with the current page's labels.
Content by Label macro
The Content by Label macro displays a list of content marked with specified labels.
Content Report Table macro
The Content Report Table macro displays a set of pages and blog posts in tabular format, based on the
specified labels.
Labels List macro
The Labels List macro lists all labels of a space, grouped alphabetically.
Recently Used Labels macro
The Recently Used Labels macro lists labels most recently used in a specified scope - global (site), space,
or personal.
Popular Labels macro
The Popular Labels macro displays popular labels in a list or in a heatmap (also called a cloud).
Drafts
A draft is a page you've never published. Unpublish
On this page:
ed changes are edits that you've made to a
published page, without republishing them.
Find drafts and unpublished changes
Confluence autosaves your drafts and unpublished Resume editing a draft
changes as you work, so if you get interrupted and Resume editing a page with unpublished
close your tab or navigate away, your content lives changes
on for you to resume editing when you're ready. Discarding unpublished changes
Delete a draft
If you're creating or editing, but don't want to publish Personal drafts
your changes yet, hit Close at the bottom-right of
the editor. This will save those changes in the editor
without publishing, and you can return to them at
any point. Closing the editor will land you back on
the published version of the page, or, if you're
working on a draft, on your Recently worked on
list.
Find drafts and unpublished changes
Drafts and pages with unpublished changes appear in Recently worked on in the dashboard. You can
easily differentiate between these as they'll have a 'draft' or 'unpublished changes' lozenge next to their
titles. The 'unpublished changes' lozenge is only visible to people who have contributed to the draft or
unpublished changes, so you don't have to worry about it distracting your viewers.
Resume editing a draft

You can find your drafts under Recently worked on or by heading to your profile and clicking on Drafts
(only drafts that you created show in your profile). Clicking on a draft will drop you straight into the editor so
you can keep editing and/or publish.
If you didn't enter a page title, the draft will be called 'Untitled'.
Resume editing a page with unpublished changes

If you've been editing a page that's already been published, you can find the page again either through the
page tree or under your Recently worked on. The 'Unpublished changes' lozenge makes them easy to
spot.
Edit the page to see the unpublished changes and keep editing, then, when you're ready, hit Publish.
Discarding unpublished changes

If you make changes to a published page, then change your mind, you can discard all changes by reverting
to the last published version of the page. This will discard all unpublished changes made by you and any
others who have edited the page since the last time it was published.
Before you revert to the last published version you should:
Check who else has edited the page since last publish - their avatars will be shown at the top of the
editor.
In the editor, go to > View changes to see all changes that have been made since last publish.
The changes won't be attributed to individual users.
Once you've checked to make sure you aren't going to inadvertently discard someone else's changes, go to
> Revert to last published version to discard all changes.
Delete a draft
To delete a draft go to > Delete unpublished page.
Because drafts have never been published, you'll be deleting the entire page or blog post. Discarded drafts
are not sent to the trash.
Drafts in Confluence are shared, meaning other people can work on them with you. If you delete a
draft that other people have worked on, you're deleting their changes too.
Personal drafts
When collaborative editing is turned off, drafts work a little differently. Instead of a shared draft, you have a
personal draft of a page. See Concurrent Editing and Merging Changes for more information.
You may see some old personal drafts in the Drafts page in your profile. These were created when
collaborative editing was turned off.
Concurrent Editing and Merging Changes
This page covers the concurrent editing behavior in Confluence 6.0 Related pages:
or later when your administrator has chosen to disable collaborative
Page History and
editing.
Page Comparison
Views
In most cases, this won't apply to your Confluence site.
Drafts
Sometimes, another user may edit the same page as you're editing, at the
same time you do. When this happens, Confluence will do its best to ensure
nobody's changes are lost.
How will I know if someone else is editing the same page as I am?
If another user is editing the same page as you, Confluence will display a
message above your edit screen letting you know who the other user is and
when the last edit was made.
Screenshot: Concurrent editing notification
What happens if two of us are editing the same page and the other user saves before I do?
If someone else has saved the page before you, when you click Save, Confluence will check if there are any
conflicts between your changes and theirs. If there are no conflicting changes, Confluence will merge the
changes.
If there are conflicts, Confluence will display them for you and give you the option to:
Continue editing - Continue to edit the page; useful if you want to manually merge the changes.
Overwrite - Replace the other person's edits with yours (their edits will not be included in the latest
version).
Cancel - Discard your changes and exit the editor, keeping the other person's edits.
Example Scenario
For example, Alice and Bob both edit the same page at the same time.
If Alice clicks save before Bob, Bob is now effectively editing an out-of-date version of the page. When Bob
clicks save, Confluence will examine his changes to see if any overlap with Alice's. If the changes don't
overlap (i.e. Alice and Bob edited different parts of the page), Bob's changes will be merged with Alice's
automatically.
If Bob's changes overlap with Alice's, Confluence will display an error message to Bob showing where Alice
has changed the page, and giving Bob the options to overwrite Alice's changes with his own, to re-edit the
document to incorporate Alice's work, or to cancel his own changes entirely, maintaining Alice's changes.
Page Restrictions
Page restrictions allow you to control who can view
and/or edit individual pages in a space. So, if you're On this page:
working on a page that shouldn't be viewed by just
anybody, it's easy to lock it down to the people who
Restrict a page or blog post
need to know. You can add restrictions for
Remove restrictions from a page
individuals or for Confluence groups.
Copy a restricted page
Get access to a restricted page
To add or remove page restrictions, you'll need to
View all restricted pages in a space
have permissions to edit the page and 'Restrict' or
Notes
'Admin' permission in the space.
Restrict a page or blog post

To restrict who can view or edit a page or blog post:
1. Choose the Restrictions icon at the top of the page.

2. Choose whether you just want to limit only who can Edit, or who can View and / or Edit.
3. Enter users or groups then click Add to add them to the list.
If you chose Viewing and Editing restricted you can further specify for each person or group
whether they can edit or just view the page.
4. Apply the restrictions.
You can add as many users and/or groups as you need. You can apply page restrictions to published and
unpublished (draft) pages.
In this example, some users and groups can view only, others can also edit, plus there are inherited
restrictions that might impact who can view the page.
1. Speed it up: apply the same restriction to multiple people and groups.
2. Watch out: restrictions on other pages can affect this one.
3. Be specific: choose exactly what each group or person can do.
Who is 'everyone'?
When we say "everyone can view this page" everyone means all the people who can view the page by
default. There are two things that can affect who can view a page - the space permissions, and view
restrictions on any parent pages that are being inherited.
Restrictions don't override a person's space permission. For example, if you say a person 'can view' in the
restrictions dialog and they don't have 'view' permissions for the space, they won't be able to see the page.
How do inherited restrictions work?
View restrictions are inherited, which means a restriction applied to one page will cascade down to any child
pages. Edit restrictions are not inherited, which means pages need to be restricted individually.
The restrictions dialog will tell you when there are inherited restrictions that might affect who can view your
page.
Here's the basics:
If you restrict viewing to a person or group, only they will be able to see that page and all its child
pages (unless there are further restrictions on the child pages).
If you restrict editing to a person or group, they'll be able to see and edit that page, plus see its child
pages.
Parent pages (higher up in the page hierarchy) can have their own view restrictions that may prevent
people from viewing your page.
If the person you've listed as a viewer or editor can't see the page, check to make sure:
they have View space permission for that space, or

there's no view restriction on a page higher up the page hierarchy that prevents them seeing any
children of that page.
View current page restrictions
The restrictions icon at the top of the page gives you a clue that the page has restrictions:
Viewing this page is not restricted. Everyone can see this page (but editing may be restricted).
The page is restricted. Click the icon to see the list of who can view and edit this page.
The page is inheriting restrictions from another page. Click the icon then choose Inherited
Restrictions to see a list of pages this page is inheriting restrictions from.
Remove restrictions from a page

Removing restrictions is easy. Choose No restrictions to remove all restrictions, or click Remove next to
each person or group in the list if you want to change who can view or edit the page.
Copy a restricted page

When you copy a single page, we don't automatically copy the restrictions. If the page contains information
that should be private, remember to reapply restrictions in the editor before you publish, to avoid notifying
people who are watching the space.
When you copy a page and all its child pages, you have the option to copy all restrictions, or skip copying
restrictions on all pages. See Copy a Page for more information.
Get access to a restricted page

If you navigate to a page that you're not able to view or edit because it has page restrictions applied (for
example from a link, an invite, or page URL) you may be able to request access to the page.
If the request access message above doesn't appear, you're not able to request access for that particular
page. This usually is because the page has inherited view restrictions from a parent page, you don't have
adequate space permissions, or there is no mail server set up.
Request access
To request access to a restricted page:
1. On the restricted page choose Request access.

2. Confluence will send an email to up to 5 people most likely to be able to grant you access.
3. Wait for an email confirming that access has been granted.
Grant access
To grant access to a restricted page:
1. In the request access email, choose Grant access.

You'll be taken to the restricted page, and a dialog will appear with the access request.
2. Choose Grant access.
(We'll let you know if someone else got there before you, and has already granted access)
The user will receive an email confirming that access has been granted.
This process is the same as navigating to > Restrictions and adding a 'View' restriction for the user.
Who can grant access?
When a user requests access to a restricted page, Confluence will send an email to up to 5 people who are
most likely to be able to grant access, in the following order:
1. people who have contributed to the page in the past, can see the page and have 'Restrict' or 'Admin'
space permission (sorted by last edit date)
2. space administrators who can see the page (sorted alphabetically).
This means that the request should be actioned quickly, as it prioritizes the people who have been
interacting with the page most recently. There's no follow up email if none of the 5 people respond, the user
will need to contact a space administrator directly to ask for access.
Disable the ability to request access
If you don't want people to be able to request access to restricted pages, for example if you're using
Confluence for public documentation, you can disable the Confluence Request Access Plugin. See Managin
g System and Marketplace Apps.
View all restricted pages in a space

You need space admin permissions to view the list of restricted pages in a space.
To view restricted pages:
1. Go to the space and choose Space tools > Permissions from the bottom of the sidebar
2. Choose Restricted Pages.
Screenshot: Restricted pages in a space
Notes
You can't exclude yourself
When you apply a restriction, Confluence will automatically add you to the list. You can't remove
yourself from this list.
Space Admin and System Administrator access to restricted pages
Users with 'Admin' permissions in a space, or users with the System Administrator global permission
can remove restrictions from pages, even if the page restriction prevents them from viewing the
page. Go to Space Administration > Restricted Pages.
Links
You can create links to pages, blog posts, anchors, attachments, external
On this page:
websites, Jira issues and more. Links can be text or images, and can be
added in many different ways.
Insert a text link
Links to pages within your Confluence site are relative, which means that Other ways
you can move pages and rename pages without breaking links. to do this
Insert an image link
This page explains the most common ways to create links. Modify a link
Remove a link
Link to specific
types of content
Insert a text link Link to Confluence
pages from other
To insert a link on a page:
websites
Link to a comment
1. Select some text or position your cursor where you want to insert the
Using shortcut
link
Links
2. Choose Link on the toolbar or use the keyboard shortcut Ctrl+K
3. Select a page, blog post or attachment, or enter an external URL
Related pages:
(see below for how to link to particular types of content)
4. Enter or modify the link text (this is the text that will appear on the Anchors
page. If this field is left blank, the page name or URL will be used as Inserting JIRA
the link text.) Issues
5. Choose Insert The Editor
Other ways to do this
There are a few other ways to insert a link:
Type [ followed by the page or attachment name. Autocomplete will

suggest matching items for you, or
Paste a URL directly onto your page. Confluence will automatically
create the link, and if the URL is for a page in the current site, the
page name will be set as the link text.
Confluence doesn't provide an option to configure a link to open in a new

window or tab. Users can choose to right click / CTRL+click the link if they
want to open it in a particular way.
Insert an image link
1. Select an image on your page
2. Choose Link on the Image Properties toolbar
3. Select a page, blog post or attachment, or enter an external URL (see below for how to link to
particular types of content)
4. Choose Insert
Modify a link
1. Select the link text or image
2. Choose Edit from the link properties toolbar
3. Modify the link and choose Save
Remove a link
1. Select the link text or image
2. Choose Unlink from the properties toolbar
Link to specific types of content

Confluence supports many methods for creating links. Some of the common ones are listed here.
Type of link Ways to do this
Link to a page Choose Link > Search then enter part of the page name.
or
Choose Link > Recently viewed and select a page from the list.
or
Type [ and enter part of the page name then select the page from the list.
or
Paste the URL of the page onto your page (Confluence will automatically create the
link).
Link to a page in Choose Link > Search enter part of the page name and select All Spaces from the
another space drop down.
or
Choose Link > Advanced then enter the space key followed by the page name spa
cekey:mypage.
or
Type [ and enter part of the page name then select the page from the list.
(you can hover over each suggestion to see which space the page is from).
Link to a blog post Choose Link > Search and enter part of the blog post name.
or
Type [ and enter part of the blog post name then select the blog post from the list.
Link to an Choose Link > Attachment then upload or select an attachment from the list.
attachment or
image on this page or
Type [ and enter part of the attachment file name then select the attachment from
the list.
Link to an Choose Link > Search and enter part of the attachment name.
attachment on
another page or
Type [ and enter part of the attachment file name then select the attachment from
the list
(you can hover over each suggestion to see which space the page is from).
Link to a website Choose Link > Web Link then enter the website URL.
or
Type or paste the URL onto the page (Confluence will automatically create the link).
Link to an email Choose Link > Web Link then enter the email address.
address
or
Type or paste the email address onto the page (Confluence will automatically
create a 'mailto:' link).
Link to an anchor Choose Link > Advanced then enter the anchor name in one of the formats below.
on a page
For an anchor on this page: #anchor name.
For an anchor on another page in this space: page name#anchor name.
For an Anchor on another page in another space: spacekey:page

name#anchor name.
See Anchors for more information on using anchors.
Link to a heading Choose Link > Advanced then enter the heading in one of the formats below.
on a page Heading text is case sensitive and must be entered without spaces.
For a heading on this page: #MyHeading.
For a heading on another page in this space: Page Name#MyHeading.
For a heading on another page in another space: spacekey:Page

Name#MyHeading.
Be aware that these links will break if you edit the heading text. Consider using the
Table of Contents macro or an Anchor instead.
Link to a comment Go to the comment, right click the Date at the bottom of the comment and copy the
on a page link. Paste the link directly onto your page or choose Link > Web Link and paste in
the URL.
or
Type [$ then enter the Comment ID ('12345' in this example): [$12345]
Link to an Choose Link > Advanced then enter the new page name (a page will be created
undefined page on click).
(a page that does
not exist yet) or
Type [ then enter the new page name then choose Insert link to create page.
See Undefined Page Links for more information on undefined pages.
Link to a personal Choose Link > Search then enter the user's name and select their personal space
space or user homepage or their profile from the list.
profile
or
Type [ then enter the user's name and select their personal space homepage or
their profile from the list.
Link to a Jira issue Paste the Jira issue URL - Confluence will automatically create a Jira Issue macro.
(where Confluence
is connected to
Jira)
Link to Confluence pages from other websites

The best way to link to a Confluence page from outside Confluence, for example from another site or in an
email, is to use the share link which is a permanent URL. This ensures that the link to the page is not broken
if the page name changes.
To access the permanent URL for a page:
1. View the page you wish to link to.

2. Choose Share.
3. Copy the Share link.
You do not need to use the share link to link to pages within your Confluence site. Confluence automatically
updates links when you rename or move a page to another space.
If you want to link to specific content such as anchors, headings or comments you need to use the following
link syntax. Note that there are no spaces in the page name, anchor name or heading text.
In the examples below, the anchor name is 'InsertLinkAnchor' and the heading text is 'Insert a link'.
Purpose Link syntax
Link to an http://myconfluence.com/display/spacekey/Page+name#pagename-
anchor anchorname
(from an
external Example from this page:
website)
https://confluence.atlassian.com/display/DOC
/Working+with+Links#WorkingwithLinks-InsertLinkAnchor
Link to a http://myconfluence.com/display/spacekey/Page+name#pagename-
heading headingtext
(from an
website)
https://confluence.atlassian.com/display/DOC
/Working+with+Links#WorkingwithLinks-Insertalink
Link to a http://myconfluence.com/display/spacekey/pagename?
comment focusedCommentId=commentid#comment-commentid
(from an
website)
https://confluence.atlassian.com/display/DOC/Working+with+Links?
focusedCommentId=368640803#comment-368640803
Some things to note when linking to anchors from a website or email message:
The page name is repeated in the URL, after the # sign. The second occurrence of the page name is
concatenated into a single word, with all spaces removed.
There is a single dash (hyphen) between the concatenated page name and the anchor name.
The anchor name in the full URL is concatenated into a single word, with all spaces removed.
The anchor name is case sensitive. You must use the same pattern of upper and lower case letters
as you used when creating the Anchor.
Link to a comment
You can add a link to a comment by using the comment URL (a permanent link), or by using wiki markup to
link to the Comment ID.
To find out the comment URL and comment ID:
1. Go to the comment you wish to link to

2. Choose the Date at the bottom of the comment and examine the URL
The number after 'comment-' is the Comment ID. An example is shown here.
https://confluence.atlassian.com/display/DOC/Working+with+Links?focusedCommentId=368640803#comment-
368640803
You can use wiki markup directly in the editor to link to a comment. Enter [$ followed by the Comment ID, for
example [$12345] where '12345' is the Comment ID.
Using shortcut Links
We ended support for shortcut links in Confluence 7.0

Shortcut links can still be added and used on pages, but we will no longer fix bugs relating to this
feature, and plan to remove it in a future Confluence release.
If you have configured shortcut links on your Confluence site, then you can link to an external site using a
shortcut link that looks like this:CONF-17025@jira.
Our Confluence site (where this documentation is housed) is configured to allow shortcut links to our Jira
site, using the shortcut @jira. So the shortcut link CONF-17025@jira produces this link.
To add a shortcut link using the 'Insert Link' dialog:
1. Choose Link > Advanced and enter or paste the shortcut link into the Link field (shortcut links are
case-insensitive)
2. Modify or enter link text (this is the text that will appear on the page)
3. Choose Insert
You can also type '[' and choose Insert Web Link > Advanced to enter a shortcut link.
See Configuring Shortcut Links for more details.
Anchors
On this page:
You can use anchors to enable linking to specific locations on a page, and
they can be especially useful for allowing your readers to navigate to
specific parts of a long document. Anchors are invisible to the reader when Step 1: Create the
the page is displayed. anchor
Step 2: Create a
There are two steps to using an anchor: link to the anchor
Notes
Step 1: Create the anchor
Related pages:
Step 2: Create a link to the anchor
Links
Step 1: Create the anchor
Add the Anchor Macro to mark the location you want to link to:
1. Do either of the following in the Confluence editor:

Choose Insert > Other Macros, then find and select the
Anchor macro
Type { and the beginning of the macro name, then select the
Anchor macro
2. Enter the Anchor Name (For example, 'bottom' or 'important
information')
3. Choose Insert
Macro options (parameters)
Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in
the macro browser, it will be listed below in brackets (example).
Parameter Default Description
Anchor None This is the anchor name that you will use when creating the link.
Name
The anchor name can include spaces. Confluence will remove the spaces
automatically when building a URL that points to this anchor.
The anchor name is case sensitive. You must use the same pattern of upper
and lower case letters when creating the link as you used when creating the
Anchor macro.
Step 2: Create a link to the anchor

You can link to an anchor from:
A page on the same Confluence site. The link may be on the same page as the anchor, another page
in the same space, or a page in another space on the same Confluence site.
Another web page or another Confluence site, using a specifically formatted URL.
Link to an anchor on the same Confluence site:
1. Select some text or position your cursor where you want to insert the link
2. Choose Link in the toolbar or press Ctrl+K
3. Choose Advanced and enter the anchor name in the Link field, following the format below.
Anchor location Link syntax for anchor Examples

Same page #anchor name #bottom
#important information
Page in same space page name#anchor name My page#bottom
My page#important information
Page in different spacekey:page name#anchor DOC:My page#bottom

space name
DOC:My page#important
information
4. Enter or modify the Link Text (this is the text that will appear on the page. If this field is left blank, the
page name or URL will be used as the link text)
5. Choose Save
Anchor names are case sensitive

Enter page and anchor names with spaces when you link to them in the same Confluence site
If you're linking to an anchor on a different page that has special characters in its name,
where the URL displays a page ID rather than a name, you should still enter the page name
when linking to it
Screenshot: The 'Advanced' option in the link dialog
Link to an anchor from another web page or another Confluence site:
Use a full URL in the following format:
Link syntax Examples
http://myconfluence.com/display/spacekey http://myconfluence.com/display/DOCS
/pagename#pagename-anchorname /My+page#Mypage-bottom
http://myconfluence.com/display/DOCS
/My+page#Mypage-importantinformation
Notes about the full URL:
The page name is repeated in the URL, after the # sign. The second occurrence of the page name is
concatenated into a single word, with all spaces removed.
There is a single dash (hyphen) between the concatenated page name and the anchor name.
The anchor name in the full URL is concatenated into a single word, with all spaces removed.
The anchor name is case sensitive.
If the page name contains special characters, where the URL displays a page ID rather than a name,
the link to an anchor will look more like this http://myconfluence.com/pages/viewpage.
action?pageId=54689987#Test-page1!-anchor
In this example the page title is Test - Page 1! and the anchor name is anchor.
Notes
Table of contents on a page: Consider using the Table of Contents Macro to generate a list of links
pointing to the headings on the page. The list of links will appear on the page, and will be
automatically updated each time someone changes the wording of a heading.
Linking to headings: You can link directly to the headings of a page. See Links. However, if
someone changes the wording of a heading, those direct links will be broken. Use the Anchor macro
to ensure a lasting link within the body of a page.
Site welcome message: If you are adding an anchor to a page that you are using in the site
welcome message, you can only link to that anchor from another page. Internal links within that page
will not work.
Templates: When you are previewing a template, a link to an anchor is displayed as a 'broken' link.
However, when you create a page using the template the resulting page will have the correct link.
Tables
Confluence tables allow you to present important information and discuss it
On this page:
with your team. Use familiar table formatting options –resizing columns,
coloring cells, rows and columns, and sorting the table by clicking the
column headers – to view the information the way you like it. Insert a table
Edit your table
Using Confluence Cloud? Check out our info on the new Confluence Shortcut keys
Cloud editor if your table looks like this one. Sort the table in
view mode
Sticky table
headers in view
mode
Related pages:
Page Layouts,
Columns and
Sections
The Editor
Insert a table
To create a table:
1. Hit the Table button in the toolbar

2. Click a cell in the drop-down to set the number of columns and rows
in your table
Edit your table

To resize table columns, just click and drag the column's border. To make other changes to your table, click
inside it to reveal the table toolbar.
Here's a summary of the table tools:
Column width modes
Responsive – choose this mode if you want the table

to expand as you add content. You can drag to resize
the columns. It'll also resize itself to fit the page-
viewer's window size (within reason).
Fixed width – choose this mode if you want to drag
column borders to set width. Columns appear at your
set size, regardless of content and window size.
Rows
Insert rows before or after the current row

Delete the current row
Cut, copy and paste the current row
Mark a row as a header row (shaded with bold text)
Columns
Insert columns before or after the current column

Delete the current column
Cut, copy and paste the current column
Mark a column as a header column (shaded with bold
text)
Add a numbering column to automatically number
each row
Cells
Merge selected cells

Split selected cells
Change cell color
Table
Delete entire table
Shortcut keys
Windows Action Mac OS X
Ctrl+Shift+c Copy the current table row, or the selected rows. Cmd+Shift+c
Ctrl+Shift+i Insert a table. (Opens the Insert Table dialog.) Cmd+Shift+i
Ctrl+Shift+v Paste the table rows from your clipboard, placing them above the Cmd+Shift+v
current row.
Ctrl+Shift+x Cut the current table row, or the selected rows. Cmd+Shift+x
Alt+Up Arrow Add a row above the current row. Alt+Up Arrow
Alt+Down Add a row below the current row. Alt+Down

Arrow Arrow
For more editor keyboard shortcuts, see Keyboard shortcuts.
Sort the table in view mode

When viewing a table on a page, you can sort it by clicking the sort icons in the header row.
Screenshot: A colorful, sortable table
The default sort order is the order the table rows are listed in the editor. You can use the Cut row and Paste
row icons to move rows around in the editor.
Sticky table headers in view mode

In some instances the header rows of your table will stick to the top when you're scrolling down a page,
making those really long tables easier to read.
You don't need to do anything to enable sticky table headers, however there are a lot of situations where
headers won't stick. These include when your table:
Is inside a page layout, inside another table, or inside a macro.

Has no header row or there are cells in the top row that aren't marked as headers.
Has a header column, instead of a header row, and scrolls horizontally.
Contains another table, that has its own header row.
There's no way to freeze rows or columns in Confluence tables.
See
CONFSERVER-54343 - Table header with heading column not sticky when scrolling
LONG TERM BACKLOG
for issues with sticky table headers.
Add, Assign, and View Tasks
Keep track of the things that need to get done with tasks. With the ability to
On this page:
give each task an assignee and due date, and plenty of ways to see your
tasks, you can make sure nothing slips through the cracks.
Add a task
View tasks
Add a task Notes
You can add tasks on any page in Confluence. For example, you might add
tasks under action items on a meeting notes page, or in a requirements
page – anywhere you need a lightweight task management solution.
To create a task:
1. In the editor, choose the Task list button or use the keyboard shortcut [ ]
2. Start typing your task – @mention someone to assign the task to them, and type // and choose a due
date
The first person you mention in a task is the assignee; you can even assign tasks to yourself.
Note: If you assign a task to someone who doesn't have permission to view the page or space, they won't
see the task.
View tasks
There are a number of ways to keep track of tasks assigned to you, or tasks you've created for others.
On a page
The simplest way to see a task is on the page it was originally created on. It's easy to see if a task is
complete, who it's assigned to, and when it's due. If a task is nearing or passed its due date, the color of the
date will change (red for overdue, orange for due in the next 7 days).
In your profile
The tasks page in your profile gives you a place to see all the tasks relevant to you. Easily keep track of the
status of tasks assigned to you, and tasks you've created and assigned to others.
To view the tasks page, go to Profile > Tasks. Use the filters to show tasks that were assigned to you or
created by you in the last 6 months, and toggle between complete or incomplete tasks.
If you need to see more than just your last 6 months of tasks, use a Task Report.
In a Task Report
If you're looking for a more custom view of tasks, the Task Report blueprint is a great way to track tasks
assigned to a specific team or project.
To create a task report:
1. Choose Create > Task Report

2. Select the type of report:
Assigned to my team – for tasks assigned to particular people.
In my project – for tasks that appear in a specific space or page.
Custom – for a wide range of filtering options, including by date or page label.
3. Follow the prompts to create the report.
This blueprint uses the Task Report Macro. You can also choose to use this macro on an existing page, for
example, on a project or team space homepage.
Notes
The date picker can be triggered by typing // or by typing a date in the format dd/mm/yyyy or dd-mm-
yyyy. Typing other date formats in the editor won't trigger the date picker.
Personal Tasks (created in the Workbox in older versions of Confluence) don't appear in the Tasks
view or Task Report. To migrate any incomplete personal tasks, go to Workbox > Personal Tasks an
d follow the prompts.
The wiki markup based Tasklist Macro has been removed from the macro browser. If you have a
Tasklist macro on a page it will continue to work, but you will be unable to add new Tasklists using
this macro.
Do more with Confluence
For even more ways to organize your tasks in Confluence, check out these apps from the Atlassian
Marketplace:
Comala Workflows: Improve document collaboration by assigning users to review, approve,

and publish pages
TodoMe for Confluence: Add, assign, and view tasks from every Confluence page
Agile Retrospectives for Confluence: Interactively assign action items to team members
Autocomplete for links, files, macros and mentions
When using the Confluence editor, you can type a trigger character or press
On this page:
a keyboard shortcut to see a list of suggested links, files or macros to add
to your page, or to mention another user (and automatically notify them of
this). Summary of
autocomplete
Summary of autocomplete Using
autocomplete for
links
What you want to do Trigger Keyboard Description
Using
character shortcut
autocomplete for
Add a link on your page Ctrl+Shift+K See a list of images, videos,
[
suggested pages audio files and
or other locations documents
to link to from your Using
page. More... autocomplete for
macros
Display an image, ! Ctrl+Shift+M See a list of Using
video, audio file or suggested images, autocomplete for
document on your page multimedia files mentions
and documents to Canceling
embed in your autocomplete
page. More... Enabling and
disabling
Add a macro on your { None See a list of autocomplete
page suggestions as Ignoring
you begin typing a autocomplete
macro name. More.
.. Related pages:
Notify another user by @ None See a list of Links

email that you have suggested users Using Images
mentioned them on to mention. More... Macros
your page Keyboard shortcuts
Your profile and
settings
Using autocomplete for links

Type '[', or press Ctrl+Shift+K, to see a list of suggested pages or other locations to link to from your page.
You can link to pages, user profiles, images, documents and other file attachments.
To autocomplete a link:
1. Edit the page.

2. Click where you want to insert a link and do one of the following:
Type '[' and then the first few characters of the page title, user's name, image name or file
name.
Type the first few characters of the page title, user's name, image name or file name (or select
relevant text) and then press Ctrl+Shift+K.
3. Click the relevant link from the list of suggestions.
If the item you need is not in the list, either:
Choose Search for 'xxx' to continue looking for the page within Confluence, or
Choose Insert Web Link to insert a link to an external web page using the link browser.
Screenshot: Autocomplete for a link

Using autocomplete for images, videos, audio files and documents

You can use the autocomplete as a fast way of embedding images, videos, audio files and documents into
your page. Type an exclamation mark or press Ctrl (or Cmd)+Shift+M to see a list of suggested images,
multimedia files and documents to display on your page. You can use autocomplete to embed the following
file types:
Images – any format that Confluence supports.

Videos, audio files and all multimedia formats that Confluence supports.
Office documents supported by the Confluence Office Connector: Word, Excel and PowerPoint.
PDF files.
Autocomplete works most efficiently for files that are already attached to the Confluence page.
To embed an image, video, audio file or document:
1. Edit the page.

2. Click where you want to insert the image, video, audio file or document and do one of the following:
Type '!' and then the first few characters of the image, file or document name.
Type the first few characters of the name of the image, file or document (or select relevant text)
and then press Ctrl (or Cmd)+Shift+M.
3. Choose the relevant file from the list of suggestions.
If the item you need is not in the list, either:
Choose Open file library to find images and documents using the image browser, or
Choose Insert other media to embed videos, audio and other multimedia files using the macro
browser.
Screenshot: Autocomplete for an image or file
Using autocomplete for macros

Type '{' to see a list of suggested macros to add to your page.
Autocomplete provides access to all available macros in your Confluence site, including any user macros
that your administrator has added and made visible to all.
You need to know the name of macro. Autocomplete for macros will only match the name of the macro,
not the description.
To autocomplete a macro using '{':
1. Edit the page.

2. Click where you want to insert the macro.
3. Type '{' and then the first few characters of the macro name.
4. Choose the relevant macro from the list of suggestions.
5. Configure the macro by completing the form fields as prompted.
If the macro you need is not in the list, choose Open Macro Browser in the list of suggestions to continue
looking for the macro in the macro browser. See Macros.
Screenshot: Autocomplete for a macro
Using autocomplete for mentions
You can use autocomplete to automatically notify another Confluence user that you have mentioned them in
a page, blog post, or comment. Type '@' and part of the person's name, to see a list of suggested users.
Note: Use the person's full name. Autocomplete will recognize users' full names only, not their usernames.
Canceling autocomplete
The autocomplete starts automatically when you press the trigger characters. You may want to close the
autocomplete menu or escape from autocomplete once it has started.
There are a few different ways to stop the autocomplete once it has started:
Press the escape key, 'Esc', on your keyboard.

Click somewhere else in the editor panel.
Press an arrow key to move out of the autocomplete area.
For the link autocomplete only: enter a right-hand square bracket, like this: ]
Enabling and disabling autocomplete

You can turn off the triggering of autocomplete by the '[' and '!' characters. This will prevent the autocomplete
from starting automatically when you press one of the trigger characters. You can also turn it back on again.
Notes:
This setting does not affect the keyboard shortcuts for autocomplete (Ctrl+Shift+K and Ctrl+Shift+M).
Even if the trigger characters are disabled, you can still use the keyboard shortcuts for autocomplete.
This setting affects only you. Other people using Confluence can enable or disable the setting on their
user profiles independently.
Note that autocomplete is enabled by default.
To enable or disable the autocomplete trigger characters:
1. Choose your profile picture at top right of the screen, then choose Settings
2. Choose Editor under 'Your Settings' in the left-hand panel.
3. Choose Edit.
4. Either:
Disable autocompletion by selecting Disable Autocomplete.
Enable autocompletion by clearing Disable Autocomplete.
5. Choose Submit.
Screenshot: User settings for the editor
Ignoring autocomplete
You can add macros, links and images by wiki markup alone. Type the macro, including its parameters and
the closing curly bracket. Add a link, such as an anchor link, and end it with a square bracket. Insert an
image or other embedded object, enclosed between exclamation marks. As soon as you close the macro,
link, or embedded image, Confluence will convert it to rich text format and add it to the page.
For more information about mouse-free macros, links and images, choose Help > Keyboard Shortcuts
from the Confluence header.
Page Layouts, Columns and Sections
The layout of your pages can have a big impact on how they're read, and
On this page:
layouts, used well, allow you to position text, images, macros, charts, and
much more, to have the best visual impact.
The Section and
There are two ways to modify the layout of a Confluence page: Column macros
Use page layouts to add sections and columns

Use macros to add sections and columns.
Page layouts provide a simple, visual representation of your page layout in

the editor, while the macros are more flexible and allow for greater
complexity in your layout.
Use page layouts

The page layouts tool allows you to structure your page using horizontal sections and vertical columns. By
adding multiple sections with different column configurations you can build quite complex layouts very easily.
Screenshot: Editor view of a page showing three sections with different column configurations.
Start by adding a horizontal section to your page.
To add a section:
1. Choose the Page Layout button in the toolbar

The Page Layout toolbar appears.
2. Choose Add Section
The new section appears below your current content, with the boundaries of the section(s) indicated by
dotted lines (the dotted lines aren't visible when you view the page).
To change the column layout in a section:
1. Place your cursor in the section you wish to change

2. Choose a layout from the page layout toolbar (for example, two columns or three columns)
Any text, images or macros in your section are not lost when you change the column layout. When you
decrease the number of columns, Confluence will move your content to the left. When you increase the
number of columns, Confluence will add blank columns to the right of your existing content.
To move a section to another part of the page:
1. Place your cursor in the section you wish to move

2.
2. Choose the Move up or Move down buttons
The section and all of its content will be moved above or below other sections on the page.
To delete a section:
1. Place your cursor in the section you wish to remove

2. Choose Remove section
The section and all of its content will be removed.
Notes about Page Layouts
Column width – The width of the columns are fixed. If you need more than three columns, or
columns of a specific width, you should use the Section and Column macros described below.
Very wide tables – The width of each column is set to a percentage of the page width. The icons in
the drop-down menu indicate the relative widths for each layout. In most cases, Confluence will adapt
the width of the columns to fit the width of the page. If a column includes an item that's too wide for it,
you'll see a horizontal scroll bar when viewing the page.
The Section and Column macros

You can use the Section and Column macros to add a set of columns to the page. The Section macro
defines an area that will contain the columns. You can have as many sections as you like. Within each
section, you can have as many columns as you like.
The Section and Column macros are useful if you want to define a specific percentage or pixel width for
each column.
To add a section and some columns to a page:
1. In the Confluence editor, choose Insert > Other Macros

2. Find the Section macro, select it and insert it onto the page
3. Choose Insert > Other Macros again
4. Find and insert the Column macro
5. Add your content to the column
Insert as many columns as you like within the section.
You should always have at least one column macro within a section macro. Using a section macro
without any column macros can negatively affect page loading time.
Screenshot: A section and two columns in the editor
Macro parameters
Where the parameter name used in Confluence storage format or wikimarkup is different to the label used
in the macro browser, it will be listed below in brackets (example).
Parameters of the Section macro
Show Border false Select this option to draw a border around the section and columns.
Note: Without a Column macro , the border will not be displayed correctly.
Parameters of the Column macro
Column 100% of the page width, divided Specify the width of the column, in pixels (for
Width equally by the number of columns example, 400px) or as a percentage of the available
in the section. width (for example, 50%).
All content within your section must be enclosed within a Column macro, otherwise the section
layout will not work as expected.
Create Beautiful and Dynamic Pages
Confluence has a number of features that help you
On this page:
build attractive pages to engage your readers and
give them the opportunity to interact with up-to-date
information. This page summarizes those features Add visual appeal
and provides links to detailed instructions. Bring numbers to life
Display presentations and documents
Pull in content from Jira applications
Add visual appeal Tell a story in pictures
Vary the structure of your pages
Pictures, photographs and Integrate your content with social media
screenshots. Confluence pages Show activity streams
can display images from your
Confluence site and from other Related pages:
websites. To put an image into
Confluence, you can upload it Macros
and attach it to a page or blog The Editor
post, then display it on any page, Create and Edit Pages
blog post or comment. Alternatively, display a
remote image using its web address (URL). See Dis
playing Images.
Galleries. Use the Gallery Macro to display a set of

images. When viewing the page, people can click
any of the pictures to zoom in and view the images
as a slide show.
People. Add a Profile Picture Macro to show a picture of a Confluence user, or a User Profile Macro to show
a summary of the person's profile as well as their avatar.
Multimedia. You can display movies, animations and videos, and embed audio files on your Confluence
page. For example, Confluence supports Adobe Flash, MP3, MP4, and various other movie formats. See Em
bedding Multimedia Content.
Social video and image sharing. The Widget macro displays live content from social sites such as YouTube
and other video sharing sites, and Flickr for shared photographs. See the guide to the Widget Connector
Macro.
Bring numbers to life

The Chart Macro offers a variety of graphs and charts that you can use to illustrate statistics and other
numerical data.
Illustration: A 3-dimensional bar chart produced by the Chart macro

Display presentations and documents

Display your Office documents and other presentations directly in Confluence.
Attach your Office documents to a Confluence page then display them on the page, using the View
File Macro. This works for Excel spreadsheets, PowerPoint presentations and Word documents.
Display PDF files in Confluence too, also with the View File Macro.
Use the Widget Connector Macro to show slide decks hosted on SlideShare and other online
presentation sites.
Illustration: A PowerPoint slide deck
Pull in content from Jira applications

Many project teams and customers also use Jira applications such as Jira Software or Jira Service Desk.
Rather than copying and pasting issues onto your Confluence page, you can display it directly from the
source, thus ensuring that the information shown in Confluence is always up to date.
Link to a feature request in your issue tracker, or display a list of fixed issues – useful for release notes and
project planning. See the Jira Issues Macro.
Tell a story in pictures
A number of Marketplace apps for Confluence provide sophisticated tools for creating diagrams and
mockups.
For example:
Balsamiq Mockups for Confluence

Creately for Confluence
Gliffy Confluence Plugin
Graphviz Plugin for Confluence
Lucidchart for Confluence
Search the Atlassian Marketplace for more apps.
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.
Illustration: A Gliffy diagram
Vary the structure of your pages

You can build up a custom layout by using the page layout tool to add sections and columns to your page.
See the detailed guidelines to Page Layouts, Columns and Sections.
Do you need to display tabular data, which your readers can sort when viewing the page? See Tables.
Use other macros to highlight and format sections of your page:
Panel
Info, Tip, Note, and Warning
Code block
Noformat
Integrate your content with social media

People share information on various social sites. You can make Confluence a focal point where people
collect their shared information and see what is happening in the areas that matter to them.
Use the Widget Connector macro:
Show a live stream of tweets from a Twitter user, or tweets matching a Twitter search.
Display a video from YouTube or other online movie sites.
Share photographs from Flickr.
See what else the Widget Connector macro can do.
Illustration: Twitter stream via the Widget macro
Show activity streams

Make your Confluence pages dynamic and interactive with:
An activity stream showing updates and comments on Confluence and other linked applications. See
Gadgets.
An RSS feed from within Confluence or an external site. See Subscribe to RSS Feeds within
Confluence.
A list of recent blog posts from within Confluence. See Blog Posts Macro.
Page Templates
When you add a new page, you don't have to start from scratch. Instead,
you can base your new page on a template – a Confluence page with On this page:
predefined content. Some templates are provided by blueprints or
Marketplace apps, and you can even create your own templates.
Global templates
and space
Some examples of useful templates are:
templates
Create a template
The meeting notes template will help you and your team collaborate
Use a template
on notes and follow-up tasks
Templates
The requirements template allows you to capture your software
provided by
/hardware product requirements, and create related Jira issues from
blueprints
the page
Promote templates
in the Create dialog
Global templates and space templates System templates
In Confluence, there are two categories of page templates: Related pages:
Space templates: These page templates are available in a specific Create a Template
space only. If you have space administrator permission, you can Create a Page
define templates via the space administration screen. from a Template
Global templates: These page templates are available in every
space on your site. If you have Confluence Administrator permission,
you can define global templates via the Confluence Administration
Console.
Create a template
You can write your template using the Confluence editor. You can also add special variables to the page, if
you want to include fields that the author will complete when adding the page. See Create a Template for
more information.
Use a template
Page templates are used only when adding a page. It is not possible to apply a template to an already-
existing page. Once a page has been added using a template, the template is no longer linked to the page.
All further editing is performed as if the template was never used. Some Marketplace apps provide enhanced
template functionality. You can search the Atlassian Marketplace for template apps. See Create a Page from
a Template for more information.
Templates provided by blueprints

A blueprint is a page template with added functionality to help you create, manage and organize content in
Confluence, and there's a collection of predefined ones that ship with Confluence. You can also download
additional blueprints from the Atlassian Marketplace. You can customize the blueprint templates to suit your
individual needs, disable particular blueprints or even develop your own blueprints.
Promote templates in the Create dialog

If you're a space administrator, you can choose to promote specific templates and blueprints in the Create
dialog. Promoting items can help ensure consistency in a space by encouraging users to create particular
types of content, instead of blank pages.
The promoted templates or blueprints will appear at the top, with all other content types, including Blank
Page and Blog Post collapsed under them. To view the other types of content available choose the Show
more link.
1. Show more: see more templates and blueprints.
To promote a template or blueprint:
1. Go to Space Tools > Content Tools

2. Choose Promote next to the templates or blueprints you want to appear in the Create dialog. You can
only promote templates created in this space.
Remember, by promoting a blueprint or template you'll be hiding all other items, including blank page and
blog post, under the Show more link.
If you use the Show more link in the create dialog more than three times in a single space, the dialog will
show you all templates by default from then on.
System templates
Confluence also provides 'system templates' containing content like the site welcome message and default
space content. See Administering Site Templates.
Create a Template
In Confluence, there are two categories of page templates:
On this page:
Space templates: These page templates are available in a specific
space only. If you have space administrator permission, you can Add a template
define templates via the space administration screen. The template editor
Global templates: These page templates are available in every Template
space on your site. If you have Confluence Administrator permission, variables
you can define global templates via the Confluence Administration Labels
Console. Images and
other
attachments
Instructional
Add a template text
Add a description
To create a new space template: to your template
Edit or delete a
1. Go to the space and choose Space tools > Content Tools from the template
bottom of the sidebar Notes
2. Choose Templates > Create new template.
Related pages:
To create a new global template:
Create a Page
1. Go to > General Configuration Global Templates and from a Template
Blueprints. Page Templates
2. Choose Add New Global Template Add, Remove and
Search for Labels
Macros
The Editor
Check out the article How to document releases and share release notes to see how helpful creating
templates in Confluence can be.
The template editor

When you create or edit a template, you'll be using the editor in much the same way as when you edit a
page or blog post. In addition you can add variables, which will produce a form for data collection when
anyone adds a page based on the template.
Screenshot: The template editor with an image, table, text, and variables
Screenshot: The form displayed when you create a page based on the template
Template variables
When you add variables to your template, they will act as form fields. When you create a page based on a
template, you'll see a text entry box for each field. Enter data into each field, and it'll be added to the page.
You can add the same variable more than once in the same template, which is useful if you need the same
information in more than one place on the page.
To insert a variable into a template:
1. Choose Template > New Variable from the editor toolbar (or choose an existing variable to add it to
the page)
2. Enter a name for the variable
3. Press Enter (by default this will create a single-line text input field)
To change the variable type, click the variable placeholder and the variable's property panel will appear.
Choose one of the variable types: Text, Multi-line Text, or List.
You can change the number of lines and width in characters of a Multi-line Text field. If you choose List,
enter each of the items in your list, separated by commas.
Hint: Type $ and the variable name, then press Enter to add a new variable or to select an existing variable
from a list of suggestions. The suggestions dialog shows variables already defined in this template.
Labels
If you'd like all pages created using this template to have one or more labels, choose the labels icon next
to the breadcrumbs at the top of the page to add them.
Images and other attachments
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.
Instructional text
Instructional text is placeholder content in a template, and is only visible while you're editing the page. Use it
to give guidance to whoever is creating a page from the template.
To insert instructional text:
1. Choose Template > Instructional Text in the toolbar

2. Type in your instructional text (for example, Insert an image of the interface here.)
Instructional text appears in italics with a shaded background, to distinguish it from normal paragraph text.
You can also change the placeholder type from Text to either:
User mention – Opens the user mention dialog.

Jira Macro – Opens a dialog that allows you to create a new Jira issue, or search for one or more Jira
issues to include on the page.
Add a description to your template

The template description displays in the 'Create' dialog, and is useful for explaining the purpose of your
template to other users.
To add a description to a template:
Go to the space or global templates page (as described above)

Choose the Edit icon in the 'Description' column
Enter your description and choose Save
1. Edit: use the pencil icon to edit your template's description.
Edit or delete a template

If you need to change anything about your template, or want to delete it, navigate to either your space or
global template (as described above) and choose either Edit or Delete.
Notes
existing page. Once a page has been added using a template, the template is no longer linked to the
page. All further editing is performed as if the template was never used. Some Marketplace apps
provide enhanced template functionality. You can search the Atlassian Marketplace for template apps.
When you use a Table of Contents macro in a template, you'll see an error when you preview the
template, but the Table of Contents macro works on the pages that people create from the template.
The editor for templates is available only in Confluence 4.3 and later. Please refer to the earlier
documentation for a description of the wiki markup editor templates.
Confluence also provides 'system templates' containing content like the site welcome message and
default space content. See Administering Site Templates.
Create a Page from a Template
You can create a page based on a global template (available to all spaces)
On this page:
or a space template (available only to that space).
Information copied
If you want to quickly create a blank page, hit the Create button in from the template
the header; if you want to create a page from a template, hit the Cre to the page
ate from template button. Form fields
displayed by the
template
Using a template to
create a page
Notes
2. Create from template Related pages:
Create a Template
The Editor
Information copied from the template to the page Add, Remove and
Search for Labels
When you create a page based on a template, Confluence will copy the
following content and information from the template to the new page:
Labels
Text and styles
Layouts and formatting
Macros
Embedded images and other files. Note that you cannot attach an
image or other file to a template. But if the template displays an
image or file from another page, the new page will display that image
or file too.
Form fields displayed by the template

If the template author included variables in the template, Confluence will display a form prompting you to
supply values for the variables when you add the page.
Using a template to create a page

To create a page based on a template:
1. Choose Create from template in the Confluence header

2. Select a space and the template you want to use and choose Next
If the template contains variables, you'll see a form allowing you to add values for the form variables.
3. Type the relevant information into the form fields, and choose Next
Now you'll see a new page based on the template. If you added information in the form fields, the
page content will include that information.
4. Name your page, add content or make any other changes required and hit Save
Screenshot: Form showing template variables when creating a page from a template
Notes
existing page. Once a page has been added using a template, the template is no longer linked to the page.
All further editing is performed as if the template was never used. Some Marketplace apps provide enhanced
template functionality. You can search the Atlassian Marketplace for template apps.
Blueprints
What's a blueprint?
On this page:
A blueprint is a set of page templates with added functionality to help you
create, manage and organize content in Confluence more easily. What's a blueprint?
Create content
Create meeting notes, shared file lists and requirements documentation out using a blueprint
of the box, and Customize the blueprint templates to suit your individual Customize
needs. You can even develop your own blueprints. blueprint templates
Promote blueprints
Create content using a blueprint in the Create dialog
Add more
blueprints
1. Choose Create from template in the Confluence header Disable a blueprint
2. Select a blueprint from the create dialog Full list of blueprints
3. Hit Create
Related pages:
The editor will open, and, depending on the blueprint selected, a prompt to
Page Templates
enter information or the page will appear. You can now follow the
Request
instructions built in to the blueprint to add content.
Marketplace Apps
The first time a blueprint is used in a space, Confluence creates an index page and adds a shortcut to your
sidebar (if you're using the default theme). The index displays a list of pages made with the blueprint, and
information selected from your blueprint pages. For example, the meeting notes index displays a list of all
meeting notes pages in the space, who created them, and when they were last modified. Here's the index
page for the Meeting Notes blueprint:
1. Easy to find: notes from all your meetings are listed here.
2. Start a new meeting: create a new meeting notes page here.
Customize blueprint templates

Blueprints are made up of templates that can often be customized for an individual space or the whole site.
This means you can adapt the content of the blueprint pages to suit your specific needs. For example, you
might update the Meeting Notes blueprint templates to include a heading for apologies.
If you have space administrator permissions, you can customize blueprint templates for the spaces you are
an administrator of. You must be a Confluence Administrator to customize blueprint templates for a whole
site. See Administering Site Templates for more information.
To customize a blueprint template for a space:
2. Choose Edit beside the blueprint template you wish to edit
3. Make your changes to the template and choose Save
Editing a blueprint template is very similar to editing a page template, except:
Be careful not to remove any macros that the blueprint page or index page may use to store and
display information
You can't remove a blueprint template or change the template name
Not all blueprints are customizable. Some, including the Team Playbook blueprints (health monitor,
DACI, project poster, and experience) can't be edited.
To reset a blueprint template back to the default:
2. Choose Reset to default beside the blueprint template you wish to reset
See Working With Templates and Administering Site Templates for more information on templates.
As with user created space and site templates, editing a blueprint template will not change existing pages,
but any new blueprint pages will be based on the updated template.
Promote blueprints in the Create dialog

If you're a space administrator, you can choose to promote specific templates and blueprints in the Create
dialog. Promoting items can help ensure consistency in a space by encouraging users to create particular
types of content, instead of blank pages.
The promoted templates or blueprints will appear at the top, with all other content types, including Blank
Page and Blog Post collapsed under them. To view the other types of content available choose the Show
more link.
1. Show more: see more templates and blueprints.
To promote a template or blueprint:
1. Go to Space Tools > Content Tools

2. Choose Promote next to the templates or blueprints you want to appear in the Create dialog. You can
only promote templates created in this space.
Remember, by promoting a blueprint or template you'll be hiding all other items, including blank page and
blog post, under the Show more link.
If you use the Show more link in the create dialog more than three times in a single space, the dialog will
show you all templates by default from then on.
Add more blueprints
You can find more blueprints for Confluence in the Atlassian Marketplace. Blueprints are managed using
apps (also known as add-ons, or plugins).
See Request Marketplace Apps for information on how you can search for new blueprint apps and send a
request to your System Administrator.
If you are a System Administrator, see Managing System and Marketplace Apps for information on how to
install new blueprint apps.
You can also develop your own blueprints. See our developer documentation on Writing a Blueprint.
Disable a blueprint
You may want to disable particular blueprints. For example, you may not want to see the Product
Requirements blueprint in the create dialog in an HR or Social space. If you are a Confluence Administrator
you can also disable particular page and space blueprints for the whole site.
To disable a blueprint in a space:
Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
Choose Disable next to the blueprint you wish to disable in that space
You can re-enable the blueprint at any time.
To disable a blueprint across a whole site:
Choose the cog icon , then choose General Configuration (You need Confluence Administrator
permissions to do this)
Choose Global Templates and Blueprints
Choose Disable next to the page or space blueprint you wish to disable
The blueprint will not appear in the 'Create' or 'Create Space' dialogs.
Full list of blueprints

Here's the full list of blueprints bundled with Confluence.
Page blueprints Space blueprints
Meeting notes Documentation space

File list Team space
Decision Knowledge base space
How-to article
Troubleshooting article
Jira report
Product requirements
Retrospective
Share a link
Task report
DACI decision (Atlassian Team Playbook)
Experience canvas (Atlassian Team Playbook)
Health Monitor (Atlassian Team Playbook)
Project poster (Atlassian Team Playbook)
Decisions Blueprint
The Decisions blueprint helps you make decisions and record the outcomes
Related pages:
with your team.
Blueprints
The first time you use the Decisions blueprint in a space, Confluence will File List Blueprint
create an index page and add a shortcut on your space sidebar (if you're Meeting Notes
using the default theme). The index acts as your Decision Log and lists all Blueprint
the decisions in that space. Product
Requirements
Blueprint
If you want to quickly create a blank page, hit the Create button in
the header; if you want to create a page from a template, hit the Cre
ate from template button.

To create a decision page:

2. Select Decision and hit Next
3. Enter information about the decision and relevant stakeholders (the
blueprint will prompt you) and hit Create
Once you save your first decision page, Confluence will create a decision
log page for the space you're in, and add a shortcut to it in the space's
sidebar.
Here's how the decisions page looks in the editor:
Once you save your first decision page, Confluence will create a decision log page for the space you're in,
and add a shortcut to it in the space's sidebar. The decision log lists all the decisions in that space.
1. Decision pages: your existing decisions appear here.

2. More decisions: create new pages using the decision template.
The Decisions blueprint uses these Confluence features:
Page Properties and Page Properties Report macro - content that you enter within the page
properties macro can appear on the index page.
Mentions - add a user as a stakeholder, owner or @mention them on the page and they will be
notified in their workbox.
For an example of the Decisions Blueprint, and some other great page elements, check out: How to
make better decisions as a development team.
Customizing this blueprint

You can customize the templates that are used by the Decisions blueprint - see Customizing the blueprint
templates. For example, you might choose to edit the decisions index page in a space to change the
columns displayed by the Page Properties Report macro.
You can also edit the page template to add headings or instructional text to the background section, or even
add rows to the Page Properties macro. For example, a row for the date the decision was made.
See Instructional text to find out more about using instructional text in templates.
File List Blueprint
The File List blueprint helps you to create lists of files to share with your
Related pages:
team. Great for organizing documents, images and presentations.
Blueprints
The first time you use the File List blueprint in a space, Confluence will Meeting Notes
create an index page and add a shortcut to your space sidebar (if you're Blueprint
using the default theme). The index page lists the latest File List pages in Product
that space. You can have as many File List pages as you need. Requirements
Blueprint

To create a file list:

2. Select File List and hit Next
3. Enter the details for your file list and hit Create
4. Drag files from your desktop or choose browse for files to search for files on your computer
Here's an example of a file list page:

1. Expand: view each file's details and preview.

2. Upload and download: drop files to upload, and download all files.
3. Version history: see and manage other file versions.
Attachments appear on the page, and you can expand each attachment to preview the file and/or view its
details.
In this example, we've created three file list pages to store project-related presentations, images and
customer feedback. Confluence looks after the versioning of the files, so there's no need to use the
document file name to mark version numbers.
Once you save your page, Confluence will create an index page and add a shortcut to your space sidebar.
The index page lists the latest File List pages in the space. Create as many File List pages as you need.
1. Space shortcut: a quick way to find all of your file lists in this space.
2. Create a new list: create more file lists in this space.
3. Current file lists: see all the file lists in this space.
You can customize the templates that are used by the File List blueprint - see Customizing blueprint
templates.
The File List blueprint template uses the attachments macro. You can customize the macro to change the
sort order or hide features such as version history and the upload attachment fields.
You can also edit the Content Report Table macro used on the Index page to specify the number of pages
you want to display.
Meeting Notes Blueprint
The Meeting Notes blueprint helps you to plan your meetings and share
Related pages:
notes and actions with your team.
Blueprints
The first time you use the Meeting Notes blueprint in a space, Confluence File List Blueprint
will create an index page and add a shortcut on your space sidebar (if you Product
are using the default theme). The index page lists the latest Meeting Notes Requirements
pages in that space. Blueprint

To create a meeting notes page:

2. Select Meeting Notes and hit Next
3. Enter the information required by the template and hit Create
4. Save your page and get ready to attend your meeting
You can edit the page during or after your meeting, and enter your notes, action items and @mention users
to assign tasks to them.
Screenshot: A Meeting Notes index page

Screenshot: A blank Meeting Notes page showing instructional text
The Meeting Notes blueprint uses some cool Confluence features:
Instructional text - this handy text prompts you to enter information and disappears when you start
typing or view the page.
Mentions - @mention a user on the page and they will be notified in their workbox.
Task lists - @mention a user in a task to assign it to them – the task will appear as a personal task in
their workbox. You can also add a due date by typing //, then choosing a date from the calendar.

You can customize the templates that are used by the Meeting Notes blueprint – see Customizing the
blueprint templates.
You might choose to edit the headings or add additional headings, or change the instructional text that
prompts users to enter information to suit your context. To find out more about using instructional text in a
template, see Instructional text.
Product Requirements Blueprint
The Product Requirements blueprint helps you to define, scope and track
Related pages:
requirements for your product or feature.
Blueprints
Learn more about writing downsized product requirements File List Blueprint
Meeting Notes
The first time you use the Product Requirements blueprint in a space, Blueprint
Confluence will create an index page and add a shortcut on your space
sidebar (shortcut only available in the default theme). The index lists all the
Product Requirements pages in that space, and displays a summary of the
information on each page (such as status and owner). You can have as
many Product Requirements pages as you need.

To create a requirements page:

2. Select Product Requirements and hit Next
3. Enter information about your product or feature (the instructional text will prompt you) and hit Create
You can @mention team members to bring them into the conversation about the page.
In this example we've created a series of Product Requirements pages. The index page shows summary
information about each one.
1. New requirements: create more requirements pages in this space.

2. Requirements pages: see the existing requirements pages in this space.
Here's how a requirements page looks in the editor:

The Product Requirements blueprint uses these Confluence features:
Page Properties and Page Properties Report macro - content that you enter within the page
properties macro can appear on the index page.
Instructional text - this handy text prompts you to enter information or create a Jira issue
and disappears when you start typing or view the page.
Mentions - @mention a user on the page and they will be notified in their workbox.

As no two products or projects are alike, you can customize the templates that are used by the Product
Requirements blueprint - see Customizing the blueprint templates.
You might choose to edit the index page in a space to change the columns to be displayed by the Page
Properties Report macro.
You might choose to edit the page template to:
edit the headings or add additional headings

change the instructional text that prompts users to enter information to suit your context
add or remove rows within the Page Properties macro.
Shared Links Blueprint
The Shared Links blueprint helps you take content from the web and share
Related pages:
it with your team. You can use Shared Links to share and collaborate on
web content, or to create a centralized repository of useful links. Blueprints
Decisions Blueprint
The first time you use the Shared Links blueprint in a space, Confluence will File List Blueprint
create an index page and add a shortcut on your space sidebar (if you're Meeting Notes
using the default theme). The index lists all the shared links in that space. Blueprint
Product
Requirements
Blueprint

To create a shared links page:

2. Select Share a link and hit Next
3. Enter the URL of the web content you want to share, then hit Create
You can also:
Include topics to help categorize your links – these are added as labels to your page.
Share the link immediately with another user or group – users will receive a notification.
Add a comment to start the discussion.
To make sharing links even faster, you can add a Share on Confluence button to your browser's
toolbar. Click this button and the webpage you're currently viewing will be added as a shared link!
To add the Share on Confluence button to your browser:
1. Choose Create from template , then select Share a link

2. Drag the Share on Confluence button to your browser toolbar
Now, when you want to share a link in Confluence, choose the Share on Confluence button in your browser
and follow the prompts.
Screenshot: Share a link from the Create dialog.

Security considerations and limitations
To prevent people from accidentally or maliciously sharing links that may pose a security risk to your site,
domains must be added to the whitelist, before they can be shared using the share a link blueprint. For
example if you wanted to use the blueprint to share links to this documentation site you would need to add htt
ps://confluence.atlassian.com/ to the whitelist. The shared link blueprint is different to just inserting a link on
a page because it shows a preview of the linked site. See Configuring the whitelist for more information.
If external connections are disabled for your site, you can still share a link (as long as it's in the whitelist), but
we won't show a preview of its contents. Your admin can enable external connections at > General
Configuration under Connection Timeouts.
Jira Report Blueprint
The Jira Report blueprint helps you create easy to read reports to
communicate the progress of your Jira Software projects and releases. You On this page:
can choose from a Change Log report that generates a list of Jira issues or
a Status Report that includes charts to visually communicate your progress.
Create a Change
Log
The first time you use the Jira Reports blueprint in a space, Confluence will
Create a Status
create an index page and add a shortcut on your space sidebar (if you're
Report
using the default theme).
Customizing this
blueprint

To use the Jira Report Blueprint your Confluence and Jira application (such
as Jira Software) must be connected via Application Links .
Create a Change Log

The Change Log report displays a list of issues from your Jira application. This list can be static or dynamic,
automatically updating as the status of your issues change in Jira.
To create a static change Log:

2. Select Jira report and hit Next
3. Select a Change log and hit Next
4. Enter the information required for the change log and hit Create
A report page will be created with sample text and a list of all issues for the project and fix versions selected,
organized by issue type. This list of issues is static; it won't be updated when the issues are updated, and is
visible to users who don't have Jira access or permissions to view that project.
Screenshot: Creating a Change Log in simple mode.

Screenshot: Static list of Jira Issues displaying in the Change Log.
To create a dynamic change log:

3. Select a Change log and hit Next
4. Choose Switch to advanced
5. Enter a JQL query or paste in the URL of a Jira search (find out about using JQL in the JIRA
Documentation)
6. Hit Create
A report page will be created with sample text and a Jira issues macro that's configured to show your issues.
The macro is dynamic and will update when the issues are updated. For more information on changing the
information displayed, refer to the JIRA Issues macro.
Screenshot: Dynamic list of Jira Issues displaying in the Change Log.
Create a Status Report

The Status Report displays the progress of a Jira project and fix version in pie charts by status, priority,
component and issue type. The Status Report uses the Jira Chart macro, and is dynamic.
To create a status report:

3. Select a Status report and hit Next
4. Enter the information required for the report and hit Create
A report page will be created with sample text and a series of pie charts, using the Jira Chart macro. The
macro is dynamic and will update when the issues in Jira are updated. For more information refer to the JIR
A Chart macro.
As with the Change Log, you can switch to Advanced mode and use JQL or paste in a Jira URL to search for
issues to display in the report.
Screenshot: Excerpt from the Status Report.

You can customize the templates used by this blueprint. The Change Log uses the Snapshot Jira Report
Template (for static list of issues) and the Dynamic Jira Report Template, and the Status Report uses the
Status Report Template. See Customizing the blueprint templates. Variables represent the Jira Issues and
Jira Chart Macros. While these can't be edited, they can be moved around the page or deleted if you don't
want every chart to be included.
You can also choose to edit the page template to modify the format of the page, change some headings, or
modify the instructional text. To See Instructional text to find out more about using instructional text in
templates.
Retrospective Blueprint
Retrospective pages help you track team successes and opportunities after
Related pages:
projects or at the end of a sprint. Use this blueprint to document what went
well, what needed improvement, and assign actions for the future. Blueprints
File List Blueprint
The first time you create a retrospective page in a space, Confluence will Meeting Notes
automatically create an 'index' page, which will list all retrospectives in the Blueprint
space, and add a shortcut to it in the space sidebar.

To create a retrospective page:

2. Select Retrospective and hit Next
3. Add participants, change the title if you want to and click Create
Screenshot: The 'retrospective' template page

The Retrospective blueprint uses the following Confluence features:
Page Properties and the Page Properties Report macro make content listed within the macro visible
on the index page.
Instructional text prompts you to enter information and disappears when you start typing or view the
page.
Mention a user on the page to notify them in their workbox.
Check out how the retrospectives blueprint can be used in the article Create sprint retrospective and
demo pages (like a BOSS).
Customize this blueprint

Every team conducts retrospective meetings differently, so you can customize the Retrospective blueprint
template to match your team's culture and practices. You can:
Edit headings and pre-populated text

Add instructional text to capture specific information
Add additional sections and content
See Customize blueprint templates for instructions.
How-To Article Blueprint
The How-To Article blueprint helps you to provide step-by-step guidance for
Related pages:
completing a task.
Blueprints
To create a How-To Article page: Troubleshooting
Article Blueprint
Create Technical
1. Choose Create from template in the Confluence header and Onboarding
2. Select How-To Article and hit Next Documentation
3. Enter the article name and some labels and hit Create Use Confluence as
a Knowledge Base

Screenshot: A blank How-To Article page showing instructional text
Once you save your page, Confluence will create an index page and add a shortcut to your space sidebar.
The index lists all the How-To Article pages in that space, and displays a summary of the information on
each page (such as creator and modified).
The How-To Article blueprint uses some cool Confluence features:
Instructional text - Prompts you to enter information and disappears when you start typing or view the
page.
Content by Label Macro - Displays lists of pages that have particular labels, to let you collect related
pages together.
Page Properties Macro - This works together with the Page Properties Report Macro to automatically
create a list of 'related issues' on each article.

You can customize the templates used by the How-To Article blueprint - see Customizing the blueprint
templates. For example, you might choose to edit the How-to index page in a space to change the columns
displayed by the Page Properties Report macro.
add rows to the Page Properties macro. For example, a row for the date the How-To Article was created.
Troubleshooting Article Blueprint
The Troubleshooting Article blueprint helps you to provide solutions for
Related pages:
commonly-encountered problems.
Blueprints
How-To Article
Blueprint
To create a Troubleshooting Article page:
Create Technical
and Onboarding
1. Choose Create from template in the Confluence header Documentation
2. Select Troubleshooting Article and hit Next Use Confluence as
3. Enter the article name and some labels and hit Create a Knowledge Base

Screenshot: A blank Troubleshooting Article page showing instructional text
Once you save your page, Confluence will create an index page and add a shortcut on your space sidebar.
The index lists all the Troubleshooting Article pages in the space, and displays a summary of the information
on each page (such as creator and modified).
The Troubleshooting Article blueprint uses some cool Confluence features:
Instructional text - Prompts you to enter information and disappears when you start typing or view the
page.
Content by Label Macro - Displays lists of pages that have particular labels, to let you collect related
pages together.
Page Properties Macro - This works together with the Page Properties Report Macro to automatically
create a list of 'related issues' on each article.

You can customize the templates used by the Troubleshooting Article blueprint - see Customizing the
blueprint templates. For example, you might choose to edit the decisions index page in a space to change
the columns displayed by the Page Properties Report macro.
add rows to the Page Properties macro. For example, a row for the date the Troubleshooting Article was
created.
Create a Blueprint-Style Report
Using a combination of templates and macros you can make a wide range of reports for managing anything
from customer interviews, product requirements to IT service catalogs and more. In this tutorial we'll guide you
through the process of creating a blueprint-style report.
In this example, we'll create a multi-team status report. Here's the scenario we'll use for this tutorial.
The Design, Development and QA teams working on the Blue Sky Project need to produce a short status
update page each week, containing the focus area for the week, contact person, risks and overall status for
each team. They like the way the Product Requirements blueprint works and want to be able to manage their
status updates in a similar way.
What do each of the players want out of this report?
Project Lead – Wants an at-a-glance report that shows only the status for each team.
Team Leads – Want a summary report, including the focus areas and risk, just for their team.
All team members – Want it to be easy to create the new page each week.
Management Team – Want to see all the details for a week on one page, and don't want to have to
look at a different page for each team.
With this scenario in mind, this tutorial will guide you through how to:
1. Create a status update template containing a separate page properties macro for each team's section of
the report.
2. Create a high level status report, showing just the status of all teams.
3. Create a summary report for each team.
4. Create your first status update page.
You'll need Space Administrator permissions to complete some of the steps in this tutorial.
Part 1: Create a status update template

First we'll create a page template and add the Page Properties macros.
1. Go to Space Admin > Content Tools > Templates

2. Choose Create Template
3. Give the template a name (in this example the template will be called 'Status Update')
4. Add the skeleton of your status report to the page
5. Choose the label icon at the top of the page to add a label to the template (in this example, we'll add
the label: 'status-update')
Screenshot: Adding teams to our status update template

Now we'll add a Page Properties macro to record the status of the Design team.
6. Choose Insert > Other Macros > Page Properties to add the Page Properties macro to the page
7. In the macro body create a two column table and remove the heading row
8. In the left column enter the column headings for your report (these are known as metadata 'keys')
In this example we'll add 'Design Focus', 'Design Status', 'Design Contact' and 'Design Risks').
9. In the right column, leave the cells blank, or enter some instructional text to prompt your users (Choose T
emplate > Instructional Text)
We've also added a status macro.
10. Edit the Page Properties macro and enter a Page Properties ID for this macro (in this example we'll use
'status-update-design'. This will allow us to report on the status of just the Design team later on)
Repeat this process for the Development and QA teams, remembering to specify a different ID for each
macro (we used 'status-update-dev' and 'status-update-qa').
11. Finally, add any other headings, instructional text or content to your template and Save.
You can enter a Description for your template - this appears in the Create dialog.
Screenshot: Our status update template
Part 2: Create a report showing the high level status of each team
Next we'll create an index page, just like you see in many blueprints.
1. In your space create a new blank page (this will be our 'Status Report - all teams' page, showing just the
status of each team)
2. Choose Insert > Other Macros > Page Properties Report to add the Page Properties Report macro to
the page
3. Enter the Label to report on (in this example, it'll be the 'status-update' label we added to the template
page)
4. Leave the Display options > Page Properties ID field blank (we want to report on all the macros on the
page)
5. In the Columns to Show field, list the 'keys' from each macro that you want to include in the report (in
this example, we only want to show the values of 'Design Status', 'Dev Status', 'QA Status')
6.
6. Choose Save to add the macro to the page
Screenshot: The page properties report macro on the 'Status Report - all teams' page
Now we'll add a button to the page to allow team leads to easily create new status update pages from the
template we created earlier.
7. Choose Insert > Other Macros > Create from Template to add the Create from Template macro to the
page
8. Enter the text for the button (in this example we'll call the button 'New Status Update Page')
9. Select the template from the Template Name drop down (in this example our template was called 'Status
Update')
10. Specify the title of any pages to be created (This is a great way to keep your titles consistent. In this
example we'll call the page 'Status update week ending @currentDate', which will append the current
date when the page is created, as in the meeting notes blueprint)
11. Choose Insert
12. Add any other content, links or images to the page and Save
13. Choose Space Tools > Configure Sidebar > Add Link to add a shortcut to the page on the sidebar
Part 3: Create a separate report for each team
Now we'll create some index pages that show a more detailed summary for each team, starting with the Design
team.
1. Create a new blank page – this will be the 'Design Status Report' index page, showing just information for
that team.
2. Choose Insert > Other Macros > Page Properties Report to add the Page Properties Report macro to
the page
3. Enter the Label (the page label is once again 'status-update', the label we added to the template)
4. Expand the Display options and enter the Page Properties ID that was specified in the Page Properties
macro in the template (in this example it was 'status-update-design') – this allows us to report on just
information in that macro.
5. Leave all of the other fields blank (we want to show all columns from this Page Properties macro)
6. Choose Save to add the macro to the page
Screenshot: The page properties report macro on the 'Design Status Report' index page
7. Add any other content, links or images to the page and Save
8. Choose Space Tools > Configure Sidebar > Add Link to add a shortcut to the page on the sidebar
9. Create a new page and repeat this process for each team
Remember to specify a different Page Properties ID each time (in this example 'status-report-dev' and
'status-report-qa').
If your Design, Dev and QA teams have their own team spaces, this summary report could even be created in
their team spaces. Just be sure to specify the space where the Status Updates pages are created in the Restrict
to spaces field, to make sure the macro can find the pages to report on.
Part 4: Create your first status update page
That's it! Create from template in the Confluence header, then select Status Update, or use the Create
a new status update button to make your first status update page. Just like a blueprint, but 100% made by you.
Here's how our finished pages look.
Screenshot: Team Leads and the management team still have a single page for the weekly status update
Screenshot: The Project Lead can see the status of each team, each week, at a glance in the All Teams status
report.
Screenshot: Each team can see their focus, risks and status at a glance in their status report.
Remember, these concepts don't just apply to status updates – you can use them for any purpose at all.
Import Content Into Confluence
There are a number of ways you can get existing
content, such as text, images and other content into On this page:
Confluence.
Import content from other Confluence sites
Import content from other Confluence sites Import content from a Microsoft Word
document
To import content from another Confluence site you Import web content
can: Importing content from another wiki
Import other content
Import a backup of the entire Confluence site Migrate to Confluence Cloud
Import an XML export of an individual space.
Page history, attachments, and page content
will be preserved.
See Restoring a Site and Restoring a Space for more information.
Import content from a Microsoft Word document

The Office Connector allows you to create pages by importing Word documents. The document content is
copied onto one or more Confluence pages. See Import a Word Document into Confluence.
Import web content

To embed web content on a page:
Use the Widget Connector Macro to display videos, slide shows, twitter chats, documents and more,
sourced from other web sites and displayed on your Confluence page.
Embed an external web page into Confluence with the HTML Include macro.
Use HTML code in a page with the HTML macro.
Note: The HTML macro is not enabled in all sites. Talk to your Confluence Admin about whether you can
use this macro.
Importing content from another wiki

Confluence does not provide a method for importing content from another wiki.
You may be able to build your own import solution using our REST APIs, as mentioned below, or work with
an Atlassian Solution Partner to develop a custom solution.
Import other content

Importing non-wiki markup into Confluence requires a conversion process:
Text with basic formatting can be pasted directly into the editor. This includes simple Word documents
or web pages.
Confluence pages saved to disk can be imported from disk.
Files can be uploaded in bulk using the Confluence WebDav Plugin. See Use a WebDAV Client to
Work with Pages.
Build your own import solution using the Confluence APIs.
Migrate to Confluence Cloud

If you're migrating from Confluence Server to Confluence Cloud, you can use the Confluence Cloud
Migration Assistant to migrate your content and spaces.
Import a Word Document into Confluence
The Office Connector allows you to import Word
documents and create one or more Confluence On this page:
pages from the content.
Import a Word document
You can create a single page, or divide the contents
Import options
up into multiple pages, based on the headings in
Supported file types
your document.
Limitations
This is useful if you have a lot of content stored in
Related pages:
existing documents, or if you are migrating from
another system or platform that allows you to export Export Content to Word, PDF, HTML and
to Word format. XML
Import a Word document

To import a Word document in Confluence:
1. Create a page in Confluence or go to an existing page (you want to view the page, not edit it).
2. Choose > Import Word Document
3. Choose Browse and locate the Word document you want to import, then choose Next.
The import document options appear.
4. Enter a title for the new page (useful if you don't want to use the file name as your page title).
5. Choose where you want to import the file (as a brand new page, or overwriting an existing page with
the same title).
6. Choose how to handle title conflicts (rename the new pages or replace existing pages).
7. Choose whether to create a single page or multiple pages based on the heading styles in the file (this
option is only available if the file contains heading styles).
8. Click Import.
When the upload has finished, pages will be created with the content of the Word documents. You can then
view and edit this page as normal. There's no connection between the original Word document and this page.
Import options
There are a number of options when importing a Word document that control how pages are created,
whether the import should overwrite existing pages in the space, and how it should handle page name
conflicts.
Option Description
Root This is the title of the page that will be created or updated by the import.
page
title
Where Controls whether the document is imported into the current page (the page you were viewing
to when you selected Tools > Import) or created as a new page. Choose from
import
Import as a new page in the current space - a new page will be created as a child of the
space home page.
Replace <page name> - content will be imported into the current page. The title of this
page will change to the title you specified in the Root page title field.
Delete existing children of <pagename> - any existing children of the current page will be
removed when the content of the page is replaced.
Title Controls how page name conflicts (a page with the same title already exists in the space) are
conflicts handled.
Rename imported pages if page name already exists - new pages get a new name (a
number added to the end of the page title). Existing pages will be unchanged.
Replace existing pages with imported pages of the same title - overwrite the content of
existing pages. The change will be shown in the Page History for the page.
Remove existing pages with the same title as imported pages - remove original pages
and then create new pages. The change is not shown in the Page History for the page.
Split If the document contains Word heading styles you can choose to create multiple pages based
by on the heading. Options are:
heading
Don't split - creates a single page.
Level Headings - creates multiple pages in a hierarchy based on the heading levels in the
document.
A preview of the pages that will be created appears under Document Outline.
Screenshot: Import Word options for a document that contains multiple heading levels.

Confluence can import the content from Microsoft Word 97-2013 documents (.doc and .docx).
Limitations
In order to prevent out of memory errors, we limit the uncompressed size of the file you can import to 20 MB.
Your administrator can change this limit using the confluence.word.import.maxsize system property.
Undefined Page Links
You can add links to pages that don't yet exist in Confluence, but you intend to create later. Known as links to
'undefined pages', they allow you to create a link which, when clicked, will create a page with the name you
specify in the link.
Create an undefined page link

1. Choose Insert > Link or press Ctrl+K on your keyboard.
2. Choose Advanced.
3. Enter the name of the page to be created in the Link field.
A link to an undefined page is shown in dark red while in the editor. When anyone clicks the link, Confluence will
create a new page with the name you typed in the Link field.
View undefined pages in a space

The Undefined Pages view shows you all undefined pages in your space. The undefined page links are
badged with a icon to remind you that those pages are yet to be created.
To view a list of the undefined links in a space:
2. Choose Undefined Pages.
You can choose the link for an undefined page to create the page and add content to it.
Links to pages that are in the trash are not considered undefined links, and will not appear in this list.
View Page Information
The Page Information view for a page shows you useful information about the page.
To see the information about the page:
1. View the page.

2. Choose > Page Information
You will see the following information:
Page details: Title, author, date of creation, date of last modification and the tiny link (permalink) of the
page.
Page hierarchy: Parent-child relationships of the page.
Incoming links: Lists other pages in your Confluence Site that have links to this page, or reference this
page in an Include Page or Excerpt Include macro.
Labels: Any labels (tags) that have been applied to this page. See Add, Remove and Search for Labels.
Page Permissions: Displays page-level security restrictions that apply to the page (if present). See Page
Restrictions.
Recent Changes: Links to the five most recent versions of the page along with the name of the editor
and the date of modification. See Page History and Page Comparison Views. Choose View page history
to see the page history view, all the versions of the page in reverse chronological order and allows you
to compare versions or to restore a previous version.
Outgoing links: A summary of the links contained on this page, pointing to other pages on the
Confluence site or to external websites.
Note: if there is no information to report (for example the page has no restrictions or no incoming links), that
section of the Page Information won't appear.
Screenshot: Page information for this page

Page History and Page Comparison Views
Confluence tracks the history of changes to each page by creating a new
On this page:
version of the page each time it's modified. You can view the changes
between different versions, and roll back to a previous version if you need
to. Access the page
history
View an older
Access the page history version
Restore a previous
To view the history of a page: version
Delete a specific
1. Go to the page and choose > Page History version
2. Choose a version number to view the content of that version View the changes
made
Screenshot: Page history View unpublished
changes
Compare two
versions
More about the
comparison view
Related pages:
View Page
Information
Create and Edit
Pages
Watch Pages,
Spaces and Blogs
Hover over each avatar to see the names of people who contributed changes in that version. It is not
possible to view the individual changes made by each person in a single page version.
View an older version

When you select a previous version of the page, you'll see a header like this at the top of the page:
If you want to send this page version to someone, copy and paste the URL from your browser. The link
will look something like this: http://confluence.atlassian.com/pages/viewpage.action?
pageId=12345.
When you're viewing a specific version of the page, the following functions are available:
Function Description
current version View the latest version of the page.
Compare with Compare the differences between the version of the page you are viewing and the
Current current version.
Restore this Roll back the content of the page to the previous version that you are viewing.
Version
View Page History Return to the list of page versions.
<< Previous and Ne View the previous or next version of the page.
xt >>
Restore a previous version

2. Choose Restore this version beside the version you want to restore (or at the top of the page if
you've opened the version)
3. Change the default change comment if necessary, and choose OK
All page history is retained; restoring an older version creates a copy of that version. For example, if you
restore version 39, Confluence will create a copy of version 39 and the copy will become the new, current
version.
If the page has an unpublished draft, the content of the draft will be lost when you restore a previous version.
We'll warn you if there is an unpublished draft.
Delete a specific version

Choose Delete next to a version in the page history, to remove that version.
View the changes made

Using the page history view or the page information view, you can see the recent changes made to a page.
To view recent changes made to a page:
1. Choose > Page Information

In the section titled 'Recent Changes' you'll see the most recent versions of the page, along with the
date of their modification and the name of the modifying author.
2. Choose View Changes beside the required version
The page comparison view is displayed, showing the differences between the selected and previous
versions.
View unpublished changes

When you're in the editor, you can see all changes since the page was last published. Go to > View
changes.
Changes are not attributed to individual people. The avatars of everyone who has contributed will be shown
at the top of the editor.
Compare two versions

2. Choose the versions you want to compare by selecting the check boxes beside them
3. Choose Compare selected versions
You'll see the page comparison view showing the differences between the selected versions. Changes are
highlighted as follows:
Highlighted color Meaning
Green Added content
Red Deleted content
Blue Changed formatting
Screenshot: Comparing changes
More about the comparison view

When you view a page comparison, all large sections of unchanged text are hidden and reduced to an
ellipsis (. . .).
You can view page changes between versions which are adjacent to your current page comparison view.
Click the link containing:
<< to view the page comparison with the earlier adjacent version
>> to view the page comparison with the more recent adjacent version
For example, if your page comparison view is between v. 30 and v. 34 of a page, you can view changes
between:
v. 29 and v. 30 by clicking << Changes from 29 to 30

v. 34 and v. 35 by clicking Changes from 34 to 35 >>
Confluence Markup
This section describes two types of markup found in Confluence:
Related pages:
Confluence storage format. Confluence stores the content of
pages and blog posts in an XHTML-based format. Advanced users Macros
can view the storage format of a page and even edit it, provided their The Editor
Confluence site is configured to allow that.
Wiki markup. Confluence allows data entry via a shorthand code
called wiki markup. Some parts of the Confluence administration
interface also accept wiki markup for defining content. For a
description of the wiki markup syntax, see Confluence Wiki Markup.
Wiki markup code examples for macros can be found in the documentation
for each macro.
Confluence Storage Format
This page describes the XHTML-based format that Confluence uses to
On this page:
store the content of pages, page templates, blueprints, blog posts and
comments. This information is intended for advanced users who need to
interpret and edit the underlying markup of a Confluence page. Headings
Text effects
We refer to the Confluence storage format as 'XHTML-based'. To be Text breaks
correct, we should call it XML, because the Confluence storage format does Lists
not comply with the XHTML definition. In particular, Confluence includes Links
custom elements for macros and more. We're using the term 'XHTML- Images
based' to indicate that there is a large proportion of HTML in the storage Tables
format. Page layouts
Resource identifiers
You can view the Confluence storage format for a given page by choosing Template variables
> View Storage Format. This option is only available if one of the Instructional Text
following is true:
You are a Confluence administrator.

Your Confluence site has the Confluence Source Editor plugin
installed and you have permission to use the source editor.
If you would like to edit the storage format for a page, your
Confluence system administrator will need to install the Confluence
Source Editor plugin.
Clarification of terminology: If you choose > View Source, you'll
see the format used within the editor panel, not the storage format of
the page.
Headings
Format type In Confluence 4.0 and later What you will get
Heading 1 <h1>Heading 1</h1>
Headings 4 to 6 are also available and follow the same pattern
Text effects
strong/bold <strong>strong text</strong> strong
emphasis <em>Italics Text</em> emphasis

strikethrough <span style="text-decoration: strikethrough

line-through;">
strikethrough</span>
underline <u>underline</u> underline
superscript superscript
<sup>superscript</sup>
subscript <sub>subscript</sub> subscript
monospace <code>monospaced</code> monospaced
preformatted <pre>preformatted text</pre>

preformatted text
block quotes <blockquote>

<p>block quote</p>
</blockquote> block quote
text color <span style="color: rgb(255,0,0);">red text red text

</span>
small <small>small text</small> small text
big <big>big text</big> big text
center-align <p style="text-align: center;">centered text centered text

</p>
right-align <p style="text-align: right;">right aligned text right aligned text

</p>
Text breaks
New paragraph <p>Paragraph 1</p> Paragraph 1
<p>Paragraph 2</p> Paragraph 2
Line break Line 1 <br /> Line 2 Line 1

Line 2
Note: Created in the editor using Shift + Return/Enter
Horizontal rule <hr />
— symbol — —
– symbol – –
Lists
Unordered list – round <ul>

bullets Round bullet list
<li>round bullet list item</li> item
</ul>
Ordered list (numbered list) <ol>

1. Ordered list item
<li>numbered list item</li>
</ol>
Task Lists <ac:task-list>

<ac:task> task list item
<ac:task-status>incomplete</ac:task-
status>
<ac:task-body>task list item</ac:task-
body>
</ac:task>
</ac:task-list>
Links
Format type In Confluence 4.0 and later What you will

get
Link to another <ac:link> Link to another

Confluence page <ri:page ri:content-title="Page Title" /> Confluence page
<ac:plain-text-link-body>
<![CDATA[Link to another Confluence Page]]>
</ac:plain-text-link-body>
</ac:link>
Link to an attachment <ac:link> Link to an

<ri:attachment ri:filename="atlassian_logo.gif" /> attachment
<![CDATA[Link to a Confluence Attachment]]>
</ac:link>
Link to an external site <a href="http://www.atlassian.com">Atlassian</a> Atlassian
Anchor link (same page) <ac:link ac:anchor="anchor"> Anchor Link

<![CDATA[Anchor Link]]>
</ac:link>
Anchor link (another <ac:link ac:anchor="anchor"> Anchor Link

page) <ri:page ri:content-title="pagetitle"/>
<![CDATA[Anchor Link]]>
</ac:link>
Link with an embedded <ac:link ac:anchor="Anchor Link">

image for the body <ac:link-body>
<ac:image><ri:url ri:value="
http://confluence.atlassian.com/
images/logo/confluence_48_trans.png" /></ac:image>
</ac:link-body>
</ac:link>
For rich content like images, you need to use ac

:link-body to wrap the contents.
A note about link bodies
All links received from the editor will be stored as plain text by default, unless they are detected to contain
the limited set of mark up that we allow in link bodies. Here are some examples of markup we support in link
bodies.
An example of different link bodies
<ac:link>

<ri:page ri:content-title="Home" ri:space-key="SANDBOX" />
<ac:link-body>Some <strong>Rich</strong> Text</ac:link-body>
</ac:link>
<ac:link>
<ri:page ri:content-title="Plugin developer tutorial stuff" ri:space-key="TECHWRITING" />
<ac:plain-text-link-body><![CDATA[A plain <text> link body]]></ac:plain-text-link-body>
</ac:link>
<ac:link>
<ri:page ri:content-title="Plugin developer tutorial stuff" ri:space-key="TECHWRITING" />

</ac:link>
The markup tags permitted within the <ac:link-body> are <b>, <strong>, <em>, <i>, <code>, <tt>, <sub>,
<sup>, <br> and <span>.
Images
Attached <ac:image>
image <ri:attachment ri:filename=
"atlassian_logo.gif" />
</ac:image>
External image <ac:image>

<ri:url ri:value="http://confluence.atlassian.
com/
images/logo/confluence_48_trans.png" /></ac:
image>
Supported image attributes (some of these attributes mirror the equivalent HTML 4 IMG element):
Name Description
ac:align image alignment
ac:border Set to "true" to set a border
ac:class css class attribute.
ac:title image tool tip.
ac:style css style
ac:thumbnail Set to "true" to designate this image as a thumbnail.
ac:alt alt text
ac:height image height
ac:width image width
ac:vspace the white space on the top and bottom of an image
ac:hspace the white space on the left and right of an image
Tables
Format type In Confluence 4.0 What you will get

and later
Two column, two row (top header row) <table> Table Table
<tbody>
Heading Heading
Cell 1 Cell 2
<tr>
Normal Cell 1 Normal Cell 2
<th>Table Heading
Cell 1</th>
<th>Table Heading
Cell 2</th>
</tr>
<tr>
<td>Normal Cell 1<

/td>
<td>Normal Cell 2<

/td>
</tr>
</tbody>
</table>
Two column, three rows, 2nd and third with <table> Table Table
merged cells in first row
<tbody>
Heading Heading
Cell 1 Cell 2
<tr>
Merged Cell Normal Cell 1
<th>Table Heading
Cell 1</th> Normal Cell 2
<th>Table Heading
Cell 2</th>
</tr>
<tr>
<td rowspan="2"
>Merged Cell</td>
<td>Normal Cell 1<

/td>
</tr>
<tr>
<td colspan="1"
>Normal Cell 2</td>
</tr>
</tbody>
</table>
Page layouts
Confluence supports page layouts directly, as an alternative to macro-based layouts (using, for example, the
section and column macros). This section documents the storage format XML created when these layouts
are used in a page.
Element In Confluence 5.2 and later Attributes

name
ac: Indicates that the page has a layout. It should be the top level element in the None
layout page.
ac: Represents a row in the layout. It must be directly within the ac:layout tag. ac:type
layout- The type of the section indicates the appropriate number of cells and their
section relative widths.
ac: Represents a column in a layout. It must be directly within the ac:layout- None
layout- section tag. There should be an appropriate number of cells within the layout-
cell section to match the ac:type.
The recognized values of ac:type for ac:layout-section are:
ac:type Expected number of Description

cells
single 1 One cell occupies the entire section.
two_equal 2 Two cells of equal width.
two_left_sidebar 2 A narrow (~30%) cell followed by a wide cell.
two_right_sideba 2 A wide cell followed by a narrow (~30%) cell.

r
three_equal 3 Three cells of equal width.
three_with_sideb 3 A narrow (~20%) cell at each end with a wide cell in

ars the middle.
The following example shows one of the more complicated layouts from the old format built in the new. The
word {content} indicates where further XHTML or Confluence storage format block content would be
entered, such as <p> or <table> tags.
<ac:layout>
<ac:layout-section ac:type="single">
<ac:layout-cell>
{content}
</ac:layout-cell>
</ac:layout-section>
<ac:layout-section ac:type="three_with_sidebars">
<ac:layout-cell>
{content}
</ac:layout-cell>
<ac:layout-cell>
{content}
</ac:layout-cell>
<ac:layout-cell>
{content}
</ac:layout-cell>
<ac:layout-section ac:type="single">
<ac:layout-cell>
{content}
</ac:layout-cell>
</ac:layout>
Emoticons
Emoticons <ac:emoticon ac:name="smile" />
<ac:emoticon ac:name="sad" />
<ac:emoticon ac:name="cheeky" />
<ac:emoticon ac:name="laugh" />
<ac:emoticon ac:name="wink" />
<ac:emoticon ac:name="thumbs-up" />
<ac:emoticon ac:name="thumbs-down" />
<ac:emoticon ac:name="information" />
<ac:emoticon ac:name="tick" />
<ac:emoticon ac:name="cross" />
<ac:emoticon ac:name="warning" />
Resource identifiers
Resource identifiers are used to describe "links" or "references" to resources in the storage format.
Examples of resources include pages, blog posts, comments, shortcuts, images and so forth.
Resource Resource identifier format
Page <ri:page ri:space-key="FOO" ri:content-title="Test Page"/>
Notes:
ri:space-key: (optional) denotes the space key. This can be omitted to create a
relative reference.
ri:content-title: (required) denotes the title of the page.
Blog Post <ri:blog-post ri:space-key="FOO" ri:content-title="First Post" ri:posting-day="2012/01

/30" />
Notes:
ri:space-key: (optional) denotes the space key. This can be omitted to create a
relative reference.
ri:content-title: (required) denotes the title of the page.
ri:posting-day: (required) denotes the posting day. The format is YYYY/MM/DD.
Attachment <ri:attachment ri:filename>

... resource identifier for the container of the attachment ...
</ri:attachment>
Notes:
ri:filename: (required) denotes the name of the attachment.

the body of the ri:attachment element should be a resource identifier denoting the
container of the attachment. This can be omitted to create a relative attachment
reference (similar to [foo.png] in wiki markup).
Examples:
Relative Attachment Reference
<ri:attachment ri:filename="happy.gif" />
Absolute Attachment Reference
<ri:attachment ri:filename="happy.gif">
<ri:page ri:space-key="TST" ri:content-title="Test Page"/>
</ri:attachment>
URL <ri:url ri:value="http://example.org/sample.gif"/>
Notes:
ri:value: (required) denotes the actual URL value.
Shortcut <ri:shortcut ri:key="jira" ri:parameter="ABC-123">
Notes:
ri:key: (required) represents the key of the Confluence shortcut.

ri:parameter: (required) represents the parameter to pass into the Confluence
shortcut.
The example above is equivalent to [ABC-123@jira] in wiki markup.
User <ri:user ri:userkey="2c9680f7405147ee0140514c26120003"/>
Notes:
ri:userkey: (required) denotes the unique identifier of the user.
Space <ri:space ri:space-key="TST"/>
Notes:
ri:space-key: (required) denotes the key of the space.
Content <ri:content-entity ri:content-id="123"/>

Entity
Notes:
ri:content-id: (required) denotes the id of the content.
Template variables
This screenshot shows a simple template:
The template contains the following variables:
Variable name Type Values
$MyText Single-line text
$MyMulti Multi-line text Size: 5 x 100
$MyList List List items: Apples,Pears,Peaches
The XML export produces the following code for the template:
<at:declarations>
<at:string at:name="MyText" />
<at:textarea at:columns="100" at:name="MyMulti" at:rows="5" />
<at:list at:name="MyList">
<at:option at:value="Apples" />
<at:option at:value="Pears" />
<at:option at:value="Peaches" />
</at:list>
</at:declarations>
<p>This is Sarah's template</p>
<p>A single-line text variable: <at:var at:name="MyText" /></p>
<p>A multi-line text variable: <at:var at:name="MyMulti" /></p>
<p>A selection list: <at:var at:name="MyList" /></p>
<p>End of page.</p>
Instructional Text
Instructional text allows you to include information on how to fill out a template for an end-user (the person
using creating a page from the template). Instructional text will:
automatically clear all instructional text as the user types in a specific text block, and
automatically trigger a @mention prompt for user selection (for 'mention' type instructional text).
Screenshot: Example of instructional text.
<ul>
<li><ac:placeholder>This is an example of instruction text that will get replaced when a user selects
the text and begins typing.</ac:placeholder></li>
</ul>
<ac:task-list>
<ac:task>
<ac:task-status>incomplete</ac:task-status>
<ac:task-body><ac:placeholder ac:type="mention">@mention example. This placeholder will
automatically search for a user to mention in the page when the user begins typing.</ac:placeholder></ac:
task-body>
</ac:task>
</ac:task-list>
Confluence Wiki Markup
This page describes the wiki markup used on some administration screens
On this page:
in Confluence.
Wiki markup is useful when you want to do one of the following: Can I type wiki
markup into the
Type wiki markup directly into the editor. Confluence will convert it to editor?
the rich text editor format as you type. Can I insert
Create links using the Advanced tab of the Links Browser. markdown?
Add custom content to the sidebar, header or footer of a space. Headings
Insert a block of wiki markup (or markdown) into the Confluence Lists
editor. (Choose Insert > Markup.) Tables
Text Effects
Note: You cannot edit content in wiki markup. Confluence does not Text Breaks
store page content in wiki markup. Although you can enter wiki markup into Links
the editor, Confluence will convert it to the rich text editor format Images
immediately. You will not be able to edit the wiki markup after initial entry. Page Layouts
Macros
Can I type wiki markup into the editor?
Yes. You can type wiki markup directly into the editor, and Confluence will convert it as you type. (You
cannot edit the wiki markup after conversion.) See it in action in this video:
Can I insert markdown?

Confluence supports inserting content in markdown. This is often used in ReadMe files. See Markdown
syntax guide for some examples of markdown syntax.
To insert markdown in the editor:
1. Choose Insert > Markup

2. Select Markdown
3. Type or paste your text - the preview will show you how it will appear on your page
4. Choose Insert.
As with wiki markup, Confluence will convert your markdown to the rich text editor format. You will not be
able to edit your content using markdown.
Headings
To format a line as a heading, type "hn." at the start of your line, where n can be a number from 1 to 6.
What you need to type What you'll get
h1. Biggest heading

Biggest heading
h3. Big heading Big heading
h5. Small heading Small heading
Lists
Wiki markup allows you to create bulleted or numbered lists, and is flexible enough to allow a combination of
the two list types.
If you need to separate the text within lists using line breaks, make sure you do so using a double slash (
//). Empty lines may disrupt the list.
Simple lists
Use the hyphen (-) to create simple lists with square bullets. Make sure there's a space between the hyphen
and your text.
- some
- bullet some
- points bullet
points
Bulleted lists
Use the asterisk (*) to create bullets. For each subsequent level, add an extra asterisk.
Make sure there is a space between the asterisk and your text.
* some
* bullet some
** indented bullet
** bullets indented
* points
bullets
points
Numbered lists
Use the hash (#) to create numbered lists.

Make sure there is a space between the hash and your text.
# a
# numbered 1. a
# list 2. numbered
3. list
A second level of hashes will produce a sub-list, such as the alphabetical sub-list shown below.
# Here's a sentence.
## This is a sub-list point. 1. Here's a sentence.
## And a second sub-list point. a. This is a sub-list point.
# Here's another sentence. b. And a second sub-list point.
2. Here's another sentence.
You can use a third level of hashes to produce a sub-sub-list.
# Here's a sentence.
## This is a sub-list point. 1. Here's a sentence.
### Third list level. a. This is a sub-list point.
### Another point at the third level. i. Third list level.
## And a second sub-list point.
ii. Another point at the third level.
# Here's another sentence.
b. And a second sub-list point.
2. Here's another sentence.
Note: In numbered lists as described above, the format of the 'number' displayed at each list level may be
different, depending upon your browser and the style sheets installed on your Confluence instance. So in
some cases, you may see letters (A, B, C, etc; or a, b, c, etc) or Roman numerals (i, ii, iii, etc) at different list
levels.
Mixed lists
# Here
#* is 1. Here
#* an is
# example an
#* of
2. example
#* a
# mixed
of
# list a
3. mixed
4. list
Tables
You can create two types of tables.
Table Type 1
Allows you to create a simple table with an optional header row. Once you've added this type of table, you
can set the width of the columns using the table controls in the toolbar.
Use double bars for a table heading row.
What you need to type:
||heading 1||heading 2||heading 3||

|cell A1|cell A2|cell A3|
|cell B1|cell B2|cell B3|
What you'll get:
heading 1 heading 2 heading 3
cell A1 cell A2 cell A3
cell B1 cell B2 cell B3
You can also use a vertical header.
What you need to type:
||heading 1|col A1|col A2|col A3|

||heading 2|col B1|col B2|col B3|
What you'll get:
heading 1 col A1 col A2 col A3
heading 2 col B1 col B2 col B3
Table Type 2
This method uses section and column macros to create the table, and allows you to specify the width of the
columns in the markup.
What you need to type
{section:border=true}
{column:width=30%}
Text for this column goes here. This is the smaller column with a width of only 30%.
{column}
{column:width=70%}
Text for this column goes here. This is the larger column with a width of 70%.
{column}
{section}
What you'll get

Text for this column goes here.
This is the smaller column with
a width of only 30%.
Text for this column goes here. This is the larger column with a width of
70%.
For more details please see the Column Macro and the Section Macro.
Advanced Formatting
Color and Other Formatting
To add color and other formatting to your tables, you can use the Panel Macro within columns.
More table-formatting options may be available if your Confluence administrator has installed additional macr
os.
Lists
Here's an example of how to embed lists in a table:
What you need to type
||Heading 1||Heading 2||

|* Item 1
* Item 2
* Item 3|# Item 1
# Item 2
# Item 3|
What you'll get
Heading 1 Heading 2
Item 1 1. Item 1
Item 2 2. Item 2
Item 3 3. Item 3
Text Effects
Use the markup shown in the examples below to format text.
*strong* strong
*bold text* bold text
_emphasis_ emphasis
_italics_ italics
Hint: To italicize parts of a word, add braces (curly
brackets) around the underscore. For example,
Thing{_}x_
gives you this: Thingx
??citation?? citation
-deleted- deleted
+inserted+ inserted
Text with^superscript^ Text withsuperscript
Hint: There are two ways to make superscripts work,

when used directly after another word or character:
Add a space before the superscript. For example, kg

/m ^3^ gives you this: kg/m 3
Add braces (curly brackets) around the superscript
markup. For example,
kg/m{^3^}
gives you this: kg/m3
Text with~subscript~ Text withsubscript
{{monospaced}} monospaced
bq. Here's how you make a

paragraph appear as a block
quotation. Here's how you make a paragraph
appear as a block quotation.
{color:red}look ma, red text!{color} look ma, red text!
Text Breaks
Paragraph Break
In wiki markup, a paragraph is a continuous line of text ending in two carriage returns. This is equivalent to a
continuous line of text followed by a blank line.
When rendered into HTML, the result is a line of text wrapped in a set of <p></p> tags.
Line Break
Confluence provides two options for forcing a line break within a paragraph of text:
Implicitly, by entering a single carriage return at its end.
Explicitly, by entering two consecutive backslashes: \\
When rendered into HTML, the result is a paragraph of text that is split into separate lines by <br> tags,
wherever a forced line break appears.
For most purposes, explicit line breaks are not required because a single carriage return is enough.
The examples below show how to use explicit line breaks.
here is some text here is some text

divided
\\
using line
divided \\
breaks
using line \\ \\
breaks\\
This is a short list: This is a short list:

* Point 1
Text to go with point 1 Point 1
* Point 2 Text to go with point 1
Point 2
\\ \\
Text to go with point 2 with a break
Text to go with point 2 with a break
If you wish to use multiple consecutive line breaks, each should be separated by a space character. For
example, use this for two consecutive line breaks:
\\ \\
Horizontal Rule
To create a horizontal line across the width of your page or content block, type four dashes (like this: ----) at
the beginning of a line, then press Enter or space.
Make sure that the dashes are on a separate line from the rest of the text.
here is some text here is some text

----
divided by a horizontal rule
divided by a horizontal rule
Links
You can use wiki markup to add hyperlinks to your text.
[#anchor] A link to an anchor on the same page.
[Confluence Wiki A link to a file attached to the page.

Markupâttachment.ext]
[pagetitle] A link to a page.
[pagetitle#anchor] A link to an anchor on another page.
[pagetitleâttachment.ext] A link to a file attached to another page.
[spacekey:pagetitle] A link to a page in another space.
[spacekey:pagetitle#anchor] A link to an anchor on a page in another space.
[spacekey: A link to a file attached to a page in another space.

pagetitleâttachment.ext]
[/2004/01/12/blogposttitle] A link to a blog post.

Note: blogposttitle is the title of the blog as it appears on the page.
[spacekey:/2004/01/12 A link to a blog post in another space.

/blogposttitle] Note: blogposttitle is the title of the blog as it appears on the page.
[/2004/01/12] A link to a whole day's blog posts.
[spacekey:/2004/01/12] A link to a whole day's blog posts in another space.
[spacekey:] A link to the space homepage (or the space summary page of the space.
[~username] A link to the user profile page of a particular user.
[phrase@shortcut] A shortcut link to the specified shortcut site. Shortcuts are configured by
the site administrator.
[http://confluence.atlassian. A link to an external resource.

com]
[mailto: A link to an email address.

legendaryservice@atlassian.
com]
[file://z:/file/on/network/share. A link to a file on your computer or on a network share that you have
txt] mapped to a drive. This only works on Internet Explorer.
[!http://external/image.png! Displays an external image and links to an external URL.

|http://external/link.html]
Note that Confluence treats headings as anchors, so you can link to headings using this pattern: [spacekey:
pagename#headingname], where headingname is case-sensitive and must be entered without spaces.
For each of these link forms:
You can prepend a link alias, so that alternate text is displayed on the page. Example: [link
alias|pagetitle#anchor]
You can append a link tip, which appears as a tooltip. Example: [pagetitle#anchor|link tip]
Images
You can display images from attached files or remote sources.
What you What you'll get

need to
type
!http://www. An image from a remote source is displayed on the page. Uses a fully qualified URL.
host.com
/image.gif!
!attached- An image file attached to the page is displayed.

image.gif!
! An image file attached to a different page is displayed.

pageTitleîm
age.gif!
!spaceKey: An image file attached to a page in a different space is displayed.

pageTitleîm
age.gif!
!/2010/05/23 An image file attached to a blog post is displayed.

/My Blog
Postîmage.
gif!
!image. The image is displayed as a thumbnail on the page (only works with images that are
jpg|thumbnai attached to the page). Users can click on the thumbnail to see the full-sized image.
l! Thumbnails must be enabled by the site administrator for this to work.
!image. For any image, you can specify attributes of the HTML image tag as a comma separated
gif|align=righ list of name=value pairs.
t, vspace=4!
Available HTML image tags include:
Image Details
tag
align Available values are 'left', 'right', 'bottom', 'center', 'top'.
border Specifies the width of the border (in pixels).
borderc Use with the 'border' tag. Specify colors by name or hex value.
olor
hspace Specifies the amount of whitespace to be inserted to the left and right of the image (in pixels).
vspace Specifies the amount of whitespace to be inserted above and below the image (in pixels).
width Specifies the width of the image (in pixels). This will override the natural width of the image.
height Specifies the height of the image (in pixels). This will override the natural height of the image.
title Specifies alternate text for the image, which is displayed when the pointer hovers over the
image.
alt Specifies alternate text for the image. This text is retrievable via search, and contributes to
accessibility of the page for text-only viewing.
Page Layouts
There is no wiki markup representation for page layouts.
Macros
Storage format and wiki markup examples have been included in the documentation for each macro.
Files
Share your team's PDFs, Office documents, images, and more in one place
by uploading your files to Confluence. Automatic versioning, instant On this page:
previews, permissions, and full-text search, means shared network drives
can be a thing of the past for your team.
Using Files
When you upload a file it is attached to the current page or blog post. This Permissions
is why files are often referred to as attachments in Confluence.
Related pages:
You can attach anything from project plans and design mockups to video
and audio files. You and your colleagues can also collaborate by commentin Configuring
g on files displayed on Confluence pages. Attachment Size
Configuring your
Attachment Storage
Using Files
Upload Files
Display Files and Images
Manage Files
Share and Comment on Files
Edit Files
Edit in Office using the Office Connector
Install Atlassian Companion
Permissions
The 'Add Attachment' and 'Delete Attachment' permissions are used to control who can upload and delete
attachments in a space.
Users with 'Add Page' or 'Add Blog' permissions can insert existing attachments to their pages, but not
upload new attachments unless they also have the 'Add Attachment' permission.
There is no permission that controls downloading attachments. See our knowledge base article about disabli
ng the download of attachments if you need to do this.
Upload Files
When you upload a file, such as an image or
On this page:
document, it will be attached to the current page.
You can then choose to display the file on the page Upload a file
as a link, an image or embed it in the page (using a Accepted file types and size
macro). What happens after a file is uploaded?
Notes
To upload a file you'll need the 'Add Attachments'
space permission. Related pages:
Files
Upload a file Configuring Attachment Size
Manage Files
There are many ways to attach a file to a page.
In the editor you can:
Drag the file directly onto the page.

Go to Insert > Files and images and upload
a file.
When viewing a page you can:
Drag the file directly onto the page.

Go to > Attachments and upload a file.
You can attach multiple files at a time.
Accepted file types and size

Confluence allows you to attach most file types, but you cannot attach a folder of files (including folders
created by applications like Keynote - you'll need to export your presentation to zip or other format).
Although just about any file type can be attached to a page, not all file types can be displayed on or
embedded in a page. See Display Files and Images to find out more.
The maximum file size you can upload to Confluence is set by your system administrator. By default it's
100mb, but your administrator may have increased or reduced this limit.
File versions
If you upload a file with the same name as an existing attachment on the same page, Confluence will
overwrite the existing attachment. Version history is kept for all attachments. See Manage Files to find out
more.
Any changes you make to the source file will not affect the copy that was uploaded to Confluence. To update
the Confluence copy, you need to upload the new version of the file.
What happens after a file is uploaded?
Text extraction and indexing
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.
See Configuring Attachment Size for more information on how files are indexed.
Thumbnail and preview generation

When you insert an uploaded 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.
Because this process can be very memory intensive, a 30 second time limit applies when performing
document conversion for complex image or presentation files (such as PPT, PPTX, EMF, WMF). Your
administrator can increase or decrease this timeout using the confluence.document.conversion.
imaging.convert.timeout or confluence.document.conversion.slides.convert.timeout sy
stem properties.
Thumbnails are not generated for TIFF or PSD (Photoshop) files by default. Your administrator can override
this behaviour using the confluence.document.conversion.imaging.enabled.tif or confluence
.document.conversion.imaging.enabled.psd system properties.
In Confluence Server, document conversion is handled by Confluence. In Confluence Data Center this
process is externalised, to minimise the impact on individual Confluence nodes. See Document conversion
for Confluence Data Center to find out about how this affects thumbnail and preview generation.
Notes
We recommend you don't use special characters in page or attachment names, as the page or
attachment may not be found by Confluence search, and may cause some Confluence functions to behave
unexpectedly.
Files can be displayed on a page as a thumbnail or as a link. There are a
few different ways to Upload Files. On this page:
You can control how the file appears on your page. The options available
Insert a file into
depend on the type of file.
your page
Insert a file
Insert a file into your page attached to
another page
There's a few ways to insert a file into your page: Insert an
image file
Go to Insert > Files on the editor toolbar and select any of the from the web
previously uploaded files, or Delete files
Drag the file directly into the editor (this will upload and insert the file from your
in one step), or page
Type ! and choose an attached file from the autocomplete drop down. Preview a file
Office and PDF files
Your file will appear on your page as a thumbnail. Click the thumbnail to Image files
resize it or to switch to showing the file as a link. Multimedia files
Show a list of files
on a page
Related pages:
Links
Manage Files
Edit Files
Insert a file attached to another page
You can display a file that's attached to a different page of the same Confluence site, if you know the name
of the file.
To display an image attached to a different page:
1. Go to Insert > Files and choose the Search on other pages.

2. Enter the name of the file.
3. Choose whether to search the current space or All Spaces and choose Search.
4. Select the file from the search results and choose Insert.
Insert an image file from the web
You can display an image from a remote web page on your Confluence page, without needing to attach it to
your page. You need to know the URL for the image, not for the web page it appears on. This is only
available for image files, not other types of files (like documents).
To display an image from a web page:
1. While editing the page, position the cursor where you want to place the image.
2. Choose Insert > Files and choose Images from the web.
3. Enter a URL for the image. (example: http://atlassian.wpengine.netdna-cdn.com/wp-content/uploads
/AtlassianBushRegeneration-12January2012-083-trunc.jpg
4. Choose Preview to check that the URL and image are correct.
5.
5. Choose Insert.
Delete files from your page
If you delete a file or image in the editor, the attached file will not be deleted. Go to > Attachments to
delete the attachment completely from the page.
Seeing an 'unknown attachment' placeholder on your page? This means that the attached file has been
deleted from the page (or another page).
Preview a file
Click an image, file thumbnail or link when viewing a page to launch the preview.
The preview includes images from the web that are displayed on the page and files that are attached to the
page (even if they are not currently displayed on the page).
In the preview you can:
Download the image file.

Upload a new version of the file (attached files only).
Comment on the file.
Choose to edit the file with a desktop application.
Zoom in, out or fit the image to the width of your browser.
Browse like a slideshow using the next and back buttons.
See other files attached to the page and select a thumbnail to preview that file.
Switch to a full screen presentation mode.
Many file types can be previewed, including Office files, PDFs and many image types.
Images files Office files Other files
JPEG DOC PDF

PNG DOCX MP3
TIFF PPT MP4
PSD PPTX
WMF XLS
EMF XLSX
ICO
ICNS
1. See more files: see other files also attached to this page.
2. Manage this file: download the file, upload a new version or share with your team.
3. Add a comment: drag the pin to comment on the file.
Office and PDF files

Inserting a file in a page is a great way to make useful documents, spreadsheets, presentations and other
files available to your team.
As with all file types, you can choose to insert the file as a link, or as a thumbnail. The thumbnail shows a
preview of the document's contents, and can be resized.
To view an Office or PDF file, click the link or thumbnail to see the full preview (no need to have Excel, Word
or PowerPoint installed). Alternatively, use the Download button in the preview to download the file and view
offline.
You can even edit and comment on Office and PDF files.
Image files
When editing the page, select an image to show the image properties panel. The panel allows you to set the
display size, add a border and effects and link the image to other pages.
From the image properties panel you can:
Choose a preset size for the image

Enter a width for the image (between 16px and 900px)
Add a border around the image

Link the image to a page or URL
Align the image (you can use the left and right align buttons to make the text wrap around the image
too)
Add a title, which is shown when you hover over the image (go to Properties > Title)
Add alt text, which is used by screen readers and when the image can't be shown (go to Properties >
Title)
Add effects to the image such as drop shadow or snapshot (go to Properties > Effects).
To add a caption to an image using the Instant

Camera effect:
Choose Effects in the image properties panel

and choose the Instant Camera image effect.
Save the page.
Go to > Attachments to go to the
'Attachments' view of the page.
Choose Properties next to the image file.
Add a comment to the attachment. The text in
your comment will appear as the image caption.
You will need to re-enter the comment each time you

upload a new version of the image.
Note: The Instant Camera effect only works with Latin

character languages, due to a lack of handwriting style
fonts in multi-byte languages.
Note about image effects
Displaying image effects can be resource intensive. Confluence will prevent users from applying an image
effect if the image is very large (based on data size and dimensions in pixels).
Confluence also limits the threads that are dedicated to displaying image effects so that it does not impact
your whole instance. If a thread is not available, Confluence will display the image without the effect. See Im
age effects are not displayed in Confluence 5.5 or later if you need to adjust the number of threads.
Multimedia files
The file preview also supports MP3 audio and MP4 video files. It uses HTML5 to play attached audio and
video files. This means the file types people can play in the preview depends on the audio and video formats
their browser supports.
You can also display a wider range of multimedia files (video, audio and animation) using the Multimedia
Macro.
Display online video (such as YouTube or Vimeo videos) using the Widget Connector Macro.
Show a list of files on a page

There are several ways you can display a list of files on a page. You can:
Use the Attachments Macro to show files attached to the current page.
Use the Space Attachments Macro to show all files in a space.
Use the Gallery Macro to show thumbnails of images attached to a page.
You can also use the File List blueprint for uploading, viewing and managing lists of files.
Manage Files
Files are attached to Confluence pages. See Upload
On this page:
Files to find out about attaching files to pages.
Once attached you can download, delete and edit Download attached files
these files, for example if you need to upload a new Delete an attached file
version of the file, or change the page it is attached Upload a new version of an attached file
to. Move a file to another page
Edit properties of an attached file
Download attached files View all attached files in a space
Any user with permission to view a page can also

download any files attached to that page. Related pages:
To download an individual file: Files

Click the Download button in the file
preview, or
Go to > Attachments
and then right click on the file name and save
the link.
To download all files attached to a page as a zip

file:
1. Go to > Attachments
2. Click Download All.
There's no option to download all attachments in a

space.
Delete an attached file
You'll need the 'Delete Attachment' space permission to delete an attached file.
To delete all versions of an attached file:
1. Go to the page that contains the attachment.

3. Choose Delete next to the attachment you want to delete.
4. Choose Delete to confirm your action.
Deleted files can be restored from the trash. You'll need to be a space admin to do this.
Space Admins can also delete specific versions of an attachment:
2. Click the expand arrow next to the attachment name to see the list of attachment versions
3. Choose Delete next to the version you want to delete.
Deleted file versions are not recoverable from the trash.
Screenshot: Attachments and attachment versions

Upload a new version of an attached file

There are two ways up upload a new version of an attached file. You can:
Upload a file with the same file name to the page.

Use the Upload a new version button in the file preview to upload a file with a different name (for
images and PDFs only).
To view attachment versions:
Go to > Attachments
Click the expand arrow next to the attachment name.
All earlier versions of the file will appear.
You can't revert to an earlier version of the file, but you can choose to remove earlier versions if you have
Space Administrator permissions.
Move a file to another page

You'll need the 'Add Page', 'Add Attachment' and 'Remove Attachment' space permissions to move an
attached file to another page.
To change the page that a file is attached to:
Go to > Attachments
Choose Properties next to the attachment you want to move.
Enter the name of the page you want to move the attachment to (for example My Destination
Page).
Choose Save.
If you want to move the file to a page in another space, add the space key before the page name (for
example DOC:My Destination Page).
Edit properties of an attached file

You'll need the 'Add Attachment' permission in the space to edit the file properties.
To edit the properties of an attached file:
Go to > Attachments
Click Properties beside the attachment you want to edit.
You can:
change the file name

add a comment (used in the version list and also by the Snapshot image effect)
change the MIME type
move the attachment to another page
add a label.
Changing the MIME type may cause your file to display incorrectly.
View all attached files in a space

There are two ways you can view all files in a space. You can:
Use the Space Attachments macro to display the list of files on a page.
Go to the space and choose Space tools > Content Tools from the bottom of the sidebar Then
choose Attachments.
You can use the filters to only show files with a particular label or file extension.
Screenshot: Space attachments macro
Share and Comment on Files
Collaboration doesn't just happen on pages; often you'll need to collaborate
On this page:
with your team on documents, presentations, images and spreadsheets.
Whether it's mockups for a new marketing campaign or a full project plan,
you can simplify your team's feedback loop by working together on files in Share a file
Confluence. Comment on a file
Share a file Related pages:

Files
Do you have lots of files on a page and want to get a team member's input
Edit Files
on just one of them? You can share the file with them directly.
Display Files and
Images
It works just like sharing a page:
Comment on
pages and blog
1. Click the thumbnail or link to preview the file.
posts
2. Choose the Share button.
3. Enter an email address, user name or group name, add your
message and send.
Your team members will get an email with your message and a link to view
the file.
Share notifications are only sent by email, they won't appear in the workbox .
Comment on a file
Whether it's an image – like a mockup of the new marketing campaign that needs feedback – a PDF, a
presentation, or any other file you can preview in Confluence, you can drop a pin anywhere on the preview
and add your comment to start a conversation.
To comment on a file:

2. Drag the pin icon from the bottom of the preview and drop it where you want to comment.
3. Add your comment and Save.
Pinned comments work just like inline comments on pages. You can use @mentions and links, and drop as
many pins as you need on any part of the file. You can even add simple macros such as the code macro
using wiki markup autocomplete. Anyone with permission to add comments to the page can add and reply to
comments on a file.
When you preview a file, you'll see pins for any existing comments on that version of the file. Select a pin to
view the comment.
Once the conversation is finished, you can resolve the comment to hide it (and any replies) from view. If you
need to see resolved comments again, you can reopen them. Go to > Resolved comments in the
preview.
1. Resolved comments: Choose the 'more options' button to show or hide resolved comments.
2. Comments: Drag a pin onto a file to comment.
You can't comment on files that are hosted on a web server and added to Confluence using their
URL, or on files that can't be viewed in the preview (such as videos, zip files, and some other file
types).
What happens to comments when you upload a new version?
Comments are specific to the version of the file. This is to avoid confusion when the part of the document or
image the comment is pinned to has changed significantly.
To see inline comments on a previous version of the file:

2. Click the filename dropdown in the top left and select a previous version.
3. Comment pins will now be visible, for all comments made on that version.
How many comments can you add to one file?
While there is no limit to the number of comments that can be added to a file, Confluence can only display
100 comments. See CONFSERVER-43397 GATHERING INTEREST for more information.
Edit Files
This page covers how to edit files attached to a
On this page:
Confluence page.
Install and connect the Atlassian

Companion app
Change your default app
Edit conflicts
Manually upload an edited file
Limitations
Revoke trust between Confluence and the
Companion app
Related pages:
Administering the Atlassian Companion
app
Confluence provides two methods for editing files:
Edit files using the Atlassian Companion app

Allows you to edit any type of file, if you have a compatible application installed. Requires you to
install Companion on your computer.
Allows you to edit Microsoft Excel, PowerPoint, and Word files with a compatible browser and
Microsoft Office application. Provided for organizations who can't use Companion.
Your Confluence administrator will decide which method is best for your organisation.
To check which method is available in your site, go to the file preview (click an image or file thumbnail). If
you don't see the Edit button, your site is using the Edit in Office method, so the information on this page
doesn't apply to you.
Download the latest Companion version
Download the Atlassian Companion app for Mac or Windows.
See Install Atlassian Companion for a step-by-step guide.
Edit an attached file

You can edit any file attached to a Confluence page using your preferred desktop application, then when
you're ready, upload the file back to Confluence. You can edit Office documents, Photoshop files, Keynote
presentations — any attached file with a compatible application installed on your computer.
To edit a file you'll need the 'Add Attachments' space permission.
To edit files, you'll also need to install the Atlassian Companion app and allow it to connect to your
Confluence site. Once the Companion app is installed and running, you can start editing.
To edit a file in Confluence:
1.
1. Go to the page containing the attached file.

2. Click the file to open it in preview.
3. Click Edit.
4. Your browser will prompt you open / launch the Companion app.
5. The Companion window will appear, and your file will open in the default application for that file type.
6. Make your changes and then save your file in the desktop application.
7. In the Companion window, click Upload to upload the edited file. It will be saved as a new file version.
Screenshot: Editing an image file with Companion.
1. Edit button - if a file can be edited, you'll see an Edit button in the preview.
2. Download Companion - if you haven't already installed Companion, you can download it from this
flag. The flag always appears, but you only need to download Companion once.
3. Launch Companion - your browser will ask for your permission to open Companion. The prompt is
different in each browser, and will appear each time you edit a file.
4. Upload or discard file - once you have saved the changes to your file, click the Upload button
to upload your edited file back to Confluence, or click the x icon to discard the changes, and remove
the file information from the list.
There is a known issue with editing attached files in some browsers in Confluence 6.11 to 7.2. See C
an’t edit files in Confluence Server using Atlassian Companion app in Internet Explorer, Edge,
Firefox, or Safari for more information and some workarounds.
Other ways to edit files
You can also edit a file from the attachments macro, view file macros (Word, Excel, PowerPoint, and PDF),
or the attachments page.
To edit a file from the attachments page:
1. Go to the page that contains the attached file.

3. Next to the file name, click Edit , then follow the instructions above to edit and save your changes.
Install and connect the Atlassian Companion app

The Atlassian Companion app manages the download and re-upload of files you edit in Confluence.
The first time you edit a file, you'll be prompted to install the Companion app and allow it to connect to your
Confluence site.
1. Click the file to open it in preview.

2. Click Edit.
3. Follow the prompts to download and install the Atlassian Companion app.
4. Launch the Companion app.
5. In Companion, click Trust to confirm you want to connect to Confluence.
6. Return to Confluence, and follow the steps above to edit the file.
You can also download and install the app manually for Mac or Windows or use a Microsoft Installer (.msi
file). See Administering the Atlassian Companion app for details.
For detailed installation instructions for your operating system, see Install Atlassian Companion.
Change your default app
Confluence allows you to edit files in your operating system's default app for that file type (for example, .psd
files will open in Photoshop). To change the app your Confluence file opens in, change the default app in
your operating system.
Edit conflicts
When you edit a file, Companion downloads a copy of the file to your computer. Once you're finished editing
and you attempt to upload the file, Companion will warn you if a newer version of the file was uploaded after
you downloaded the file. You can choose to click the x icon to discard your changes, or continue to upload
your changes as a new version. Both versions will be available in the file history.
Confluence doesn't provide an option to check-out a file before you start editing. There are apps available
on the Atlassian Marketplace that can provide this functionality.
Manually upload an edited file

You can only upload changes back to Confluence if those changes are saved in the original file. You won't
be able to upload if:
you edit the file and save it as a new version (save as)
the application you’re using saves the file in a different format to the original — for example, from a
PowerPoint file (.pptx) to a Keynote file (.key).
If this happens, you can upload your new version manually:
1. Click the original file in Confluence to open it in preview.

2. Click the Upload a new version button and select your new file version.
3. Click Done.
What to do if you lose your edited file
Any files you've opened with Companion will remain listed in the Companion window. The status information
below the file will indicate the time since the file was downloaded, edited, or uploaded. Files that haven't
been edited in the last 60 days are cleared when Companion app restarts.
You can also follow our guide to accessing Confluence files edited with the Atlassian Companion app if the
file isn't listed or you're not able to re-open it in your desktop application.
Limitations
File size limits
Confluence won't allow you to upload your changes if the edited file is larger than your site's maximum file
size limit. This limit is set by your system administrator. By default the limit is 10 MB, but your admin may
have increased or reduced it. Check out Upload Files for more information.
Blocked file types
We block file types that might pose a risk to your security, including executable files such as .exe or .bat
files.
It's possible to modify the file types companion can open using an environment variable. See How to
change the file types blocked by Companion in Windows.
Cross file links and references
If your file links or references to other files (for example if you link a worksheet in one Excel file, to another
Excel file) these links will not work once the files have been uploaded to Confluence.
Revoke trust between Confluence and the Companion app
If you want to disconnect the Companion app from your Confluence site, you can remove it as a trusted site.
To revoke trust:
1. Click the Companion app icon in your system's toolbar.

2. Choose Clear all trusted domains.
Note: clearing trusted domains won't kill active connections. If you select Clear all trusted domains while
editing a file, you'll still be able to upload those changes back to Confluence.
This page covers how to edit files using the legacy E
dit in Office method. Editing Office files attached to a page
Other ways to edit
Office Connector pre-requisites
Enable Edit in Office
Troubleshooting
Confluence provides two methods for editing files:
Edit files using the Atlassian Companion app

Allows you to edit any type of file, if you have a compatible application installed. Requires you to
install Companion on your computer.
Allows you to edit Microsoft Excel, PowerPoint, and Word files with a compatible browser and
Microsoft Office application. Provided for organizations who can't use Companion.
Your Confluence administrator will decide which method is best for your organisation.
To check which method is available in your site, go to the file preview (click an image or file thumbnail). If
you see the Edit button, your site is using the Companion app method, so the information on this page
doesn't apply to you.
Editing Office files attached to a page

The Office Connector allows you to edit Office files that are attached to pages, if your site does not use the
Companion App method. You'll need to use a browser, operating system and application (either Microsoft
Office or OpenOffice) as described in the compatibility matrix below.
To edit an Office document attached to a Confluence page:
2. Choose Edit in Office beside the attachment you want edit.
Your browser will ask you to confirm that you want to open the file.
3. Choose OK.
You may also see a security warning or be asked to log in to your Confluence server - enter your
Confluence username and password, then choose OK.
4. The file will open in your Office application - make your changes then save the document. It will be
saved back to Confluence.
Edit in Office will not work on files that have special characters (such as ' # @ or €) in the filename.
Screenshot: Edit in Office option on the attachments page

Other ways to edit

Edit options also appear in the:
Attachments macro (choose Edit in Office beside each attached office file)
Office Word and Office Excel macros – choose the Edit button above the content.
Office PowerPoint macro – choose the edit icon on the viewer.
Office Connector pre-requisites

You can only edit files using the Office Connector if your system administrator has enabled this feature on
your site. By default, Confluence requires you to install the Atlassian Companion app to edit attached files.
See Edit Files
Configuration matrix
Edit in Office is only compatible with desktop applications. Online versions of Office applications are not
supported.
You need one of the following software combinations to edit Office files from your Confluence page.
Software Operating system Browser
Microsoft Office 2010 SP2, 2013, 2016, 2019

Windows Chrome
Firefox1
Internet Explorer 11
Edge
Microsoft Office 2011, 2016, 2019

Mac OS Chrome
Firefox
Safari
Microsoft Office XP, 2003, 2007, 2010 SP1

Windows Internet Explorer 11
OpenOffice 2.x – 3.x

Windows Chrome
Linux Firefox
Safari
LibreOffice 6.x
MacOS Chrome
Windows Firefox
Linux Safari
1 Firefox only works in Windows with Confluence 7.1 and later.
Note
The known supported Office editors for Linux are OpenOffice & LibreOffice, but in theory it should work with
any WebDAV-aware application.
If you experience problems editing documents using the Office Connector (using an application, operating
system and browser combination above) contact our support team, who can raise an issue about it. Tell us
as much as you can about your operating system, application version, document version (if it's different to
the version of Office / Open Office you're using to open the document) and browser.
Here are a few common issues:
Using Internet Explorer? You can only edit documents in Microsoft Office. OpenOffice is not
supported.
Using Linux? You can only edit documents in OpenOffice. Microsoft Office is not supported.
Special characters in the filename? Edit in Office does not work for files with special characters
(like ' # @ €) in the filename. See
CONFSERVER-22403 - Attaching office documents with special characters stops the ability to
edit from office GATHERING IMPACT
Not seeing the Office Connector options? Your system administrator needs to enable this feature,
and can control how it appears on your site. See Enable Edit in Office as a dark feature and Configurin
g the Office Connector.
Enable Edit in Office

You need System Administrator global permission to do this.
To enable the legacy Edit in Office functionality:
1. Go to > General Configuration > Office Connector.

2. Choose Enable Edit in Office for all users and save your changes.
This will disable Companion app functionality for all users in the site.
Troubleshooting
Having problems with the Office Connector?
The WebDAV plugin must be enabled, because the Office Connector uses WebDAV to transfer
information to and from Office documents. The WebDAV plugin is bundled with Confluence, and can
be enabled or disabled by the System Administrator. If necessary, refer to the instructions on managin
g system and marketplace apps and configuring the WebDAV options.
Ensure that your Confluence server's base URL is set correctly (see Configuring the Server Base URL
to find out how to check this). When a user edits a Confluence page in Word and then uploads the
page back to the Confluence server, the base URL determines where the document will be saved. If
the base URL is incorrect, the documents may be saved to a different Confluence server.
Using Office 2013? Your administrator will need to enable 'Allow authentication tokens in the URL
path' in the Office Connector configuration. See Configuring the Office Connector.
See the Office Connector Limitations and Known Issues knowledge base article for more troubleshooting
tips.
Install Atlassian Companion
If your site uses Atlassian Companion method to edit files, you will need to install the Atlassian Companion app
before you can start editing. Learn more about Editing Files.
The way you install Companion will depend on your operating system, and your organisation's environment.
Windows
These instructions are for Windows 10. The process is similar in earlier, supported Windows versions.
1. Download the Companion app from Windows download

2. Double click to run the Atlassian Companion-1.X.X Setup.exe file you just downloaded.
3. That's it. You may briefly see a progress indicator like the one below.
Once installed, Companion runs in the background. You may need to click the Show hidden items arrow in the
system tray to see it. Right click the Companion icon to see the version you have installed.
The first time you edit a file, you'll be prompted to trust your Confluence site. Once that's done, Companion is
ready to use.
Mac
These instructions are for MacOS 10. Your version may look slightly different.
1. Download the Companion app from Mac download

2. Double click the Atlassian Companion.dmg file you just downloaded.
3. The install dialog will appear. Drag the Atlassian Companion icon to the Applications folder icon.
4. Launch the companion app:

a. In Finder, go to your Applications folder, and click Atlassian Companion.app, or
b. In Launchpad, select Atlassian Companion, or
c. In Spotlight, search for Atlassian Companion.
Once launched, Companion runs in the background. Click the Companion icon in the status area of the menu
bar to see the version you have installed.
The first time you edit a file, you'll be prompted to trust your Confluence site. Once that's done, Companion is
ready to use.
Linux
Atlassian Companion is not currently available for Linux.
Managed or restricted environments

If you're not able to install applications on your computer, your administrator or IT team may need to do this for
you.
Send them a link to Administering the Atlassian Companion App for information about MSI installation.
Troubleshooting
Companion is installed twice in Windows
It's possible to have two versions of Companion installed simultaneously if you have installed Companion using
the installer (.exe) and the MSI (.msi). If this happens, you should uninstall both versions from Add/Remove
programs and then re-install Companion (either using the .exe or the .msi depending on how you want to be
able to update Companion in future).
Remove residual files after uninstalling Companion in Windows
If you need to completley uninstall Companion you may want to check if any residual files remain.
The default installation directories are:
EXE: %LOCALAPPDATA%/atlassian-desktop-companion
MSI: Program Files (x86)/Atlassian Companion
The app stores temporary data and edited files in:
%APPDATA%/Atlassian Companion
C:\Users\<UserName>\.atlassian-companion
Companion creates the following registry entries:
Computer\HKEY_CLASSES_ROOT\atlassian-companion
Computer\HKEY_CURRENT_USER\Software\Classes\atlassian-companion
Computer\HKEY_CURRENT_USER\Software\Microsoft\atlassian-desktop-companion
You can do a registry search for "atlassian" to locate them. These are used for both the MSI and EXE.
Confluence Mobile
There are two ways to stay connected to your team's work in Confluence
On this page:
while you're out and about - the Confluence Server mobile app for iOS and
Android, or via your device's browser.
What you'll need
If you're a Confluence user, check out the two ways you can use Considerations for
Confluence on your device. administrators
Limitations and
Using the Confluence Server mobile app known issues
Using Confluence via your mobile browser
If you're an administrator, read on to find out whether your team will

be able to use the mobile app. Once you've met the requirements, I
nvite your team to use the app!
What you'll need
Confluence requirements
In order for your users to try the Confluence Server mobile app, you will need to:
upgrade your Confluence site to Confluence 6.8 or later

allow users to access your site on their device (if your site isn't accessible on the public internet,
people will need be connected to your network or use a VPN)
Device requirements
In order to use the app, your users will need a device with either:
Android 4.4 (KitKat) or later, or

iOS 11 or later (iPhone, iPad or iPod Touch)
Users will need to log in to use the app, even if your site allows anonymous users.
Considerations for administrators

Here are some things to consider when determining whether your users will be able to use the app.
VPN and firewalls
If your Confluence site is not accessible on the public internet, users will need to connect their device to your
network or virtual private network (VPN) in order to use the app.
We recommend providing your users with step-by-step instructions on how to connect to your VPN when
you let them know the mobile app is available, as this is something Atlassian Support will not be able to help
them with.
The mobile app will also attempt to check the compatibility of your site prior to presenting the login screen. If
you've configured a custom filter to prevent unauthenticated requests to your server, you will need to change
it to allow <confluence-base-url>/rest/nativemobile/1.0/info/login to pass through without
authentication.
HTTPS and certificate requirements
In the latest version of the iOS and Android apps, you can connect to the app using either HTTP or HTTPS.
If you're using HTTPS your proxy must allow TLS 1.2 traffic. This is an iOS requirement that we've chosen to
implement for both the iOS and Android apps to prevent confusion (for example where one device can log in,
and another cannot).
Ideally, your certificate should be from a trusted Certificate Authority. If you have certificate that is self-
signed, or from an unknown Certificate Authority (for example, you are your own CA), users may still be able
to use the app by manually installing your certificate on their device. See our Knowledge base article for
more information on how to do this.
iOS 13 introduced a number of other requirements that your certificate will need to meet if your users will be
using the app on iOS devices. See Requirements for trusted certificates in iOS 13.
Login and authentication
The app supports all common Confluence user management configurations, including external user
directories and SAML single sign-on. Users will need to sign in to use the app, even if your site allows
anonymous access.
Storage and encryption
The iOS and Android apps cache some content (spaces, pages, attachments) locally on the user's device.
This helps keep the app responsive when navigating around pages and spaces. We don't use any
application-level encryption when storing cached data, but the device's internal storage may be encrypted by
the operating system.
When a user logs out, all cached data is deleted.
We don't store passwords in the app. Instead we use session cookies, which are encrypted by default.
Mobile Device Management (MDM)
You can distribute the Confluence Server app to people in your organisation using your MDM solution. For
more info on how to do this, see Mobile Device Management.
Marketplace apps, themes, and visual customizations
The mobile app provides a simple, lightweight way for users to view, create, edit and collaborate on pages.
Complex interactions, including those provided by Marketplace apps, such as blueprints, calendars,
workflows will not be available in the app. Some third party macros may be available, depending on whether
the third-party app supports rendering these macros on mobile.
Any theming or look and feel customizations you've made to your site will not be reflected in the mobile app.
Cloud services
In order to provide push notifications to users' devices, we have developed a cloud-based notification
service. This service is developed and maintained by Atlassian, and is hosted on our AWS infrastructure
(AWS SNS). See Push notifications service below for more information.
This is the only cloud-based service used by the app.
Push notifications service
The Confluence Server mobile app can push notifications directly to users' devices. Users choose whether
they'd like to receive push notifications from the app, and can opt out at any time. This feature uses a cloud-
based notifications service developed and maintained by Atlassian and hosted on our AWS infrastructure.
No user or message content is sent to the service, only notification IDs, and we don't store any data.
If you need to avoid using any cloud-based services you can choose to disable push notifications entirely.
Head to > General Configuration > Mobile apps.
If you're using restrictive firewall or proxy server settings, you'll need to allow (whitelist) https://mobile-
server-push-notification.atlassian.com to ensure push notifications work as expected.
For sites that are not accessible on the public internet (for example users need to be connected via VPN to
use the app) we adapt the push notification message as follows:
If the user is connected to your network or VPN, we'll show the full notification, for example "Sara
Leung shared 'End of year party' with you"
If the user is not currently connected to your network or VPN, we'll show a shorter notification, for
example "1 new notification".
Mobile web and linking directly to pages
It is not possible to go directly from a link, for example in an email notification, to the app. To help with this
limitation, when people land on a Confluence page in their device's browser, they'll see the Open in app
button. Tapping this prompt will open the app, if they have it installed, or take them to the App or Play store
to download it.
If you don't want this button to display in mobile web, you'll need to disable the entire Confluence Mobile
plugin, which is required to use the mobile app.
Limitations and known issues
Not all macros are available
Not all macros will display in the app or mobile web. If a macro can't be displayed, you'll see the message
below, and have the option to tap through to the desktop version of the page, in your device's browser.
Screenshot: Error that appears when a macro is not rendered in Confluence mobile
Administrators can disable Confluence mobile on your site
If you're not able to use the mobile app or mobile web, it may be because your administrator has disabled
one or both of the following system apps:
Confluence mobile plugin (required to use the mobile app)

Confluence mobile web plugin (required to use mobile web)
Disabling the 'Confluence Mobile Plugin' will also disable all the modules of the Workbox - Host
Plugin plugin. This issue is being tracked at
CONFSERVER-40782 - Disabling the Confluence Mobile Plugin also disables the Workbox -
Host Plugin in Confluence GATHERING IMPACT
Seperate Cloud and Server mobile apps
While the functionality of the two mobile apps is very similar, you will need to download the Confluence
Server mobile app to be able to authenticate with a server site. You can't use the Confluence Cloud app
with a Confluence Server site or vice versa.
Using the Confluence Server mobile app
Stay connected to your team's work with the Confluence mobile app. No
On this page:
matter whether you have an iPhone, iPad, Android phone, or Android tablet,
we've got you covered when you're away from your desk.
Confluence Server
If you're the first in your organisation to try the app, ask your Confluence for Android
admin to have a read through Confluence Mobile - Considerations for Confluence Server
administrators, so they can make sure you're able to connect. for iOS
Customizing push
Which app do I need? notifications
Confluence Server app - If you're using Confluence 6.8 or later,

download the Confluence Server app from Play Store or App Store.
Confluence Cloud app - If you're using Confluence Cloud (your

Confluence version number is 1000 or higher) head over to our
Cloud documentation to find out about the Confluence Cloud app
for iOS and Android.
Confluence Server for Android

Here's what you'll get, and what you can do in the app:
Create and edit pages

Create a quick page when you're on site with a customer, or fix that typo on an existing page before
anyone notices. Create and edit lets you do the important stuff, wherever you are.
Notifications when you need them most
Get push notifications for mentions, comment replies, page shares, and tasks assigned to you, so you
can act quickly when it really matters.
Collaborate on the go
Comment on pages to keep work moving, wherever you are. Like pages to show your support, and
share them via email and other apps.
Get back to your work, fast
The Recents tab lets you quickly find pages you've viewed recently. Find those meeting notes you
added yesterday, or the blog post you were reading earlier.
Visit any space, and browse using the page tree
The Spaces tab lets you visit your My Spaces, and any other space on your site. Pick a space and
browse using the familiar Confluence page tree.
Have ideas on how to make the app even more useful? We want your feedback! Shake your phone (or head
to Settings > Feedback) to drop us a note.
Some page macros won't display in the app or mobile web. You'll need to view the page in your
browser (or switch to full desktop mode on your device).
Image and file upload is not currently available in the app.
Links to Confluence pages (from emails or other apps) don't automatically open in the app.
Admins can disable push notifications for your entire site.
Confluence Server for iOS

Confluence Server for iOS is a universal app for iPhone and iPad, so you can choose the best device for the
job. If you'd rather not create and edit pages on your iPhone, switch over to your iPad and take advantage of
the larger screen and keyboard. You can also use split view on iPad and work side by side with other apps.
Here's what you'll get, and what you can do in the app:
Create and edit pages

Create a quick page when you're on site with a customer, or fix that typo on an existing page before
anyone notices. Create and edit lets you do the important stuff, wherever you are.
Notifications when you need them most
Keep up with what your team is doing with push notifications for new pages and posts, comments,
mentions, page shares, likes, and tasks assigned to you.
Get back to your work, fast
The Your work tab serves up pages you've viewed or worked on recently. Find those meeting notes
you added yesterday, or the blog post you were reading earlier.
Visit any space, and browse using the page tree
The Spaces tab lets you visit your My Spaces, and any other space on your site. Pick a space and
browse using the familiar Confluence page tree. While you're in the spaces list, you can add spaces
to My Spaces or remove the ones that aren't important any more.
Stay connected to your team
The activity feed lets you see all activity on your site, or filter it by space. Like and comment on pages,
or share a link to any page, right from the app.
Have ideas on how to make the app even more useful? We want your feedback! Shake your phone (or head
to Settings > Feedback) to drop us a note.
Some page macros won't display in the app or mobile web. You'll need to view the page in your
browser (or switch to full desktop mode on your device).
Image and file upload is not currently available in the app.
Links to Confluence pages (from emails or other apps) don't automatically open in the app.
Admins can disable push notifications for your entire site.
Did you participate in our beta?
First of all, thank you! Your feedback was invaluable to us. To keep using the app, however, you'll
need to:
Upgrade your site to Confluence 6.8 or later, and

Update your app to version 1.x or later:
For Android, head to the Play Store and hit Update.
For iOS, head to the App Store to download the official app.
If you update your app without upgrading Confluence, the app will still work for a while, but you won't
get access to new features, like push notifications. Also, once you log out, you won't be able to log
back in, as the app checks that you have the required Confluence version.
Customizing push notifications

Push notifications are a great way to stay in the loop, as they appear on your device, even when you're not
using the app. Tap the notification, and be taken straight into the app.
There are three notification levels, 'All activity', 'Activity for me', and 'None'. iOS users also have an
additional 'Custom' option, where they can turn off individual notifications.
To change your push notification settings:
For Android tap > Settings > Push

For iOS tap > Settings > Push
Here's a summary of common Confluence actions, and whether a push notification is sent.
Push notification setting
Action All activity Activity for me None
Someone mentions you
Someone shares a page / blog post with you
Someone assigns a task to you
Someone comments on a page / blog post you're watching
Someone comments on a page / blog post you created
Someone replies to your comment
Someone likes a page / blog post you created
Someone likes your comment or your reply
Someone likes a page / blog post you're watching
Someone invites you to edit a page / blog post
Someone edits a page / blog post / comment
If you're using the iOS app, choose 'Custom' to further tailor your notifications, and turn off any of the
following notifications individually:
Shares
Mentions
Tasks
Comments on pages / blog posts you created
Likes on pages / blog posts / comments you created
Comments on pages / blog posts you're watching.
Good to know
If your site isn't accessible on the public internet (for example you need to be connected to your office
wifi, or use a VPN to access it from home) we adapt the push notification message, so that you get a
shorter version when you're not connected to your network.
Your admin can disable push notifications for the entire site. If this is the case, you'll see a message
when you go to the Push settings screen in the app.
On iOS, when you first install the app, you'll be prompted to allow the app to send notifications to your
device. We recommend you choose Allow, as you can very easily mute the notifications in the app
later. If you do choose Don't allow, and change your mind, you'll need to go to Settings > Notificatio
ns > Confluence then make sure Allow notifications is enabled.
Using Confluence via your mobile browser
This page is about Confluence mobile web, which is accessed On this page:
using the browser your your device.
The dashboard –
For a richer experience, try the Confluence Server mobile app for
the first thing you
iOS and Android.
see
Searching for
When you access Confluence using the browser on a mobile device, you'll content and people
see a version of Confluence which is optimized for mobile viewing. Viewing pages,
Confluence chooses the mobile or desktop interface based on your device, blog posts and
but you can still switch to the desktop site on your mobile by choosing menu comments
Viewing people's
then choosing Switch to desktop version. profiles
Following up on
notifications
Viewing tasks
You can also swap from the desktop view to the mobile view if you're on a mobile device, by choosing Switc
h to Confluence Mobile at the top of the page.
On your supported mobile device, you can:
View the Confluence dashboard, pages, blog posts, and user profiles.
Add or reply to a comment on a page or blog post.
Like a page, blog post or comment.
Watch a page or blog post.
See your notifications and tasks.
You can't add or edit pages or blog posts, or edit existing comments, using the mobile interface.
The dashboard – the first thing you see

Choose a tab to see:
Popular content – what people like in your wiki.

Recent blogs – the latest blog posts.
Network – updates by people in your network.
Tap the links to view the full content of a page, blog post or comment.
Searching for content and people
Tap the menu icon to open the menu panel on the left of the page. Then type text or a person's name
in the Search box. The mobile interface offers the quick search, which returns matches on page title only. To
use advanced search, switch to desktop mode.
Viewing pages, blog posts and comments

Tap a link on the dashboard or on any other page. Confluence will display the linked page, blog post or
comment.
You can:
View the content, tap a link to move to another page, and interact with the page using the standard
functionality supported by mobile browsers.
Like or unlike a page, blog post or comment.
Watch or stop watching a page or blog post.
Add or reply to a comment.
Viewing people's profiles

Search for a person's name, then view that person's user profile. Tap the options to phone, SMS or email a
colleague directly from your mobile device.
Following up on notifications
You can view and respond to your notifications on your phone or other mobile device. Tap the menu icon
to open the menu panel on the left of the page. Choose Notifications, and tap a notification to see its
details. You can reply, watch or like via the inline actions. Tap Open to open the page or blog post in a new
page. For full details, see Workbox Notifications.
Viewing tasks
You can view and manage your tasks on your phone or other mobile device too. Tap the menu icon to
open the menu panel on the left of the page. Choose Tasks then tap a task to see its details.
Invite your team to use the app
If you're running Confluence 6.8 or later, invite your team to start using the Confluence Server mobile app.
Head to Confluence Mobile to read up on some considerations for administrators, and find out whether you can
use the app with your site.
Users don't need any additional permissions to use the app, you just need to let them know where to download
it and how to log in. If your Confluence site is not accessible on the public internet, you may also need to help
them connect to your network or VPN on their device.
Email template
Here's a suggested email template that you can adapt to let your users know that the Confluence Server mobile
app is available. Don't forget to test that you can connect to your site before sending!
Hi everyone,
Confluence mobile apps are now available for Android and iOS, and you can use them with our
Confluence instance. With the mobile apps, you can create, edit and read pages, straight from your
device.
To use the app, you'll need a device with either Android 4.4 (KitKat) or later, or iOS 11 or later (iPhone,
iPad or iPod Touch).
Download the app for:
Android: https://play.google.com/store/apps/details?id=com.atlassian.confluence.server
iOS (Apple) https://itunes.apple.com/us/app/id1288365159?mt=8.
To log in you'll need our Confluence URL: <add your full URL, e.g. https://yoursite.customer.com
/confluence>
<If your site isn't accessible outside your network>

To use the app you'll need to be connected to our network / VPN. <Add steps for connecting to VPN,
if applicable>
<If your certificate is self-signed or from an unknown Certificate Authority>

You'll also need to install our certificate on your device. <Add steps for downloading the certificate>
Best,
Your name here

Mobile Device Management (MDM)
You can distribute the Confluence Server app to people in your organisation using your MDM solution. This
allows you to:
Deploy the Confluence Server app to company-approved iOS and Android devices.
Pre-populate your Confluence site URLs (just the URL, we don't pass login credentials). People will still
be able to enter a URL, which is useful if you have some rarely used sites, and don't want to pre-populate
them all. Requires Confluence Server iOS app version 1.8.0 / Android app version 0.4.3 or later.
MDM Function Supported for Jira Server app
App deployment Yes
App configuration Yes - to pre-populate the site URL only
App tunnel Yes
Single sign-on (SSO) No
Access control No
Security policies No
Read more about AppConfig and what we currently support in our AppConfig Technical Capabilities white
paper.
Distribute the app to managed devices

The way you do this will depend on your particular MDM provider. In most cases you will:
Add the app to your MDM app catalog.

For iOS you will likely bulk purchase through the Apple VPP store, then link the app in your MDM
solution (this might be by providing an sToken, or could happen automatically)
Choose which devices should be able to install the app (this might be called something like distributing or
assigning the app).
Refer to the documentation for your MDM provider for more information.
Pre-populate site URLs on the login screen

If your MDM solution supports the AppConfig standard, you can save your users time and prevent mistakes by
pre-populating your site URL in the app.
To pre-populate the mobile app login screen with one site URL:
1. In your MDM, navigate to the App Config section. Check the documentation for your MDM for how to do
this.
2. Add a new key called "sites"
3. In the Value field for the key, enter your site title and URL in JSON format as shown in the examples
below. Replace the title and base URL with your own site details.
For a single URL:
[
{ "title": "My Confluence Site", "baseURL": "https://conf.example.com"}
]
For multiple URLs:

[
{"title": "My Docs Site", "baseURL": "https://docs.example.com"} ,
{"title": "Intranet", "baseURL": "https://team.example.com/confluence", "skipInfo": false}
]
Copy the JSON carefully, including the [ and ].

4. Save your changes. We recommend you access the Confluence Server app on a device to check you
have passed the URLs correctly, before distributing the app config changes to your users. You'll see an
error if the app can't display your list of sites.
Parameters
The following parameters are accepted for the sites key in app config.
Parameter Required Description
title Yes Descriptive name of your Confluence instance. This will appear above the URL
on the app login screen.
baseURL Yes The base URL of your Confluence site. To check it, go to > General
Configuration.
skipInfo No Use this parameter if you have log in problems in because your proxy server
blocks any unauthenticated requests. When set to true, the mobile app won’t
make login/server-info calls that require authorization and instead will redirect
your users to your single sign-on page.
In general, the Confluence Mobile plugin is a prerequisite for using the mobile
app. However, if the skipInfo parameter is set to true, and the plugin is
disabled, your users will see a desktop version of Confluence and be able to
log into it, which is not the correct behavior, but might not look like an obvious
error.
(Requires iOS app 1.14.0)
Here's an example of how the AppConfig looks in AirWatch and MobileIron, two popular MDMs. These
screenshots are for the Jira Server app, but the process is the same for Confluence.
Macros
Macros are how you supercharge your Confluence pages.
On this page:
You can use macros to:
Macro basics
change the format and layout of your page
Confluence macros
display media like video, audio, and social media content
Get more macros
collate and organise Confluence pages, blogs, and files
Macro usage
perform actions from a page, such as creating a page from a
statistics
template.
Take your Confluence space to the next level using macros.

Screenshot: Page containing Status, Page Properties Report, Livesearch, and Profile Picture macros to help
people find information about particular projects.
Macro basics
Add a macro to your page
To add a macro to your page:
1. From the editor toolbar, choose Insert > Other Macros.

2. Select a macro from the list.
3. Enter any required parameters.
4. Choose Insert.
In the editor you'll see a placeholder that represents the macro. Once you publish your page, you'll see the
macro in its full glory.
Edit a macro
Macro parameters are used to change the behaviour of a macro.
To change the macro parameters:

1. In the editor, click the macro placeholder and choose Edit.
2. Update the parameters as required then choose Insert.
Head to the documentation for specific macros below for full details of the parameters available in each
macro.
Confluence macros
Here's a list of macros currently available with Confluence Server and Data Center.
Click a macro name for details of the usage, including optional parameters and examples.
Anchor Macro
Attachments Macro
Blog Posts Macro
Change History Macro
Chart Macro
Cheese Macro
Children Display Macro
Code Block Macro
Column Macro
Content by Label Macro
Content by User Macro
Content Report Table Macro
Contributors Macro
Contributors Summary Macro
Create from Template Macro
Create Space Button Macro
Excerpt Include Macro
Excerpt Macro
Expand Macro
Favorite Pages Macro
Gallery Macro
Global Reports Macro
HTML Include Macro
HTML Macro
IM Presence Macro
Include Page Macro
Info, Tip, Note, and Warning Macros
Jira Chart Macro
Jira Issues Macro
Labels List Macro
Livesearch Macro
Loremipsum Macro
Multimedia Macro
Navigation Map Macro
Network Macro
Noformat Macro
Office Excel Macro
Office PowerPoint Macro
Office Word Macro
Page Index Macro
Page Properties Macro
Page Properties Report Macro
Page Tree Macro
Page Tree Search Macro
Panel Macro
PDF Macro
Popular Labels Macro
Profile Picture Macro
Recently Updated Dashboard Macro

Recently Updated Macro
Recently Used Labels Macro
Related Labels Macro
Roadmap Planner Macro
RSS Feed Macro
Search Results Macro
Section Macro
Space Attachments Macro
Space Details Macro
Spaces List Macro
Status Macro
Table of Contents Macro
Table of Content Zone Macro
Task Report Macro
User List Macro
User Profile Macro
View File Macro
Widget Connector Macro
Get more macros

This documentation provides information on all the macros that are provided with Confluence by default.
There may be other macros in your site, from Marketplace Apps, or perhaps developed in-house.
Third-party macros from the Atlassian Marketplace
You can find a wide range of Atlassian and third party macros at The Marketplace. These are distributed as
apps and can be installed by a Confluence Administrator.
Create your own macros
Users with System Administrator permissions can create user macros - see Writing User Macros.
If you want to create something more complex, you can develop your own plugin - see Writing Confluence
Plugins.
Macro usage statistics

Confluence administrators can check how often each macro is used in your site.
To see how often a macro is used, go to > General Configuration > Macro Usage. This lists how often
each macro is used in current spaces but doesn't include any macros used on pages in archived spaces or
macros provided by disabled apps.
Extend Confluence with one of the hundreds of other macros in the Atlassian Marketplace, such as:
Composition Tabs & Page Layouts: Toggle or expand the visible of portions of your pages
with the Toggle and Cloak macro
Content Formatting for Confluence: Over 30 easy-to-use Confluence macros gives you the
ability to create better, more engaging content
Anchor Macro
Add the Anchor macro to a page to link to a specific part of a page.
On this page:
This is useful on long pages, where you want to link to specific parts of the
page. Add the anchor
macro to your page
Don't see the Anchor macro? This macro isn't available in the Linking to an
new Confluence Cloud editor. See We're cleaning up our macros anchor
for alternative ways to link. Change the macro
parameters
Other ways to add
The example below shows an example of an Anchor macro as it appears in this macro
the editor, and as it would appear to someone viewing the page.
1. Anchor macro as it appears in the editor

2. Anchor macro as it appears when viewing a page (it isn't visible).
Add the anchor macro to your page

To add the Anchor macro to a page:

2. Choose Anchor from the Confluence content category.
3. Enter the anchor name - this will form part of your link.
4. Choose Insert.
You can then add a link to your macro from this page or another page.
Linking to an anchor
To link to an anchor on the same page:
1. Click the Insert Link icon.

2. Choose the Advanced tab.
3. Enter # followed by your anchor name in the Link field. For example #top.
4. Choose Insert.
You can also link to an anchor on another page. See Anchors for more information on the different link
syntax you can use.
Animation: Adding the Anchor macro to a page, then linking to that macro.
Change the macro parameters

Here's a list of the parameters available in this macro.
Anchor None This is the anchor name that you will use when creating the link.
Name
The anchor name can include spaces. Confluence will remove the spaces
automatically when building a URL that points to this anchor.
The anchor name is case sensitive. You must use the same pattern of upper
and lower case letters when creating the link as you used when creating the
Anchor macro.
Other ways to add this macro

Add this macro as you type
Type { followed by the start of the macro name, to see a list of macros.
Add this macro using wiki markup
This is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: anchor
Macro body: None.
{anchor:here}
Attachments Macro
On this page:
This macro is available in Confluence Server and Data Center. Learn
about the macros available in Confluence Cloud.
Add this macro to
Add an Attachments macro to your page to display a list of files attached to your page
your current page, or another page in your site. Change the macro
parameters
This macro is great for providing quick access to: Edit a file displayed
by this macro
project files Other ways to add
forms and downloadable templates this macro
images and diagrams.
Related pages:
Because you can display files attached to any page, you can use this macro
Display Files and
to avoid duplication if you need to provide quick access to the same file on
Images
multiple pages.
Screenshot: The Attachments macro, showing details of an attachment.
Once added to a page, people with appropriate space permissions can:
view a list of attached files

upload a file to the page, directly from the list
edit attachment properties and labels
delete an attached file (this deletes all versions of the file)
preview image files
download all files attached to the page as a zip file.
For general information about working with files in Confluence, see Files.
Add this macro to your page

To add the Attachments macro to a page:

2. Choose Attachments from the Confluence content category.
3. Set any parameters. These are all optional.
4. Choose Insert.
You can then publish your page to see the macro in action.
Screenshot: Entering parameters and changing the sort order in the Blog Posts macro.

Filename all A comma-separated list of regular expressions, used to filter the attachments by
Patterns file name. Note that the parameter values must be regular expressions. For
(patterns example:
)
To match a file suffix of 'jpg', use .*jpg (not *.jpg).
To match file names ending in 'jpg' or 'png', use .*jpg,.*png
Attachmen (none) A list of labels, used to filter the attachments to display. If you wish to enter more
t Labels than one label, separate the labels with commas. Confluence will show only
(labels) attachments that have all the labels specified. (The match is an AND, not an
OR.) For information on labelling the attachments, see Add, Remove and
Search for Labels.
Include false A value of true will include previous attachment versions in the list.
Old
Attachmen
t Versions
(old)
Sort By date The sort order for attachments. Note that people viewing the page can change
(sortBy) the sort order by clicking the column headings. Valid values are:
date – sorts by updated date in reverse chronological order (newest first)

size – sorts largest to smallest
name – sorts alphabetically
created date - sorts by creation date in reverse chronological order (newest
first)
Sort Order ascendi Used in combination with the Sort By parameter, to sort the attachments in
(sortOrd ng ascending or descending order.
er)
Allow true If selected, the list of attachments will include options allowing users to browse
Upload for, and attach, new files.
(upload)
Page Title (none) Used to display attachments from another page. If you do not enter a page title,
(page) the macro will display the files attached to the current page.
Show true Used to display a preview of the attached file. If true, preview will be visible
Previews when the list item is expanded.
(preview)
It can be useful to disable previews if you have very large attachments.
Edit a file displayed by this macro

There are a few ways to edit attachments in Confluence.
To edit a file from the attachments macro list:
1. Click the arrow next to the file name to view its version history.
2. Click Edit.
3. Atlassian Companion will open the file in your desktop application.
4. Make your changes and then save your file. When you're ready, click Upload in Companion to send
the file back to Confluence.
Learn more about editing files in Confluence.

Macro name: attachments
Macro body: None.
{attachments:old=false|patterns=.*png,.*jpg|sortby=name|page=My page about

chocolate|sortorder=descending|labels=chocolate,cookies|upload=false|preview=false}
Blog Posts Macro
On this page:
Add the Blog Posts
Add the Blog Posts macro to a page to display a curated list of blog posts. macro to your page
You can choose to show the just the title, an excerpt from the blog, or the Change the macro
entire contents of each blog post. parameters
Other ways to add
This macro is great when you want to present a curated list of blogs for: this macro
company announcements
new team member introductions
point-in-time project updates
change management communications.
Because you can display blog posts from any space, with any label or
author, you can display the same blogs on multiple pages. This reduces
duplication and helps people in your team find information when they need
it.
Screenshot: The Blog Posts macro, configured to show an excerpt of each blog post.
For general information about blogging in Confluence, see Blog Posts.
Add the Blog Posts macro to your page

To add the Blog Posts macro to a page:

2. Choose Blog Posts from the Confluence content category.
3. Use the parameters below to determine how you want the blog posts to display, and to narrow your
query by time frame, space, author, or label.
4. Choose Insert.
Screenshot: Entering display type, time frame, and label parameters in the Blog Posts macro.

Parameter Required Default Description
Content No titles Available values:

Type to
Display titles — Display the title, creator, space, and created date
stamp for each blog post.
(content) excerpts — Display a short excerpt from each blog post. If
the post contains an Excerpt macro, the Blog Posts macro will
display the content defined in the Excerpt macro. If the post
does not contain an Excerpt macro, the Blog Posts macro will
display the first few sentences of the post.
entire - Display the whole content of each blog post.
Time No no limit Specify how far back in time Confluence should look for the blog
Frame posts to be displayed.
(time)
Available values:
m — Minutes
h — Hours, so '12h' displays blog posts created in the last
twelve hours.
d — Days, so '7d' displays blog posts created in the last

seven days.
w — Weeks
Restrict to No None Filter the results by label. The macro will display only the blog
these posts which are tagged with the label(s) you specify here.
Labels
(label) You can specify one or more label values, separated by a comma
or a space.
To exclude content which matches a given label, put a minus

sign (-) immediately in front of that label value. For example: If
you specify a label value of -badpage you will get only
content which is not labeled with 'badpage'.
To indicate that the results must match a given label value,
put a plus sign (+) immediately in front of that label value. For
example: If you specify a label value of +superpage,
+goodpage you will get only content which has at least two
labels, being 'superpage' and 'goodpage'.
Restrict to No None Filter the results by author. The macro will display only the blog
these Auth posts which are written by the author(s) you specify here.
ors
(author)
Restrict to No @self, i. This parameter allows you to filter content by space. The macro
these e. the will display only the pages which belong to the space(s) you
Spaces space specify here.
(spaces) which
contains You can specify one or more space keys, separated by a comma
the page or a space.
on which
the To exclude content in a specific space, put a minus sign (-)
macro is immediately in front of that space key. For example: If you
coded specify a space key of -BADSPACE you will get only content
which is not in the BADSPACE.
To indicate that the results must come from a specific space,
put a plus sign (+) immediately in front of that space key. For
example: If you specify a space key of +GOODSPACE you will
get only content in GOODSPACE. (Note that this is not
particularly useful, because each content item belongs to one
space only. If you put a plus sign next to one space key and
list other space keys too, the other space keys will be ignored.)
Special values:
@self — The current space.

@personal — All personal spaces.
@global — All site spaces.
@favorite — The spaces you have marked as favorite.
@favourite — The same as @favorite above.
@all — All spaces in your Confluence site.
* — The same as @all above.
When specifying a personal space, remember to use the tilde (~)

sign in front of the username, such as ~jbloggs or ~jbloggs@e
xample.com.
No 15 Specify the maximum number of results to be displayed. Note that

the results are sorted first, and then the maximum parameter is
applied.
Maximum
Number of
Blog Posts
(max)
Sort By No creation Specify how the results should be sorted. If this parameter is not
(sort) specified, the sort order defaults to descending order (newest
first) based on the creation date.
Values:
title — Sort alphabetically by title.

creation — Sort by the date on which the content was added.
modified — Sort by the date on which the content was last
updated.
Reverse No false Select to change the sort from descending to ascending order
Sort (oldest first). Use this parameter in conjunction with the Sort By
(reverse) parameter. This parameter is ignored if the Sort By parameter is
not specified.
In storage format and wikimarkup a value of true changes the

sort order.

Macro name: blog-posts
Macro body: None.
{blog-posts:content=titles|spaces=@self,
ds|author=jsmith|time=4w|reverse=true|sort=creation|max=10|label=chocolate,cookies}
Change History Macro
On this page:
Add the Change
Add the Change History macro to a page to display a table of recent History macro to
updates to that page including version number, author, date and version your page
comment. Change the macro
parameters
This macro is great for: Other ways to add
this macro
document control
change management
wiki gardening and keeping your pages fresh.
Screenshot: The Change History macro in Confluence showing two history versions.
For general information about version control in Confluence, see Page History and Page Comparison
Views.
Add the Change History macro to your page

To add the Change History macro to a page:

2. Choose Change History from the Confluence content category.
3. Choose the number of page versions to display.
4. Choose Insert.
Screenshot: configuring the Change History macro in the macro browser.


Number of No blank Limit the amount of page history to display. Leave blank
versions to display to display all versions in the page history.
(limit)

Macro name: change-history
Macro body: None.
{change-history:limit=2}
Chart Macro
On this page:
This macro is available in Confluence Server
and Data Center. Learn about the macros
available in Confluence Cloud. Add the Chart macro to your page
Add the Chart macro to a page to display a chart Pie chart
based on data in a table on the same page, or from Bar chart
an attached file. 3D Bar chart
Time series chart
This is great for showing a simple visualisation of XY Line Chart
data on the page. XY Area Chart
Area chart
Stacked area chart
Gantt chart
Chart type parameters
Chart display parameters
Chart title and label parameters
Chart data parameters
Chart color parameters
Chart axis parameters
Pie chart Parameters
Chart attachment parameters
Screenshot: Page with two chart macros.
Want to display information from Jira on your page? Check out the Jira Chart Macro.
Add the Chart macro to your page

To add the Chart macro to a page:

2. Choose Chart from the Visuals and images category.
3. Choose Insert.
4.
4. Enter your chart data as one or more tables in the body of the macro placeholder. See the examples
later in this page for more info.
5. Click the macro placeholder and choose Edit.
6. Select a chart type using the Type parameter (see below).
7. Choose other parameter settings in the macro browser, as described below.
8. Click Refresh in the 'Preview' area, to check that the chart appears as you expect.
9. Click Save to add the chart to your page.
Screenshot: Two Chart macros in the editor, containing the data for a pie chart and stacked chart.


Chart Type Parameters | Display Control Parameters | Title and Label Parameters | Data Specification
Parameters | Color Parameters | Axis Parameters | Pie Chart Parameters | Attachment Parameters
Chart Type Parameters
These parameters determine the type of chart to display and the way the chart looks.
Type pie The type of chart to display. XY charts have numerical x- and y-axes.
The x values may optionally be time-based (see the Time Series
parameter).
Standard — pie, bar, line, area
XY Plots — xyArea, xyBar, xyLine, xyStep, xyStepArea, scatter,

timeSeries
Other — gantt
Display vertical Applies to area, bar and line charts.

Orientation
vertical — y-axis is vertical
horizontal — x-axis is vertical
Show in false Applies to area, bar and line charts.

3D
Stacked false Applies to area and bar charts.

Values
Show true Applies to line charts. Shapes are shown at each data point.
shapes
Opacity A percentage value between 0 (transparent) and 100 (opaque) that

75 percent for determines how opaque the foreground areas and bars are.
3D charts
50 percent for
non-stacked
area charts
100 percent
for all other
charts
Display Control Parameters
Width 300 The width of the chart in pixels. The maximum width is limited by the conflue
nce.chart.macro.width.max system property.
Height 300 The height of the chart in pixels. The maximum height is limited by the conflu
ence.chart.macro.height.max system property.
Display false Sets whether to display the rendered body of the macro (usually the data
rendered tables). By default, the chart data table isn't rendered.
data
before — the data are displayed before the chart.
after — the data are displayed after the chart.
Image png The image format to be used for the chart.

format
png
jpg
Title and Label Parameters
Chart Title none The title of the chart.
Chart Subtitle none A subtitle for the chart, using a smaller font than for Title.
Horizontal-axis Label none The label for the x-axis (domain).
Vertical-axis Label none The label for the y-axis (range).
Show Legend true Show a legend or key.
Data Specification Parameters
The data for the chart is taken from tables found when the macro body is rendered. These options control
how this data is interpreted. By default, numeric and date values are interpreted according to the Confluence
global default language (locale) formats. If conversion fails, other languages defined in Confluence will be
tried. Additional conversion options can be specified using the parameters below.
Tables all first Comma separated list of table ids and/or table numbers (starting at 1) contained
level within the body of the macro that will be used as the data for the chart. If data
tables tables are embedded in other tables, then table selection will be required. This
occurs when more complex formatting is done (for example using section and
column macros).
Columns all Comma separated list of column labels and/or column titles and/or column
columns numbers for tables used for chart data. This applies to all tables processed.
Columns are enumerated starting at 1. Column label is the text for the column in
the header row. Column title is the (html) title attribute for the column in the
header row.
Content horizon
Orientation tal vertical — data table columns will be interpreted as series.
horizontal — data tables rows will be interpreted as series.
Time false
Series true — the x values in an XY plot will be treated as time series data and
so will be converted according to date formats.
Date Conflue For time series data, the date format allows for additional customization of the
format nce conversion of data to date values. If a Date format is specified, it will be the first
languag format used to interpret date values. Specify a format that matches the time
e series data. See simple date format.
defined
date
formats
Time Day The time period for time series data. Defines the granularity of how the data is
Period interpreted. Valid values are: Millisecond, Second, Minute, Hour, Day, Week,
Month, Quarter, Year.
Language none Use in combination with the Country parameter to form a locale.
These additional number and date formats will be used for data conversion
before the default languages.
Valid values are 2 character ISO 639-1 alpha-2 codes.
Country none Use in combination with the Language parameter to form a locale. Valid values
are 2 character ISO 3166 codes.
Forgive true
true — the macro tries to convert numeric and date values that do not
totally match any of the default or user-specified formats.
false — enforce strict data format. Data format errors will cause the chart
to not be produced.
Color Parameters
Colors are specified using hexadecimal notation or HTML color names.
Background White Background of the chart.

Color
Border Color no Border around the chart.

border
Colors Comma-separated list of colors used to customize category, sections, and

series colors.
Axis Parameters
Depending on the chart type, the range and domain axis may be customized. These values are
automatically generated based on the data but can be overridden by specifying one or more more of these
parameters.
Range none Range axis lower bound.

Minimum
Value
Range none Range axis upper bound.

Maximum
Value
Range none Range axis units between axis tick marks.

Axis Tick
Unit
Range none Angle for the range axis label in degrees.

Axis Label
Angle
Domain none Only applies to XY plots. Domain axis lower bound. For a date axis, this value
Axis must be expressed in the date format specified by the Date format parameter.
Lower
Bound
Domain none Only applies to XY plots. Domain axis upper bound. For a date axis, this value
Axis must be expressed in the date format specified by the Date format parameter.
Upper
Bound
Domain none Only applies to XY plots. Domain axis units between axis tick marks. For a date
Axis Tick axis, this value represents a count of the units specified in the Time Period
Unit parameter. The Time Period unit can be overridden by specifying a trailing
character: y (years), M (months), d (days), h (hours), m (minutes), s (seconds),
u (milliseconds).
Domain none Only applies to XY plots. The angle for the domain axis label, in degrees.
Axis Label
Angle
Category none Placement of the axis label text for categories.

Label
Position up45 — 45 degrees going upward
up90 — 90 degrees going upward
down45 — 45 degrees going downward
Date Tick start Placement of the date tick mark.

Mark
Position start — tick mark is at the start of the date period.
middle — tick mark is in the middle of the date period.
end — tick mark is at the end of the date period.
Pie Chart Parameters
Pie Show only the pie Format for how pie section labels are displayed. The format uses a
Section section key value string with special replacement variables:
Label
%0% is replaced by the pie section key.
%1% is replaced by the pie section numeric value.
%2% is replaced by the pie section percent value.
Example 1: "%0% = %1%" would display something like

"Independent = 20"
Example 2: "%0% (%2%)" would display something like
"Independent (20%)"
Pie No exploded Comma separated list of pie keys that are to be shown exploded.
Section sections Note: requires jFreeChart version 1.0.3 or higher.
Explode
Attachment Parameters
These are advanced options that can be used for chart versioning, to enable automation and to improve
performance. Use these options carefully! Normally, the chart image is regenerated each time the page is
displayed. These options allow for the generated image to be saved as an attachment and have subsequent
access re-use the attachment. This can be useful especially when combined with the Cache Pluginto
improve performance. Depending on the options chosen, chart images can be versioned for historical
purposes.
Attachment none The name and location with which the chart image will be saved as an
attachment. The user must be authorized to add attachments to the page
specified.
âttachmentName.png — the chart is saved as an attachment to the

current page.
pageâttachmentName.png — the chart is saved as an attachment to
the page name provided.
space:pageâttachmentName.png — the chart is saved as an
attachment to the page name provided in the space indicated.
Attachmen new Defines the the versioning mechanism for saved charts.
t Version
new — creates new version of the attachment.
replace — replaces all previous versions of the chart. To replace an
existing attachment, the user must be authorized to remove attachments
for the page specified.
keep — only saves a new attachment if an existing export of the same
name does not exist. An existing attachment will not be changed or
updated.
Attachmen none Comment used for a saved chart attachment.

t Comment
Thumbnail false
true — the chart image attachment will be shown as a thumbnail.
Chart Type Parameters | Display Control Parameters | Title and Label Parameters | Data Specification
Parameters | Color Parameters | Axis Parameters | Pie Chart Parameters | Attachment Parameters
Pie chart
Here's an example of a pie chart.
To create this chart, we set these parameters in the macro browser:
Type: pie
Chart title: Fish sold in 2011
Show legend: true
Content orientation: vertical
and added this table in the macro body:
Fish Type 2011
Herring 9,500
Salmon 2,900
Tuna 1,500
Bar chart
Here's an example of a bar chart.
Type: bar
Chart title: Fish sold
Show legend: True
Fish Type 2010 2011
Herring 9,500 8,300
Salmon 2,900 4,200
Tuna 1,500 1,500
3D Bar chart
Here's an example of a 3D bar chart.
Type: bar
Show in 3D: true
Opacity: 50
Show legend: true
2009 2010 2011
Revenue 12.4 31.8
Expense 43.6 41.8
Time series chart

Here's an example of a Time series chart.
Type: Time series

Date format: MM/yyyy
Time period: Month
Content orientation: vertical
Range axis lower bound: 0
Show legend: true
and added these two tables in the macro body:
Month Revenue
1/2011 31.8
2/2011 41.8
3/2011 51.3
4/2011 33.8
5/2011 27.6
6/2011 49.8
7/2011 51.8
8/2011 77.3
9/2011 73.8
10/2011 97.6
11/2011 101.2
12/2011 113.7
Month Expenses
1/2011 41.1
2/2011 43.8
3/2011 45.3
4/2011 45.0
5/2011 44.6
6/2011 43.8
7/2011 51.8
8/2011 52.3
9/2011 53.8
10/2011 55.6
11/2011 61.2
12/2011 63.7
XY Line Chart
Here's an example of a XY Line chart.
Type: xyLine
Show legend: true
12 14 23
Revenue 41.1 31.8 12.4
Expense 31.1 41.8 43.6
XY Area Chart
Here's an example of an XY Area chart.
Type: xyArea
Show legend: true
12 14 23
Revenue 41.1 31.8 12.4
Expense 31.1 41.8 43.6
Area chart
Here's an example of an area chart.
Type: area
Show legend: true
Width: 300
Height: 300
Opacity: 50
Satisfaction 2009 2010 2011
Very satisfied 20 23 34
Satisfied 40 34 23
Dissatisfied 25 26 25
Very dissatisfied 15 17 18
Stacked area chart

Here's another example of an Area chart.
Type: area
Show legend: true
Width: 300
Height: 300
Stacked values: true
Satisfied 1 34 36
Dissatisfied 4 6 22
Very dissatisfied 2 7 12
Gantt chart
Here's an example of a Gantt chart.
Type: gantt
Width: 300
Height: 200
Columns: ,,1,2,3,4 (note the two commas to start)
Date format: MM/dd/yyyy
and added these two tables in the macro body:
Plan Start End Status
Stage 1 6/25/2013 7/10/2013 30%
Stage 2 7/13/2013 11/28/2013 40%
Stage 3 12/1/2013 12/25/2013
Actual Start End Status
Stage 1 6/25/2013 7/26/2013 100%
Stage 2 7/29/2013 12/01/2013 40%
Stage 3 12/10/2013 12/25/2013
You must include the two leading commas in the column parameter (for example ,,1,2,3,4) for the
chart to be created correctly.

Macro name: chart
Macro body: Accepts rich text, consisting of tables that hold the chart's data.
Below is a simple example of a pie chart. See more examples in Wiki Markup Examples for Chart Macro.
{chart:type=pie|title=Fish Sold}
|| Fish Type || 2004 || 2005 ||
|| Herring | 9,500 | 8,300 |
|| Salmon | 2,900 | 4,200 |
|| Tuna | 1,500 | 1,500 |
{chart}
This macro recognizes a large number of parameters, listed here by type.

Chart type parameters
These parameters determine the type of chart to display and how the chart looks.
type No pie The type of chart to display. XY charts have numerical x-

and y-axes. The x values may optionally be time-based.
See the timeSeries parameter.
Available values:
Standard charts - pie, bar, line, area

XY plots – xyArea, xyBar, xyLine, xyStep,
xyStepArea, scatter, timeSeries
Other charts – gantt
orientati No vertical The display orientation. Applies to area, bar and line
on charts.
Available values:
vertical – y-axis is vertical

horizontal – x-axis is vertical
3D No false Show in three dimensions. Applies to area, bar and line

charts.
stacked No false Stacked values. Applies to area and bar charts.
showShapes No true Applies to line charts. Shapes are shown at each data
point.
opacity No A percentage value between 0 (transparent) and 100

75 percent (opaque) that determines how opaque the foreground
for 3D areas and bars are.
charts
50 percent
for non-
stacked
area charts
100
percent for
all other
charts
Chart display parameters
width No 300 The width of the chart in pixels.
height No 300 The height of the chart in pixels.
dataDispl No false Determines whether to display the body of the macro,

ay consisting of the data table. By default, the chart data table is
not displayed.
Available values:
false – the data is not displayed.

true or after – the data is displayed after the chart.
before – the data is displayed before the chart.
imageForm No png The image format to be used for the chart.

at
Available values:
png
jpg
Chart title and label parameters
title No (None) The title of the chart.
subTitle No (None) A subtitle for the chart.
xLabel No (None) The label for the x-axis (domain).
yLabel No (None) The label for the y-axis (range).
legend No false Determines whether to show a legend (key) for the chart.
Chart data parameters
The data for the chart is taken from tables found in the macro body. The parameters below control how
this data is interpreted. By default, numeric and date values are interpreted according to the Confluence
global default language (locale) formats. If conversion fails, other languages defined in Confluence will be
tried. You can specify additional conversion options using the parameters below.
tables No All first You can supply a comma-separated list of table IDs and/or
level table numbers (starting at 1) contained within the body of the
tables macro that will be used as the data for the chart. If data tables
are embedded in other tables, then table selection will be
required. This occurs when more complex formatting is done
(for example using section and column macros).
columns No All You can supply a comma-separated list of column labels and/or
columns column titles and/or column numbers for tables used for chart
data. This applies to all tables processed. Columns are
enumerated starting at 1. Column label is the text for the
column in the header row. Column title is the HTML title
attribute for the column in the header row.
dataOrien No horizo The content orientation. By default, the data tables will be
tation ntal interpreted as columns (horizontally) representing domain and x
values.
Available values:
vertical – data table columns will be interpreted as

series.
horizontal – data tables rows will be interpreted as
series.
timeSerie No false If 'true', the x values in an XY plot will be treated as time

s series data and so will be converted according date formats.
dateForma No Conflue For time series data, the date format allows for additional
t nce customization of the conversion of data to date values. If a date
languag Format is specified, it will be the first format used to interpret
e date values. Specify a format that matches the time series data.
defined See simple date format.
date
formats
timePerio No day The time period for time series data. Defines the granularity of
d how the data is interpreted.
Available values: millisecond, second, minute,

hour, day, week, month, quarter, year
language No (None) Use in combination with the country parameter to form a

locale. These additional number and date formats will be used
for data conversion before the default languages.
Available values are the two-character ISO 639-1 alpha-2 codes.
country No (None) Use in combination with the language parameter to form a

locale. Valid values are the two-character ISO 3166 codes.
forgive No true Determines whether the macro will forgive (allow) some data
formatting errors.
Available values:
true — the macro tries to convert numeric and date values

that do not totally match any of the default or user-specified
formats.
false — the macro enforces strict data formatting. If there
are data format errors, the chart will not be produced.
Chart color parameters
Colors are specified using hexadecimal notation or HTML color names.
bgColor No White Background color of the chart.
borderCol No No Color of the border around the chart.

or border
colors No A comma-separated list of colors used to customize the colors

of categories, sections, and series.
Chart axis parameters
Depending on the chart type, the range and domain axis may be customized. These values are
automatically generated based on the data but can be overridden by specifying one or more more of
these parameters.
rangeAxis No (None) Minimum value for the range axis.

LowerBoun
d
rangeAxis No (None) Maximum value for the range axis.

UpperBoun
d
rangeAxis No (None) Range axis units between axis tick marks.

TickUnit
rangeAxis No (None) Angle for the range axis label in degrees.

LabelAngle
domainAxi No (None) Only applies to XY plots. Domain axis lower bound. For a date
sLowerBou axis, this value must be expressed in the date format specified
nd by the dateFormat parameter.
domainAxi No (None) Only applies to XY plots. Domain axis upper bound. For a date
sUpperBou axis, this value must be expressed in the date format specified
nd by the dateFormat parameter.
domainAxi No (None) Only applies to XY plots. Domain axis units between axis tick
sTickUnit marks. For a date axis, this value represents a count of the
units specified in the timePeriod parameter. The timePeriod
unit can be overridden by specifying a trailing character: y
(years), M (months), d (days), h (hours), m (minutes), s
(seconds), u (milliseconds).
domainAxi No (None) Only applies to XY plots. The angle for the domain axis label, in
sLabelAng degrees.
le
categoryL No (None) Placement of the axis label text for categories.

abelPosit
ion Available values:

dateTickM No start Placement of the date tick mark.

arkPositi
on Available values:
start — tick mark is at the start of the date period.

middle — tick mark is in the middle of the date period.
end — tick mark is at the end of the date period.
Pie chart Parameters
pieSectio No Show only the Formatof pie section labels. The format uses a string
nLabel pie section key with special replacement variables:
value
%0% is replaced by the pie section key.
%1% is replaced by the pie section numeric value.
%2% is replaced by the pie section percent value.
Example 1: To display something like 'Independent =

20':
%0% = %1%
Example 2: To display something like 'Independent

(20%)':
%0% (%2%)
pieSectio No No exploded A comma-separated list of pie keys that are to be

nExplode sections shown exploded. Note: requires jFreeChart version
1.0.3 or higher.
Chart attachment parameters
These are advanced options that can be used for chart versioning, to enable automation and to improve
performance. Use these options carefully! Normally, the chart image is regenerated each time the page is
displayed. These options allow for the generated image to be saved as an attachment and have
subsequent access to re-use the attachment. This can be useful especially when combined with the
Cache plugin to improve performance. Depending on the options chosen, chart images can be versioned
for historical purposes.
attachment No (None) The name and location where the chart image will be saved as
an attachment. The user must be authorized to add
attachments to the page specified.
Available syntax for this parameter:
âttachmentName.png — the chart is saved as an

attachment to the current page.
page nameâttachmentName.png — the chart is saved
as an attachment to the page name provided.
nameâttachmentName.png — the chart is saved as an
attachment to the page name provided in the space
indicated.
attachmen No new Defines the the versioning mechanism for saved charts.
tVersion
Available values:
new — creates new version of the attachment.

replace — replaces all previous versions of the chart. To
replace an existing attachment, the user must be authorized
to remove attachments for the page specified.
keep — only saves a new attachment if an existing export
of the same name does not exist. An existing attachment
will not be changed or updated.
attachmen No (None) Comment used for a saved chart attachment.

tComment
thumbnail No false If true, the chart image attachment will be shown as a

thumbnail (small, expandable) image.
Create interesting and engaging charts for your Confluence pages with these top charts and
diagrams apps on the Atlassian Marketplace.
Wiki Markup Examples for Chart Macro
This page is an extension of the documentation for the Chart Macro. This page contains additional examples for
the Chart macro.
Pie chart
Here is a simple example of a pie chart.
Wiki markup
{chart:type=pie|title=Fish Sold}
|| Fish Type || 2004 || 2005 ||
|| Herring | 9,500 | 8,300 |
|| Salmon | 2,900 | 4,200 |
|| Tuna | 1,500 | 1,500 |
{chart}
Resulting chart
Bar chart
Here is a simple example of a bar chart.
Wiki markup
{chart:type=bar|title=Fish Sold}
|| Fish Type || 2004 || 2005 ||
|| Herring | 9,500 | 8,300 |
|| Salmon | 2,900 | 4,200 |
|| Tuna | 1,500 | 1,500 |
{chart}
Resulting chart
Time series chart

Here is an example of a time series chart.
Wiki markup
{chart:type=timeSeries|dateFormat=MM/yyyy|timePeriod=Month|
dataOrientation=vertical|rangeAxisLowerBound=0|domainaxisrotateticklabel=true}
|| Month || Revenue ||
| 1/2005 | 31.8 |
| 2/2005 | 41.8 |
| 3/2005 | 51.3 |
| 4/2005 | 33.8 |
| 5/2005 | 27.6 |
| 6/2005 | 49.8 |
| 7/2005 | 51.8 |
| 8/2005 | 77.3 |
| 9/2005 | 73.8 |
| 10/2005 | 97.6 |
| 11/2005 | 101.2 |
| 12/2005 | 113.7 |
|| Month || Expenses ||
| 1/2005 | 41.1 |
| 2/2005 | 43.8 |
| 3/2005 | 45.3 |
| 4/2005 | 45.0 |
| 5/2005 | 44.6 |
| 6/2005 | 43.8 |
| 7/2005 | 51.8 |
| 8/2005 | 52.3 |
| 9/2005 | 53.8 |
| 10/2005 | 55.6 |
| 11/2005 | 61.2 |
| 12/2005 | 63.7 |
{chart}
Resulting chart
XY line chart
Here is an example of an XY line chart.
Wiki markup
{chart:type=xyline}
|| || 12 || 14 || 23 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
Resulting chart
XY bar chart
Here is an example of an XY bar chart.
Wiki markup
{chart:type=xybar|opacity=60}
|| || 2005 || 2006 || 2007 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
Resulting chart
XY area chart
Here is an example of an XY area chart.
Wiki markup
{chart:type=xyarea}
|| || 12 || 14 || 23 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
Resulting chart
Area chart
Here are two examples of area charts.
Wiki markup for area chart 1
{chart:type=area|dataDisplay=true|legend=true|width=300|height=300|opacity=50}
|| Satisfaction || 2002 || 2003 || 2004 ||
| Very satisfied | 20 | 23 | 34 |
| Satisfied | 40 | 34 | 23 |
| Disatisfied | 25 | 26 | 25 |
| Very disatisfied | 15 | 17 | 18 |
{chart}
Resulting area chart 1
Satisfied 40 34 23
Disatisfied 25 26 25
Very disatisfied 15 17 18
Wiki markup for area chart 2
{chart:type=area|dataDisplay=true|legend=true|width=300|height=300|stacked=true}
|| Satisfaction || 2002 || 2003 || 2004 ||
| Very satisfied | 12 | 23 | 31 |
| Satisfied | 1 | 34 | 36 |
| Disatisfied | 4 | 6 | 22 |
| Very disatisfied | 2 | 7 | 12 |
{chart}
Resulting area chart 2
Satisfied 1 34 36
Disatisfied 4 6 22
Very disatisfied 2 7 12
Cheese Macro
On this page:
Add the Cheese
Add a Cheese macro to your page to display the words "I like cheese!". macro to your page
Change the macro
This macro is great for: parameters
Other ways to add
testing Confluence macro functionality this macro
sharing your love of cheese.
Seriously though, this macro is just for testing purposes. It's provided by the
Basic Macros system plugin, and you can disable the Cheese module if
cheese isn't your thing.
Add the Cheese macro to your page
To add the Cheese macro to a page:

2. Choose Cheese from the Confluence content category.
3. Choose Insert.

This macro has no parameters.

Macro name: cheese
Macro body: None.
{cheese}
Children Display Macro
On this page:
Add the Children
Add the Children Display macro to a page to display a list of pages from a Display macro to
specific part of the page hierarchy. You can choose to display pages that your page
are a child of the current page, or a child of any other page in a space. Change the macro
parameters
This macro is great for providing quick access to: Other ways to add
this macro
pages related to a project
procedures and how-to pages.
Because it relies on the page hierarchy, the list of pages is automatically

updated when pages are added, deleted, or moved. You can even show an
excerpt from the page for extra context.
Screenshot: The Children Display macro, showing a list of pages about printers.
Want to create a table of contents from headings on your page? See Table of Contents Macro
Add the Children Display macro to your page

To add the Children Display macro to a page:

2. Choose Children Display from the Confluence content or Navigation category.
3. Use the parameters below to specify which pages to display, and how you want them to look.
4. Choose Insert.
Screenshot: Specifying the parent page and display options in the Children Display macro.

Show false Choose whether to display all the parent page's descendants.
Descendan
ts If true shows the complete tree of pages underneath the parent page,
(all) regardless of Depth of Descendants
Parent current Specify the page to display children for, from either the current space
Page or a different space. Enter:
(page)
'/' — to list the top-level pages of the current space, i.e. those
without parents.
'pagename' — to list the children of the specified page.
'spacekey:' — to list the top-level pages of the specified space.
'spacekey:pagename' — to list the children of the specified
page in the specified space.
Number of none Restrict the number of child pages that are displayed at the top level.
Children
(first)
Depth of none Enter a number to specify the depth of descendants to display. For
Descendan example, if the value is 2, the macro will display 2 levels of child pages.
ts
(depth) This setting has no effect of Show Descendants is enabled.
Heading none Choose the style used to display descendants.

Style
(style)
Include none Allows you to include a short excerpt under each page in the list.
Excerpts Choose between:
(excerpt)
None - no excerpt will be displayed
Simple - displays the first line of text contained in an Excerpt macro
any of the returned pages. If there is not an Excerpt macro on the
page, nothing will be shown.
Rich content - displays the contents of an Excerpt macro, or if
there is not an Excerpt macro on the page, the first part of the page
content, including formatted text, images and some macros.
Sort Manual if Leave blank to display pages in the order they currently appear in the
Children manually page tree. Alternatively, choose:
By ordered,
(sort) otherwise creation — to sort by content creation date
alphabetical title — to sort alphabetically on title
modified — to sort of last modification date.
Reverse false Use with the Sort Children By parameter. When set, the sort order
Sort changes from ascending to descending.
(reverse)

Macro name: children
Macro body: None.
{children:reverse=true|sort=creation|style=h4|page=Home|excerpt=none|first=99|depth=2|all=true}
Extend Confluence with one of the hundreds of other macros in the Atlassian Marketplace. Here are
a couple for organizing your Confluence page:
Navitabs: Create tabs to group content to improve navigation between Confluence pages
Advanced Children Display for Confluence: combine Confluence's built-in children display and
table of contents macros
Subspace Navigation for Confluence: Use the navigation macro to create overviews of the
menu within a Confluence page
Code Block Macro
On this page:
available in Confluence Cloud. Add the Code Block macro to your page
Add a Code Block macro to your page to display Administer the Code Block macro
code examples with syntax highlighting. Other ways to add this macro
This is great for sharing code snippets such as:
sample code
terminal commands
excerpts from application logs.
Screenshot: code sample in the Code Block macro, with syntax highlighting and a dark theme.
Add the Code Block macro to your page

To add the Code Block macro to a page:

2. Choose Code Block from the Formatting category.
3. Choose a language for syntax highlighting.
4. Use the parameters below to customise how the code block should appear on your page.
5. Choose Insert.
6. Type or paste your code into the macro placeholder.
Screenshot: Choosing syntax highlighting language and theme in the Code Block macro
Note: You type the code block directly into the macro placeholder in the editor. Note that any white space
contained in the placeholder is not manipulated in any way by the Code Block macro. This is to provide the
writer with flexibility over code indentation.

Syntax java Specifies the language (or environment) for syntax highlighting. The default
highlighting language is Java but you can choose from one of the following languages
/environments:
(language
) ActionScript
AppleScript
Bash
C#
C++
CSS
ColdFusion
Delphi
Diff
Erlang
Groovy
HTML and XML
Java
Java FX
JavaScript
PHP
Plain Text
PowerShell
Python
Ruby
SQL
Sass
Scala
Visual Basic
YAML
Title none Adds a title to the code block. If specified, the title will be displayed in a header
row at the top of the code block.
Collapsible false If selected, the code macro's content will be collapsed upon visiting or refreshing
(collapse the Confluence page. Clicking the expand source link allows you to view this
) content. If false, the code macro's content is always displayed in full.
Show line false If selected, line numbers will be shown to the left of the lines of code.
numbers
(linenum
bers)
First line 1 When Show line numbers is selected, this value defines the number of the first
number line of code.
(firstli
ne)
Theme Default Specifies the color scheme used for displaying your code block. Many of these
themes are based on the default color schemes of popular integrated
development environments (IDEs). The default theme is Confluence (also
known as Default), which is typically black and colored text on a blank
background. However, you can also choose from one of the following other
popular themes:
DJango
Emacs
FadeToGrey
Midnight
RDark
Eclipse
Confluence
Administer the Code Block macro

You can configure the Code Block macro to use a specific language and theme by default and also upload
new languages. You need Confluence Administrator permissions to change the default theme and language
and System Administrator permissions to upload new languages.
To set the default appearance of code blocks in your site:
1. Go to > General Configuration > Configure Code Macro.

2. Select a Default Theme and Default Language.
3. Choose Save.
All new code blocks will use the default theme and language unless you specify otherwise. Existing code
blocks will be unchanged.
To add an additional language:
1. Go to > General Configuration > Configure Code Macro.

2. Choose Add a new language.
3. Locate your language file and enter a Name for the new language (this will appear when selecting the
language).
4. Choose Add.
Language files must be correctly formatted JavaScript files and adhere to the Custom Brush syntax. You can
see examples in <install-directory>/confluence/includes/js/third-party.
To disable or remove a user-installed language:
1. Go to > Manage apps.

2. Go to User-installed Apps and locate the app for your uploaded language - it will appear like this
'Custom Code Macro Highlighting for...'
3. Choose Uninstall or Disable.
The language will no longer appear in the Code Macro.

Macro name: code
Macro body: Accepts plain text.
{code:title=This is my
title|theme=FadeToGrey|linenumbers=true|language=java|firstline=0001|collapse=true}
This is my code
{code}
Extend Confluence with one of the hundreds of other macros in the Atlassian Marketplace. Some of
our most popular include:
Code Pro for Confluence - Get a real-time view of your code from any source in Confluence.
Include Bitbucket Server for Confluence - Easily include code snippets in Confluence that
sync automatically to Bitbucket Server.
Markdown Extension for Confluence - Embed markdown from private and public Github &
Bitbucket repositories in Confluence.
Column Macro
Add the column macro to a page to organise your content in columns. This
On this page:
macro is used in conjunction with the Section macro, and provides more
flexibility than page layouts.
Add this macro to
This macro is great for situations where: your page
Change the macro
you need more than three columns, or parameters
you need your columns to be a specific width. Other ways to add
this macro
Screenshot: page with a four column layout using the Section and Column macros.
Want a simpler way to lay out your page? Try a page layout instead.

Column macros must be added inside a page layout section, or within a Section macro.
To add the Column macro to a page:
1. Position your cursor inside the body of a Section macro, or page layout section.
3. Choose Column from the Formatting category.
4. Choose Insert.
You can then start typing into the macro body, then publish your page to see the macro in action.
Screenshot: section and column macros in the editor


Parameter Required Default Parameter description and accepted values

name
width No 100% of the page width, The width of the column. Can be specified either
divided equally by the in pixels (for example, 400px) or as a
number of columns in the percentage of the available page width (for
section. example, 50%).

Macro name: column
Macro body: Accepts rich text.
{column:width=100px}
This is the content of *column 1*.
{column}
Content by Label Macro
Add a Content by Label macro to your page to display a list of pages, blog
On this page:
posts or attachments that have particular labels.
This macro is great for for collecting related pages together and filtering out Add this macro to
content that you don't want to see. You could: your page
CQL filters
list of all pages that have the label 'feature-shipped' and include the Change the macro
word 'Blueprint' parameters
list any pages with the label 'meeting-notes' that you've been Other ways to add
mentioned in. this macro
Screenshot: The Content by Label macro showing all pages that contain the label "printer".
For general information about using labels in Confluence, see Add, Remove and Search for Labels.

To add the Content by Label macro to a page:

2. Choose Content by Label from the Confluence content category.
3. Enter the labels you want to use as the basis for your query.
4. Add additional filters to further narrow your query. These filters use CQL.
5. Choose Show to change the macro parameters. These are optional.
6. Choose Insert.
Screenshot: Using CQL to search for content with a particular label in two spaces in the Content by Label
macro
CQL filters
CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in
some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add
filters to build up a search query, adding as many filters as you need to narrow down the search results.
Use the Add a filter link to add more filters to your query.
For an OR search, specify multiple values in the same field.

So to show pages with 'label-a', 'label-b' or both you'd put 'label-a' and 'label-b' in the same Label
field, like this:
For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a
second Label field to the macro, and put 'label-b' in the second one, like this:
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to
add that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.
You can use the following CQL filters to build your query:
Filter Description Operators
Label* Include pages, blog posts or attachments with these labels. OR (multiple values in the
same filter)
AND (multiple Label filters)
With Include pages that are children of this page. OR (multiple values in the
ancestor same filter)
This allows you to restrict the macro to a single page tree.
Contributor Include pages or blog posts that were created or edited by OR (multiple values in the
** these people. same filter)
Creator Include items created by these people. OR (multiple values in the

same filter)
Mentioning Include pages and blog posts that @mention these people. OR (multiple values in the
user same filter)
With parent Include only direct children of this page (further sub-pages EQUALS (one page only)
won't be included)
In space** Include items from these spaces. OR (multiple values in the

same filter)
Including Include items that contain this text. CONTAINS (single word or
text** phrase)
With title Include items that contain this text in the title. CONTAINS (single word or
phrase)
Of type** Include only pages, blogs or attachments. OR (multiple values in the

same filter)
* This field is required in CQL-powered macros.
** You can add these filters in CQL-powered macros but in search they're part of the standard search filters,
so they don't appear in the Add a filter menu.

Sort by Modified Sort the list by title, the date it was created, or the date it was last modified. If
you don't select an option, CQL default ordering by relevancy is used.
Reverse sort False Sort the list descending instead of ascending (Z - A, earliest - latest)
Maximum 15 Limit the number of items to include in the list. This can be any value up to 500
number of pages.
pages
List title Blank Include an optional heading for the macro
Show labels True Show or hide the labels applied to each item
for each
page
Show space True Show or hide the space name for each item
name for
each page
Display False Allows you to include a short excerpt under each page in the list. Choose
excerpts between:
None - no excerpt will be displayed.

Simple - displays the first line of text contained in an Excerpt macro any of
the returned pages. If there is not an Excerpt macro on the page, nothing
will be shown.
Rich content - displays the contents of an Excerpt macro, or if there is not
an Excerpt macro on the page, the first part of the page content, as
formatted text, including images and some macros.
Exclude False Allows you to exclude the page the macro appears on from the list. This is
current page useful when the current page contains the same labels as the pages you want
to include in the list.

You can't use wiki markup to add this macro.
Content by User Macro
Add the Content by User macro to a page to display a list of all the things
On this page:
created by a particular user including spaces, pages, blog posts, comments,
attached files, and even user accounts.
Add this macro to
This is a legacy macro, and doesn't provide any way to limit the amount of your page
information displayed. This means it can cause timeouts if the user Change the macro
specified has created a lot of content. parameters
Other ways to add
Advanced search is a much better way to find all content created by a this macro
specific person.
Screenshot: The Content by User macro displaying everything created by a particular user.

To add the Content by User macro to a page:

2. Choose Content by User from the Confluence content category.
3. Enter the username of the person you want to activity for.
4. Choose Insert.
Screenshot: specifying a user in the Content by User macro


Username yes none The Confluence username for a person who has created content.
(name) This parameter is unnamed in wiki markup.

Macro name: content-by-user
Macro body: None.
{content-by-user:jsmith}
Content Report Table Macro
Add the Content Report Table to a page to display a table of pages and
On this page:
blog posts with a specific label along with the creator and modified date.
This macro is great for situations where you need to see information about Add this macro to
a set of pages at a glance, such as: your page
Change the macro
project pages parameters
document control Other ways to add
change management this macro
process and procedure documentation.
You can see this macro in action in the Meeting Notes blueprint.
Screenshot: The Content Report Table macro, configured to show pages with the label "printer".

To add the Content Report Table macro to a page:

2. Choose Content Report Table from the Confluence content category.
3. Enter the labels you want to display pages for.
4. Use the parameters below to narrow your query.
5. Choose Insert.
Screenshot: Entering the label parameter in the Content Report Table macro.

Label(s) Yes None This parameter is required. Specify one or more labels, separated
(labels) by a comma. The macro will display the content tagged with any of
the label(s) specified here.
For example, if you specify labels 'A' and 'B', the macro will display
all pages that have the label 'A', and all pages that have the label
'B', and all pages that have both those labels.
Space(s) No (All Specify one or more Space Keys, separated by a comma or a

(spaces) spaces) space. The macro will display only the content which belongs to
the space(s) specified here.
When specifying a personal space, remember to use the tilde (~)

sign in front of the username, such as ~jbloggs or ~jbloggs@ex
ample.com.
Maximum No 20 Define the maximum number of pages that the macro will show in
Number of a single set of results. If there are more pages to be shown, the
Pages macro will display a link labeled 'Find more results'. People viewing
(maxResul the page can choose the link to go to a search view, which shows
ts) all pages tagged with the specified label(s).
Which pages will appear? Before displaying the results,

Confluence will sort them by the date the page was last modified.
The most-recently created/updated pages will appear first.

Contributors Macro
Add the Contributors macro to a page to display a list of Confluence users
On this page:
who have contributed to this page, another page, or set of pages.
Contributors includes people who:
Add this macro to
created or edited the pages your page
commented on the pages Change the macro
added labels to the pages, or parameters
are simply watching the pages. Other ways to add
this macro
This macro is great for:
document control and compliance

providing a list of people to contact about a page.
Screenshot: Page showing contributors to the printer how-to pages.
In this example, the Display Format parameter has been set to list.

To add the Contributors macro to a page:

2. Choose Contributors from the Confluence content category.
3. Enter the type of contributor you want to display, and set any parameters.
4. Choose Insert.
Screenshot: Setting parameters in the Contributors macro


Contribution authors Filters by either the type of contribution made to a page (and optionally its
Type descendant pages), or the watches on the page. Contribution types are:
(include)
authors - includes people who created or have edited the page(s)
comments - includes people who have added comments to the page(s)
labels - includes people who have added labels to the page(s)
watches - includes people who are watching the page(s).
You can specify one or more contribution types, separated by commas.
Sort By count Specifies the criteria used to sort contributors. Sort criteria are:
(order)
count - sorts people based on the total number of contributions to the
page(s)
name - sorts people into alphabetical order
update - sorts people based on the date of their last contribution to the
page(s).
Reverse Sort false Reverses the sort order of contributors in the list. Must be used in
(reverse) conjunction with the Sort By parameter.
Maximum no limit Limits the number of contributors in the list. If a number is not specified, all
Number of contributors are included.
Contributors
(limit)
Display inline Sets how the list of contributor's names is formatted:

Format
(mode) inline — a comma-separated list
list — a bullet list.
Show false Sets whether to include those who contributed anonymously to a page.
Anonymous
Contributions?
(showAnonym
ous)
Show Count? false Sets whether to show the number of times each person made a
(showCount) contribution of the specified Contribution Type.
Show Last false Sets whether to show the last time each person made a contribution of the
Contribution specified Contribution Type.
Time?
(showLastTi
me)
Page Name current Specifies the page to use when generating the list of contributors. If Page
(page) Name and Space(s) are left blank, the current page is assumed.
Label(s) none Filters the list of contributors to those who created the specified labels from
(labels) a page. You can specify one or more labels, separated by commas.
Space(s) current Specifies the space key of the Confluence space that contains the page set
(spaces) in Page Name or alternatively, specifies the spaces to search. Space keys
are case-sensitive.
This parameter also takes special values, including:

You can specify one or more space keys or special values, separated
by commas.
If no Page Name and Label(s) are specified, all pages from the
specified set of spaces are included.
Content Type both Restricts the content type to use when generating the list of contributors:
(contentType pages
) and blog pages — pages
posts blogposts — blog posts.
Blog Post none Specifies the publish date for a blog post. The date format required is:
Date YYYY/MM/DD.
(publishDate
)
Include Page specified Specifies additional pages to include when generating the list of
Hierarchy page only contributors:
(scope)
children — just the child pages of the specified page
descendants — all descendants of the specified page.
Show false Sets whether to show a list of the pages used to generate the list of
Selected contributors.
Pages
(showPages)
Custom default Specifies the message to be used to override the default message that is
"None message displayed when no contributors are found.
Found"
Message
(noneFoundM
essage)

Macro name: contributors
Macro body: None.
This example specifies a content type of blog posts:
{contributors:limit=10|spaces=ds,@personal|reverse=true|labels=chocolate,
cake|showPages=true|noneFoundMessage=Oh dear, no contributors
found|showCount=true|contentType=blogposts|include=authors,comments,labels,
watches|mode=list|showAnonymous=true|order=update|showLastTime=true|publishDate=2012/06/30}
This example specifies a content type of pages:
{contributors:limit=10|spaces=ds,@personal|reverse=true|scope=descendants|labels=chocolate,
cake|showPages=true|noneFoundMessage=Oh dear, no contributors
found|showCount=true|contentType=pages|include=authors,comments,labels,
watches|mode=list|showAnonymous=true|order=update|page=ds:Advanced Topics|showLastTime=true}
Contributors Summary Macro
Add the Contributors macro to a page to display statistics about people
On this page:
contributing to this page, a specific page, or set of pages. Contributors
includes people who:
Add this macro to
created or edited the pages your page
commented on the pages To add the
added labels to the pages, or Contributors
are simply watching the pages. Summary macro to
a page:
This macro is great for: Change the macro
parameters
collaboration leaderboards Other ways to add
recognising frequent documentation contributors this macro
tracking contributions to high value pages.
Screenshot: Page with two Contributors Summary macros, one displaying contributions by user, the other by
page.

To add the Contributors Summary macro to a page:

2. Choose Contributors Summary from the Confluence content category.
3. Choose whether to show contributions by user or page
4. Set any parameters to refine your query.
5. Choose Insert.
Screenshot: Setting parameters in the Contributors Summary macro


Group By contribut Specifies the basis for grouping contribution-based statistics:

(groupby) ors
contributors — group by the people who have contributed
pages — group by the pages used to find contributors.
Columns to edits, Sets the columns that should appear in the table. The statistics or type of
Display comment information presented depends on the basis for grouping set with the Group
(columns) s,labels By parameter. Statistics may be calculated for:
edits — the number of times each contributor has edited the page(s) or
the number of edits made to each page.
edited — a list of the pages edited by each contributor or a list of
contributors who have edited each page.
comments — the number of times each contributor has added comments
to the page(s) or the number of comments on each page.
commented — a list of pages to which each contributor has added
comments or a list of contributors who have commented on each page.
labels — the number of times each contributor has added labels to the
page(s) or the number of labels on each page.
labeled — a list of pages to which each contributor has added labels or
a list of contributors who have added a label to each page.
labellist — a list of labels either added by each contributor or on each
page.
watches — the number of pages being watched by each contributor
/person or the number of contributors/people watching each page.
watching — a list of pages being watched by each contributor/person or
a list of contributors/people watching each page.
lastupdate — the last time each contributor made an update or when
each page was last updated. Valid updates can include edit, comment or
label modifications to a page.
One or more columns can be used.
Sort By edits Sets the criterion used for sorting items in the table. The items sorted depend
(order) on the basis for grouping set with the Group By parameter. Sort criteria are:
edits — sorts items in the table based on the total number of edits made,
either by a contributor or to a page.
name — sorts items in the table in alphabetical order, either by contributor
or page name.
editTime — sorts items in the table based on when the contributor last
edited a page (or a specified set of pages) or when the page was lasted
edited.
update — sorts items in the table based on when the contributor last
made any contribution to a page (or a specified set of pages) or when the
page last had any contribution made to it.
Reverse false Reverses the sort order of items in the table, as specified using the Sort By
Sort parameter. (Used only in conjunction with the Sort By parameter.)
(reverse)
Maximum no limit Limits the number of contributors or pages in the table to the value specified. If
Number of no number is specified, all items are included.
Items
(limit)
Show false Includes individuals who have made anonymous contributions to a page.
Anonymous
Contributio
ns?
(showAnon
ymous)
Show Zero false Sets whether contributors or pages are included for which a calculated
Counts? statistic is zero.
(showZero
Counts)
Page Name current Sets the page for which to calculate the contribution-based statistics. If no
(page) values for Page Name and Space(s) are specified, the current page is
assumed.
Label(s) none Restricts the contribution-based statistics to the specified labels only. You can
(labels) specify one or more labels, separated by commas.
Space(s) current Specifies the space key of the Confluence space which contains the specified
(spaces) page name or alternatively, specifies a scope of spaces to search. Space keys
are case-sensitive.
This parameter also takes special values, including:

You can specify one or more space keys or special values, separated by
commas.
If no Page Name and Label(s) are specified, all pages from the specified set
of spaces are included.
Content both Restricts page types to either pages (pages) or blog posts (blogposts). If no
Type pages value is specified in the Macro Browser, both pages and blog posts are
(contentT and blog included.
ype) posts
Available values pages and blogposts.
Blog Post none Specifies the publish date for a blog post. The date format required is: YYYY
Date /MM/DD.
(publishD
ate)
Include specified Includes either the immediate children or all descendants of the specified
Page page page. If no value is indicated in the Macro Browser, only the specified page is
Hierarchy only included.
(scope)

Macro name: contributors-summary
Macro body: None.
This example specifies a content type of blog posts:
{contributors-summary:limit=10|spaces=ds,
@personal|reverse=true|showAnonymous=true|order=update|labels=chocolate,cake|columns=edits,comments,
labels,lastupdate|groupby=pages|contentType=blogposts|showZeroCounts=true|publishDate=2012/06/07}
This example specifies a content type of pages:
{contributors-summary:limit=10|spaces=ds,
@personal|reverse=true|showAnonymous=true|scope=descendants|order=update|page=ds:Advanced
Topics|labels=chocolate,cake|columns=edits,comments,labels,
lastupdate|groupby=pages|contentType=pages|showZeroCounts=true}
Create from Template Macro
Add the Create from Template macro to a page to provide a way to create
On this page:
pages in a specific location, using a particular template.
When someone clicks the button, the macro opens the editor, loads the Add this macro to
template or blueprint, and is ready to use. When saved, the page will be a your page
child of the page containing the macro. Change the macro
parameters
this macro
project pages
documentation
recurring processes.
Screenshot: Page showing the Create from template button, used to create DACI decision pages.

To add the Create from Template macro to a page:

2. Choose Create from Template from the Confluence content category.
3. Select a template.
4. Choose Insert.
Screenshot: Configuring the macro to have custom button text, and a default page title which includes the
current date.

Button 'Create from The description that people will see when viewing this macro
Text Template' on the page.
Template None Select the template or blueprint to base the new page on. Only
Name global and user-created templates for the current space
appear (unless you have specified a different space in the
'Space Key' field).
Template Blank Specify a default title for pages created using this macro
Title (optional). You can include @currentDate, @spaceName and
@spaceKey variables in the title.
Some blueprints, such as the Decision blueprint, will override

your custom title.
Space Key The space Supply the unique space identifier (space key), to determine
where the where the new page will be created when someone uses this
current page macro to create a page.
is located

Create Space Button Macro
Add the Create Space Button macro to a page to
On this page:
provide a quick, visual prompt to create a space in
Confluence. The Create Space Button provided by
the macro is only be visible to people who have Add this macro to your page
the who have the Create Space global permission. Change the macro parameters
This is a legacy macro and was primarily used
before you could create a space directly from the
Spaces dropdown in the header. However, it might
be useful when documenting a procedure that
requires creating a space, for example a set-up
guide for new teams.
Screenshot: page showing the Create Space Button macro.

To add the Create Space Button macro to a page:

2. Choose Create Space Button from the Confluence content category.
3. Choose Insert.


Icon Size large Specify whether to use large or small icon. Available values:
size
large
small

Macro name: create-space-button
Macro body: None.
{create-space-button:size=small}
{create-space-button:height=50px|width=50px}
The following additional parameters are available in wiki markup.

name
width No Natural The width of the icon to be displayed, specified in pixels.

size of Confluence will stretch or shrink the width of the icon to the
icon number of pixels specified.
(1:1 Note: This parameter is not available via the macro browser.
pixel
ratio)
height No Natural The height of the icon to be displayed, specified in pixels.

size of Confluence will stretch or shrink the height of the icon to the
icon number of pixels specified.
(1:1 Note: This parameter is not available via the macro browser.
pixel
ratio)
Excerpt Include Macro
Add the Excerpt Include macro to display the contents of an Excerpt macro
On this page:
on another page.
This is great single sourcing important information. For example you could Add this macro to
provide the contact details and dates from each project page on a summary your page
page. When the info is updated in the excerpt, it will flow though to all the Change the macro
other places it is used. parameters
Other ways to add
This is a two-step macro. You need to add the Excerpt macro to another this macro
page, before you can use the Excerpt Include macro.
The example below shows an example of an Excerpt Include macro as it appears in the editor, and as it
would appear to someone viewing the page. We have set the options to show both the title of the page and
the panel surrounding the content.
1. The Excerpt Include macro as it appears in the editor.

2. The Excerpt Include macro as it appears when viewing the page.
The content is being pulled from a Excerpt macro on a page called 'reusable note'.

To add the Excerpt Include macro to a page:

2. Choose Excerpt Include from the Confluence content category.
3. Enter the title of the page containing the Excerpt macro you want to include.
4. Choose Insert.
If the page contains more than one Excerpt macro, the Excerpt Include macro will display the contents of the
first one on the page. It can't display content from multiple Excerpt macros on the same page.
Want to show more than just an excerpt? The Include Page Macro allows you to include the entire
contents of another page.


Page none Type the name of the page that contains the excerpt to be displayed. You can
Containing use an excerpt from a page in the same space or another space in the same
the wiki.
Excerpt
(default When you type the name of the page into the Excerpt Include macro dialog,
- Confluence will offer a list of matching pages, including those from other spaces.
parameter
) Alternatively, you can type the space key followed by a colon (:) and the page
name, like this:
SPACEKEY:Page name
This parameter is unnamed in wikimarkup.
Remove false Determines whether Confluence will display a panel around the excerpted
Surroundi content. The panel includes the title of the page containing the excerpt, and the
ng Panel border of the panel. By default, the panel and title are shown.
(nopanel)

Macro name: excerpt-include
Macro body: None.
{excerpt-include:My page name|nopanel=true}
Excerpt Macro
Add the Excerpt macro to a page to define a snippet of content to be re-
On this page:
used on another page.
This is great single sourcing important information. For example you could Add this macro to
provide the contact details and dates from each project page on a summary your page
page. When the info is updated in the excerpt, it will flow though to all the Using this macro
other places it is used. Change the macro
parameters
This is a two-step macro. Once you've added the Excerpt macro to one Other ways to add
page, use the Excerpt Include, Children Display, or Blog Posts macro to this macro
display the contents of that excerpt on another page.
Screenshot: A project summary page containing a Children Display macro, configured to show the contents
of the Excerpt macro on each child page.

To add the Excerpt macro to a page:

2. Choose Excerpt from the Confluence content category.
3. Choose Insert.
Enter your text into the macro body. You can then publish your page to see the macro in action.
Screenshot: the Excerpt macro in the editor, containing a short project summary.
Using this macro

This macro must be used in conjunction with either the Excerpt Include, Children Display, or Blog Posts macr
os.
You can only have one excerpt per page. If you add more than one excerpt macro to a page, only the first
one will be used by these macros.
You can choose to position the except on its own line, or inline with the surrounding text. This option affects
only the page that contains the Excerpt macro, it doesn't affect how the content displays when it is reused on
other pages.
Screenshot: The Excerpt macro placeholder and options panel
1. New line
2. Inline

Hide false Controls whether the page content contained in the Excerpt macro
Excerpted placeholder is displayed on the page.
Content
(hidden) Note that this option affects only the page that contains the Excerpt macro. It
does not affect any pages where the content is reused.

Macro name: excerpt
{excerpt:hidden=true|atlassian-macro-output-type=BLOCK}
This is the *text* I want to reuse in other pages. This text is inside an Excerpt macro.
{excerpt}
Expand Macro
On this page:
available in Confluence Cloud. Add this macro to your page
To add the Expand macro to a page:
Add the Expand macro to your page to provide Change the macro parameters
content in an expandable / collapsible section. Other ways to add this macro
Notes
This is one of Confluence's most popular macros.
It's great for:
visually reducing the amount of information

on a page
breaking process information down
into clickable steps
hiding background or obsolete information,
while still keeping it on the page for future
reference.
The macro is collapsed by default, people need to

click each one to expand it. There's no way to
expand all macros on a page at once, however all
Expand macros are automatically expanded when
you print or export the page to PDF.
Screenshot: page showing four expand macros. Two are collapsed, and two are expanded.

To add the Expand macro to a page:

2. Choose Expand from the Formatting category.
3. Enter a Title. This is the text a user will click on to show the hidden content.
4. Type or paste your text into the body of the macro. This content will be visible when someone clicks
the macro title.
5. Choose Insert.
Screenshot: The expand macro in the editor

Title Click here to expand... Defines the text that appears next to the expand/collapse icon.

Macro name: expand
{expand}
This text is _hidden_ until you expand it.
{expand}
Notes
Text is expanded in PDF and HTML exports. When you export the page to PDF or HTML, the text
between the macro tags is expanded so that readers can see it in the PDF and HTML versions of the
page.
Nesting your Expand macros. You can put one Expand macro inside another, and Confluence will
correctly show and hide the contents of all Expand macros, including the nested ones.
Using the Confluence Cloud editor? This macro may not be available in the new editor. See Expand
macro for more information.
Extend Confluence with one of the hundreds of other macros in the Atlassian Marketplace, such as:
Composition Tabs & Page Layouts: Toggle or expand the visible of portions of your pages
with the Toggle and Cloak macro
Content Formatting for Confluence: Over 30 easy-to-use Confluence macros gives you the
ability to create better, more engaging content
Favorite Pages Macro
Add the Favorite Pages macro to a page to display a list of all the pages
On this page:
you've saved for later.
This is a legacy macro and was primarily used in personal spaces, before Add this macro to
you could access starred pages from the dashboard or profile menu. your page
However, it can be a useful way to share pages you've saved for later with Change the macro
other people. parameters
Other ways to add
this macro
Screenshot: A page with the Favorite pages macro to help new people in a team.

To add the Favorite Pages macro to a page:

2. Choose Favorite Pages from the Confluence content category.
3. Choose Insert.



Macro name: favpages
Macro body: None.
{favpages}
Gallery Macro
Add the Gallery macro to a page to display a collection of images attached
On this page:
to this page, or other Confluence pages.
This macro is great for situations where you need to: Add this macro to
your page
curate a collection of images that are attached to several different Change the macro
pages parameters
display a set of images in a particular order, such as by date. Image file formats
Other ways to add
One benefit of the Gallery macro over simply inserting images into a page is this macro
that it will automatically update when files are added or removed from the
page.
Screenshot: Gallery macro on a page showing images from this page, with captions.
The captions below the images are drawn from the comments on the attachments. For information about
adding comments to attachments, see Upload Files.
For general information about working with files in Confluence, see Files

To add the Gallery macro to a page:

2. Choose Gallery from the Media or Visuals & Imagery categories.
3. Use the macro parameters below to specify the files you want to display.
4. Choose Insert.
Screenshot: Entering parameters for the Gallery macro


Gallery Nothing Specify a title for your gallery.

Title
(title)
Number of 4 Specify the number of columns for your table.

Columns
(columns)
Images to No exclusions. The gallery will ignore any pictures specified. You can specify
Exclude Include all the more than one picture, separated by commas.
(exclude) pictures on the page. Note: The filename and filetype for this parameter are case-
sensitive. For example, 'my picture.PNG' will not be recognized as
'my picture.png'.
Include Include all the If you specifically include one or more pictures, the gallery will
these pictures on the page. show only those pictures. You can specify more than one picture,
Images separated by commas.
Only Note: The filename and filetype for this parameter are case-
(include) sensitive. For example, 'my picture.PNG' will not be recognized as
'my picture.png'.
Exclude No exclusions. The gallery will ignore any pictures that have the specified label.
Images Include all the You can specify more than one label, separated by commas. For
with these pictures on the page. information on labeling the attachments, see Add, Remove and
Labels Search for Labels.
(exclude
Label)
Include None. The images Filters the images to display, based on a list of labels. If you wish
Images are not filtered by to enter more than one label, separate the labels with commas.
with these label. Confluence will show only images that have all the labels
Labels specified. (The match is an AND, not an OR.) For information on
Only labeling the attachments, see Add, Remove and Search for Labels.
(include
Label)
Use If no page is Specify the title of the page which contains the images you want
Images in specified, the gallery displayed. You can specify more than one page name, separated
these macro displays the by commas. To specify a page in a different space, use the
Pages images attached to following syntax: SPACEKEY:Page Title
(page) the page on which
the macro is used.
Sort None. The sort order Specify an attribute to sort the images by. Sort order is ascending,
Images By is unspecified and unless you select the Reverse Sort parameter (see below).
(sort) therefore Options are:
unpredictable.
name – file name.
comment – comment linked to the attached file.
date – date/time last modified.
size – size of the attached file.
Reverse Off. Sort order is Used in combination with the Sort Images By parameter above.
Sort ascending Use Reverse Sort to reverse the sort order, from ascending to
(reverse) descending.
Available values in storage format and wikimarkup:
true – Sort order is descending.

false – Sort order is ascending.
If the name of an attached file or page contains a comma, you can refer to it in the relevant parameters
below by enclosing it in single or double quotes, for example "this,that.jpg", theother.png
Image file formats

You can attach image files of any format to a page. Confluence supports the following image formats in the
Gallery macro and when displaying an image on a page:
gif
jpeg
png
bmp (depending on browser support)
Macro name: gallery
Macro body: None.
{gallery:title=My holiday pictures|reverse=true|sort=size|page=My page1, ds:Welcome to

Confluence|excludeLabel=badlabel1, badlabel2|columns=3|exclude=badpicture.png}
Global Reports Macro
Add the Global Reports macro to a page for access to several feeds that
On this page:
can help you stay on top of new content in your site.
This is a legacy macro and is no longer fully functional. However, the link Add this macro to
to new or updated pages since your last login can be quite useful. your page
Change the macro
parameters
Other ways to add
this macro
Screenshot: The Global Reports macro

To add the Global Reports macro to a page:

2. Choose Global Reports from the Reporting category.
3. Choose Insert.

Width of 99% Specify the width of the table in which the links are displayed, as a percentage
Table of the window width.
(width)

Macro name: global-reports
Macro body: None.
{global-reports:width=50%}
HTML Include Macro
Add the HTML Include macro to a page to include the contents of specific
On this page:
URL in a Confluence page. This allows you to embed a webpage in your
Confluence page.
Security
This is a legacy macro, and is often disabled by Confluence administrators considerations
for security reasons. Add this macro to
your page
Change the macro
parameters
Enabling the HTML
Include Macro
Troubleshooting
Other ways to add
this macro
Security considerations
HTML macros are disabled by default

The HTML macro will only be available if it has been enabled by an administrator. Enabling these
macros can make your Confluence site vulnerable to cross-site scripting attacks.

To add the HTML Include macro to a page:

2. Choose HTML Include from the External content category.
3. Enter the URL you want to display.
4. Choose Insert.

HTML Page's URL Yes None The URL of the page to include.
(url)
Enabling the HTML Include Macro

The HTML Include macro is disabled by default. You'll need Confluence Administrator or System
Administrator permissions to enable this macro.
Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks. You
should only turn on these macros if you trust all your users not to attempt to exploit them. We strongly
recommend leaving this macro disabled if you allow self-signed up or anonymous users to create content.
To enable the HTML Include macro:
1. Go to > Manage apps

2. Select System from the drop down and search for the Confluence HTML Macros system app.
3. Expand the listing and enable the html-include (html-include-xhtml) module.
Administrators can also choose to use the whitelist to restrict URLs that can be displayed in the HTML
Include macro.
Troubleshooting
Administrators can define a whitelist of trusted URLs. If a URL is not in the whitelist, you will see an
error message in the HTML Include macro.
You can only use the HTML Include macro for pages with absolute links. If you use the macro to
include an HTML page that has relative links, you will see a 'Page Not Found' error. See
CONFSERVER-6567 - HTML Include macro should rewrite relative links to point to remote site
CLOSED

Macro name: html-include
Macro body: None.
{html-include:url=http://www.example.com}
HTML Macro
On this page:
Security
Add the HTML macro to a page to embed content from an external considerations
website. For example you can use this macro to embed content from your Add this macro to
company website, or a web-based tool. your page
Change the macro
This is a legacy macro, and is often disabled by Confluence administrators parameters
for security reasons. Enabling the HTML
Macro
Other ways to add
this macro
HTML macros are disabled by default

The HTML macro will only be available if it has been enabled by an administrator. Enabling these
macros can make your Confluence site vulnerable to cross-site scripting attacks.

To add the HTML macro to a page:

2. Choose HTML from the Development category.
3. Choose Insert
4. Paste the HTML embed code from the website you want to display into the body of the macro.

Enabling the HTML Macro

The HTML macro is disabled by default. You'll need Confluence Administrator or System Administrator
permissions to enable this macro.
Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks. You
should only turn on these macros if you trust all your users not to attempt to exploit them. We strongly
recommend leaving this macro disabled if you allow self-signed up or anonymous users to create content.
To enable the HTML macro:

3. Expand the listing and enable the html (html-xhtml) module.

Macro name: html
Macro body: Text, consisting of HTML code.
{html}<a href="http://www.atlassian.com">Click here</a> to see the <b>Atlassian</b> website.{html}
IM Presence Macro
The IM Presence macro indicates graphically when a contact is signed into an Instant Messaging (IM) service.
The IM Presence macro appears as a small icon on the page.
Using the IM Presence Macro
We ended support for this macro in Confluence 7.0

The macro no longer appears in the macro browser and can't be added to a page.
Any macro already on a page will still work.
Parameters
Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the
macro browser, it will be listed below in brackets (example).
Parameter Description
User ID/Screen Identify the user by their ID, account name or screen name.
Name
Service aim – AOL Instant Messenger

(service)
gtalk – Google Talk
icq – ICQ
jabber – Jabber
msn – MSN Instant Messenger
sametime – IBM Lotus Sametime
skype – Skype. Note: Skype requires 'Show my status on the web' to be checked under
'Privacy' preferences
skypeme – Skype
wildfire – Openfire Server
yahoo – Yahoo! Messenger
Show User ID Shows or hides the User ID of the contact.

(showid)
Wiki markup example
This is useful when you want to add a macro outside the editor, for example as custom content in the sidebar,
header or footer of a space.
Macro name: im
Macro body: None.
{im:MySkypeName|service=skype|showid=false}
Include Page Macro
Add the Include Page macro to a page to display the contents of another
On this page:
page or blog post in this page.
This macro is great for: Add this macro to

your page
single-sourcing instructions and procedures Change the macro
sharing useful information in multiple spaces parameters
all types of content reuse. Limitations
Other ways to add
You can add multiple Include Page macros to your page, and combine them this macro
with text, images, tables and other macros.
Because you're simply including the content of the other page, rather than
duplicating it, any changes to the original automatically flow through to
wherever the page is used.
The Include Page macro respects space permissions and page restrictions,
so be sure to check who can view the page you're including.
Screenshot: Meeting notes page with a reusable warning at the top.
To learn how to create a reusable content library, check out Develop Technical Documentation in
Confluence.

To add the Include Page macro to a page:

2. Choose Include Page from the Confluence content categories.
3. Enter the title of the page you want to include. It can be in this space, or another space.
4. Choose Insert.
Screenshot: The Include Page macro nested within a Note macro in the editor.

Page to None This is the name of the Confluence page or blog post that you want to include in
Include the current page. Start typing a page title, and Confluence will suggest matching
pages from the current space and other spaces.
Alternatively you can specify the page as follows:
If the page or blog post is located in another space, add the space key and a
colon in front of the page name. For example, DOC:My page name. The
space key is case sensitive.
To include a blog post, specify the date as well as the title of the blog post.
For example: /2010/12/01/My blog post.
You can include pages from personal spaces using ~username as the
space key, where 'username' is the person's username. For example, ~jsmi
th:My page name.
Limitations
This macro has a few limitations you need to be aware of:
The macro respects space permissions and page restrictions. It won't display the contents of the
included page to anyone who doesn't have adequate permissions to see the included page.
The macro will include the entire page content. If you only want to display part of a page, use the Exce
rpt Include Macro instead.
The macro can only display pages that exist in your current site. You can't use the Include Page
macro to display the contents of pages in other Confluence sites.

Macro name: include
Macro body: None.
{include:DOC:My chocolate page}
Info, Tip, Note, and Warning Macros
Add an Info, Tip, Note, or Warning macro to your page to make important
On this page:
information stand out. The macro is used to format your text in a colored
panel.
Add this macro to
As the names suggest, these macros are great for: your page
Change the macro
Tips and tricks parameters
Warnings Other ways to add
Important notes and other info. this macro
You can configure this macro with or without the icon and title.
Screenshot: examples of the Info, Note, Tip, and Warning macros on a page
Want more control over the color of the boxes? Try the Panel Macro.

To add the Info, Tip, Note, or Warning macro to a page:

2. Choose either Info, Tip, Note, or Warning from the Formatting categories.
3. Enter a title for the panel.
4. Choose Insert.
Screenshot: The Info, Tip, Note, and Warning macros in the editor.


Optional Title none The title of the box. If specified, the title text will be
(title) displayed in bold next to the icon.
Show information/tip/Exclamation true If "false", the icon will not be displayed.

Mark/Warning Icon
(icon)

Macro name: info/tip/note/warning
{info:title=This is my title|icon=false}
This is _important_ information.
{info}
Using Confluence Cloud? Head to Add formatting to your page if your info panel looks more like the one
below.
Jira Chart Macro
Add the Jira Charts macro to a page to build visual
On this page:
graphs and charts from information in Jira.
This is great for: Connect Confluence and Jira

team meetings and retrospectives Pie chart
project status updates Created vs Resolved chart
sharing updates with people in your Two Dimensional Chart
organization who don't use Jira regularly. Disable the Jira Chart macro
Notes
The macro can generate charts from any connected Other ways to add this macro
Jira application, including Jira Software and Jira
Service Desk.
Screenshot: Meeting notes page with a Jira Chart macro showing a breakdown of all issues for a software
version, by priority.
Connect Confluence and Jira

Before you can use this macro, your Confluence and Jira applications must be connected via Application
Links. People viewing the page will see charts for publicly accessible issues. If your Jira application has
restricted viewing (that is, people need permission to view issues) then they'll need to authenticate before
seeing the charts. This macro is compatible with Jira 5.x and later.
See Use Jira applications and Confluence together for more information.

To add the Jira Chart macro to a page:

2. Choose Jira Chart from the Development category.
3. Choose the type of report you want to create (for example Pie, Created vs Resolved)
4. Select your Jira server.
If you have multiple Jira servers linked to Confluence the drop down will default to the primary
application link.
5. Search for issues - you can enter the query in JQL or paste a Jira URL directly into the search field.
6. Choose Preview to generate the chart.
7. Choose Display Options to further control how your chart appears.
8. Choose Insert.
To find out more about searching for issues see Displaying issues using JIRA Query Language (JQL).
Screenshot: Configuring the Jira Chart Macro in the macro browser.
Pie chart
Pie charts can be used to report on issue status, priority, assignee and more.
To further control how this chart appears on your page. Choose Display options:
Chart by - select the field you want to segment the pie chart by such as:
Status
Fix version
Assignee name
Priority
Component
Issue type
Width - define the total width of the chart area. You can enter values in pixels, percent or leave blank
to auto fit.
Show border - add a border around the chart area.
Show chart information - include a text summary under the chart with the total issues count and
chart by value.
Created vs Resolved chart
Created vs Resolved charts can be used to show the difference between the number of issues created
versus the number of issues resolved over time.
To further control how this chart appears on your page choose Display options:
Period - choose a time frame to report by (week, month, quarter etc).

Days previously - the total number of days to report on (counting back from today).
Cumulative totals - choose to progressively add totals or report individual values for each period.
Show unresolved trend - add a subplot showing unresolved issues over time.
Show versions - indicate version release dates as a vertical line on the chart.
Width - define the total width of the chart area. Enter values in pixels, percent or leave blank to auto
fit.
Show border - add a border around the chart area
Show chart information - include a text summary under the chart with the total issues count and
chart by value.
Two Dimensional Chart

Two Dimensional Charts can be used to show issue statistics in a matrix. You can configure the X and Y
axes to display these issue fields:
Status
Priority
Assignee
Fix version
Component
Issue type.
For example you could use the chart to show issue types by status (as shown above).
To configure the chart axes choose Display options:
X Axis - the issue field to display on the X axis (columns).

Y Axis - the issue field to display on the Y axis (rows).
Rows to display - the maximum number to display in the chart.
Disable the Jira Chart macro

The functionality is provided by a system app (plugin) called 'Jira Macros'. This is also used for the Jira
Issues macro. To make the macro unavailable on your site, you can disable the app. See Disabling and
enabling apps.
Notes
HTTPS: The Jira Chart macro can access a Jira site running under SSL provided the Confluence server is
configured to accept the Jira SSL certificate. See Connecting to LDAP or Jira applications or Other Services
via SSL.
Authentication: If the query includes issues that require authentication (issues that are not visible to
anonymous users in Jira), users will be prompted to authenticate to view charts on the Confluence page.
In order to search for issues in the macro browser you will need to authenticate.

Jira Issues Macro
Add the Jira Issues macro to a page to display information from Jira. You
On this page:
can display a single issue, a list of issues, or a count, based on a JIRA
Query Language (JQL) search, filter, or URL.
Connect
This is great for: Confluence and Jira
Add this macro to
team meetings and retrospectives your page
project status updates Displaying issues
release notes and customer communications via a Jira Query
sharing updates with people in your organization who don't use Jira Language (JQL)
regularly. search
Displaying issues
The macro can display issues from any connected Jira application, via a Jira URL
including Jira Software and Jira Service Desk. Displaying a single
issue, or selected
issues
Displaying a count
of issues
Creating a new
issue
Configuring
application links to
display restricted
issues
Rendering HTML
from Jira
applications
Disabling the Jira
Issues macro
Notes
Other ways to add
this macro
Screenshot: Project status page with a Jira issues macro showing issues that must be resolved before
release.
Connect Confluence and Jira

Before you can use this macro, your Confluence and Jira application must be connected via Application Links
. People viewing the page will see the publicly accessible issues from the Jira site. If your Jira site has
restricted viewing (that is, people need permission to view issues) then they will need to authenticate before
seeing the restricted issues.
See Use Jira applications and Confluence together for more information.

To add the Jira macro to a page:

2. Choose Jira from the Development category.
3. Enter a filter or search for a Jira issue.
4. Choose Insert.
Screenshot: Configuring the Jira Issues Macro to show a list of issues.
Displaying issues via a Jira Query Language (JQL) search

You can use the macro to display a table of issues on your page, based on the results of a search using JIRA
Query Language (JQL).
JQL is a simple query language that is similar to SQL. A basic JQL query consists of a field, followed by an o
perator (such as = or >), followed by one or more values or functions.
Examples:
The following query will find all issues in the 'TEST' project:
project = "TEST"
The following query will find all issues in the 'documentation' component of the 'CONF' project:
project = CONF and component = documentation
For more information about JQL syntax, see Advanced searchingin the Jira Software documentation.
To display a table of issues based on a JQL search:
1.
1. Insert the Jira Issues macro onto your Confluence page, as described above.
2. Choose a Jira server next to the Search button.
3. If prompted, log in to the Jira server.
4. Enter the JQL query into the Search box.
5. Choose Search.
6. If you want to customize the display, choose Display options and adjust the columns and number of
issues that will appear in your table of issues.
7. Choose Insert.
Screenshot: Display options in the Jira Issues macro browser.
Displaying issues via a Jira URL

You can paste any of the following Jira application URLs into the Jira Issues macro. Confluence will
immediately convert the URL to a JQL search.
Any URL for an issue search or filter.

A URL for a single issue.
The URL of the XML view of a search.
Auto-convert: You can paste URLs directly into the Confluence editor (without calling up the macro
browser). Confluence will automatically convert the URL into a Jira Issues macro.
Displaying a single issue, or selected issues

To display a single Jira issue, choose one of the following methods:
Paste the URL of the issue directly onto the Confluence page. (There is no need to use the macro
browser.) Confluence will auto-convert the link to a Jira Issues macro.
Or: Add the Jira issues macro to the page as described above, and choose Recently Viewed to see
the issues you have visited recently. Select an issue and choose Insert.
Or: Add the Jira issues macro to the page as described above, and paste the issue URL into the
search box in the macro browser.
Or: Add the Jira issues macro to the page, define your search criteria in the macro browser via JQL
as described above, then select the check box next to the issue in the search results, within the
macro browser.
You can choose to show just the issue key, or the issue key and a summary. Select the macro placeholder
and choose Show Summary or Hide Summary.
To display a subset of Jira issues from your search results:
1. Add the Jira issues macro to the page.

2. Define your search criteria in the macro browser via JQL, as described above.
3. Select the check boxes next to the required issues in the search results, within the macro browser.
Screenshot: Selecting a subset of issues to display
Displaying a count of issues

You can choose to display the number of issues returned by your search, rather than a table of issues. The
Jira Issues macro will display a count of issues, linked to the search in your Jira application.
Screenshot: The Jira Issues macro displaying an issue count.
To display an issue count:
1. Add the Jira Issues macro to the page.

2. Define your search criteria in the macro browser via JQL, as described above.
3. Choose Display options, then choose Total issue count next to 'Display options' in the macro
browser.
4. Choose Insert.
Creating a new issue

While editing a Confluence page, you can create an issue in Jira and display it on your Confluence page,
without leaving the Confluence editor.
To create an issue and add it to your page:
1. Add the Jira Issues macro to the page, as described above.

2. Choose Create New Issue.
3. Supply the information about your Jira server, project, and issue, as prompted.
4. Choose Insert.
Confluence will send a request to your Jira application, to create the issue, then display the newly created
issue on your page.
Limitations
The Jira Issues macro will notify you if it is unable to create an issue in the selected project. This may be
because the project has a required field, field configuration or other customization that is not supported by
the Jira Issues macro. In this situation you will need to create the issue directly in your Jira application.
Configuring application links to display restricted issues

Before you can use this macro, your Confluence and Jira sites must be connected via Application Links.
If the Jira site allows anonymous users to view issues, you must configure an application link, but there's no
need to configure any incoming or outgoing authentication between the Jira application and Confluence.
People viewing the Confluence page will see the publicly accessible issues.
If your Jira site has restricted viewing, or if some projects or issues are restricted to viewing by certain
people, then people will be prompted to Log in & Approve before seeing the restricted issues.
Rendering HTML from Jira applications

Formatted fields from Jira can be displayed in Confluence if you set up a Confluence-to-Jira application link.
Otherwise, such formatted fields will be escaped within the output of the Jira issues macro. This is to prevent
the possibility of malicious HTML being served by an untrusted Jira server. The most likely field where you
will notice this is in the description field.
This example shows how a description column may be displayed in Jira:
Description
This is
the description
of my issue
If there is no application link between Jira and Confluence, the description will appear in the Jira issues
macro like this:
Description
<p>This is<ul><li>the description</li><li>of my issue</li></ul></p>
Disabling the Jira Issues macro

The functionality is provided by a system app called 'Jira Macros'. To make the macro unavailable on your
site, you can disable the app. See Disabling and enabling apps.
Notes
HTTPS: The Jira Issues macro can access a Jira application running under SSL provided the Confluence
server is configured to accept the Jira SSL certificate. See Connecting to LDAP or Jira applications or Other
Services via SSL.
Custom fields can be added as columns to the table simply by using the name of the field with no quotes.
Earlier versions of the macro required you to use the custom field id, e.g. customfield_10100.

Macro name: jiraissues
Macro body: None.
This example uses a Jira filter.
{jiraissues:anonymous=true|url=https://jira.atlassian.com/issues/?filter=41225}
A number of additional parameters that are not available via the macro browser are available in storage
format and wiki markup.

name
anonymous No false If this parameter is set to 'true', your Jira application will return
only the issues which allow unrestricted viewing. That is, the
issues which are visible to anonymous viewers. If this
parameter is omitted or set to 'false', then the results depend
on how your administrator has configured the communication
between the Jira application and Confluence. By default,
Confluence will show only the issues which the user is
authorized to view.
Note: This parameter is available only if you insert the macro

via wiki markup or by editing the storage format of the page.
The macro browser does not offer this parameter.
baseurl No The If you specify a 'baseurl', then the link in the header, pointing to
value of your Jira application, will use this base URL instead of the
the 'url' value of the 'url' parameter. This is useful when Confluence
paramet connects to Jira with a different URL from the one used by
er other users.
columns No By A list of Jira column names, separated by semi-colons (;). You

default, can include many columns recognized by your Jira application,
the including custom columns.
following
columns Some columns, such as those that need to be calculated by
are Jira like 'work ratio' or 'time to resolution', can't be viewed in
shown: Confluence.
type
key
sum
mary
assig
nee
repor
ter
priori
ty
status
resol
ution
creat
ed
upda
ted
due
count No false If this parameter is set to 'true', the issue list will show the
number of issues in Jira. The count will be linked to your Jira
site.
cache No on The macro maintains a cache of the issues which result from
the Jira query. If the 'cache' parameter is set to 'off', the
relevant part of the cache is cleared each time the macro is
reloaded. (The value 'false' also works and has the same effect
as 'off'.)

height No 480 (if The height in pixels of the table displaying the issues.
render Note that this height specification is ignored in the following
mode is situations:
dynamic)
If the 'renderMode' parameter (see below) is set to 'static'.
When the issues are displayed in a PDF or Word
document, in an email message or in an RSS feed.

renderMode No static If the value is 'dynamic', the Jira Issues macro offers an
interactive display which people can manipulate as follows:
Click the column headers to sort the output.

Drag and drop the columns into a different order.
Temporarily remove a column from the display.
View a page of issues at a time, for faster response times.
A value of 'static' will disable the dynamic display features.

title No Jira You can customize the title text at the top of the issues table
Issues with this parameter. For instance, setting the title to 'Bugs-to-
fix' will replace the default 'Jira Issues' text. This can help
provide more context to the list of issues displayed.

url Yes none The URL of the XML view of your selected issues.
Note: If the URL in the 'url' parameter does not contain a temp
Max argument, then the value of tempMax will default to 500. If
your Jira server is version 3.12 or earlier, this means that the
Jira Issues macro will return a maximum of 500 issues. If your
Jira server is version 3.13 or later, a value of 500 means that
the Jira Issues macro will return a maximum of 500 issues per
page.
width No 100% The width of the table displaying the issues. Can be entered as
a percentage (%) or in pixels (px).

Do more with Confluence and Jira
Take displaying Jira issues to the next level, with these apps on the Atlassian Marketplace:
Issue Macro from Jira to Confluence: customize the look of a single Jira Issue report or
generate a well-formatted filter report
Issues Forms for Confluence: Create and display Jira issues/tickets on Confluence pages
Labels List Macro
Add the Labels List macro to a page to create a directory of all the labels
On this page:
used in a space. People can then click a label to see a list of all pages with
that label.
Add this macro to
This macro is great for providing an alternative way of navigating the your page
content of a space, especially if you use Confluence for process, procedure, Change the macro
or other documentation. parameters
Other ways to add
this macro
Screenshot: Page with a Labels List macro to help people find help guides on a particular topic

To add the Labels List macro to a page:

2. Choose Labels List from the Confluence content categories.
3. Enter a space key, and any labels you might want to exclude.
4. Choose Insert.
Screenshot: The Labels List macro configured to show labels from the IT Help space, and exclude the labels
'test' and 'testing'.

Parameter name Required Default Parameter description and accepted values
Restrict to this Space No Current The key of the space whose labels you want to
Key space display.
(spaceKey)
Excluded label(s) No Blank The labels that you do not want to appear in the
(excludedLabels) list.

Macro name: listlabels
Macro body: None.
{listlabels:spaceKey=DOC}
Livesearch Macro
Add the Livesearch macro to a page to provide a fully customizable search
On this page:
field. When someone starts typing into the search field, Confluence will
suggest matching pages, blogs, or comments.
Add this macro to
This macro is great when you want to: your page
Change the macro
provide a way to search the current space, such as in a knowledge parameters
base Other ways to add
encourage people to search for particular types of content, such as this macro
pages with a particular label.
Because you can limit the search by space, label, content type, you can
provide a very targeted search experience for people viewing your space.
Screenshot: page with a Livesearch macro showing search results for the search term 'printer'

To add the Livesearch macro to a page:

2. Choose Livesearch from the Navigation category.
3. Use the parameters below to narrow down the content to be searched.
4. Choose Insert.
Screenshot: configuring the Livesearch macro to search for pages with particular labels in a specific space.

Restrict to all Specify a space key to limit the search to a single space. Case-sensitive. You
this Space spaces can't specify multiple spaces.
Key
(spaceKey) Alternatively, use @self to restrict the search to the current space.
Restrict to Specify labels to limit the search to content with that label. If unspecified will
label(s) search all content regardless of label.
(labels)
Size medium Choose a medium or large search field size.

(size)
Placeholder Specify the placeholder text to appear in the search field, for example
text 'Search this space'
(placeholder
)
Type all Specify the content types to be included in the search - choose from pages,
(type) blogs, comments, space descriptions, or all content types.
Additional space Display the space name, a page excerpt or nothing under the search result.
(additional) name

Macro name: livesearch
Macro body: None.
{livesearch:spaceKey=DOC|size=large|placeholder=Search this space}
Loremipsum Macro
Add the Loremipsum macro to a page to display a paragraphs of Lorem
ipsum placeholder text.
This is a legacy macro, and is mostly used for demonstrating how a

particular page layout or format might look with content. The text is
deliberately non-meaningful so that it does not influence the viewer's
perception of the page arrangement or design.
Screenshot: a page with headings and the Loremipsum macro in place of actual content.

To add the Loremipsum macro to a page:

2. Choose Loremipsum from the Development category.
3. Enter the number of paragraphs to include.
4. Choose Insert.

Number of 3 Determines the amount of placeholder text to display. The macro will
Paragraphs display a maximum number of 30 paragraphs.
Parameter is unnamed in storage format and wiki markup.


Macro name: loremipsum
Macro body: None.
{loremipsum:2}
Multimedia Macro
Add the Multimedia macro to a page to embed an attached video,
On this page:
animation, or other multimedia file.
The macro uses the HTML5 <video> tag, so the type of video your page Add this macro to
viewers can see depends on the video formats their browser supports with your page
the HTML5 <video> tag. Change the macro
parameters
this macro
training videos
customer interviews and research recordings
workshop or meeting recordings.
Screenshot: a meeting notes page containing a demo video.
If you want to display online multimedia content, like YouTube and Vimeo videos, take a look at the Widget
Connector Macro.
The file preview also supports MP3 audio and MP4 video files. This is handy when you want to play a
video in a larger format.

To add the Multimedia macro to a page:
1. Upload the file to your page.

3. Choose Multimedia from the Media category.
4. Select the file you want to play.
5. Choose Insert.
Screenshot: configuring the Multimedia macro



name
Page name No Current page The name of the page to which the multimedia file is
(page) attached. Start typing the name of the page and then
select it from list of suggested pages. Include the spacekey
if you want to specify a page in another space (for
example, MYSPACE:My Page Title)
File* (name) Yes None File name of the attached multimedia file.
Width No If not specified, Width of the movie window to be displayed on the page. By
the browser will default, this value is specified in pixels. You can also
determine the choose to specify a percentage of the window's width, or
width based on any other value accepted by HTML.
the file type.
Height No If not specified, Height of the movie window to be displayed on the page.
the browser will By default, this value is specified in pixels. You can also
determine the choose to specify a percentage of the window's height, or
height based any other value accepted by HTML.
on the file type.
Autoplay (a No false If the parameter is set to true then the video or audio file
utostart) will start playing as soon as the page is loaded. If this
option is set to false then the file will not play until the
user clicks the icon or image on the page.

Macro name: multimedia
Macro body: None.
{multimedia:space=DOC|page=My macros|name=ninjas.swf|autostart=true}
Navigation Map Macro
Add the Navigation Map macro to a page to display pages tagged with a
On this page:
specific label in a grid layout.
This macro is great for for visually representing a small set of pages with a Add this macro to
particular label. You could: your page
Change the macro
display of all pages that have the label 'needs-review' for highlighting parameters
pages that need work Create your own
display all pages with the label 'how-to' in your knowledge base. navmap theme
Other ways to add
If you want to get really fancy, you can style the macro by creating your own this macro
Velocity theme. This does require writing some code though.
Screenshot: page with a Navigation Map macro displaying pages with the label 'printer-how-to'.
Want more flexibility? Check out the Content by Label Macro for a more modern way to display a list of
pages with specific labels and more.

To add the Navigation Map macro to a page:

2. Choose Navigation Map from the Navigation category.
3. Enter a label.
4. Choose Insert.
Screenshot: specifying a label and title in the Navigation Map macro


Label none Specify the label associated with the pages you want to show in the
navigation map.
This parameter is unnamed in storage format and wikimarkup.
Map Title none Specify a title for the navigation map.

(title)
Number of Cells Per 5 Specify the number of cells in a row

Row
(wrapAfter)
Cell Width (Pixels) 90 Specify the cell width (enter a number only, don't include px)
(cellWidth)
Cell Height (Pixels) 60 Specify the cell height (enter a number only, don't include px)
(cellHeight)
Navigation Map Confluen Define a theme for the navmap. See further info below.
Theme ce
(theme )
Create your own navmap theme

If you want to create your own navmap 'look and feel' (for example, one with rounded corners), you need to
add a customized navmap macro theme file to the WEB-INF/classes/com/atlassian/confluence
/plugins
/macros/advanced directory. The file name convention to use is navmap-mytheme.vm. Use the name of
your choice for the mytheme part of the file name, which is also the value you use for this parameter. Hence,
if your theme was called navmap-roundededges.vm, use the value of roundededges for this parameter.
The theme must be written in Velocity. See Velocity User Guide for more information.

Macro name: navmap
Macro body: None.
{navmap:mylabel|wrapAfter=4|title=My map name|cellHeight=50px|theme=navmap-mytheme.vm|cellWidth=80px}
Network Macro
The Network macro displays a list of Network activity on a Confluence page or blog post. You can specify the
user whose network activity you wish to show. These interactions include the users that the specified user is
following or users who are following the specified user. The Network macro shows each listed user by their
profile picture. It also provides a choice of two themes and the ability to limit the number of users in the list.
Screenshot: Network macro
Using the Network macro

Parameters
Username Current The username of the Confluence user whose network interactions you wish to
user's show. If no username is specified, then current user's (that is, your) network
username interactions are shown.
Mode following Determines which users are listed, with respect to the specified user:
following – those who the user is following.

followers – those who are following the user.
This parameter is unnamed in storage format and wikimarkup.
Theme full Determines how the user's network is displayed:
full – shows a large version of user's profile pictures and, if the following
mode is set, provides an entry field function to follow more users.
tiny – shows only the small version of user's profile pictures.
Maximum No limit Restricts the number of users displayed. If the number of users exceeds the
Results imposed up specified maximum, then a Show All link is provided. This link leads to the
to a specified user's Network view, showing the complete list of network interactions.
(max) maximum
of 30
Wiki markup example
Macro name: network
Macro body: None.
{network:followers|username=admin|max=10|theme=full}
Disabling the Network macro

The Network macro is provided by the 'network' module in the 'Profile Macros' system app (plugin). To remove
the macro from your site, you can disable this module. See Disabling and enabling apps.
Noformat Macro
Add the Noformat macro to a page to display text in monospace font with no
On this page:
other formatting.
This is a legacy macro, and is similar to the Code Block Macro, but doesn't Add this macro to
provide any additional functionality such as line numbering or syntax your page
highlighting. Change the macro
parameters
Other ways to add
this macro

To add the Noformat macro to a page:

2. Choose Noformat from the Formatting category.
3. Choose Insert.
4. Paste or type your text into the macro body.
Screenshot: the Noformat macro in the editor

No Panel False Removes the panel around the content.

(nopanel)

Macro name: noformat
Macro body: Accepts plain text.
{noformat:nopanel=true}http://www.example.com{noformat}
Office Excel Macro
Add the Office Excel macro to a page to display the contents of an Excel
On this page:
spreadsheet.
This is great for situations where you need more than a basic Confluence Add this macro to
table can provide, such as for financial information or planning data. your page
Edit the attached
This macro embeds your spreadsheet in the page, rather than showing a file
simple preview. People viewing the page don't need Excel installed to be Change the macro
able to see the spreadsheet. parameters
Limitations
Other ways to add
this macro
Screenshot: a page with an Office Excel macro displaying an Excel spreadsheet.
There are other ways to add a spreadsheet to your page:
Insert the file directly into the page. We'll display a PDF thumbnail of the sheet. This is okay
for simple spreadsheets but may not be suitable for complex or multi-sheet files.
Use the Widget Connector Macro to embed a Google Sheet.

To add the Office Excel macro to a page:
1. Upload the Excel file to your page, then publish the page. See Upload Files to learn how to do this.
3. Choose Office Excel from the Confluence content category.
4. Select the attached file you want to display.
5. Choose Insert.
Screenshot: configuring the Office Excel macro in the macro browser.

Edit the attached file

If you have Excel installed, you can edit the attached file, and automatically re-upload the file back to
Confluence.
See Edit Files for more information on the ways to do this.

Page The Enter a page name, if you wish to display a document which is attached to
Name page another Confluence page.
which
contains
the macro
File Name none The file name of the Office or PDF document to be displayed. The document
must be attached to a page on your Confluence site.
If the file does not appear, publish the page, then head back into the editor and
try again.
Show true Select to show grid lines around each cell of the Excel spreadsheet. Clear to
Grid? hide these grid lines.
Worksheet Last The name of the worksheet that you want displayed.
Name workshee
t viewed
in the
spreadsh
eet
Last Row Last row The number of the last row you want displayed, starting from '0' as the first row.
with
content
Last Last The number of the last column you want displayed, starting from '0' as the first
Column column column.
with
content Hint for reducing the size of the spreadsheet: Use the Last Column and La
st Row parameters to reduce the size of the spreadsheet displayed on the wiki
page. This is especially useful to prevent the display from showing empty cells.
This will also help to prevent 'out of memory' errors.
Limitations
The Office file must be attached to the current page, or another Confluence page. The macro can't display
live Office 365 files. If you use Office 365, you'll need to download the file, and then upload it to Confluence
to display it with this macro. Alternatively, you could just link to the Office 365 file.
If your uploaded file does not appear in the File Name menu in the macro browser, you'll need to publish the
page, and then hit Edit to return to the editor.

Macro name: viewxls
Macro body: None.
{viewxls:col=5|page=Docs|name=My document.xls|grid=false|sheet=mysheet|row=5}
Add the Office PowerPoint macro to a page to display the content of a
On this page:
PowerPoint presentation.
This is great for sharing presentations, training sessions, and other visual Add this macro to
data. your page
Edit the attached
This macro displays your presentation in a viewer with next and back file
buttons, rather than showing a simple preview. People viewing the page Change the macro
don't need PowerPoint installed to be able to see the presentation. parameters
Limitations
Other ways to add
this macro
Screenshot: Project page with an Office PowerPoint macro.
There are multiple ways to show a file on a page. See Display Files and Images for more.

To add the Office PowerPoint macro to a page:
1. Upload a PowerPoint file to your page, then publish the page. See Upload Files to learn how to do
this.
3. Choose Office PowerPoint from the Confluence content category.
4. Select the attached PowerPoint file you want to display.
5. Choose Insert.
Screenshot: Configuring the Office PowerPoint macro.


If you have PowerPoint installed, hit the Edit icon on the macro to edit the attached file, and automatically re-
upload it back to Confluence.

Page The Enter a page name, if you wish to display a document which is attached to
Name page another Confluence page.
which
contains
the
macro
File Name none The file name of the PowerPoint file to be displayed. The document must be
attached to a page on your Confluence site.
Height Specify the height of the display, in pixels (default) or as a percentage of the
window's height.
Slide none Specify the number of the slide that you want displayed on the Confluence
Number page, where the first slide is numbered zero. Instead of a slide show, the page
will display just the single slide, represented as a JPEG image. If not specified,
all slides display as a slideshow.
Width Specify the width of the display, in pixels (default) or as a percentage of the
window's width.
Limitations

Macro name: viewppt
Macro body: None.
{viewppt:height=20%|page=Docs|width=20%|name=My document.ppt|slide=4}
Office Word Macro
Add the Office Word macro to a page to display the contents of a Word
On this page:
document.
This is great for situations where you can't simply copy the content into the Add this macro to
Confluence page, because you want to preserve formatting or other Word your page
functionality. Edit the attached
file
This macro embeds your document in the page, rather than showing a Change the macro
simple preview. People viewing the page don't need Word installed to be parameters
able to see the document. Limitations
Other ways to add
this macro
Screenshot: A page with an Office Word macro displaying a Word document with images and tracked
changes.
There are other ways to add a document to your page:
Insert the file directly into the page. We'll display a PDF thumbnail of the document.
Use the Widget Connector Macro to embed a Google Doc.

To add the Office Word macro to a page:
1. Upload the Word file to your page, then publish the page. See Upload Files to learn how to do this.
3. Choose Office Word from the Confluence content category.
5. Choose Insert.
Screenshot: Configuring the Office Word macro in the macro browser.

If you have Word installed, you can edit the attached file, and automatically re-upload the file back to
Confluence.

Page The page which Enter a page name, if you wish to display a document which is
Name contains the attached to another Confluence page.
macro
File Name none The file name of the Office or PDF document to be displayed. The
document must be attached to a page on your Confluence site.
If the file does not appear, publish the page, then head back into the
editor and try again.
Limitations

Macro name: viewdoc
Macro body: None.
{viewdoc:page=Docs|name=My document.doc}
Page Index Macro
Add the Page Index macro to a page to create an alphabetical index of all
On this page:
pages in the current space.
This is a legacy macro, and does have some limitations, so it's not suitable Add this macro to
for use in very large spaces. your page
Limitations
In small spaces, this macro can be useful for providing a directory of pages, Change the macro
such as: parameters
Other ways to add
project pages this macro
knowledge base articles
process and procedure pages.

To add the Page Index macro to a page:

2. Choose Page Index from the Navigation category.
3. Choose Insert.
Screenshot: Page Index macro on a page.
Limitations
The Page Index macro can be quite memory hungry in large spaces. To prevent it causing out of memory
errors in your site, we:
don't show page excerpts when there are more than 200 pages in the space,
don't list any pages if there are more than 5000 in the space. This limit is configurable. System
Administrators can use the page.index.macro.max.pages system property to reduce the number
of pages displayed.


Macro name: index
Macro body: None.
{index}
Page Properties Macro
When used together, the Page Properties and Page Properties Report
macro can be used to create a table of information drawn from multiple On this page:
pages.
Add this macro to
These macros are great for:
your page
Page properties
Decision registers
layout options
Status reports
Using multiple
Policy and procedure documentation
Page Properties
In short anywhere you have several distinct pieces of information you want macros on one
to be able to roll-up, and cross-reference in a table on another page. page
Change the macro
To use this macro, you need to add a Page Properties macro on one or parameters
more pages, and then you can add a Page Properties Report macro on Limitations
another page, as shown below. Other ways to add
this macro
Related pages:
Page Properties
Report Macro
Decisions Blueprint
Product
Requirements
Blueprint
Screenshot: A project page with status information presented in a Page Properties macro.
Screenshot: A page with a Page Properties Report macro showing status information from the Page
Properties macro on several different project pages.
You can see examples of these two macros in action in the Decisions and Product Requirements blu
eprints.

There are quite a few steps involved to set up this macro correctly, but once it's done, it's very easy to copy
the macro to other pages, or add it to a template.
To add the Page Properties macro to a page:

2. Choose Page Properties from the Confluence content category.
3. Choose Insert.
4. In the macro body create a two column table
5. In the left column list your 'properties' – these will be the column headings in your report table.
6. Apply the Heading column style to the left column - this will indicate to the Page Properties Report
macro that these are your properties.
7. In the right column list the value for each property – these will populate the rows in your report table
8. Save your page.
9. Add a label to your page - you'll need to specify this label in the page properties report macro
Next you need to add the Page Properties Report macro to a different page.
Screenshot: The Page Properties macro on a page in the editor, with a vertical layout.
Page properties layout options
Horizontal or vertical layout
You can choose to arrange the properties in your table vertically or horizontally. Just make sure you apply
the Heading row or Heading column style to your properties, to tell the Page Properties Report macro,
where to find them.
Here's an example of a horizontal layout.
Screenshot: The Page Properties macro on a page in the editor with a horizontal layout.
Hidden or visible
You can choose whether the contents of the Page Properties macro should be visible when someone views
the page.
This is useful when the information isn't relevant to everyone. For example if you're using this macro to track
when a policy was last reviewed and approved, you may only want that info to be visible on the page
containing the Page Properties Report macro, not the page itself.
Screenshot: Configuring the Page Properties macro to be hidden.
Using multiple Page Properties macros on one page

You can add multiple Page Properties macros on a single page, and choose whether to include all or only
specific macros in the report. You might use multiple macros because you want the information in the macro
to display in context with the rest of the page, or because you want to be able to report on individual Page
Properties macros separately.
The Page Properties macro includes an optional ID parameter that can be used to identify specific Page
Properties macros.
To show the contents of all Page Properties macros in the report:
1. Add a label to the page containing the Page Properties macros

2. Specify this label in the Page Properties Report macro
To show the contents of selected Page Properties macros in the report:
1. Add a label to the page containing the Page Properties macros

2. Specify an ID in the Page Properties macro that you want to report on
3. Specify both the label and ID in the Page Properties Report macro
Note: The Page Properties Report macro can only accept one page label, and one ID.
See the Page Properties macro in action in How to document product requirements in Confluence.
This powerful macro lets you create a summary page that pulls in information from multiple pages.

Page (None) Optional ID used to identify a particular Page Properties macro on a page.
Properties Specify this ID in the Page Properties Report to include summary information
ID from macros with this ID only.
Hidden False Determines whether the data in the Page Properties macro will be displayed on
the current page. This setting does not affect the display of the detail in the
Page Properties Report macro.
Limitations
You can't use macros in the left column as the data in this column is used to populate the column
headings in your Page Properties Report macro.
It is not possible to reference the metadata using the metadata key from within the page, or anywhere
else on a Confluence page.
There's a known issue where the macro does not work correctly when placed inside an expand
macro, which is inside a panel macro. See CONFSERVER-59594 GATHERING IMPACT .

Page Properties Report Macro
The Page Properties and Page Properties Report macro work together to
enable you to show summary information from one page on another On this page:
page. You can see examples of these two macros in action on the Decision
and Product Requirements blueprints.
Adding the Page
Properties Report
This macro was previously known as the Details Summary macro.
macro to a page
Reporting on
Adding the Page Properties Report macro to a page specific Page
Properties macros
To add the Page Properties Report macro to a page: CQL fields
Macro display
1. In the editor, choose Insert > Other Macros > Page Properties options
Report. Troubleshooting
2. Enter the Labels you want to report on - this is the label added to Limitations
pages containing the Page Properties macro.
3. Further narrow down your search by adding more fields, or Related pages:
specifying a Page Properties ID (more info on this below)
4. Choose Insert. Page Properties
Macro
Decisions Blueprint
Product
Requirements
Blueprint
Here's how the macro looks on your page:
And here's how you would set it up in the macro browser:

Reporting on specific Page Properties macros

It's possible to add multiple Page Properties macros on a page, and choose whether to include all or only
specific macros in the report. The Page Properties macro includes an optional ID parameter that can be
used to identify specific Page Properties macros.
To show the contents of:
Selected Page Properties macros in the report - specify the label for the page and the ID of the
particular Page Properties macro (under Options)
All Page Properties macros in the report - specify just the label for the page - leave the Page
Properties ID field blank.
Note: The Page Properties Report macro can only accept one ID.
CQL fields
CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in
some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add
filters to build up a search query, adding as many filters as you need to narrow down the search results.
For an OR search, specify multiple values in the same field.

So to show pages with 'label-a', 'label-b' or both you'd put 'label-a' and 'label-b' in the same Label
field, like this:
For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a
second Label field to the macro, and put 'label-b' in the second one, like this:
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to
add that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.
Label* Include pages, blog posts or attachments with these labels. OR (multiple values in the
same filter)
AND (multiple Label filters)
With Include pages that are children of this page. OR (multiple values in the
ancestor same filter)
This allows you to restrict the macro to a single page tree.
Contributor Include pages or blog posts that were created or edited by OR (multiple values in the
** these people. same filter)
Creator Include items created by these people. OR (multiple values in the

same filter)
Mentioning Include pages and blog posts that @mention these people. OR (multiple values in the
user same filter)
With parent Include only direct children of this page (further sub-pages EQUALS (one page only)
won't be included)
In space** Include items from these spaces. OR (multiple values in the

same filter)
Including Include items that contain this text. CONTAINS (single word or
text** phrase)
With title Include items that contain this text in the title. CONTAINS (single word or
phrase)
Of type** Include only pages, blogs or attachments. OR (multiple values in the

same filter)
** You can add these filters in CQL-powered macros but in search they're part of the standard search filters,
so they don't appear in the Add a filter menu.
Macro display options

These options control how the macro appears on your page.
Page Blank If not specified, the report will show data from all Page Properties macros on a
Properties page, where there are multiple macros. Specify an ID to include only data from
ID Page Properties macros with the same ID.
Title Title The heading to display on the first column in the report table. This column
column contains links to pages displayed by the report. The default column heading is
heading 'Title'.
Columns If not specified, the report will show all columns. You can specify a comma
to show separated list of columns to include.
If your column heading includes commas, use double quotes around the column
name. If your column heading includes quotes, use double quotes. For example,
A column, "My ""new"" column, yes", Third column
Number of 30 Number of items to display in the table before displaying pagination options for
items to additional items.
display
The macro can display a maximum of 3000 pages. System administrators can
increase or decrease this limit. It is a good idea to use pagination, rather than
listing all your pages in one go.
Sort by Modified Sort the table by a specific column heading. Enter the column name, exactly as
it appears in the corresponding Page Properties macro.
Select the Reverse Sort check box to sort the table in reverse order.
Show No Displays the number of comments for each page in the table.
Comments
Count
Show No Displays the number of likes for each page in the table.
Likes
Count
Troubleshooting
If your report is empty, check:
You have entered the label correctly and that the label does appear on pages containing a Page
Properties macro.
The Page Properties macros on each page are configured correctly.
Any other fields you have specified have not narrowed your search too far (for example there are no
pages with that label under the Parent page you've specified).
Limitations
The macro can display a maximum of 3000 pages. System administrators can increase or decrease this limit
using the pagePropertiesReportContentRetrieverMaxResult system property.
Page Tree Macro
Add the Page Tree macro to a page to display all or part of the hierarchy of
On this page:
pages in a space.
This macro is great for providing: Add this macro to

your page
quick and easy navigation to pages about a specific project, if the Change the macro
pages are organised together under one parent page parameters
a table of contents like experience to help people navigate a set of Other ways to add
procedures this macro
an overview of pages in the current part of the hierarchy in
documentation spaces.
Screenshot: The Page Tree macro in Confluence showing two levels of hierarchy.

To add the Page Tree macro to a page:

2. Choose Page Tree from the Confluence content category.
4. Choose Insert.
Screenshot: Configuring the Page Tree macro to display all pages below a specific page, in another space.

Root Page The Specify the parent page for the page tree. The tree will include all children of the
(root) home given page, plus their children and grand-children etc. The tree will not include
page of the root page itself.
the
space Specify the page title or a special value as follows:
Your page title — to specify a page name for the parent or root of the tree.
The tree will include all children and grand-children of the specified root. The
tree will not include the specified root page itself.
'@home' — will include all pages under the home page of the space
(default).
'@self' — will include all pages under the current page.
'@parent' — will include all pages under the parent of the current page,
including the current page.
'@none' — will include all pages in the space, including orphaned pages and
the home page.
Restrict to Current Enter a space name to show the page tree for a different space. Leave blank to
this space space use the current space.
key
Set this parameter before the Root Page if you intend to specify a root page in
another space.
Sort position Specify the order to display the pages in the tree. This sort order is for display
Pages By purposes only. It does not permanently re-arrange the page order. The value
(sort) may be one of the following:
bitwise — sort alphabetically, for example: title1, title10, title2.

creation — sort by date of creation.
modified — sort by order of date last modified.
natural — sort in 'natural' alphabetical order, for example: title1, title2, title10.
position — sort by the default Confluence sorting rules. If your pages have
been ordered manually, this sort will respect the defined order. Otherwise
the pages will be displayed in the 'natural' alphabetical order, such as: title1,
title2, title10.
Include false Select if you want the page tree to show excerpts from each page. The excerpts
Excerpts must be defined on each page by the Excerpt macro.
in Page
Tree
(excerpt)
Reverse false Select to show the pages in reverse (descending) natural order. Must be used in
Order combination with the Sort Pages By parameter.
(reverse)
Include false Select if you want to include a search box above the page tree. The search box
Search allows your readers to search within the page tree for the specified value.
Box above
Page Tree
(searchB
ox)
Show false Select if you want to display the 'expand all' and 'collapse all' links at the top of
Expand your page tree. Your readers can click these links to open or close all branches
/Collapse of the tree at once.
Links
(expandC Available values in wikimarkup and storage format:
ollapseA
ll) true – Show the 'expand all' and 'collapse all' options.
false – Do not show the options.
Start 1 Enter any number greater than 0 to set how many levels of children the tree
Depth should show when it opens for the first time.
(startDe
pth)

Macro name: pagetree
Macro body: None.
{pagetree:root=Page
Name|sort=natural|excerpt=true|reverse=false|startDepth=3|expandCollapseAll=true|searchBox=true}
Page Tree Search Macro
Add the Page Tree Search macro to a page to provide users with a way to
On this page:
search for pages in a specific page hierarchy.
This macro is useful when you want to provide a way to search: Add this macro to
your page
one section of the current space, such as in a knowledge base Change the macro
a specific part of a page hierarchy, such as one project in a space parameters
that contains multiple projects. Other ways to add
this macro
After someone enters a keyword and clicks the Search button on this
macro, the results are presented on Confluence's advanced search screen.
Screenshot: Page Tree Search macro on a Confluence page.
For a better search experience, check out the Livesearch Macro, or enable the integrated search field in
the Page Tree Macro.

To add the Page Tree Search macro to a page:

2. Choose Page Tree Search from the Confluence content category.
4. Choose Insert.


Name of none The name of the root page whose hierarchy of pages will be searched by this
Root Page macro. If this not specified, the root page is the current page.
(root)
Note: Unlike the Page Tree macro, the Page Tree Search macro does not
accept the special values that start with an @ sign, such as @home or @self.

Macro name: pagetreesearch
Macro body: None.
{pagetreesearch:root=My page name}
Panel Macro
On this page:
Add this macro to
Add the Panel macro to a page to format your text in a customizable your page
coloured panel. It's similar to the Info, Tip, Note, and Warning Macros Change the macro
except you have complete control over the border, background, title and parameters
text colours. Available colors
Other ways to add
This is great for adding some visual interest to your pages. You can use this macro
panels in table cells and in page layouts, as in the example below.
Screenshot: page with a purple Panel macro containing a list of useful links.

To add the Panel Map macro to a page:

2. Choose Panel from the Formatting category.
3. Enter any parameters. Leave blank for a simple white panel with a grey border.
4. Choose Insert.
Screenshot: specifying a title, border, and background colour in the Panel macro.

Panel Title none The title of the panel. If specified, this title will be displayed in its own
(title) title row.
Border Style solid The style of the panel's border. Accepted values are solid, dashed
(borderStyle) and other valid CSS border styles.
Border Color The color of the panel's border. Colors can be specified as HTML color
(borderColor) names or hexadecimal codes.
Border Pixel Width The width of the panel's border (in pixels).
(Value Only)
(borderWidth)
Background Color The background color of the panel. Colors can be specified as HTML
(bgColor) color names or hexadecimal codes.
Title Background The background color of the title row of the panel. Colors can be
Color specified as HTML color names or hexadecimal codes.
(titleBGColor)
Title Text Color The color of the text in the title row of the panel. Colors can be
(titleColor) specified as HTML color names or hexadecimal codes.
Available colors
You can enter the HTML or X11 name for a color such as Fuchsia, Teal, or MediumOrchid, or you can
enter hexadecimal values such as #FF00FF, #008080, and #BA55D3. You will need to include the #
symbol when entering a hexadecimal value. See Web colors for general information.

Macro name: panel
{panel:title=My
title|borderStyle=dashed|borderColor=blue|titleBGColor=#00a400|titleColor=white|bgColor=#72bc72}
A formatted panel
{panel}
Do more in Confluence
To further customize panels, check out these apps on the Atlassian Marketplace:
Panelbox: Create a set of designed panelboxes to display identical topics in the same style,
keeping your pages clear and easy to read
Panels: Make your intranet more interactive with a customizable panels
PDF Macro
Add the PDF macro to a page to display the content of a PDF document.
On this page:
First attach the document to a Confluence page, then use the macro to
display the document.
Add this macro to
This is great for sharing presentations, design documents, whitepapers, and your page
other visual data. Change the macro
parameters
This macro displays your file in a viewer, with next and back buttons, rather Other ways to add
than showing a simple preview. this macro
Screenshot: A page with a PDF macro displaying an A4 PDF document.

To add the PDF macro to a page:
1. Upload the PDF file to your page, then publish the page. See Upload Files to learn how to do this.
3. Choose PDF from the Confluence content category.
5. Choose Insert.
Screenshot: Configuring the PDF macro in the macro browser.


Page The page which Enter a page name, if you wish to display a document which is
Name contains the macro attached to another Confluence page.
(page)
File Name none The file name of the PDF document to be displayed. The document
(name) must be attached to a page on your Confluence site.

Macro name: viewpdf
Macro body: None.
{viewpdf:page=Docs|name=My document.pdf}
Popular Labels Macro
Add the Popular Labels macro to a page to highlight the most popular
On this page:
labels used throughout your Confluence site or within a space. A popular
label is a label that has been added to many pages.
Add this macro to
This is great for surfacing labels that might be trending in your site, for your page
example in a knowledge base. Change the macro
parameters
Other ways to add
this macro
Screenshot: The Popular Labels macro showing a heatmap of the 20 most popular labels.

To add the Panel Map macro to a page:

2. Choose Popular Labels from the Reporting category.
3. Enter any parameters and choose how you want the labels to display.
4. Choose Insert.
Screenshot: specifying a space key, number of labels, and heatmap display style.

Number of 100 Specifies the total number of labels to display in the heatmap.
Labels to Display
(count)
Restrict Labels none Restricts the list of popular labels to the specified space.
to this Space Key
(spaceKey)
Style of Labels list

(style) list – displays the popular labels as a bulleted list, ordered by
popularity (highest first).
heatmap – displays the popular labels using different font sizes for
each label depending on the label's popularity, ordered by label
names.

Macro name: popular-labels
Macro body: None.
{popular-labels:style=heatmap|count=20|spaceKey=ds}
Profile Picture Macro
Add the Profile Picture macro to a page to display a
On this page:
user's profile picture.
It's great for putting a face to the name on team and Interacting with the macro on a page
project pages. Change the macro parameters
Screenshot: Page with several Profile Picture macros.

To add the Profile Picture macro to a page:

2. Choose Profile Picture from the Confluence content category.
3. Enter a username.
4. Choose Insert.
Screenshot: specifying a user in the macro browser.

Interacting with the macro on a page

When viewing a page, hover your mouse-over the picture to see the Hover Profile for the user, and choose
the user's picture or name to view their user profile. When editing the page, you can also select the macro
and choose View User Profile to see the profile for the user.
Screenshot: The user profile macro displaying the profile picture for a user.

User none The username of the person you want to display a profile picture for.

Recently Updated Dashboard Macro
Add the Recently Updated Dashboard macro to a page to show a list of
On this page:
pages, blogs, files, and comments that have been created or edited
recently.
Add this macro to
This is a legacy macro, and was previously used to display recently your page
updated content on the dashboard. It is very similar to the Recently To add the
Updated Macro, except that it has a tabbed view, that lets you switch Recently Updated
between all updates, updates from your favorite spaces, updates from your Dashboard macro
network (the people you follow), or particular space categories. to a page:
Change the macro
parameters
Other ways to add
this macro
Screenshot: The Recently Updated Dashboard macro My Spaces tab showing a personalised view of recent
updates in the site.

To add the Recently Updated Dashboard macro to a page:

2. Choose Recently Updated Dashboard from the Confluence content category.
3. Enter any parameters.
4. Choose Insert.
Screenshot: Configuring the Recently Updated Dashboard macro to show updates from specific people.

Space(s) The space which Filter content by space. The macro will display only the pages etc
(spaces) contains the page which belong to the space(s) you specify here. You can specify one
on which the macro or more space keys, separated by commas.
is added
Use '*' for all spaces.
Include all types Filter content by type. You can specify one or more types, separated
these by commas. Available types are: page, blogpost or news, spaced
Content esc, attachment, comment, mail, userinfo.
Types
Only
(types)
Label(s) none Filter content by label. The macro will display only the pages etc
(labels) which are tagged with the label(s) you specify here. You can specify
one or more labels, separated by commas.
Note: If there are no pages matching any of the specified labels,
then Confluence will ignore the labels and will list all recently
updated pages.
User(s) all users Filter by username of the user who updated the content. The macro
(users) will only display content created and updated by the user(s) you
specify here. You can specify one or more usernames separated by
commas.
Width of 100% Specify the width of the macro display, as a percentage of the
Table window width.
(width)
Show false Select whether profile pictures of the users who updated the content
User are displayed.
Profile
Pictures
(showPro
filePic)

Macro name: recently-updated-dashboard
Macro body: None.
{recently-updated-dashboard:spaces=ds|users=admin|width=50%|showProfilePic=true|labels=choc|types=page}
Recently Updated Macro
Add the Recently Updated macro to a page to show a list of pages, blogs,
On this page:
files, and comments that have been created or edited recently.
This is great for: Add this macro to

your page
project landing or information pages Change the macro
team space home pages parameters
Other ways to add
It's very flexible, you can limit the list to specific people, spaces, types of this macro
content, and more.
Screenshot: project landing page showing recently created and updated pages.

To add the Recently Updated macro to a page:

2. Choose Recently Updated from the Confluence content category.
4. Choose Insert.
Screenshot: configuring the Recently Updated macro to show updates from specific people in a particular
space.

Author(s) None Filter the results by author. The macro will display only the pages etc which
by specified. were last modified by the author(s) you specify here.
username That is,
(author) display all You can specify multiple users.
content
Space(s) @self This parameter allows you to filter content by space. The macro will display
(spaces) only the pages etc which belong to the space(s) you specify here.
That is,
the space You can specify one or more space keys, separated by a comma or a space.
which
contains To exclude content in a specific space, put a minus sign (-) immediately in
the page front of that space key. For example: If you specify a space key of -
on which BADSPACE you will get only content which is not in the BADSPACE.
the macro To indicate that the results must come from a specific space, put a plus
is used sign (+) immediately in front of that space key. For example: If you specify
a space key of +GOODSPACE you will get only content in GOODSPACE.
(Note that this is not particularly useful, because each content item
belongs to one space only. If you put a plus sign next to one space key
and list other space keys too, the other space keys will be ignored.)
Special values:
@self — The current space.

@favorite — The spaces you have marked as favorite.
@favourite — The same as @favorite above.
* — The same as @all above.
When specifying a personal space, remember to use the tilde (~) sign in front
of the username, such as ~jbloggs or [email protected].
Label(s) None Filter the results by label. The macro will display only the pages etc which are
(labels) specified i. tagged with the label(s) you specify here.
e. display
all content You can specify one or more label values, separated by a comma or a space.
To exclude content which matches a given label, put a minus sign (-)
immediately in front of that label value. For example: If you specify a label
value of -badpage you will get only content which is not labeled with
'badpage'.
To indicate that the results must match a given label value, put a plus
sign (+) immediately in front of that label value. For example: If you
specify a label value of +superpage,+goodpage you will get only
content which has at least two labels, being 'superpage' and 'goodpage'.
The labels parameter only applies to the page and blog content types.
Width of 100% Specify the width of the macro display, as a percentage of the window width.
Table
(width)
Include All types This parameter allows you to filter content by content type. The macro will
these display only the content of the type you specify here.
Content
Types You can specify one or more types, separated by a comma or a space.
Only
(types) To exclude content of a given content type, put a minus sign (-) immediately
in front of that content type. For example: If you specify a content type of -
blogpost you will get pages and all other content except for blog posts.
Available values:
page — Pages.
blogpost or news — Blog posts, also known as news items.
comment — Comments on pages and blog posts.
attachment — Attachments.
Maximum 15 Specify the maximum number of results to be displayed. If this parameter is

Number of omitted, then a maximum of 15 results are displayed. The theoretical
Results maximum value that this parameter can accept is 2 to the power of 31, minus
(max) 1 (or 2147483647), though this has been limited to 200 in the code, for
performance reasons. More details are here.
theme concise Choose the appearance of this macro:

(theme)
concise — the default list, showing the names of pages which were
updated or commented on, the users who made the page modifications
and time when the modifications occurred.
social — lists recent modifications in reverse chronological order, but
groups them by user into short time segments. A 'sub' list appears within
each user's time segment, showing the names of pages which they
updated or commented on and time when these modifications occurred.
sidebar — lists recent updates in reverse chronological order, showing
the names of pages which were updated or commented on and time when
the page modifications occurred. This theme does not show authorship.
Show false Specify showProfilePic=true to display the profile pictures of the users
User who updated the content.
Profile
Pictures
(showPro
filePic)
Hide Title False Determines whether the macro hides or displays the text 'Recently Updated'
(hideHea as a title above the list of content. Only available in wikimarkup and storage
ding) format.
Accepted values:
true – Title is hidden.

false – Title is shown.

Macro name: recently-updated
Macro body: None.
{recently-updated:spaces=ds|author=admin|max=10|hideHeading=true|width=50%
|theme=sidebar|showProfilePic=true|labels=choc|types=page}
Recently Used Labels Macro
Add the Recently Used Labels macro to a page to display a list of labels
On this page:
that have recently been applied to a page, blog post or attached file.
This is great for keeping track of when new topics are added to things like: Add this macro to
your page
knowledge base articles Change the macro
process and procedure documentation parameters
project documentation. Other ways to add
this macro
You can confine the search to the current space, or the entire site.
Screenshot: a page using the Recently Used Labels macro to show the list of topics applied to knowledge
base articles recently.
You can also choose to configure this macro to show more detail, including the page titles and information
about the user who added the label.

To add the Recently Used Labels macro to a page:

2. Choose Recently Used Labels from the Confluence content category.
4. Choose Insert.
Screenshot: configuring the Recently Used Labels macro to show 35 recently applied labels.

Number of 10 Specifies the total number of labels to display in the list.

Labels to Display
(count)
Scope for global Specifies the scope of labels to be displayed in the list. Valid values
Retrieving Labels include:
(scope)
global — covers all site spaces (non-personal) in the Confluence
installation.
space — the current space.
personal — your own personal space.
List Style list

(style) list – displays the list of labels horizontally.
table – includes additional information such as the page to which the
label was added and the user who added it.
Table Title none Adds a title to the top of the list in table style. Titles are only visible when
(title) the List Style parameter has been set to table.
Macro name: recently-used-labels
Macro body: None.
{recently-used-labels:title=My title|scope=space|style=table|count=20}
Related Labels Macro
Add the Related Labels macro to give people a way to navigate to related
On this page:
content in your site.
It works by finding labels that pages have in common. It takes the label Add this macro to
used on the current page, looks for other pages that use this label, and then your page
lists any other labels that are found on those pages. Change the macro
parameters
this macro
Knowledge base articles
Process and procedure documentation.
Basically any situation where you want a map of related pages in your site.
The list updates automatically, as labels are added and removed from
pages over time.
Screenshot: the Related Labels macro guiding people to related articles in a knowledge base.

To add the Related Labels macro to a page:

2. Choose Related Labels from the Confluence content category.
3. Enter specific labels the macros should look for, or leave blank to use any labels on the page.
4. Choose Insert.
Screenshot: configuring the Related Labels macro in the macro browser.


Restrict to these none Specify the labels for which you want to view related labels. For example,
Labels documentation,how-to.
(labels)

Macro name: related-labels
Macro body: None.
{related-labels:labels=choc,cake}
Roadmap Planner Macro
Add the Roadmap Planner macro to a page to create a simple, visual
On this page:
timeline that's useful for planning projects, software releases and much
more.
Add this macro to
Roadmaps are made up of: your page
Editing your
bars to indicate phases of work Roadmap
lanes to differentiate between teams, products or streams Change the macro
markers to highlight important dates and milestones parameters
a timeline showing months or weeks. Other ways to add
this macro
You can provide more information about items on your roadmap by linking a Notes
bar to a page.
Screenshot: Page with a Roadmap Planner macro showing the various stages of a project.

To add the Roadmap Planner macro to a page:

2. Choose Roadmap Planner from the Visuals and images category.
3. Add lanes, bars and markers as described below.
4. Choose Insert.
Editing your Roadmap
To edit your roadmap:
Select the roadmap and choose Edit.

Add lanes, bars and markers.
Drag lanes, bars and markers to the desired location on the roadmap.
Select lanes, bars and markers to add text, change colors and remove from the roadmap.
Select bars to add links to existing pages, create new pages or add a description.
Set the start and end dates for the roadmap and choose to display it by weeks or months.
Screenshot: Adding bars and markets to the Roadmap Planner macro in the editor.
1. Add lanes: to differentiate your teams or streams of work.

2. Date range: display the plan by weeks or months.
3. Add bar info: to provide more info or link a bar to a page.

This macro does not use the macro browser to set parameters. You also cannot add this macro via wiki
markup or by editing the storage format directly.

Notes
The Roadmap macro was previously available from The Marketplace. The macro has changed significantly.
If you had an older version of the macro installed you will be able to view your existing roadmaps but not edit
them.
To extend Confluence's roadmap capability, check out these apps on the Atlassian Marketplace:
Live Roadmap: Build your Roadmap and keep it alive connecting it to your Jira
ProductPlan for Confluence Server: Embed your roadmap in Confluence to keep your team
aligned around high-level goals
RSS Feed Macro
Add the RSS Feed macro to a page to display the contents of an external or
On this page:
internal RSS feed. For example, to display blog posts or to list recently
updated pages in a space, you can create an internal feed in the Feed
Builder, then render it using this macro. Security
considerations
This is a legacy macro, and is often disabled by Confluence administrators Add this macro to
for security reasons. your page
Change the macro
parameters
How up to date is
the feed?
What happens to a
page containing a
disallowed URL?
Authentication
Enable or disable
the RSS Feed
macro
Other ways to add
this macro
The RSS Feed macro may be disabled by your Confluence administrator. Also, your Confluence
administrator can define a whitelist of trusted URLs. You will see an error message on the Confluence page,
if the included URL is not in the whitelist.
CAUTION: Including unknown HTML inside a webpage is dangerous.

HTML inside an RSS feed can contain active scripting components. This means that it would be
possible for a malicious attacker to present a user of your site with script that their web browser
would believe came from you. Such code could be used, for example, to steal a user's
authentication cookie and give the attacker their Confluence login password.

To add the RSS Feed macro to a page:

2. Choose RSS Feed from the External content category.
3. Enter the RSS feed URL.
4. Choose Insert.


RSS Feed URL none The URL of the RSS feed link you want to show.
(url)
Maximum Number of Entries 15 Limit the number of entries displayed.

(max)
Show Item Titles Only false Show only the titles of the news items, not the content.
(showTitlesOnly)
Show Name/Title of RSS Feed true Hide the feeds title bar.
(titleBar)
How up to date is the feed?

By default, the RSS Feed macro caches the feed results for 60 minutes before fetching the data again.
If you wish to change the default caching, use the Cache macro to define how often the RSS Feed macro
fetches the feed updates. You will need to install the Cache plugin onto your Confluence site.
What happens to a page containing a disallowed URL?

Your Confluence Administrator can set up a whitelist of allowed URLs. If this is the case, you may see an
error on the pages which contain the RSS Feed macro.
A user can add the RSS Feed macro or the HTML-include macro to a Confluence page. The macro code
includes a URL from which the content is drawn. When the page is displayed, Confluence will check the URL
against the whitelist. If the URL is not allowed, Confluence will display an error message on the page.
The error message says that Confluence "could not access the content at the URL because it is not from an
allowed source" and displays the offending URL. If the person viewing the page is a Confluence
Administrator, they will also see a link to the Administration page where they can configure the URL whitelist.
Here is an example of the error message, including the link shown only to Confluence Administrators:
Here is an example of the error message, but without the link.
Authentication
Private feeds from external sites
RSS feeds which require authentication cannot be accessed using the RSS Feed macro.
Accessing internal HTTPS feeds
This applies only to Confluence instances which have enabled HTTPS for all content. If your site is fully
HTTPS, the RSS Feed macro cannot access internal feeds. To enable the RSS Feed macro to access
internal feeds without affecting your HTTPS setup, enable local-only HTTP access:
1. Shut down Confluence.

2. Consult the SSL guide to enable HTTP access to Confluence. You'll want to ensure that you have an
HTTP connector and an SSL connector, both commented in. This means that Confluence will be
accessible via both HTTP and HTTPS. However, you should not have a redirect port, nor rules in web.
xml to redirect all traffic.
3. Instead of using web.xml to redirect traffic, insert a firewall rule to redirect all HTTP requests not from
the Confluence server to the equivalent HTTPS URL. This ensures that users will only be able to
access Confluence via HTTPS, as intended. If you have still left HTTP access for attachments
enabled (to avoid the IE download bug) you must selectively enable those URLS as well.
4. Modify your Confluence RSS Feed macro feed link to use the HTTP URL, and restart Confluence.
Enable or disable the RSS Feed macro

To enable or disable the RSS Feed macro:

3. Expand the listing and enable or disable the rss (rss-xhtml) module.

Macro name: rss
Macro body: None.
{rss:max=10|showTitlesOnly=true|url=http://myblog.com/feed|titleBar=false}
Search Results Macro
Add the Search Results macro to a page to display the results of a pre-defined search.


Search none The search terms which this macro will use to generate its results.
Terms
(query) You can refine your search query by using operators such as 'AND' and 'OR'. For
example: my_query1 AND my_query2
For more information, take a look at the documentation on the Confluence search
syntax.
Maximum 10 Set a limit to the number of search results displayed.

Number of
Results
(maxLimit)
Restrict to all Start typing the space name to find the space, or specify the key of the space you
this Space want to search in. Note that the key is case sensitive.
Key
Content all Specify the content type. The content types are: page, comment, blogpost, attac
Type hment, userinfo (the content of user profiles only) and spacedesc (the content of
(type) space descriptions only).
Last all Specify a period of time in weeks, days, hours and/or minutes, to see the content
Modified modified within that time frame.
(lastModi
These are the values you can use:
fied)
w = weeks
d = days
h = hours
m = minutes
For example:
2h 35m
3d 30m
Notes:
If no time category is specified, Confluence assumes minutes.

If you specify more than one time period (for example, weeks and days), you
must separate the periods with a space. You can put them in any order.
The time categories are not case sensitive. For example, '4d' is the same as '4D
'.
Restrict to all Specify the username of a Confluence user, to show only content created or
this updated by that user.
Username
(contribu
tor)
Notes
Permissions: When a user views the page containing the Search Results macro, the search results will show
only pages and other content types for which the user has 'View' permission.

Macro name: search
Macro body: None.
{search:lastModified=3w|query=choc|contributor=admin|maxLimit=10|type=page|spacekey=ds}
Section Macro
Add the Section macro to a page to organise your content in sections and
On this page:
columns. This macro is used in conjunction with the Column macro, and
provides more flexibility than page layouts.
Add this macro to
This macro is great for situations where: your page
Change the macro
you need more than three columns, or parameters
you need your columns to be a specific width. Other ways to add
this macro
Screenshot: page with a four column layout using the Section and Column macros.
Want a simpler way to lay out your page? Try a page layout instead.

To add the Section macro to a page:

2. Choose Section from the Formatting category.
3. Choose Insert.
You can then start typing into the macro body, add some Column macros, then publish your page to see the
macro in action.
Screenshot: section and column macros in the editor


Show Border false Select this option to draw a border around the section and columns.
(border)
Note: Without a Column macro , the border will not be displayed correctly.

Macro name: section
Macro body: Rich text, consisting of one or more Column macros.
{section:border=true}
{column:width=100px}
{column}
{column}
{column}
{section}
Space Attachments Macro
Add the Space Attachments macro to a page to display a list of all files
On this page:
attached to pages in the current space, or another space.
This is great for: Add this macro to

your page
design assets To add the Space
frequently used files, like forms Attachments macro
image libraries. to a page:
Change the macro
It shows details of the file and the includes a link to the page the file is parameters
attached to. Filter the list by label or file extension to find the file you're Other ways to add
looking for more easily. this macro
Screenshot: A page containing the Space Attachments macro, to provide quick access to files used in a
project.

To add the Space Attachments macro to a page:

2. Choose Space Attachments from the Confluence content category.
4. Choose Insert.
Screenshot: Configuring the Space Attachments macro to only show files attached to pages in a specific
space.

Space (none) Selects the Confluence space to display attachments for. If you do not specify a
space, the current space will be used.
Show true Determines whether or not the filter panel is shown. If you select this option,
Filter people viewing the page will be able to filter the list of attachments by file type
Controls (extension) and by label.
(showFil
ter)

Macro name: space-attachments
Macro body: None.
{space-attachments:showFilter=false|space=ds}
Space Details Macro
The Space Details macro displays the details of a Confluence space, including the space name, description,
and more.


Width of 100% The width of the space details table, specified as a percentage (%) of the page
Table width.
(width)

Macro name: space-details
Macro body: None.
{space-details:width=50%}
Spaces List Macro
Add the Spaces List macro to a page to display a list of spaces on a page.
On this page:
This is legacy macro. It was previously used in the dashboard, and has
been known to cause issues large sites. Although limited, this macro is Add this macro to
great if you want to: your page
To add the Spaces
highlight spaces that have been created in the last 7 days List macro to a
provide a list of spaces, that can be filtered by space category. page:
Change the macro
parameters
Troubleshooting
Other ways to add
this macro
Screenshot: Page with a Spaces List macro showing cross-team spaces.
This macro works best with space categories. See Use Labels to Categorize Spaces to find out how
to categorize spaces in your site.

To add the Spaces List macro to a page:

2. Choose Spaces List from the Confluence content category.
4. Choose Insert.
Screenshot: Configuring the spaces list macro to show spaces by category.


Parameter Required? Default Description
Scope of spaces no all The view from which spaces are listed. Available
options are:
(blank) - All spaces in your site, with tabs.

all – All spaces in your Confluence site.
category – Spaces grouped according to space
categories.
favorite – Spaces which you have added to My
Spaces.
new – spaces created within the last 7 days.
This parameter is unnamed in wiki markup and storage

format.
Width of List no 100% The width of the spaces list, specified as a percentage
(width) (%) of the window width.
Include archived no False Include spaces that have been archived in the list.
spaces These are excluded by default.
(includeArchivedS
paces)
Troubleshooting
This macro is known to cause issues in sites with large number of spaces. See
CONFSERVER-59804 - Using the Spaces List macro in a Confluence Page may overload the database
GATHERING IMPACT
This macro is provided by the Dashboard Macros system app. Disable the Spaces module if you want to
prevent people using this macro.

Macro name: spaces
Macro body: None.
{spaces:favourite|width=80%}
Status Macro
Add the Status macro to a page to highlight the
On this page:
status of a project, task, or item with a colored
lozenge (rounded box).
Using the Status macro
This macro is great for indicating: To add the Status macro to a page:
items that are problematic or removed Other ways to add this macro
a successful project
tasks that are in progress.
You can choose a solid or light background color for

the lozenge and the text that appears inside the
lozenge. The macro displays its current
status directly in the editor.
Screenshot: Status macros in a table highlighting important tasks, actions, and items.
See the Status macro put to excellent use in How to build a release planning page in Confluence.
Using the Status macro

To add the Status macro to a page:

2. Choose Status from the Confluence content category.
3. Enter a status and choose a color.
4. Choose Insert.
Screenshot: Selecting lozenge colour in the Status macro.


Color Grey The color of the lozenge. The following colors are available: Grey , Red, Yellow,
(colour) Green and Blue.
Title The The text that will appear inside the lozenge. If you do not specify any text, the
(title) color title will be the color of the lozenge, that is 'Grey', 'Red', 'Yellow', 'Green' or
that you 'Blue'.
select.
Use False The lozenge background color and text color. The default lozenge style is a
lighter solid background color with white text. Select this parameter to use a lighter
lozenge lozenge background color with colored text.
color
(subtle)

Macro name: status
Macro body: None.
{status:colour=Green|title=On track|subtle=true}
For more customizable status macros check out these apps on the Atlassian Marketplace:
Build Status Tracker for Confluence: Provide visibility on build status from Bamboo or Jenkins
on your Confluence pages
Spectrum Formatting Macros: Show a page status as a draft, as outdated, as action required
or as official
Table of Contents Macro
Add the Table of Contents macro to a page to help
On this page:
your readers skip directly to the information they’re
looking for.
Using the Table of Contents macro
This macro is great for situations where: Change the macro parameters
Examples
you have a large page with lots of information Other ways to add this macro
you want to build your headings into a neat Notes and known issues
table of contents.
This macro is popular because it helps you navigate

lengthy pages. The macro organises your table of
contents by nesting Heading 2 under Heading
1, and indenting progressively, like in the image
below.
Screenshot: Table of Contents macro neatly organises lengthy blog content.
Using the Table of Contents macro

To add the Table of Contents macro to a page:

2. Choose Table of Contents from the Confluence content category.
4. Choose Insert.
Screenshot: Entering parameters for the Table of Contents macro.


Output list
Type list — produces a typical list-type table of contents.
(type) flat — produces a horizontal menu-type series of links.
Display clear Select the check box to apply outline numbering to your headings, for example:
Section 1.1, 1.2, 1.3.
Numbering
(outline)
List Style disc Select the style of bullet point for each list item. You can use any valid CSS
(style) style. For example:
none — no list style is displayed

circle — the list style is a circle
disc — the list style is a filled circle. This is the typical bullet list, and is
used for this example list.
square — the list style is a square
decimal — the list is numbered (1, 2, 3, 4, 5)
lower-alpha — the list is lower-case, alphabetized (a, b, c, d, e)
lower-roman — the list style is lower roman numerals (i, ii, iii, iv, v, vi)
upper-roman — the list style is upper roman numerals (I, II, III, IV, V, VI)
Heading Sets the indent for a list according to CSS quantities. Entering 10px will
Indent successively indent heading groups by 10px. For example, level 1 headings will
(indent) be indented 10px and level 2 headings will be indented an additional 10px.
Separator brackets This parameter applies to flat lists only. You can enter any of the following
(separat values:
or)
brackets — Each item is enclosed by square brackets: [ ].
braces — Each item is enclosed by braces: { }.
parens — Each item is enclosed by parentheses: ( ).
pipe — Each item is separated by a pipe:
anything — Each item is separated by the value you enter. You can enter
any text as a separator, for example "***". If using a custom separator, be
aware that text displays exactly as entered, with no additional white space to
further separate the characters.
Minimum 1 Select the highest heading level to start your TOC list. For example, entering 2
Heading will include levels 2, and lower, headings, but will not include level 1 headings.
Level
(minLevel
)
Maximum 7 Select the lowest heading level to include. For example, entering 2 will include
Heading levels 1 and 2, but will not include level 3 headings and below.
Level
(maxLevel
)
Include Filter headings to include according to specific criteria. You can use wildcard
Headings characters. See Sun's Regex documentation for examples of constructing
(include) regular expression strings.
Exclude Filter headings to enclude according to specific criteria. You can use wildcard
(exclude) regular expression strings.
Printable checked By default, the TOC is set to print. If you clear the check box, the TOC will not
(printab be visible when you print the page.
le)
CSS Class If you have custom TOC styles in your CSS style sheet, use this parameter to
Name output the TOC inside <div> tags with the specified class attribute.
(class)
Absolute By default, the links in the TOC are relative URLs pointing to the current page. If
URL checked, the links in the TOC will be full URLs. This setting is useful when you
(absolut are including a page with a Table of Contents in another page, and want to
eUrl ) control where the links should take the user.
Examples
The examples below are based on this table of contents:
Filtered Table of Contents
This example filters the headings to include those that contain 'Favorite', but excludes headings which end
with 'Things'. The list is styled with Roman numerals.
Parameter Value
List Style upper-roman
Include Headings Favourite.*
Exclude Headings .*Things
The resulting table of contents is:
Flat List
This example filters all headings to render a flat list of 'Unknowns' enclosed in square brackets (the default
list style).
Parameter Value
Output Type flat
Maximum Heading Level 2
Include Headings Unknown.*
The resulting table of contents is:

Macro name: toc
Macro body: None.
This example shows a list-type table of contents.
{toc:printable=true|style=square|maxLevel=2|indent=5px|minLevel=2|class=bigpink|exclude=[1//2]
|type=list|outline=true|include=.*}
This example shows a flat table of contents.
{toc:printable=true|maxLevel=2|minLevel=2|class=bigpink|exclude=[1//2]
|type=flat|outline=true|separator=pipe|include=.*}
Notes and known issues

When you use a Table of Contents macro in a template, you will see an error when you preview the
template itself. But the Table of Contents macro works on the pages that people create from the
template – the table of contents shows up after they have saved the page. (This is probably because
the template is not defined as a page, and the Table of Contents macro works for pages only.)
The Table of Contents macro only displays page or blog post content. You can't use it to add a table
of contents of headings in a comment for example.
Due to an outstanding issue in the Table of Contents macro (CONF-10619), the macro browser's Refr
esh function does not render any parameter modifications. Currently, the rendering of parameter
value modifications to the Table of Contents macro occurs only after the page is saved.
Using HTML heading markup with the Table of Contents macro

The Table of Contents macro cannot handle HTML heading markup on its own. Hence, if you use the
HTML and HTML Include macros to render HTML heading markup in a Confluence page, the Table of
Contents macro will not create a contents list out of these headings.
However, if you insert an HTML anchor into each HTML heading on your page (based on the
following syntax), the Table of Contents macro will incorporate these headings into your contents list.
<h2><a name="pagename-headingname"></a>Heading Name</h2>
The syntax for the anchor name is the page name and heading name separated by a hyphen.
Remove all spaces and convert all text to lower case. Convert all punctuation marks to their URL-
encoded equivalent.
There is a known issue where if you click a heading in the Table of Contents macro, then click the
back button in your browser, you won't be returned to the table of contents (or to your previous page).
As a workaround, use the Table of Content Zone Macro. See
CONFSERVER-40462 GATHERING IMPACT and CONFSERVER-52497 GATHERING IMPACT
for more information.
Extend Confluence with one of the hundreds of other macros in the Atlassian Marketplace. Here's
some specific to documentation:
Scroll Office for Confluence - turn your Confluence pages pages into professionally styled
documents
Advanced Children Display for Confluence: combine Confluence's built-in children display and
table of contents macros
Table of Content Zone Macro
Add the Table of Content Zone macro to a page to display a table of
On this page:
contents from a defined section of the page.

your page
creating a table of contents from sections of a page Change the macro
having multiple table of contents throughout a very long page. parameters
Examples
You'll have to create a table of contents for headings within the body of the Other ways to add
macro. this macro
Troubleshooting
Screenshot: The Table of Content Zone macro configured with flat Output Type.

To add the Table of Content Zone macro to a page:

2. Choose Table of Content Zone from the Confluence content category.
4. Choose Insert.
5. Add or paste your content into the macro body. The headings within the macro will be included in the
table of contents.
Screenshot: Entering headings within the body of the Table of Content Zone macro.

location both Specifies where in the zone the output list is displayed: top, bottom, or both,
(location which encloses the page zone content.
)
Output list Specifies the layout for the table of contents:

Type
(type) list – produces a vertical list.
flat – produces a horizontal menu-type series of links, for example: [Heading
1] [Heading 2] [Heading 3].
Display false Select to apply outline numbering to your headings, for example: 1.1, 1.2, 1.3.
Section
Numbering
(outline)
List Style none Specifies the style of bullet point for each list item. You can use any valid CSS
(style) style. For example:
none — no list style is displayed

circle --- the list style is a circle
disc — the list style is a filled circle. This is the typical bullet list, and is the
one we're using for this example list
square — the list style is a square
decimal — the list is numbered (1, 2, 3, 4, 5)
lower-alpha — the list is lower-case, alphabetized (a, b, c, d, e)
lower-roman — the list style is lower roman numerals (i, ii, iii, iv, v, vi)
upper-roman — the list style is upper roman numerals (I, II, III, IV, V, VI)
Heading Sets the indent for a list output type, according to CSS quantities. Entering
Indent "10px" will successively indent list heading levels by 10px. For example, h1
(indent) headings will be indented 10px and h2 headings will be indented an additional
10px.
Separator brackets Only applies to the flat output type. Specifies the display style of the links. You
(separat can enter any of the following values:
or)
brackets — Each item is enclosed by square brackets: [ ].
braces — Each item is enclosed by braces: { }.
parens — Each item is enclosed by parentheses: ( ).
pipe — Each item is separated by a pipe:
anything — Each is separated by the value you enter. You can enter any
text as a separator, for example '***'. If using a custom separator, be aware
that text displays exactly as entered, with no additional white space to
further separate the characters.
Minimum 1 Select the largest heading level to start your list. For example, 2 will list h2, h3,
Heading and h4 headings, but will not include h1 headings.
Level
(minLevel
)
Max 7 Select the smallest heading level to include in the table of contents. For
Heading example, 2 will list h1 and h2, but will not include h3 and below.
Level
(maxLevel
)
Include Filter the included headings according to specific criteria. You can use wildcard
(include) regular expression strings.
Exclude Exclude headings according to specific criteria. You can use wildcard
(exclude) regular expression strings.
Printable true By default, the table of contents is set to print. If you clear this parameter, the
(printab table of contents will not be visible when you print the page.
le)
CSS Class If you have a custom table of contents in your CSS style sheet, you can use this
Name parameter to output the table of conents with the specified "class" attribute.
(class)
Examples
The examples are based on a page with the following headings:
Filtered Table of Contents
This example will filter all headings to include those that contain "Favorite", but will exclude any heading
which ends with the word "Things". The list is styled with upper-case Roman numerals.
Parameter Value
Output Type list
List Style upper-roman
Include Headings Favourite.*
Exclude Headings .*Things
Screenshot: Filtered TOC 'zone' headings
Flat List
This example will filter all headings to render a flat list of "Unknowns" enclosed in square brackets.
Parameter Value
Output Type flat
Separator brackets
Max Heading Level 2
Include Headings Unknown.*
Screenshot: Filtered TOC 'zone' headings displayed as a flat list

Macro name: toc-zone
{toc-zone:printable=false|maxLevel=2|minLevel=2|location=top|type=flat|outline=true|separator=pipe}
Only headings within this block are included in the table of contents.
{toc-zone}
Troubleshooting
Using HTML heading markup with the Table of Content Zone macro — The Table of Content Zone macro
cannot handle HTML heading markup on its own. Hence, if you used the HTML and HTML Include macros
to render HTML heading markup in a Confluence page, the Table of Content Zone macro will not create
a contents list out of these headings.
However, if you insert an HTML anchor into each HTML heading on your page (based on the following
syntax), the Table of Content Zone macro will incorporate these headings into your contents list.
<h2><a name="pagename-headingname"></a>Heading Name</h2>
The syntax for the anchor name is the page name and heading name separated by a hyphen. Remove all
spaces and convert all text to lower case. Convert all punctuation marks to their URL-encoded equivalent.
Task Report Macro
Add the Task Report macro to a page to display a list of tasks. Filter the
On this page:
tasks by space, page, user, label, created date and more.

your page
meeting notes Change the macro
status reports parameters
project planning pages. Other ways to add
this macro
See Add, Assign, and View Tasks for more information on creating and
assigning tasks. You can also use the Task Report blueprint, which will Related pages:
create a page and add this macro for you.
Add, Assign, and
View Tasks
Screenshot: The Task Report macro showing incomplete tasks on a meeting notes page.

To add the Task Report macro to a page:

2. Choose Task Report from the Confluence content category.
4. Choose Insert.
Screenshot: Configuring the Task Report macro to show tasks from a specific space.

Space(s) No None Filter by the task location. The macro will only display tasks in
and Page the pages or spaces specified. You can enter a combination of
(s) spaces and pages.
(spaceAnd
Page)
Label(s) No None Filter by Label. The macro will only display tasks on pages with
(labels) at least one of the specified labels (for example, 'label-a' OR
'label-b'). Enter multiple labels, separated by a comma.
Assigned No None Filter by Assignee. The macro will only display tasks assigned
to to the users specified.
(assignee
)
Created by No None Filter by Creator. The macro will only display tasks created by
(creator) the users specified.
Created No None Filter by created date. The macro will only display tasks created
after on or after the date specified. Date must be entered as dd-mm-
(createdd yyyy.
ateFrom)
Task Yes Incomplete Show complete or incomplete tasks.

status
(status)
Number of No 20 The number of tasks to display on each page of results in the

tasks to table. Choose from 10, 20 or 40.
display
(pageSize
)
Display No description, Columns to include in the table. Available columns include desc
columns duedate, ription, duedate, assignee, location, completedate and labels.
(columns) assignee,
location
Sort by No Due date Sort tasks by due date, assignee or page title.
(sortBy)
Select the Reverse Sort check box to sort the table in reverse
order.

User List Macro
Add the User List macro to a page to display a list of Confluence users, in a
On this page:
particular group. The macro can also indicate when users are online or
offline.
Limitations
This is a legacy macro, and can cause performance issues in very large Add this macro to
sites. We recommend you don't use this macro to attempt to show all users your page
in a site. Change the macro
parameters
Other ways to add
this macro
Screenshot: A page containing two User List macros.
Limitations
The User List macro can be quite memory hungry in sites with lots of users. To prevent it causing out of
memory errors in your site, we don't show this macro if there are more than 10,000 people in the groups
specified. Your administrator can change this limit using the confluence.extra.userlister.limit sys
tem property.

To add the User List macro to a page:

2. Choose User List from the Confluence content category.
3. Enter the group you want to display.
4. Choose Insert.
Screenshot: Configuring the User List macro to show the members of a group.

Group(s) none Specify the group name. Specify multiple groups separated by a
(groups) comma, or use * to show all users in Confluence.
See this knowledge base page for more information about controlling
which users can see the details of other users.
Display Online All List online or offline users. Leave blank to show all users, irrespective
/Offline Users registered of status.
(online) users
Accepted values:
Unspecified – The macro will show all registered users.

true – The macro will show only online users.
false – The macro will show only offline users.

Macro name: userlister
Macro body: None.
{userlister:groups=confluence-users|online=false}
User Profile Macro
Add the User Profile macro to a page to show profile information about a
On this page:
user.
This can be useful for: Add this macro to

your page
team space homepages Change the macro
project pages. parameters
Other ways to add
The macro will display any details the user has added to their profile, such this macro
as their phone number, role, department, and location.
Screenshot: Four User Profile macros on a project page.
This macro is more useful if your profile is complete. Head to Your User Profile to find out how you
can edit your profile details.

To add the User Profile macro to a page:

2. Choose User Profile from the Confluence content category.
3. Enter the username of the person you want to display.
4. Choose Insert.
Screenshot: Specifying a user in the User Profile macro.


Username none The username of the Confluence user whose profile summary you wish to show.
(user)

Macro name: profile
Macro body: None.
{profile:user=admin}
View File Macro
The View File macros allow you to embed an Office or PDF document on a
On this page:
page. First attach the document to a page and then use one of the View
File macros to display the document's content.
Add this macro to
When people view the page, they will see the content of the Office or PDF your page
document. They do not need to have Office installed in order to see the Supported file types
content of the file. Editing files
Importing content
For specific information about each macro, see: from Word
documents
Office Excel Macro
Office Word Macro
PDF Macro

To add a View File macro to a page:

2. Choose Office Excel, Office PowerPoint, Office Word, or PDF from the Confluence content categ
ory.
3. Select the file you want to display and enter any additional parameters.
4. Choose Insert.

To display an Office or PDF document in a page, use one of the following View File macros in the macro
browser:
Office Excel (.xls and .xlsx)

Office PowerPoint (.ppt and .pptx)
Office Word (.doc and .docx)
PDF (.pdf)
Editing files
You can edit files embedded with the View File macro using your preferred desktop application, then save
the file back to Confluence automatically. Head to Edit files for instructions.
Word and Excel – choose the Edit button above the content.
PowerPoint and PDF – choose the edit icon on the viewer.
Importing content from Word documents

If you want to use the contents of your Word document to create a Confluence page, see Import a Word
Document into Confluence.
Widget Connector Macro
Add the Widget connector to a page to embed
On this page:
online videos, slideshows, photostreams and more.
This is great for bridging the gap between Add this macro to your page
Confluence and other sites and services your team Change the macro parameters
uses to get work done. Examples
YouTube
The macro currently supports content from these Vimeo
sites: Flickr
Twitter
YouTube Google Docs, Slides, and Sheets
Vimeo Google Calendar
Twitter Google Maps
Google Docs, Sheets, and Slides Facebook
Google Calendar LinkedIn
Google Maps Microsoft Stream
Wufoo Figma
Facebook Spotify
LinkedIn Prezi
Microsoft Stream Other ways to add this macro
Figma
Spotify
Prezi
It can also display content from these sites, once

they have been added to the whitelist:
Scribd
Flickr (requires Flash)
Slideshare (requires Flash)
Viddler (requires Flash)

To add the Widget Connector macro to a page:

2. Choose Widget Connector from the Media category.
3. Enter the URL you want to display.
4. Choose Insert.

Web Site's This is the external site's URL. In some sites this will be the URL shown in the address bar
Widget of your browser, and in other sites you may need to click a Share or Link button to get the
URL URL.
(url)
Pixel The height of the display, in pixels.

Height
(Value
Only)
(height)
Pixel The width of the display, in pixels.

Width
(Value
Only)
(width)
Examples
Every site is a little different, so we've put together some info on what you'll need to do to embed content
from each site on a page.
YouTube
The fastest way to embed a YouTube video is to paste the URL into the editor. Confluence will autoconvert
the link and insert the macro for you, like magic. Autoconvert works with both long and short YouTube URLs.
If you're pasting the URL into the Widget Connector macro URL field manually, you'll need to use the long
URL (from the address bar). Long URLs look something like this https://www.youtube.com/watch?
v=k6lK5hlB1nQ.
If you're not able to see the video in some browsers, try using https rather than http in your
link.
Links that contain a parameter to start a video at a particular time won't autoconvert or work in
the Widget Connector macro, like this link: https://www.youtube.com/watch?t=15&v=L
hHKkodOPFo. Paste in the short sharing URL to be sure it works.
Vimeo
The fastest way to embed a Vimeo video is to paste the URL into the editor. Confluence will autoconvert the
link and insert the macro for you.
You can use the URL from the address bar in your browser or the Share button in Vimeo.
Flickr
You can embed albums (formerly known as sets) and tags. You can't embed individual photos or user
photostreams.
You'll need to add the Widget Connector macro to the page first and then paste your link into the URL field.
Use the URL from the address bar in your browser.
The Widget Connector uses Flash to display this content. For security reasons, Flash is disabled in most
modern browsers.
Twitter
You can embed single tweets, profiles, lists, and moments.
Single Tweets
To embed a single tweet, click Copy link to tweet. Add the Widget Connector macro to the page and paste
the link into the URL field.
When the embedded Tweet is a reply, the parent Tweet will be displayed above the reply.
Profiles and Lists
Click on the Profile or List and copy the URL from the address bar of your browser. Paste the URL into the
editor and Confluence will autoconvert the link and insert the macro for you.
Alternatively, you can Copy link to profile or Copy link to List. These links won’t autoconvert, you’ll need
to add the Widget Connector macro to the page and paste the link into the URL field.
Moments
Click on the Moment, copy the URL from the address bar of your browser, or select Copy link to this. Add
the Widget Connector macro to the page and paste the link into the URL field. If you see an error rendering
tweet message, replace the word 'events' with 'moments' in the URL field.
Google Docs, Slides, and Sheets
In Google Docs, Sheets, or Slides, click File and select Publish to the web. Click Publish then copy the
link. Paste it into the editor and Confluence will autoconvert the link and insert the macro for you.
Google Calendar
Open Google Calendar and select Settings. Click the name of the calendar you want to embed.
You can only embed public calendars. To allow all visitors to see your calendar, open Access permissions
and check the box next to Make available to public.
In the Integrate calendar section, copy the Public URL to this calendar. Paste the URL into the editor and
Confluence will autoconvert the link and insert the macro for you.
Google Maps
You can embed interactive maps for a business, address, place, Street View 360-degree panorama, and
some (not all) search results (such as Bars, Banks, and Restaurants).
Business, address, and place
Copy the URL of a business, address, or place from the address bar of your browser and paste it into the
editor. Confluence will autoconvert the link and insert the macro for you.
Street View and search results
In Street View mode, or when viewing search results, click the menu and go to Share or embed map > Emb
ed a map > COPY HTML. Paste the link into the editor and Confluence will autoconvert the link and insert
the macro for you. You'll need to delete the additional iframe tags in the editor or they will display alongside
the map.
Facebook
On a public post, go to Embed > Advanced Settings and copy the URL of this post. Paste the URL into
the editor and Confluence will autoconvert the link and insert the macro for you. If you can't see the post
headline, description, or like count, change the Pixel Height and Pixel Width Values in the macro parameters.
LinkedIn
Only LinkedIn posts that an author has shared as Public can be embedded. Posts can include articles,
images, and videos. Select Embed this post.
Copy the code without including the HTML iframe tags, like in the image below. Paste the code into the
editor and Confluence will autoconvert the link and insert the macro for you.
Alternatively, click Copy code. Paste the code into the editor and Confluence will autoconvert the link and
insert the macro. You'll need to delete the additional iframe tags in the editor or they will display alongside
the LinkedIn post.
Microsoft Stream
To share a video, select the Share button and copy the Direct link to video. Paste the link into the editor
and Confluence will autoconvert the link and insert the macro for you. You can also paste the URL from the
address bar on the video page.
Only people authorized to see a video will be able to view it. If you receive a playback error message, select
the Open in new window button in the message to play the video in a new window.
Figma
Open a Figma file and click Share. In the Link Sharing settings, select Anyone with the link can view. Click
Copy link. Paste the link into the editor and Confluence will autoconvert the link and insert the macro for you.
If you’re using Figma in the browser, you can copy the URL from the address bar and paste it into the
editor. Confluence will autoconvert the link.
Hover your cursor over the embedded file to see options for full-screen mode and zooming in and out. You
can click, hold, and drag the embedded file to see more of it. Clicking the file name link in the bottom-left of
the embedded file will open the file directly in Figma.
Spotify
You can embed a song, album, or artist.
Click Copy Link when using the web player. If you’re using the desktop app, select Share > Copy Link.
Paste the link into the editor and Confluence will autoconvert the link and insert the macro for you.
Alternatively, in the web player, copy the URL from the address bar and paste it into the editor. Confluence
will autoconvert the link.
Prezi
Open a Presentation, Design, or Video, and Copy the link. Paste the link into the editor and Confluence will
autoconvert the link and insert the macro for you.
Alternatively, from your Prezi dashboard, select Share view link on a Presentation or Share on a Design. Co
py the link, paste it into the editor and Confluence will autoconvert the link.
Troubleshooting
If the Widget Connector can't display content from the external site, the macro will look like this:
example.com
We rely on the external website's APIs to display content in the Widget Connector macro. APIs do change
from time to time and this can cause the Widget Connector macro to stop rendering content.
If you experience problems, you can raise an issue about it to let us know.
Some sites must be whitelisted
The following sites need to be added to Confluence's whitelist before the macro can display any content.
This is due to the way we need to connect to that site.
Scribd
Flickr
Slideshare
Viddler
Some content requires Flash
The Widget Connector requires Flash for Flickr, Slideshare, and Viddler. This is blocked by most modern
browsers due to security concerns. We don't recommend you enable the Flash plugin in your browser.

Macro name: widget
Macro body: None.
{widget:height=400|width=400|url=http://youtube.com/watch?v=23pLByj_q5U}
Your profile and settings
Confluence is very flexible – not only in the many ways you can create and
Related pages:
share content, but also in how you can tailor your own Confluence
experience. Things like your profile picture, favorite spaces and pages, and Watch Pages,
your personal space can say a lot about you, and can also make navigating Spaces and Blogs
Confluence much quicker and easier. Even a simple thing like adding Create a Space
shortcut links to the sidebar of your personal space, can save you a lot of Save for later
time in finding the things you use all the time.
Set up your personal space, and take a look at any of the pages below, to
start making Confluence feel like home.
Your User Profile

Change Your Password
Edit Your User Settings
Set Your Profile Picture
Choose Your Home Page
Save for later
View and Revoke OAuth Access Tokens
Your User Profile
Your user profile contains basic information about you, which other
On this page:
Confluence users can see. It's also displayed to other users when they click
your name in the People Directory, if you haven't set up your personal space.
Find your user
In your own profile, you can access account management features and profile
update information about yourself, like your name, email address, and pass Edit your user
word. You can also view other users' profiles. profile
Notes
Find your user profile
Related pages:
To find your user profile:
Set Your Profile
Picture
Choose your profile picture at top right of the screen, then choose Profile, or
Create a Personal
choose the Profile link in the sidebar of your personal space. Space
To find someone else's user profile:
Hover your mouse pointer over a user's linked name or profile picture and choose the user's linked name to
open their user profile. Alternatively, you can choose the Profile link in the sidebar of their personal space,
or go directly to this URL:
http://your.confluence.site/users/viewuserprofile.action?username=USERNAME
Screenshot: User profile screen for the current user
From your user profile, you can access the following:
Profile
View and edit your personal details, such as your name and email address details and
optionally, your photograph and other personal information. Note that as a security
precaution, in order to change your email address, you will be required to re-enter your
password.
Upload a profile picture (optional).
Change your password.
Network
View the recent activity of users that you are following via the Network view.
Follow other users from this view.
Favorites
View a list of your favorite spaces.
Watches
View a list of the pages and spaces you are currently watching.
Drafts
Retrieve any pages you were in the process of editing. See Working with Drafts.
Settings
Edit your General Settings (homepage, language and timezone).
Subscribe to email notifications.
View and revoke your OAuth access tokens.
Edit your user profile

1. Choose your profile picture at top right of the screen, then choose Profile
Or, choose the Profile link in the sidebar of your personal space.
2. Choose Edit Profile.
3. Enter details about yourself in the form displayed.
4. Choose Save.
Fields in your user profile:
Detail Description
Full Your name as you'd like it to appear in your profile.

Name
Email Your email address that will be used to send you mail notifications.
Phone Your phone number.
IM Your Instant Messenger (IM) details.

To suit a variety of IM applications, this option accepts any string value. For example, you can
enter IM details in the form of an email address, or a user ID, like '123456789'.
Websi Your website's URL.

te
About Information about yourself that other users can view (such as your professional information,
me hobbies, and other interests). You can use Confluence wiki markup in this field.
Positi Your title or position within your organization.

on
Depart The name of your department or team.

ment
Locati Your location. This can be your town, city, region or country.
on
Handy Hint
Confluence administrators can configure Confluence to mask email addresses (e.g. 'example at
atlassian dot com'), protecting your email address from search engine spiders and the like.
Notes
The 'Administer User' link is visible to Confluence administrators only. The administrator can click this link to
go directly to the user management screen in the Administration Console.
Change Your Password
There are two scenarios where you may want to change your Confluence On this page:
password:
You're logged in, but you want or need to change your password From within
You've forgotten your password and can't log in, so you need to reset Confluence
your password From the login page
Don't see the
From within Confluence Password option?
Related Pages:
Change your password when you're logged in:
Your User Profile
1. Choose your profile picture at top right of the screen, then choose Pr Set Your Profile
ofile Picture
2. On your Profile tab, click Password in the left-hand column Create a Personal
3. Enter your current password and your new password in the form Space
displayed
4. Click Submit
1. Location of Settings in the profile menu

2. Location of Password in the side bar
From the login page

If you've forgotten your password and need to reset it, you can do so from the Confluence login page.
Choose the 'Forgot your password?' link and Confluence will step you through the process to reset your
password.
Don't see the Password option?

You may not be able to change your password directly in Confluence if your login credentials are coming
from another user directory, for example if Confluence is integrated with an LDAP directory or Jira for user
management.
Talk to your administrator about where you should change your password.
Edit Your User Settings
If you want to make Confluence fit you, like a well-worn pair of sneakers,
On this page:
you can set some preferences that will make you feel more at home:
General preferences such as home page, language and time zone General User
Editor settings Preferences
Email settings for subscriptions to email reports. More about
OAuth access tokens that you have granted from your Confluence Language
user account. Editor Preferences
Related pages:
General User Preferences Your User Profile
Set Your Profile
To edit your general user settings:
Picture
Create a Personal
1. Choose your profile picture at top right of the screen, then choose S
Space
ettings
Autocomplete for
2. Choose Edit and update the settings links, files, macros
3. Choose Submit and mentions
Setting Description
Site Homepage Select the page that you would like to see whenever you log into Confluence.
Language Select your language. See below.
Time zone Select your time zone.
Use Keyboard Shortcuts Enable keyboard shortcuts, other than for the editor.
Text select Turn off the popup options panel when highlighting text.
Screenshot: Editing your user profile settings
More about Language

Setting your language preference in your user profile is described in the section above. This section gives
more information about that setting and other settings that affect the language Confluence will use.
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
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.
Editor Preferences
You can set some options that determine the way the Confluence editor works. Note that these settings
affect only you. Other people using Confluence can enable or disable the settings on their user profiles
independently.
To change your editor preferences:
2. Click Editor under 'Your Settings' in the left-hand panel
3. Click Edit and make your changes
4. Click Submit
Setting Description
Disable Select to disable autocompletion when you press one of the trigger characters.
Autocomplete
Disable Select to disable autoformatting when you type wiki markup in the editor. Click ? on
Autoformatting the editor toolbar to learn more.
Screenshot: User settings for the editor
Set Your Profile Picture
Your profile picture is used as the icon for your personal space, to represent
you in the People Directory, and to illustrate your comments. It also appears Related pages:
in various other places next to your name, such as in the list of recent
updates on the dashboard. Your User Profile
Create a Personal
When you upload your profile picture, you can resize and reposition it to Space
make sure it looks great. Your profile and
settings
This page is about Confluence Server and Data Center. If you use
Confluence Cloud head over here to see how to update your
personal profile.
Upload and adjust your profile picture:
1. Choose your profile picture at top right of the screen, then choose Pr
ofile
2. Choose Picture on the left
3. Choose Upload image > Upload an image
4. Locate and select the picture on your computer or file server
5. Adjust the size and position of your photo, then choose Save
Screenshot: Choosing a profile picture
Screenshot: Resize and position your profile picture

You can't remove your own profile picture, but you can upload a new one any time. Alternatively you can
ask your admin to remove your profile picture for you.
Choose Your Home Page
The dashboard is the default landing page when you log into Confluence. It
Related pages:
gives you easy access to what's happening in your site, and helps you get
back to pages you recently viewed and worked on. Your profile and
settings
You can choose to personalize your experience. and use an existing space Your User Profile
home page as your landing page.
To set your home page:
ettings
2. Choose Edit
3. Choose an option from the Site Homepage drop down.
Only spaces you're allowed to view will appear.
4. Choose Submit.
You'll be directed to your new home page the next time you log in. You can change your personal home
page at any time.
Alternatively, if your Confluence administrator has set a space home page as the landing page for the whole
site, you can choose Dashboard from the Site Homepage drop down to use the dashboard as your landing
page.
Screenshot: Profile Settings
You can access the dashboard at any time using the dashboard URL. It'll look something like this: https:
//yoursite.com/wiki/dashboard.action.
Save for later
Saving pages for later helps you access them quickly from the dashboard or
On this page:
from your profile.
No time to read that page now? No problem, hit Save for later and it'll be Save a page for
waiting for you on the dashboard when you have more time. It's also a later
great place to store those pages that you use on a day to day basis. Get back to your
saved pages
Save for later was previously called Favorites.
Save a page for later

To save a page for later, hit the Save for later button at the top of the page.
The star icon will change to dark grey to indicate the page is saved. Hit the
button again if you want to remove the page from the list.
Get back to your saved pages
To view your saved pages:
Choose Saved for later on the dashboard sidebar.

Choose your profile picture at top-right of the screen, then choose Saved for later – there's a list of
your saved pages, and the spaces that you've added to My spaces.
You can also use the Favorite Pages Macro to include a list of your saved pages on any page.
Screenshot: Viewing and removing saved pages from the dashboard

View and Revoke OAuth Access Tokens
OAuth access tokens allow you to use a Confluence gadget on an external
On this page:
web application or website (also known as the 'consumer') and grant this
gadget access to Confluence data which is restricted or privy to your
Confluence user account. View your OAuth
Access Tokens
OAuth access tokens will only appear in your user profile if the following Revoke your
conditions have been met: OAuth Access
Tokens
1. Your Confluence Administrator has established an OAuth
relationship between your Confluence site and the consumer. Related pages:
Confluence Administrators should refer to Configuring OAuth for
more information about establishing these OAuth relationships. Configuring OAuth
2. You have accessed a Confluence gadget on the consumer and have for Confluence
conducted the following tasks: Admins
a. Logged in to your Confluence user account via the gadget and
then,
b. Clicked the 'Approve Access' button to allow the gadget
access to data that is privy to your Confluence user account.
Confluence will then send the consumer an OAuth 'access
token', which is specific to this gadget. You can view the
details of this access token from your Confluence site's user
account.
An OAuth access token acts as a type of 'key'. As long as the consumer is in possession of this access
token, the Confluence gadget on the consumer will be able to access Confluence data that is both publicly
available and privy to your Confluence user account. As a Confluence user, you can revoke this access
token at any time. Furthermore, all access tokens expire after seven days. Once the access token is revoked
or has expired, the Confluence gadget will only have access to publicly available Confluence data.
View your OAuth Access Tokens

To view all of your Confluence user account's OAuth access tokens:
2. Click View OAuth Access Tokens. A view similar to screenshot below is displayed. Refer to OAuth
Access Token Details below for information on interpreting this table.
If no access tokens have been set, then 'None specified' is shown.
Screenshot: Viewing your OAuth Access Tokens
OAuth Access Token Details
Your list of OAuth access tokens is presented in a tabular format, with each access token presented in
separate rows and each property of these tokens presented in a separate columns:
Column Description
Name
Consumer The name of the Confluence gadget that was added on the consumer.
Consume A description of this consumer application. This information would have been obtained from
r the consumer's own OAuth settings when an OAuth relationship was established between
Description Confluence and that consumer.
If the consumer is another Atlassian application, this information is obtained from the Consu
mer Info tab's 'Description' field of the OAuth Administration settings. The application's
administrator can customize this Consumer Info detail.
Issued The date on which the OAuth access token was issued to the consumer by Confluence. This
On would have occurred immediately after you approved this gadget access to your Confluence
data (privy to your Confluence user account).
Expires The date when the OAuth access token expires. This is seven days after the 'Issued On'
On date. When this date is reached, the access token will be automatically removed from this list.
Actions The functionality for revoking the access token.
Revoke your OAuth Access Tokens

To revoke one of your OAuth access tokens:
1. View your Confluence user account's OAuth access tokens (described above).
2. Locate the Confluence gadget whose OAuth access token you wish to revoke and click Revoke
OAuth Access Token next to it.
The gadget's access token is revoked and the Confluence gadget on the consumer will only have
access to publicly available Confluence data.
Collaboration
Confluence is all about encouraging team collaboration to get the best
Related pages:
results, so we've built in a number of ways you can notify other people
about content that may be of interest to them. Pages and blogs
Watch Pages,
You can: Spaces and Blogs
Export Content to
Work together with your team on a page or blog and see their Word, PDF, HTML
changes in real time and XML
Share a link to a page or blog post via email
Mention a user when you write a page, blog post, comment, or add a
task
Like a page, blog post or comment
Whenever you mention another user, they'll receive an email notification; if

you like a page, blog post, or comment, the author will be notified that you like
the content.
Other users can also find out about changes to content in Confluence by wat
ching pages and spaces.
Another way to share Confluence content is by exporting it to other formats s

uch as XML, HTML, Microsoft Word and PDF.
Network Overview
You can Create a network of users who are important to you, to make sure
On this page:
you're always up-to-date with their Confluence activity. You might want to
follow your boss or teammates, to see what they're working on, or whoever
creates the most entertaining blog posts. Follow another user
Access your
When someone's part of your network, you'll be able to see when they: network view
Notes
Add or edit pages or blog posts
Comment on a page or blog post or edit existing comments Related pages:
Update their user profile
Network Macro
Subscribe to a
Network RSS Feed
Follow another user
Email Notifications
You can follow another user by using either their Hover Profile or your
Network view.
To follow a user with their Hover Profile, hover your mouse over their
profile picture when it appears in a page and choose Follow.
To follow a user from your Network view:
1. Choose your profile picture at top right of the screen, then choose Network
Alternatively, choose More in the Network section of your profile sidebar.
2. Search for and select the user in the Following field
3. Choose Follow
If you now refresh or revisit your Network view, the profile picture(s) of the user(s) you just followed will
appear within the Following list on the right. Their tracked activities will also start appearing in the Recent
Activity list.
Access your network view

If you want to see what's been happening in your network, access your network view as described above.
You can access another user's Network view using the Hover Profile by choosing More > Network Page.
Screenshot: Example of the Network view
Notes
RSS feeds: you can subscribe to any Confluence user's network RSS feed and receive summaries
on the activities of other users they're following in their network. See Subscribe to a Network RSS
Feed.
Email notifications: you can request email notifications of any activity in your network. See Email
Notifications.
Likes and Popular Content
Has someone written a good blog post or page on Confluence? Or made a
On this page:
comment you agree with? Click the Like button to them know.
When you like a page, blog post or comment, the author of the content Disabling the 'like'
receives a notification. If enough people like the content, it'll appear on the P feature
opular tab of the dashboard. Disabling
notifications when
your content is
Disabling the 'like' feature 'liked'
The like functionality is provided by a system app called the 'Confluence
Related pages:
Like Plugin'. To remove the like functionality from your site, Disabling and
enabling apps. The dashboard
Email Notifications
Disabling notifications when your content is 'liked' Network Overview
There are two ways to turn the 'someone likes your page' notifications off.
Do either of the following:
Open an email notification of a like, and click Manage Notifications

Go to <your confluence URL>/plugins/likes/view-
notifications.action
Mentions
Mentions (often known as @mentions) are a useful way of drawing
Related pages:
someone's attention to a page or comment, or assigning a task to them.
When you mention a user, they'll receive a notification by email and in their The Editor
workbox; if you mention them in a task, the task is assigned to them and Autocomplete for
appears in their tasks list. links, files, macros
and mentions
There are two ways to mention someone: using autocomplete, or via the Keyboard shortcuts
Insert menu in the editor toolbar. Workbox
Notifications
Use autocomplete
To mention someone using autocomplete, type '@' in the editor then start typing their name. Choose the
person you want to mention from the list of suggestions.
Confluence will suggest people you've mentioned previously (after yourself, of course).
It then continues to suggest matches as you type. If you've not mentioned the person recently, we'll also
include information about whether they've commented or contributed to the current page, to help you find the
right person, fast.
Use the Insert menu

If you'd rather use the Insert menu, choose Insert > User Mention then search for and select the user you
want to mention.
Notes
Disable mentions – The functionality is provided by a plugin called the 'Confluence Mentions Plugin'.
If you need to remove the user mention functionality from your site, you can disable the plugin. See Di
sabling or Enabling a Plugin.
Mentioning groups – You can only mention individual users who have the 'Can Use' Confluence
global permission. There's a feature request to allow mentions for groups:
CONFSERVER-23015 - Extend 'Mentions' to work with groups as well FUTURE CONSIDERATION
Link to a user profile – You can use a square bracket '[' and a person's name to trigger Confluence
autocomplete and link to a person's user profile or personal space. Confluence will send the person a
notification just as if you had used @mention (unless the administrator has disabled the user mention
feature).
Mention notifications - A notification is sent to a person the first time you mention them in the
content of a page, but not for subsequent mentions. If you need to catch someone's attention, and
you've already mentioned them on the page, try mentioning them in a comment. A notification is sent
every time you mention someone in a page comment or inline comment, not just the first time.
Frequently mentioned people - Confluence relies on your browser's local storage to remember the
people you mention regularly. You may see different results if you switch devices, or don't allow local
storage. Confluence doesn't indicate whether someone is a creator, contributor or commenter when
they are also a recent mention (because we're grabbing them straight from your local storage, not the
page itself).
Changing the mention name - if you change the mention name in the editor (for example you
backspace to remove their surname, or edit the mention link to change their full name to their
preferred name) this will be treated as free text and won't be updated if the person changes their
name, or is deleted from Confluence.
Share a Page or Blog Post
Use the Share button when viewing a page or blog post to email anyone a
link to that page or blog post. You can either grab the short URL from the Related pages:
share dialog, or enter a Confluence user, group or email address.
Workbox
To share a page or blog post by email: Notifications
Create and Edit
1. Go to the page or blog post you wish to share. Pages
2. Choose Share. Blog Posts
3. Enter a username, group or email address, and select the Configuring a
appropriate user, group or email address from the list of suggestions. Server for
Repeat this process to add multiple recipients to the list (or use the Outgoing Mail
trash icons to remove people from the list). Space Permissions
4. Enter an optional message. Overview
5. Choose Share to send the link via email.
In addition to an email, Confluence users will also

receive a notification in their Confluence workbox.
See Workbox Notifications.
You can also share pages from inside the editor. Hit
the button in the editor to invite people to edit
the page with you.
Notes:
The option to add people is only available if

your site has a mail server configured.
Sharing or inviting someone to edit a page or
blog post does not automatically grant any
permissions - they will still need the
appropriate Confluence permissions to
access Confluence and view or edit the
page.
Comment on pages and blog posts
Comments are a great way to bring others into the conversation about a
On this page:
page or blog post. They allow you to remark on content, add important
information, ask questions, and generally drive collaboration and teamwork.
Add a page or blog
You can add a comment at the bottom of any page or blog post, or add an in post comment
line comment by highlighting specific text on the page. Add an inline
comment
Resolve inline
Add a page or blog post comment comments
Rich comments
1. Type your comment in the comment field at the bottom of the page Link to a comment
2. Optionally, choose Preview to see how your comment will appear Comment
3. By default, Watch this page is ticked (This means you'll start permissions
receiving notifications about the page. Uncheck it if you don't want to Notes
watch the page.)
4. Choose Save (Ctrl+S or +S) Related pages:
Create and Edit

Other users can reply and/or like your comment, and you or a space
Pages
administrator can edit your comment(s).
Blog Posts
Share and
Comment on Files
Share a Page or
Blog Post
Add an inline comment

1. Highlight the text you want to comment on
2. Choose the add comment button that appears above the highlighted text
3. Type your comment and choose Save (Ctrl+S or +S)
The selected text will appear with a yellow highlight indicating an inline comment; choose any highlighted
text on the page to display the related comment(s).
Just like page and blog post comments, others can reply to, or like, your inline comments, and you'll be
notified when they do.
Resolve inline comments

Hit Resolve to hide a set of inline comments once the conversation's finished. If you want to view resolved
comments, choose > Resolved comments; to reopen a resolved comment, choose Reopen at the
bottom left.
Rich comments
Inline and page comments might look simple, but they support rich text (like bold, underline, and italics), bull
eted and numbered lists, links, and @mentions. You can also drop images into any comment, to really
illustrate your point.
Link to a comment
You can link directly to a comment on a page. See Links for more information.
If you don't see a popup when you highlight text, check that Text Select is enabled in your profile
settings.
Comment permissions
Add a comment – You need the 'Add Comments' permission in the space.
Edit a comment – You need the 'Add Comments' permission. Space administrators can edit all
comments within their space. The date on a comment always indicates the time the comment was last
edited.
Delete a comment – You need the 'Remove Comments' permission. Deleted comments cannot be
restored. If you don't have the 'Remove Comments' permission, you can delete your own comments,
but only if there are no replies to your comment.
Disable comments – If you don't want comments in a particular space, remove the 'Add Comments'
permission from the 'confluence-users' or 'users' group, anonymous users and all other users and
groups. The option to add comments will no longer appear on pages or blog posts in that space.
See Space permissions for more information. There is no permission that controls comments across the
entire site.
Members of the Confluence-administrators group can add, edit and delete comments, even if you remove
their comment permissions in the Space permissions configuration.
Notes
Choose Watch at the top-right of the page to receive an email notification whenever anyone edits or
adds a comment to the page.
On blog posts only, an 'Author' lozenge will appear on any comments made by the original author of
the post.
It's not possible to delete all comments on a page simultaneously, or change the order of comments.
Inline comments on text that is included on a page using the Include macro or Excerpt include macro
won't be visible. They are only visible on the original page.
Watch Pages, Spaces and Blogs
You can 'watch' a Confluence page, blog post or space. Confluence will
On this page:
then send you a notification email whenever anyone updates your watched
content.
Watching a page
You'll receive email notifications for: or blog post
Watching an entire
Page / blog post edits (unless the author clears the 'Notify watchers' space
check box). Watch for new blog
Deletions. posts in a space
Attachments, including new versions or deletions of an existing Watch all spaces
attachment. on the site
Comments, including new comments or deletions of existing Watching for all
comments. new blog posts on
the site
By default, Confluence will assign you as a watcher of any page or blog Manage watches
post that you create or edit. This behavior is called 'autowatch'. from your user
profile
There's no daily digest for email notifications. You'll receive immediate Manage watches
emails for important notifications (like mentions and new pages), but when from the email
lots of changes are being made at the same time, you'll only receive a message
single email with all the changes (within a 10 minute window). Autowatch and
other notification
You will not receive email notifications for content changes due to the options
output of a macro, because the page content itself hasn't been edited. We
also don't send a notification when a comment is edited. Related pages:
You need 'View' permission for the page, blog post or space to receive Manage Watchers
notifications. Email Notifications
Your User Profile
Watching a page or blog post
To start watching a page or blog post:
1. Go to the page or blog post.

2. Choose Watch and select the relevant check box.
To stop watching the page or post, deselect the relevant check box.
Watching an entire space

You can choose to watch all the pages and blog posts in a particular space.
The quickest way is to use the Watch option on a page or blog post, as described above.
To stop watching the space, deselect the relevant check box.
Alternatively, choose Pages in the space sidebar, then choose Watch this space at the top right.
Watch for new blog posts in a space

You can choose to receive a notification whenever someone adds a blog post in the space. You will not
receive notification when a blog post is updated, deleted or commented on.
To watch for new posts:
1. Go to a blog post in the space.

2. Choose Watch and select Watch for new blog posts in this space.
To stop watching for new blog posts, deselect the relevant check box. Alternatively, choose Blog in the
space sidebar, then choose Watch this blog at the top right.
Watch all spaces on the site

You can receive notifications about changes to the content of pages, blog posts and comments from all
spaces on a Confluence site.
To start watching for content changes across the whole site:
2. Choose Email.
3. Choose Edit then choose Subscribe to daily updates.
4. Choose Submit.
Watching for all new blog posts on the site

You can choose to watch for all new blog posts in all spaces on the Confluence site. You will not receive
notification of updates to or deletions of blog posts, nor of comments on the blog posts.
To start watching for all new blog posts:
2. Choose Email.
3. Choose Edit then choose Subscribe to all blog posts.
4. Choose Submit.
Manage watches from your user profile

The 'Watches' page in your user profile displays a list of all pages and spaces you are currently watching.
To manage your watches:
1. Choose your profile picture at top right of the screen, then choose Watches.
2. Choose Stop Watching for any unwanted spaces or pages.
Manage watches from the email message

The email notifications that you receive from Confluence have some useful links at the bottom of the email
message. The links in each message vary, depending on the context. In general, the links allow you to view
the page online, reply to a comment, and so on.
In particular with respect to setting your notification preferences, you will see one or more of the following
links:
Stop watching page – Click this link to stop watching the page that triggered the email notification.
Stop watching space – Click this link to stop watching the space that triggered the email notification.
Stop following this user – Click this link to stop following the user whose update triggered the email
notification.
Manage Notifications – Click this link to go to the email settings page in your user profile.
Screenshot: Example email notification footer showing links
Autowatch and other notification options
By default, Confluence will assign you as a watcher of any page or blog post that you create or edit. This
behavior is called 'autowatch'. You can turn autowatch on or off, and set other notification options, in the
email settings section of your user profile. See Edit Your User Settings.
Manage Watchers
As a space admin, you may want to control who's notified about changes
Related pages:
and updates to pages and posts within a space. You'll do this by managing
the watchers of specific pages and posts, or of the entire space. Watch Pages,
Spaces and Blogs
Take the example of a new member starting on your team, who should see Email Notifications
when changes are made in the team space – you can add them as a space
watcher so they get updates when any page or post in the space is Your profile and
changed. If someone no longer needs to be notified, you can remove them settings
as a watcher just as easily.
To manage the watchers of a page or blog post:
1. Go to the page or blog post for which you want to manage the watchers
2. Choose Watch > Manage Watchers
The left-hand column of the 'Manage Watchers' dialog shows the users watching the page or blog
post. The right-hand column shows the users watching the space.
Add someone as a watcher of the page, post, or space – type their username in the relevant
search box and hit Add
Remove an existing page, post, or space watcher – choose the trash icon next to their name
Email Notifications
You can 'watch' a page, blog post or space. Confluence will then send you
a notification by email whenever anyone adds or updates content on that On this page:
page or space. You'll receive immediate emails for important notifications
(like mentions and new pages), but when lots of changes are being made at
Subscribing to
the same time, you'll only receive a single email with all the changes within
email notifications
a short window (usually 10 minutes).
Notes
You can also subscribe to daily email reports and other notifications of
Related pages:
various updates, as described below.
Watch Pages,
You'll only receive notifications for content that you have permission to Spaces and Blogs
view. Users that have been disabled by an administrator will not receive Subscribe to RSS
email notifications. Feeds within
Confluence
Subscribing to email notifications Your profile and
settings
You can subscribe to be notified when: Edit Your User
Settings
A blog post is added or changed in a space that you have permission
to view.
Someone you're following makes an update in a space that you have
permission to view.
Someone follows you.
You can also subscribe to these summary reports:
A daily report of the 30 most popular updates to all spaces that you
have permission to view.
A daily or weekly report of recommended updates, in all spaces that
you have permission to view.
To edit your email notification settings:
ettings
2. Click Email in the left-hand panel
3. Click Edit
Here's an explanation of all the email settings.
Setting Description Content
Autowatch Option: Do you want

Confluence to automatically Pages and blog posts that you create, edit or comment on.
add you as a watcher on
each page or blog post that
you add or update? If you
are a watcher of a page or
a post, you will receive
notification of future
changes.
Subscrib Receive daily email reports

e to daily showing changes to Pages and blog posts that are added, edited or deleted.
updates content in all spaces that Comments on a page or blog post that are added, edited or
you have permission to deleted.
view. Updates by users who have changed their personal profile.
Note: Daily email reports

do not include information
about attachments on a
page or blog post that are
added, edited or deleted.
Up to 30 updates will be
included, sorted by
popularity.
Subscrib Receive email notifications

e to all for changes to blogs in your Blog posts added, edited or deleted.
blog Confluence installation that
posts you have permission to
view.
Subscrib Receive email notifications

e to for changes to content by Space is created.
network all users that you are followi Page or blog post is created.
ng, which you have
permission to view.
Subscrib Receive an email message

e to new when anyone chooses to
follower follow you.
notificatio
ns
Notify on Option: Do you want to

my receive email notifications All pages and spaces that you are watching.
actions for your own changes? This affects all subscriptions set.
Note: If you have not

subscribed to any email
notifications and are not
watching any pages
/spaces, then selecting
'Notify on my actions' will
not do anything.
Show Option: Do you want your

changed notifications to include Edits to pages and blog posts.
content details of the changes
made to the content?
If you do not select this

option, your
notifications will include
only the title of the
page, and any
comment the author
made when updating
the page.
If you do select this
option, your
notifications will show
the differences between
the current and
previous versions of the
page. See Page History
and Page Comparison
Views.
Subscrib Receive a daily or weekly Confluence chooses the content to display, based on:
e to email message showing
recomme the top content that is Pages and blog posts that people have recently liked.
nded relevant to you from spaces Pages and blog posts that people have recently commented
updates
that you have permission to on.
view. Pages and blog posts that have recently been created.
How do you set the 'Recent' means any activity that occurred since the last
frequency of the mail recommended updates message was sent to you.
message? A link in the
email message allows you The activities are listed in order of popularity, with the most
to choose daily or weekly popular at the top. Likes, comments and content creations are
notifications. scored equally. Activity that involves people in your network rank
s higher than activity not involving your network. Content from
How do you enable and My spaces also ranks higher than content in other spaces. The
disable the notification? recommended updates summary does not include any content
You can turn off the that you created yourself, and it gives a lower ranking to content
notification by clicking a link that you have participated in, for example by adding a comment
in the email message. You or updating the page.
can also turn the
notification on or off by If there is no activity to report, Confluence will not send the
setting the 'Subscribe to email message.
recommended updates'
option in your user profile.
Notes
Mail server: To enable Confluence to send email notifications, a System Administrator must configure
an email server. See Configuring a Server for Outgoing Mail.
Batching window: System Administrators can change the batching window for changes and
comments on the same page or blog post in the Send batched notifications scheduled job. Increase
the time for fewer emails or reduce the time if more immediate notifications are essential in your site.
Recommended updates email: Confluence Administrators can set the default options for
the recommended updates notification.
Choose the cog icon , then choose General Configuration

. Click Recommended Updates Email in the left-hand panel. See Configuring the Recommended
Updates Email Notification.
Email threading: Confluence will attempt to group all the email notifications about changes to a
specific page together. Other notifications such as sharing a page, requesting access to a page, or
recommended updates emails are intentionally not grouped. Not all mail clients support email
threading, and different email clients use different methods for threading emails. We've tested
Confluence's email threading with Apple Mail 10.3, Outlook 2011, Outlook 2016, GMail, Google Inbox
and Outlook.com.
Take your Confluence notifications to the next level with these email notification apps on the Atlassia
n Marketplace:
Notifications - ScriptRunner for Confluence: Manage Confluence notifications more easily,

with greater control and customization
No Email Storm - change the behaviour of the Notify Watchers checkbox in the editor
Subscribe to RSS Feeds within Confluence
An RSS feed is a format for delivering summaries of regularly changing web
content. Subscribing to an RSS feed allows you to stay informed of the On this page:
latest content from sites that you are interested in.
Confluence RSS
RSS is not designed to be read in a regular web browser. Specialized RSS
feeds
newsreader programs can check RSS files every so often, and tell you
Remove an RSS
what's new on a site. Your reader may be on a website, a browser
feed
extension, part of your email program, or a stand-alone program.
Related pages:
Confluence generates its own RSS feeds for tracking updates to content
within Confluence. You will need an RSS reader which can grab the RSS Watch Pages,
feeds from Confluence and display them for you. Spaces and Blogs
RSS Feed Macro
Confluence's RSS macro allows you to display the contents of an RSS feed
on a Confluence page. The feeds may come from a Confluence feed
generator or from external sites. In this way, Confluence can act as an RSS
reader.
Confluence RSS feeds
RSS feeds allow you to track updates to content within Confluence. You will need an RSS newsreader to
read a feed.
You can create a customized RSS feed using the RSS Feed Builder or subscribe to one of the pre-specified
feeds generated by Confluence.
What would you like to do?
Create and subscribe to customized RSS feeds using the RSS Feed Builder – Create a customized
RSS feed. For example, you can filter your feed using a label, specify the number of items and days
to include in your feed, and so on.
Subscribe to pre-specified RSS feeds – Generate an RSS feed automatically in a minimal number
of steps.
Subscribe to a feed of any Confluence user's network – Track the activities of users the selected
person is following.
Remove an RSS feed

There is no need to try to delete or remove an RSS feed built by the Confluence RSS feed builder.
Explanation: The feeds generated by the RSS Feed Builder are dynamically generated via the parameters
included in the feed URL (address). For example, take a look at the following feed URL:
http://confluence.atlassian.com/createrssfeed.action?types=page&sort=modified&showContent=true...
The above feed URL will generate a list of pages ('types=page'), sorted by the modification date and
showing the page content. The feed is generated at the time when the URL is fetched and there is no RSS
feed information stored on the database. For that reason, there is no need to remove anything.
Subscribe to pre-specified RSS feeds
This page tells you how to get hold of an RSS feed which Confluence has
Related pages:
predefined for you.
The RSS Feed
To subscribe to predefined RSS feeds for a particular space: Builder
RSS Feed Macro
1. Go to the space and choose Space tools > Content Tools from the Network Overview
2. Choose RSS Feeds
3. Copy and paste the link for one of the feeds into your RSS
newsreader
Feeds include:
Pages Comments
Blog Attachments
Mail All content
To subscribe to predefined RSS feeds for a particular page (where available):
Note that the word 'page' here means a part of the Confluence user interface, rather than a page that
contains Confluence content. For example, your Network view offers an RSS feed.
1. Go to the page
2. Locate the following icon, which is available in the top-right corner of certain pages:
3. Copy and paste the icon's link into your RSS newsreader
Notes
The predefined RSS feed will return no more than 10 entries within the last 5 days, if you want to customize
your Confluence RSS feed (for example, use a label to filter your feed), use the RSS Feed builder instead of
the above instructions.
The RSS Feed Builder
Using the RSS feed builder, you can create customized RSS feeds to
subscribe to changes within Confluence.
Wondering what an RSS feed is? See more information about RSS Feeds.
On this page:
Build an RSS feed
Build an RSS feed
Follow the steps below to build your feed, choosing the type of content and Notes
the time period you want to monitor.
Related pages:
To create a customized RSS feed:
Watch Pages,
Spaces and Blogs
1. Choose the help icon at top right of the screen, then choose Fe Subscribe to RSS
ed Builder Feeds within
2. Select the content types you want in your feed Confluence
Check Mail if you want to know when the email archive is updated.
(See the overview of mail archives in Confluence.)
3. Select one or more spaces from the list
4. Click Advanced Options to set the following:
Option Description
Feed The default name is based on the name of your

Name Confluence installation. For example, 'Extranet RSS
Feed'.
With Enter one or more labels separated by spaces or

these commas. Confluence returns all content (of the selected
labels types) that matches one or more of the labels. See the h
int below about using labels to customize your feeds.
Exclud Exclude specific spaces from those already selected.

e
these
spaces
Sorted Sort content by either the date or creation or the date

by they were last updated.
Limit to Specify the number of items returned in your feed.
Within Specify how old items returned can be.

the last
Include Specify whether the entire page is displayed in the feed.

content
for
pages
5. Choose Create RSS Feed
6. Drag or copy the link into your RSS reader
Hints
Separate feeds. Try building separate feeds, one for pages only and one that includes comments as
well. This allows you to monitor only pages if you are short of time, and to read the comments when
you have more time.
Labels to customize your feed. You can use the RSS feed builder to track updates to labeled pages
and comments on those pages. Here is an idea for customizing your RSS feed by using your own
personal label(s). This is useful if you want to track updates to specific pages or blog posts, and you
do not want to deal with emails. You can use this method as an alternative to watching pages.
Build an RSS feed that returns pages, blog posts and comments labeled with a personal label,
such as 'my:feed'.
Each time you want to 'watch' a page, just label it with 'my:feed'.
All updates and comments will automatically come through your RSS feed.
Notes
Removing an RSS feed:
There is no need to try to delete or remove an RSS feed built by the Confluence RSS feed builder.
Explanation: The feeds generated by the RSS Feed Builder are dynamically generated via the
parameters included in the feed URL (address). For example, take a look at the following feed URL:
http://confluence.atlassian.com/createrssfeed.action?types=page&sort=modified&showContent=true...
The above feed URL will generate a list of pages ('types=page'), sorted by the modification date and
showing the page content. The feed is generated at the time when the URL is fetched and there is no
RSS feed information stored on the database. For that reason, there is no need to remove anything.
Feed authentication options: Confluence can offer you the option of an anonymous feed or a feed
that requires authentication.
An anonymous feed will show only the content that is visible to anonymous users. The feed
URL does not contain the &os_authType parameter mentioned below. This feed is useful
only if your Confluence site allows anonymous access. If a feed is anonymous, you only get
anonymously-viewable content in the feed regardless of whether you are a Confluence user or
not.
An authenticated feed requires you to log in to Confluence before you can retrieve the
content. The feed URL contains the following parameter: &os_authType=basic.
The option to choose between an anonymous and an authenticated feed is currently not
available on the feed builder screen. The feed builder offers only authenticated feeds. See CO
NF-21601 for details and a workaround.
Subscribe to a Network RSS Feed
You can create an RSS Feed from any user's network view, allowing you to
On this page:
receive summaries on the activities of users they are following in their
network. The types of activities tracked in these RSS feed summaries
include: Subscribe to a
user's network feed
Additions or edits to pages or blog posts Customize your
Comments added to a page or blog post or edits to existing network RSS feed
comments Notes
Updates to a user's profile
Related pages:
Subscribe to a user's network feed Network Overview
Subscribe to RSS
To subscribe to a user's network RSS feed: Feeds within
Confluence
1. Locate the RSS icon , which is available from the top-right of: Your profile and
The 'Recent activity of the users you are following' section of settings
your network page, or
The 'Activity of followed users' section of another user's
network page.
2. Copy and paste the icon's link into your RSS newsreader
Customize your network RSS feed

Confluence does not provide a way of customizing a network RSS feed via the user interface. However, you
can modify the maximum number of results and type of content displayed in these feeds by directly editing
the RSS feed link in your RSS newsreader.
To modify the maximum number of results displayed in your RSS feed:
1. Edit the RSS feed link in your RSS newsreader.

2. Change the value of the max parameter from its default value of 40 to a value of your choice.
Example:
http://confluence.atlassian.com/feeds/network.action?
username=MYNAME&max=60&publicFeed=false&os_authType=basic&rssType=atom
3. Save the modified link in your RSS newsreader.
To modify the type of content displayed in your RSS feed:
1. Edit the RSS feed link in your RSS newsreader.

2. Append the parameter contentType to the end of the link, followed by an equals sign (=) and then
add the appropriate content type value of your choice:
PAGE — restricts the RSS feed to page additions or updates.
BLOG — restricts the RSS feed to blog post additions or updates.
ATTACHMENT — restricts the RSS feed to attachment additions or updates.
COMMENT — restricts the RSS feed to comment additions or updates.
Content type values are case-sensitive. Ensure that each parameter is separated from the other by an
ampersand (&).
Example:
http://confluence.atlassian.com/feeds/network.action?
username=ggaskell&max=40&publicFeed=false&os_authType=basic&rssType=atom&contentType=B
LOG
3. Save the modified link in your RSS newsreader.
Notes
It is not possible to filter for more than one type of content by adding multiple values to the contentType
parameter.
Workbox Notifications
The Confluence workbox displays all
notifications collected from Confluence page On this page:
watches, shares, mentions, and tasks. From your
workbox you can reply to comments, like a Manage your notifications
comment or page, watch a page, or open the Which notifications are included?
relevant page or blog post. Keyboard shortcuts
Manage notifications with Confluence
If your Confluence site is linked to a Jira application mobile
such as Jira Software or Jira Service Desk, you'll Notes
also see notifications from your Jira application in
the workbox. Related pages:
Looking to manage your notification email Configuring Workbox Notifications
messages instead? See Email Notifications. Email Notifications
Watch Pages, Spaces and Blogs
Manage your notifications Likes and Popular Content
1. Choose the workbox icon in the header.

A number will appear the workbox icon, to indicate the number of unread notifications waiting
for your attention.
You can use the keyboard shortcut: Type g then n. (When in the Confluence editor, click
outside the editor before pressing the keyboard shortcut keys.)
2. Choose a notification from the list, to see the notification details. You can then:
Open the related page, blog post, or comment.
Like or Unlike the page, blog post, or comment.
Watch or Stop Watching to receive notifications, or stop receiving notifications, about a page
or blog post.
Reply a comment, without leaving the workbox.
Screenshot: Your Confluence notifications in the workbox

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.
Keyboard shortcuts
Shortcut Action
g then n Open the Confluence workbox.
j Move down to the next entry in the notification list.
k Move up to the previous entry in the notification list.
n Move down to the next notification for a particular page or blog post.
p Move up to the previous notification for a particular page or blog post.
Enter Open the selected notification.
u Return to the notification list after opening a particular notification.
Manage notifications with Confluence mobile

You can also view and respond to notifications on your phone or other mobile device. See Confluence Mobile
for more about mobile platforms.
Notes
Read notifications are automatically deleted after 2 weeks.
Unread notifications are automatically deleted after 4 weeks.
You cannot delete your notifications yourself.
If a new notification arrives while you have workbox open, the count appears on the workbox icon but
the notification is not added to the workbox. You need to close workbox and re-open it to see the new
notification.
The ability to receive notifications from Jira or another Confluence site is available in Confluence
4.3.3 and later. To receive Jira notifications, you need Jira 5.2 or later.
Administrators can enable and disable the workbox on your Confluence site. They can also connect a
Jira site or another Confluence site, so that notifications from those sites appear in your workbox too.
See Configuring Workbox Notifications.
The Confluence workbox is provided by a set of plugins. To remove the personal notifications and
tasks functionality from your site, you can disable the following plugins. See Disabling or Enabling a
Plugin for instructions. Disabling these plugins will disable the entire workbox . It is not possible to
disable only tasks or only notifications:
Workbox - Common Plugin
Workbox - Host Plugin
Workbox - Confluence Provider Plugin
If you want to re-enable the plugins, do so in the following order: Common Plugin, Host Plugin,
Confluence Provider Plugin.
There is no option to disable the workbox for an individual user.
Search
Confluence gives you a few ways to find what you're looking for. Here's an
overview of Confluence search, and a few tips to help you find things more On this page:
easily.
How Confluence
How Confluence search works search works
Start a search
When you enter a search term, Confluence looks for content in all spaces Filter your search
(including personal spaces), pages, mail, personal profiles, and space results
descriptions. It also looks at the content of some attached file types (Word, Search for admin
Text, PowerPoint, Excel, PDF, and HTML). options
Advanced search
Search results are based on your Confluence permissions, so you'll only Advanced search
see content you're allowed to view. syntax
Related pages:
Confluence Search
Syntax
Confluence Search
Fields
Recently Viewed
Pages and Blog
Posts
Search Results
Macro
Livesearch Macro
Search the People
Directory
Start a search
To search Confluence:
1. Click the search field in the top-right of Confluence to open the search panel.
2. Start typing your search term.
Results will appear as you type — you don't need to hit enter.
We exclude comments from your search results unless you select the comment option from the type filter.
Screenshot: the search panel

1. Search filters – refine your results by space, contributor, type, date, label, or space category.
2. Advanced search – go the the advanced search page.
3. Search tips – get search help, and tips for refining your search.
Tip: Type / on your keyboard to quickly open the search panel.
Filter your search results

You can refine your search using interactive filters on the left-hand side of the search panel.
Search within a space
Use the space filter to find content within a particular space or list of spaces. The space you're currently in
will appear at the top of the list by default. Start typing the space name and choose from the list of suggested
spaces.
Click the toggle to search within archived spaces.
Search for content by a specific person
Use the contributor filter to restrict your search to content modified (created, updated, or commented on) by
particular people. Start typing the person's username, or part of their name, and we'll show you a list of
possible matches. You can add as many people as you like.
Tip: To search for your own work, click the Contributor filter, then select your profile from the drop-
down menu. Your name appears here by default, so it's easy to find.
Filter by content type
Use the type filter to only show content of a certain type, such as pages, blog posts, comments or user
profiles.
Search within a specific time frame
Use the date filter to search for content last modified (created, updated, or commented on) within a particular
period of time.
To search within a specific date range:
1. Click Advanced Search on the left-side of the search panel.

2. In the Last modified section, choose Custom.
3. Select the date range from the drop-down date picker.
Search for content with a specific label
Use the label filter to search for content containing a specific label. Start typing the name of the label and
choose from the list of possible matches.
Search within a space category
Use the space category filter to search within a group of related spaces. Start typing the category name and
choose from the list of possible matches. You can browse existing categories from the Space directory.
Tip: Space admins can organize spaces into categories. You can create space categories for
departments, subject areas, office locations — whatever works for your team. Learn how to create a
space category
Search for admin options

As a Confluence admin, you can can quickly access admin options from the search panel.
Start typing what you want to do. We'll show the top three matching admin items at the top of your search
results. You'll only see options you have permission to perform.
If you apply a search filter, admin items will no longer appear in your results.
Advanced search
The advanced search page allows you to add more search filters, such as creator, title, date range or
ancestor page.
To use advanced search:
1. Click the search field at the top-right of Confluence.

2. Click Advanced search on the left-side of the search panel.
3. Type your keyword in the search field and hit enter.
Adding a filter from the advanced search page
To add a search filter from the advanced search page:
1. Click Add a filter on the bottom left of the advanced search page.
2. From the drop-down menu, select the relevant filter.
Screenshot: advanced search page
1. Search filters – narrow your search by adding filters.

2. Add a filter – add more filters for even more precise search.
You can choose from these additional filters:
Creator – Restrict your search to content created by a particular person. Start typing the person's
username or part of their name and Confluence will offer you a list of possible matches.
Label – Only search for content containing specific labels.
With parent – Only search for direct children of a specific parent page.
With ancestor – Only search for pages below a certain page in the hierarchy.
Created – Choose or enter a date to only show content created within a particular period of time.
Mentioning user – Only search for content that mentions a particular Confluence user.
With title – Only search within page or blog titles.
These filters are provided by Confluence Query Language (CQL).
Advanced search syntax

You can also refine your search using Confluence search syntax. These are words or symbols you enter into
the search field to help narrow down your results. Learn more about Confluence Search Syntax.
Confluence Search Syntax
You can create an advanced search query using Confluence search syntax.
On this page:
These are special words and symbols you enter into the search field to
narrow the focus of your search.
How to use search
This page outlines the syntax supported by Confluence's search engine, Luc syntax
ene. Search for an
exact match
Search using
wildcards
Exclude words
from your search
Combine search
terms
Search for nearby
words (proximity
search)
Search within an
alphabetical range
Search for words
spelled similarly
(fuzzy search)
Combining search
operators
Searching for
macros
Search specific
fields in Confluence
Confluence search
fields
Related pages:
Search
Confluence Search
Fields
Search the People
Directory
How to use search syntax

To create a search query using Confluence syntax:
1. Click the search field at the top right of Confluence to open the expanded search panel.
2. Type your query using syntax supported by Confluence.
You can use multiple search words and operators in your query.
Screenshot: an example of a search query using Confluence search syntax

Search for an exact match

Use double quotes around your search term to find a specific word or phrase. For example "product
roadmap" will search for content that contains the phrase 'product roadmap', or a phrase where 'product' and
'roadmap' are the major words.
"product roadmap"
Limitations with exact match search
Phrases with stop words
Confluence ignores common words (stop words) — such as 'and', 'the', 'or', and 'it' — even if they are
included within double quotes.
For example, searching for "the IT budget" will only return pages containing 'budget', because 'the' and 'it'
are stop words.
If you'd like to change this, vote on this improvement request:

CONFSERVER-14910 - Provide ability to override Lucene tokenisation and stemming and search for
exact text (literal search) FUTURE CONSIDERATION
Phrases with special characters
Confluence ignores all symbols, such as hyphens or underscores, even if they are included within double
quotes.
For example, if you search for "DOC-8510", you get all pages containing 'doc' and '8510'.
Avoid using special characters, such as hyphens, in page or attachment names as they may not be
found by Confluence search.
Search using wildcards

Wildcards replace one or more characters in your search. They can help expand your search. For example,
the search below would find https://www.atlassian.com or http://www.atlassian.jp
http*.atlassian.*
Confluence doesn't support leading wildcards. This means searching for *heese will not return cheese.
Wildcard Description Example
Multiple Use an asterisk (*) at the end of your word to print* finds content containing 'printer',
characters replace multiple characters. 'printing', 'prints' and so on.
Multiple Use asterisks (*) to add more than one r*c* finds content containing 'react',
wildcards multiple-character wildcard 'recovery', 'refactor' and so on.
Single Use a question mark (?) to replace a single b?tter finds content containing 'butter',
character character in your search. 'bitter', 'better', 'batter' and so on.
Leading wildcards
Lucene doesn't allow wildcards at the beginning of your search, but you can format your search as a
regular expression as a workaround. For example, you can't search for *hum* or ?hum*, as they
begin with a wildcard, but you can search for /.*hum.*/ and find things like hum, human, and
inhumane.
Exclude words from your search

Use NOT or minus (-) to exclude words from your search.
chalk NOT cheese
Operator Description Example
NOT Use NOT (in capital letters) to exclude chalk NOT cheese finds content containing
a word from your search. 'chalk' but NOT 'cheese'
Minus (-) Put a minus sign (-) in front of words chalk butter -cheese finds content containing
you want to leave out. 'chalk' and 'butter' but not 'cheese'
Combine search terms
Operator Description Example
OR Use OR (in capital letters) to search for content chalk OR cheese finds content
that contains one of the terms. containing either 'chalk' or 'cheese'
AND Use AND (in capital letters) to search for content chalk AND cheese finds content
that contains more than one search term. containing both 'chalk' and 'cheese'
You can also combine search terms and operators, for example:
(cheese OR butter) AND chalk
Search for nearby words (proximity search)

Use a tilde (~) followed by a number to find two words within a certain number of words of each other.
For example, the following search will return 'Octagon blog post', but not 'Octagon team blog post':
"octagon post"~1
The following search won't work, because you can't search for two words within zero words of each other. If
you think the words are next to each other, use the matched phrase search.
"octagon post"~0
Search within an alphabetical range

Use 'TO' (in capital letters) to search for names that fall alphabetically within a specified range. For example:
[adam TO ben]
Note: You can't use the AND keyword inside this statement.
Search for words spelled similarly (fuzzy search)

Use a tilde (~) to find words spelled similarly, or to pick up misspellings.
For example, if you want to search for octagon, but you're not sure how it's been spelled, type the word
followed by a tilde:
octogan~
Combining search operators

You can also combine various search terms together:
o?tag* AND past~ AND ("blog" AND "post")
Searching for macros

You can search Confluence pages to find where a macro is used. Start your search with macroName: and
type the macro name after the colon. For example, to search for all excerpt-include macros:
macroName:excerpt-include*
Search specific fields in Confluence

Confluence data is stored in fields, for example title, label, type and so on. To search for content using a
specific field, type the name of that field into the search box followed by a colon (:), and then the term you're
looking for.
You can use multiple fields in the same query. For example, you could use the following query to find all blog
posts containing the Excerpt Include macro.
type:blogpost AND macroName:excerpt-include*
Confluence will only look for the term directly after the colon. For example, the query below will search for
'some' in the title field and 'title' in the default fields:
title:some title
Use double quotes if you want to find multiple keywords:
title:"some title"
Confluence search fields
This table lists some common search fields, and shows examples of what to type into the search box. Fields
are case sensitive, so make sure you type the field name exactly as it appears in the table below.
Field Description Examples
macro Searches for pages that contains a specific macro. Type the name of the macroName:
Name macro in lowercase. You can use a wildcard to make sure Confluence finds excerpt-
the macro you're after. include*
macroName:
jira*
space Searches for content within a specific space, using the space key. Type the spacekey:
key name of the space key in capital letters. MARKETING
You can add multiple spaces using brackets and commas. spacekey:
(IT,
MARKETING)
title Searches for content with specific words in the title. title:"
product
roadmap"
type Searches for content of a particular type. You can use the following content type:
types in your query: attachment
page type:
blogpost blogpost
attachment
comment (only supported when using advanced search).
labelT Searches for content containing a specific label. If the label has a hyphen, labelText:
ext include it within double quotes. roadmap
labelText:"
product-
roadmap"
For more information about search fields, see Confluence Search Fields.
Confluence Search Fields
This page gives an overview of the Apache Lucene search fields used in
On this page:
Confluence.
Filter with CQL

Filter with CQL Searching for
content in specific
Before you dive into learning more about Lucene fields, you may want to fields
learn about the powerful search filtering offered by Confluence Query Confluence search
Language (CQL). fields
Personal
CQL (Confluence Query Language) is a query language developed for Information
Confluence, which you can use in some macros and the Confluence Pages
search. Confluence search and CQL-powered macros allow you to add Blog
filters to build up a search query, adding as many filters as you need to Attachments
narrow down the search results. Mail items
Notes
Related pages:
For an OR search, specify multiple values in the same field. Search
So to show pages with 'label-a', 'label-b' or both you'd put Confluence Search
'label-a' and 'label-b' in the same Label field, like this: Syntax
Search the People
Directory
For an AND search, add more than one filter and specify a
single value in each.
To show only pages with label-a and label-b you'd put 'label-a'
in one label field, then add a second Label field to the macro,
and put 'label-b' in the second one, like this:
Put simply, OR values are entered in the same filter, AND

values are entered in different filter.
Only some filters support AND. If the filter doesn't support the
AND operator, you won't be able to add that filter more than
once.
For a NOT search, enter a minus sign (-) before the label.
This'll exclude everything with that label.
Label* Include pages, blog posts or OR (multiple

attachments with these labels. values in the
same filter)
AND (multiple
Label filters)
With Include pages that are children of this OR (multiple

ancest page. values in the
or same filter)
This allows you to restrict the macro to
a single page tree.
Contri Include pages or blog posts that were OR (multiple

butor** created or edited by these people. values in the
same filter)
Creator Include items created by these people. OR (multiple

values in the
same filter)
Mentio Include pages and blog posts that OR (multiple

ning @mention these people. values in the
user same filter)
With Include only direct children of this EQUALS (one

parent page (further sub-pages won't be page only)
included)
In Include items from these spaces. OR (multiple

space** values in the
same filter)
Includi Include items that contain this text. CONTAINS

ng (single word or
text** phrase)
With Include items that contain this text in CONTAINS

title the title. (single word or
phrase)
Of Include only pages, blogs or OR (multiple

type** attachments. values in the
same filter)
** You can add these filters in CQL-powered macros but in search

they're part of the standard search filters, so they don't appear in the Add
a filter menu.
Searching for content in specific fields

Confluence data is stored in fields which can be specified in the search. To
search a specific field, type the name of the field followed by a colon ':' and
then the term you are looking for. For example:
title:"Some Title"
labelText:chalk
The field specification applies only to the term directly preceding the colon.
For example, the query below will look for "Some" in the title field and will
search for "Heading" in the default fields.
title:Some Heading
To learn more about using Confluence search fields in an advanced search query, head to Confluence
Search Syntax.
Confluence search fields

Below are the fields which can be searched, listed by content type.
Personal Information
Name Indexed Stored Tokenized Notes
handle true true false
type true true false
urlPath true true false
fullName true true true
title true true false
labelText true true true
modified true true false
created true true false
contentBody true true true
Pages
title true true true
spacekey true true false
macroName true true false The name of a macro used on the page
Blog
macroName true true false The name of a macro used in the blog
Attachments
filename true true true
title true true false
comment true true true
Mail items
messageid true true false
inreplyto true true false
recipients true true true
Notes
To find out the version of Lucene Confluence is using go to <installation directory>/confluence
/WEB-INF/lib and locate the Lucene jar files. The Lucene version number will be part of the filename.
Search the People Directory
The people directory displays a list of people who
are authorized to log in to your Confluence site On this page:
(they have the 'Can Use' global permission).
View the people directory
The people directory includes anybody who has
Search for people
logged into Confluence or who has had a user
Follow people's activities
account created for them in Confluence.
Notes
The people directory does not include users who
Related pages:
can log into Confluence using external user
management if they have never yet logged in. Create a Personal Space
Editing your User Profile
View the people directory Set Your Profile Picture
Choose People at the top of the screen.

Search for people
To search for a particular person, type their first name and/or last name into the search box and choose Sear
ch.
To see everyone who uses your Confluence site, choose All People.
To see just those people who have set up a personal space, choose People with Personal Spaces.
Follow people's activities

Confluence's network features allow you to 'follow' (that is, keep track of) other people's activities in your
Confluence site. For more information, please refer to Network Overview. You can use the hover profile
feature in the people directory to start following other people.
To start following someone, move your mouse over their name or profile picture and choose Follow in
their profile popup.
To stop following someone, move your mouse over their name or profile picture and choose Stop
Following in their profile popup.
Once you start following another person, their activities will start appearing in your network view.
Screenshot: The people directory
Notes
The people directory uses the hCard microformat for simple integration with a variety of microformat-
enabled tools. hCard is an open data format for representing people, companies, organizations, and
places. Read more about microformats and hCard.
By default, deactivated users (disabled user accounts) are excluded from the people directory. You
can include them by adding the showDeactivatedUsers parameter to the URL. For example:
http://my.confluence.com/dopeopledirectorysearch.action?showDeactivatedUsers=true
Any user who does not have the 'Can Use' Confluence global permission won't appear in the People
directory (for example, Jira Service Desk customers who can view KB articles, but do not have a
Confluence license).
By default, externally deleted users (for example, users deleted from an LDAP repository) are
excluded from the people directory. You can include them by adding the showExternallyDeletedU
sers parameter to the URL. For example:
http://my.confluence.com/dopeopledirectorysearch.action?showExternallyDeletedUsers=true
The Confluence administrator can hide the people directory. If it is hidden, you will not see the People
Directory option.
Recently Viewed Pages and Blog Posts
The Recently Viewed list in Confluence keeps track of pages and blog
Related pages:
posts you've recently visited, and allows you to easily navigate back to them.
Create and Edit
To view your recently viewed content: Pages
Your profile and
1. Choose your profile picture at top right of the screen, then choose settings
Recently Viewed
2. Choose the title of the page you want to revisit
To filter the list, type part of a page title or user's name in the Filter field.
Your last ten recently viewed pages also appear when you click in Confluence's Search field before you
start typing a search query.
Permissions and restrictions
As a tool for communication and collaboration, we
believe Confluence is at its best when everyone can On this page:
participate fully. Confluence keeps a history of all
changes to pages and other content, so it's easy to
Levels of permission
see who has changed what, and reverse any
Global permissions
changes if you need to.
Space permissions
Page restrictions
Confluence does, however, give you the choice to
How do permissions and restrictions
make your site, spaces, and pages as open or
interact?
closed as you want to.
Check who can view a page
Levels of permission Related pages:
There are three levels of permissions in Confluence: Confluence Groups

Global Permissions Overview
global permissions Space Permissions Overview
space permissions, and Page Restrictions
page restrictions. Configuring Confluence Security
Global permissions
Global permissions are site-wide permissions, and are assigned by a Confluence administrator or system
administrator.
Global permissions cover things like whether a user can log in or create a space. They don't really interact
with space permissions or page restrictions.
For full details, check out the Global Permissions Overview.
Space permissions
Every space has its own independent set of permissions, managed by the space administrators, which
determine the access settings for different users and groups.
They can be used to grant or revoke permission to view, add, edit, and delete content within that space, and
can be applied to groups, users, and even to anonymous users (people who aren't logged in) if need be.
For full details, check out the Space Permissions Overview.
One thing to watch out for is where a user is a member of multiple groups. You may have revoked
permission for that individual user to add pages, for example, but if they're a member of a group that is
allowed to add pages, they'll still be able to create new pages in the space.
If you can't get the result you want from space permissions, or you're not sure, check with one of
your Confluence administrators to determine what permissions you should apply to individuals and
groups.
Page restrictions
Page restrictions work a little differently to global and space permissions. Pages are open for viewing or
editing by default, but you can restrict either viewing or editing to certain users or groups if you need to.
Page restrictions can be applied to published or unpublished pages and blog posts (drafts).
Don't forget, every page in Confluence lives within a space, and space permissions allow the space admin to
revoke permission to view content for the whole space. Even the ability to apply restrictions to pages is
controlled by the 'restrict pages' space permission.
For full details, check out Page Restrictions.
How do permissions and restrictions interact?

You can restrict viewing of a page or blog post to certain users or groups, so that even if someone has the
'view' permission for the space, they won't be able to view the content of the page or blog post.
If someone is a space admin and you've used page restrictions to prevent them viewing a page, they won't
be able to see the page when they navigate to it. As a space admin though, they can see a list of restricted
pages in the space and remove the restrictions.

To check who can view a page, go to > People who can view. This will show a list of people, including
administrators, who have space permission to see the space, and are not prevented by page restrictions
from seeing the page. See Check who can view a page for more information.
The diagram below shows the points at which someone could be prevented from viewing a page.
Site - they don't have permission to log in to Confluence.

Space - they don't have permission to view the space.
Parent page - the current page has a view restriction preventing them from viewing.
Child page - the current page is inheriting a view restriction from another page higher up in the page
hierarchy, preventing them from viewing.
What about links?
Space permissions and page restrictions affect how links between Confluence pages are displayed.
If someone doesn't have 'View' space permission, links to pages in that space will be visible, but
they'll get a "page not found" message. The space key is not revealed in the link URL.
If someone has the "View" space permission, but the page has view restrictions, the link will be visible
but they'll get an "access denied" message when they click the link.
Links to attachments are also affected. If the visitor doesn't have permission to view the page the attachment
lives on, the link won't be rendered.
Confluence Groups
Grouping users in Confluence is a great way to cut
down the work required when managing On this page:
permissions and restrictions.
If you're a space admin, you can assign a set of spa Default Confluence groups
ce permissions to a group rather than to each Anonymous users
individual user. And as a page creator with 'Add Unlicensed users from linked applications
/Delete Restrictions' permission, you can also add
and remove page restrictions for groups. Related Pages:

Default Confluence groups Assign Space Permissions
Page Restrictions
There are two default groups in every Confluence Confluence Groups for Administrators
instance and, beyond that, Confluence
administrators are free to set up and edit groups in
any way they see fit.
The two default groups in Confluence are:
confluence-users - this is the default group into which all new users are usually assigned. In most
sites this is the group that provides the permission to log in to Confluence.
confluence-administrators – this super group grants the highest level of administrator
permissions. Members of this can view all pages, including restricted pages. While they can't edit
existing pages, they can add, delete, comment, restore page history, and administer the space. They
can also access the admin console and perform all administrative tasks.
Overlapping permissions
Space permissions are additive. If a user is granted permissions as an individual or as a member of
one or more groups, Confluence will combine these permissions together. This is sometimes known
as their effective permissions.
Sasha is a member of the confluence-users group and the developers group. The conflu
ence-users group has 'export' permission, but does not have 'restrict' permission. The develo
pers group has 'restrict' permission but does not have 'export' permission.
By being a member of these two groups, Sasha can restrict and export content. The permissions
do not conflict, they combine to determine what Sasha is allowed to do in this space.
Anonymous users
People who don't log in when they access Confluence are known as 'anonymous' users. By default,
anonymous users don't have access to view or change any content in your Confluence site, but Confluence
admins can assign permissions to anonymous users if it's required.
Unlicensed users from linked applications

If you're using Confluence as a knowledge base for Jira Service Desk, your Jira Service
Desk administrator can choose to allow all active users and customers (that is logged in users who do not
have a Confluence license) to view specific spaces.
These users have very limited access, and cannot be granted permissions in the same way as an individual
or group. However, it's important to note that this permission overrides all existing space permissions, so any
logged in Confluence user will also be able to see the space (regardless of their group membership). This is
due to the way Confluence inherits permissions.
Confluence is open by default, however because of the layers of space
On this page:
permissions and page restrictions that can be applied, it isn't always
obvious who can see your page.
Check who can
If you want to share a page with someone in a different team, for example, view a page
it's useful to know whether they have adequate permissions to see it before Why can
you share. these
people
view?
What should
I do if
someone
can't see my
page?
How do I
make my
page
completley
private?
Disable the People
who can view
option
Related pages:
Permissions and
restrictions
Global Permissions
Overview
Space Permissions
Overview

To check who can view a page:
1. Go to > People who can view.

2. A list of all the people who can view the page will appear.
3. Start typing a name to filter the list.
People who can view is available in both Confluence Server and Confluence Data Center.
Screenshot: the People who can view dialog showing a list of 5 people.
Why can these people view?
The list includes everyone who:
is allowed to view the space, via space permissions, and

is not prevented from viewing the page by page restrictions.
The list also includes members of the confluence-administrators super group, who can always see all spaces
and pages. This means that even if you restrict a page to yourself, it's possible that at least one other person
can see it.
What should I do if someone can't see my page?
If you want to share your page with a person, and they're not listed, you'll need to work out what is
preventing them from viewing the page.
If you restricted the page, add them to the page restrictions, and then check the People who can view list
again.
If they still aren't listed, it's likely they don't have permission to see the space. You'll need to contact a space
admin to help with this. Go to Space Tools > Overview for a list of space admins.
How do I make my page completley private?
The short answer is, you can't. Confluence is designed to be open. It's for sharing work with your team.
While you can restrict a page to yourself, it's important to note that:
Space administrators always have the ability to remove page restrictions, even from pages they can't
see.
People with Confluence Administrator and System Administrator global permissions can't see your
pages by default, but they can grant themselves space administrator permission to the space.
Members of the confluence-administrators super group can see all spaces and pages. This group
grants the highest possible permission in Confluence. Some organisations use this group heavily,
while others don't use this group at all.
Disable the People who can view option

People with Confluence Administrator or System Administrator permissions can disable the People who can
view option, if they don't want people to be able to see a list of user's names.
To disable the People who can view option:
1. Go to <base-url>/admin/plugins/gatekeeper-plugin/global/configuration.action
2. Deselect Show 'People who can view' option and save the change.
Inspect permissions
Inspect permissions is an advanced On this page:
permissions feature, and is only available in
Confluence Data Center.
Troubleshoot permissions problems
Inspect permissions via space
Confluence is open by default, but because of the administration
layers of group, individual and anonymous Inspect permissions via the Global
permissions that can be applied, it can be administration
challenging to find out exactly who can do what. Inspect permissions for a group
Permissions explanations
Inspect permissions helps you: Audit permissions
Bulk apply permissions
troubleshoot permissions problems Bulk apply permissions for a group
audit who can do what in your site Bulk apply permissions for a user
apply the permissions granted to a user or Troubleshooting and known issues
group in one space to multiple spaces. General cache problems
Export options limited in Internet
It reveals a person's effective permissions, Explorer 11
combining everything we know about their Inspect permissions for a group only
permissions in a way that can be easily interpreted. shows direct permissions
Excluding spaces with no
permissions can take a long time in
large sites
Related pages:

Troubleshoot permissions problems

Often you will need to find out why someone can or can't do something in Confluence. By inspecting
permissions you can drill right down to the root of the problem.
For example, someone reports to you that a teammate can see a space they shouldn't be able see. By
inspecting permissions you can work out exactly what group memberships, for example, might be
contributing.
Inspect permissions via space administration
You need space admin permissions for the space you want to troubleshoot.
To find out why someone can or can't view this space:
2. Go to the Inspect permissions tab
3. Enter the person's name or username.
4. Leave the Page field blank (unless you need to investigate a specific page in this space).
5. Choose Show.
A table showing the person's effective permissions in this space will appear. Click one of the icons to go to
the detail view, and find out exactly why they do or don't have that permission.
If you choose to specify a particular page, the permissions explanations will also include information about
any page restrictions. The icons will represent just that page, not the user's permissions for the entire space.
Screenshot: Inspect permissions tab in Space Tools showing permissions for two users.
Animation: Inspect permissions tab in Space tools showing permissions explanations for a user
Inspect permissions via the Global administration
You need Confluence Administrator or System Administrator global permission to do this. You don't need to
have permission to view the space itself.
To find out why someone can or can't view this space:
1. Go to > General Configuration > Inspect permissions.

2. Enter the person's name or username.
3. Enter the spaces you want to view.
4. Choose Show.
A table showing the users and spaces you searched for will appear. Click the link to see the detailed view,
then click the icons to find out exactly why they do or don't have that permission.
Screenshot: Inspect permissions in Global administration showing permissions for two users and three
spaces.
Animation: Inspect permissions in Global administration showing searching for all spaces containing the
word "project" and then viewing permissions explanations for a user.
Inspect permissions for a group
You can also inspect permissions for a specific group. This can only be done via the global administration.
To inspect permissions for a group:

2. Choose the Groups tab
3. Enter the group name.
4. Enter the spaces you want to view.
5. Choose Show.
A table showing the groups and spaces you searched for will appear. Click the link to see the detailed view.
When inspecting permissions for a group, be aware:
We don't indicate when a group does not have the Can Use global permission, as we do for users.
We don't show effective permissions for the group, as we do for users. We only show permissions
directly granted to that group (not granted via membership of a parent group. This is only an issue if
your external user directory has nested groups).
Using wildcards in your search

When searching for users, groups, or spaces, you can use * as a wildcard. For example if you wanted to
search for all spaces that contain the word project in their title, type *project and select Search for
*project from the suggestions dropdown.
Permissions explanations
The detail view shows the effective permissions for a single user or group in a space. Click each icon to see
a detailed explanation, as shown here.
1. Icons - icons indicate whether the user or group can or can't do this action.
2. Explanation - explains why the user can or can't do this action.
3. Good to know information - provides additional information that may become relevant, for example
that space administrators can grant themselves permissions they don't currently have.
The purpose of these explanations is to provide a simple reason why someone can or can't do something in
a space. The messages are designed to be short, and present the most relevant information first.
The table below contains a more detailed explanation of every message, including the conditions that trigger
the message.
Explanations about users
Explanation Message appears when...
Permission granted as an individual The user is listed in the space permissions for that space.
Permission granted as a member of: The user is a member of a group, that is listed in the space
permissions for that space. If the user is a member of multiple
groups that are listed in the space permissions, we will list all
of them.
Permission granted as an individual The user is listed in the space permissions for that space,
and as a member of: and is also a member of a group that is listed in the space
permissions for that space.
Permission granted to anonymous us The permission is granted to anonymous users in this space,
ers, which means everyone will get and your site is public (you have granted anonymous users
this permission by default, including the Can use global permission).
people who are not logged in.
Logged in users can't have fewer permissions than
anonymous users.
Permission granted to anonymous us The permission is granted to anonymous users in this space,
ers, which means everyone who is but your site is not public (anonymous users do not have the
logged in will get this permission by Can use global permission).
default.
anonymous users. This is sometimes used as a shortcut way
to provide 'everyone' with space permission, without making
the site itself public.
No permission granted as an The user isn't listed in the space permissions for that space,
individual or as a member of a group. they are not a member of a group that is listed in the space
permissions for that space, and anonymous has not been
granted any permissions.
This person doesn't have the Can use This user exists in the user directory, but doesn't have a
global permission, so they can't log Confluence license seat. They are not a member of
in to Confluence. confluence-users or another group that has the 'Can use'
global permission.
This person is a Confluence The user, or a group they're user is a member of, has
administrator so could grant Confluence Administrator global permission. This means they
themselves this permission. can recover permissions for a space they don't have
permission to see, and then change the permissions for that
space. Unlike members of the confluence-administrators
super group, they can't see the space by default.
This person is a space admin, so The user has space admin permissions in this space. This
could grant themselves this means they can modify permissions for this space, and could
permission. grant themselves any permissions they don't currently have.
This person is a space admin, so The user has space admin permissions in the space. This
can edit restrictions. They can also means they can always change page restrictions (even if they
remove all restrictions from pages don't have the Restrict permission), and can access a list of
they don’t have permission to edit or all restricted pages in the space, and remove all restrictions
view. from these pages.
This person has Delete own permissi The user can delete pages, blog posts, comments, and
on so can delete their own pages, attached files that they have created. They can't delete
blog posts, comments, and pages, blog posts, comments, and attached files created by
attachments. other users unless they also have Delete permission in the
space. For example the user can delete a page they created,
but they cannot delete a page their team mate created unless
they also have the Delete Page space permission.
To add and delete restrictions this The user has Restrict permission, but does not have the Add
person also needs the Add page per page permission. Applying a page restriction is considered
mission. editing the page, so both permissions are required.
This person is a member of the confl The user is a member of the confluence-administrators group.
uence-administrators super group. This is a default group that has significant privileges in
This means they can view all pages, Confluence, beyond that provided by the Confluence
including restricted pages. While they Administrator or System Administrator global permission.
can't edit existing pages, they can
add, delete, comment, restore page
history, and administer the space.
This person can't log in because their This user exists in the user directory, but their account has
account is disabled. been disabled. They don't have a Confluence license seat.
This is usually because the person has left the organisation.
Restrictions on <page title> prevent A page restriction has been applied to the page. The user, or
this person from viewing the page. a group they're a member of, are not listed in the page
restrictions dialog, so they have 'no access'.
This message only appears when you inspect permissions for

a specific page in a space.
Restrictions on <page title> allow this A page restriction has been applied to the page. In the page
person to view, but prevent them restrictions dialog, either everyone can view or the user or
from editing the page. group they're a member of can view, but only specific users
or groups can edit.

a specific page in a space.
Restrictions on <page title> allow this A page restriction has been applied to the page. The user, or
person to view and edit the page. a group they're a member of, are listed in the page
restrictions dialog, and they have 'View and edit' access.
Restrictions on <page title> allow this A page restriction has been applied to the page. The user can
person to view the page. view the page, either because the page restriction allows
everyone to view, and only some people to edit, or the user,
or a group they're a member of, are listed in the page
restrictions dialog, and they have "View only" or 'View and
edit' access.

a specific page in a space, and click on a permission that
doesn't require permission to edit the page, for example View,
or Add comment.
Explanations about groups
These messages appear when you select a group as the entity to inspect. You need to be a Confluence
Administrator to inspect permissions for groups.
Permission explanation Message appears when...
Permission granted to all The group is listed in the space permissions for that space.
members of this group.
Permission granted to anonymous The permission is granted to anonymous users in this space,
users, which means everyone will and your site is public (you have granted anonymous users the
get this permission by default, Can use global permission).
including people who are not
logged in. Logged in users can't have fewer permissions than anonymous
users.
Permission granted to anonymous The permission is granted to anonymous users in this space, but
users, which means everyone your site is not public (anonymous users do not have the Can
who is logged in will get this use global permission).
permission by default.
Logged in users can't have fewer permissions than anonymous
users. This is sometimes used as a shortcut way to provide
'everyone' with space permission, without making the site itself
public.
No permission granted to this The group isn't listed in the space permissions for that space,
group. and anonymous has not been granted any permissions.
This group doesn't have the Can This group exists but does not have the 'Can use' global
use global permission, so people permission. This is very common. Often one group, such as
in this group may not be able to confluence-users is used to grant a Confluence license seat, and
log in to Confluence. additional groups used only to manage space permissions.
This is only an issue if a user is not a member of another group

that grant them Can use permission.
Members of this group are space The group has space admin permissions in this space. This
admins, so could grant means members of this group can modify permissions for this
themselves this permission. space, and could grant themselves or this group any permissions
they don't currently have.
Members of this group are space The group has space admin permissions in the space. This
admins, so can edit restrictions. means members of this group can always change page
They can also remove all restrictions (even if they don't have the Restrict permission), and
restrictions from pages they don’t can access a list of all restricted pages in the space, and remove
have permission to edit or view. all restrictions from these pages.
Members of this group have Delet Members of this group can delete pages, blog posts, comments,
e own permission so can delete and attached files that they have created. They can't delete
their own pages, blog posts, pages, blog posts, comments, and attached files created by
comments, and attachments. other users unless they also have Delete permission in the
space. For example the user can delete a page they created,
but they cannot delete a page their team mate created unless
they also have the Delete Page space permission.
confluence-administrators is a sup This is a default group that has significant privileges in

er group. Members of this Confluence, beyond that provided by the Confluence
group can view all pages, Administrator or System Administrator global permission.
including restricted pages. While
they can't edit existing pages, they
can add, delete, comment, restore
page history, and administer the
space.
To add and delete restrictions The group has Restrict permission, but does not have the Add
people in this group also need the page permission. Applying a page restriction is considered
Add page permission. editing the page, so both permissions are required.
Delete own is only available to This message appears when Delete Own permission is granted
members of this group who have to a group that doesn't have Can use global permission. It is just
logged in. a reminder that people must be able to log in to delete their own
content.
This permission information may This message appears when the group is nested, that is, it's a
be incomplete because this group member of another group. This hierarchy of groups comes from
is a member of one or more your external user directory.
parent groups. Permissions
granted to parent groups are not We don't show any permissions that a group is inheriting from a
shown here. parent group. You'll need to inspect these parent groups
seperately.
Explanations about anonymous
These messages appear when you select Anonymous as the entity to inspect. Anonymous in this
instance means people who have not logged in to Confluence.
Permission explanation Message appears when...
Permission granted to anonymous Permission granted to the anonymous entity listed in the
users. space permissions for that space.
No permission granted to anonymous No permission granted to the anonymous entity listed in the
users space permissions for that space.
Anonymous users don't have Can use The permission is granted to anonymous users in this
global permission. People must log in space, but your site is not public (anonymous users do not
to use Confluence. All logged in users have the Can use global permission).
will inherit this permission by default.
anonymous users. This is sometimes used as a shortcut
way to provide 'everyone' with space permission, without
making the site itself public.
Although Delete own permission can The Delete Own permission is assigned to anonymous
be granted to anonymous users, it has users. Because you need to be logged in for us to know
no effect. who you are, and what you have created, Delete Own is
never available to anonymous users, even when granted.
Restrictions on <page title> prevent A page restriction has been applied to the page.
anonymous users from viewing the Anonymous users have 'no access'.
page.
This message only appears when you inspect permissions
for a specific page in a space.
Restrictions on <page title> allow A page restriction has been applied to the page. In the page
anonymous users to view, but prevent restrictions dialog, everyone can view, but only specific
them from editing the page. users or groups can edit.
This message only appears when you inspect permissions

for a specific page in a space.
This permission can't be granted to ano This is a reminder that some permissions, such as Space
nymous users. Admin, and Restrict are never available to anonymous
users.
Anonymous access is enabled globally. This is a reminder that your site is public. Because you
have granted anonymous users the Can use global
permission, people do not need to log in to access
Confluence.
Audit permissions
If you need to regularly check who can do what in your site, for example for compliance or regulatory
reasons, you can inspect permissions to conduct an audit.
To export permissions information for all users and all spaces in your site:

2. Choose your search criteria - you can search for particular users, groups, or spaces, include disabled
accounts, or exclude users who have no permissions.
3. Choose Show. This will give you an idea of how large your query is.
4. Choose Export.
5. Keep the default separator. Comma separated is great for opening in most spreadsheet applications.
6. Choose how you want spaces to be listed. This depends on how much information you want to
include. You can include just the space key, or the title and description too.
7. Choose Export.
The CSV file will be immediatley downloaded in your browser. This can take a few minutes, depending on
the size of your query.
This file can be extremely large in sites with many users and spaces. You could use the wildcard search
feature to limit the number of users to be included in each export.
1. Wildcard search - use a wildcard to narrow your search.

2. Export - export the results to CSV for auditing or further analysis.
This example shows the output for one user, and three spaces.
A row will be created for each of the 14 space permissions that can be granted.
A column will be created for each space in your query. These are identified by space key, but you
can choose to include the space name and description in the export if you require it.
T and F indicates whether the user has this permission (true) or they do not have this permission
(false)
Username Display Name Permission SPACE1 SPACE2 SPACE3
user1 Sample User 1 view-space T T F
user1 Sample User 1 remove-own T T F
user1 Sample User 1 page-add T T F
user1 Sample User 1 page-remove T F F
user1 Sample User 1 blog-add T F F
user1 Sample User 1 blog-remove T F F
user1 Sample User 1 comment-add T T F
user1 Sample User 1 comment-remove T F F
user1 Sample User 1 attachment-add T T F
user1 Sample User 1 attachment-remove T F F
user1 Sample User 1 mail-remove T F F
user1 Sample User 1 page-restrict T F F
user1 Sample User 1 space-export T F F
user1 Sample User 1 space-admin T F F
In this example Sample User 1:
Can do everything, including administer Space1

Can view, add, and delete their own content in Space2
Can't view Space 3 at all.
Bulk apply permissions

Bulk applying permissions is useful when:
You create a new group, and want to give that group permissions to a number of existing spaces.
You need to grant someone permissions as an individual for a number of existing spaces.
You have just created several new spaces, and want to use permissions from an existing space as a
template.
We recommend using groups as an efficient way to manage permissions in your site. When someone new
starts on your team, we would recommend making them a member of appropriate groups, over using the
bulk add permission options to grant them permissions to all their spaces as an individual.
Bulk apply permissions for a group
You need Confluence Administrator or System Administrator global permissions to do this.
To give a group the same permissions in multiple spaces:

2. Go to the Groups tab.
3. Enter the name of the group.
4. Enter the name of the space that you want to use as a starting point.
5. Choose Show, then click to see the detailed view.
6. Choose Edit.
7. Make sure the correct permissions are selected. These are the permissions you'll be copying.
8. Enter the names of the spaces you want to copy these same permissions to. You can add as many
spaces as you like.
9. Choose Apply.
10. Check the confirmation dialog to make sure all spaces were successfully updated.
Screenshot: detail view of permissions for a group and space, with several spaces listed in the 'Apply to
other spaces' field.
Bulk apply permissions for a user
Before you do this, we recommend you inspect permissions to find out what permissions the user already
has for the spaces you plan to update, paying particular attention to how the permissions are granted
(individually, or via a group). In many cases the best approach is to change the user's group membership, or
the space permissions granted to a group, rather than bulk applying changes to the individual.
You need Confluence Administrator or System Administrator global permissions to do this.
To give a user permissions in multiple spaces:

2. Enter the name of the user.
3. Enter the name of the space that you want to use as a starting point.
4. Choose Show, then click to see the detailed view.
5. The user's effective permissions are shown. These permissions are a combination of any individual
and group permissions. Choose Edit.
6. Make sure the correct permissions are selected. These are the permissions you'll be copying.
7. Enter the names of the spaces you want to copy these same permissions to. You can add as many
spaces as you like.
8. Choose Apply.
9. Check the confirmation dialog to make sure all spaces were successfully updated.
As a general rule, we recommend managing permissions using groups. If you do decide to bulk
apply permissions for a user, there are some things to be aware of:
Permissions can only be granted to the user as an individual using this method.
Any permissions the user has as a member of a group will be unchanged. For example if
they are a member of a group that has Export permission, and you bulk apply permissions
that do not have Export permission, they will still have Export permission. Changing their
individual permissions can't override their group permissions.
The checkboxes, when you click Edit, reflect the user's current effective permissions - that is
the combination of all the permissions they already have as an individual or member of a
group. When you click Apply, you'll apply these exact permissions as an individual. You may
actually be doubling up on permissions the user already has, as a member of a group.
Troubleshooting and known issues
General cache problems
Confluence caches permissions information, which helps to make sure results are returned quickly when you
check who can view a page, or inspect permissions. We continually update the cache as people and
permissions change. However, we know of two scenarios where the cache is not correctly updated - when
you import a site, and when you add, disable, or change the order of your user directories.
If this happens, the best way to force Confluence to rebuild the cache is to disable the Inspect permissions
- gatekeeper plugin, then re-enable it. Alternatively, you can restart Confluence, as the cache is built on
startup.
Export options limited in Internet Explorer 11
There's a known issue with the export dialog in Internet Explorer 11. The dialog is known to intermittently
freeze if you select either of the dropdown menus. As a workaround, use the default values for the Separator
and List spaces by fields, or use another browser to complete the export.
Inspect permissions for a group only shows direct permissions
If your external directory has nested groups (a group is a member of another group), and you inspect
permissions for a group, you'll only see permissions granted directly to that group (not effectively granted by
being a member of a parent group). If you search for a user, we'll always show the effective permissions,
including those granted by parent groups.
Excluding spaces with no permissions can take a long time in large sites
In the global Inspect Permissions screen, if you select "Don't show spaces that have no permissions for
selected users" and don't specify any other filters (such as specifying users, groups, or spaces), the query
can take several minutes to return any results. This is particularly true in sites with a very large number of
users and spaces.
Permissions best practices
There are several different strategies you can use
On this page:
for managing permissions in your site. The larger
your site grows, the more important it is to make
sure that your permissions strategy can scale with Give people access
your organisation. I want everyone in my organisation
to be able to log into Confluence
Granting permission to a space on an individual by I want everyone in my organisation
individual basis may work well for small teams, but to be able to view a space
rapidly becomes unwieldy when your user base I want to give people in my team
grows to thousands of people. access to our space
I want to give my team access to all
On this page, we provide our recommendations for our project spaces
the best ways to manage common permissions I want all the spaces in my site to
scenarios. Most of the advice boils down to: have the same permissions
I want to give external people
Keep Confluence as open as possible, it's access to my space
designed to be open by default. Lock things down
Use groups over individual permissions I want to check what a person can
wherever possible, to avoid headaches in the access in Confluence
future. I need to prevent someone from
accessing Confluence
I need to prevent specific people
from viewing a space
I want to prevent people from
seeing my work in progress
I want to prevent people seeing part
of a space
I want share one page but keep the
rest of the space private
Delegate administration tasks
I want to delegate space
administration to a specific group of
people
I want to control who can create
spaces
The big questions
What permissions should I give
people?
What should I do when someone
leaves my team?
What should I do when someone
leaves my organisation?
Related pages:
Inspect permissions
Give people access
I want everyone in my organisation to be able to log into Confluence
The best way to achieve this is to make everyone a member of a group that has permission to log in to
Confluence, such as the default confluence-users group.
See Adding or Removing Users in Groups for information on how to add people to groups.
When new people join your organisation, add them to this group to grant permission to use Confluence.
If you don't want to use an existing group, you can create a new one. The process is much the same, but
you will need to explicitly grant this group global permission to use Confluence.
To change the global permissions for a group:
1. Go to > General Configuration > Global permissions.

3. Enter your new group name in the Grant browse permission to field.
4. Make sure the Can use checkbox is selected.
5. Save your changes.
I want everyone in my organisation to be able to view a space
The best way to do this is to grant space permissions to a group that all users are a member of, such as the
default confluence-users group.
If your site is not public (anonymous users do not have the 'Can Use' global permission, everyone must log
in to use Confluence), you can also use the anonymous permission as an 'everyone' shortcut. This is useful
if your groups setup is complex, and there isn't a single group that everyone is a member of. If you plan to
make your site public in future however, it's best to avoid this workaround.
I want to give people in my team access to our space
Think about whether your space really needs to be private. If not, you can grant permission to a group that
all users are a member of, such as confluence-users.
If it does need to be private, and your team is only going to be using this one space, it might be appropriate
to grant permissions as individuals. That way you don't need to ask a Confluence Administrator to add
people to groups. See Assign Space Permissions.
However, if your team needs access to multiple spaces, using a group is definitely the way to go, as it will
save you a lot of time in future when people join or leave your team. See Adding or Removing Users in
Groups.
I want to give my team access to all our project spaces
The best way to do this is to create a group, and grant that group permissions in each project space. When
people join or leave your team, you only need to change the group membership, you don't need to edit the
space permissions for multiple spaces. See Adding or Removing Users in Groups for more information.
It might be more work to set up now, but it will help you in the long term.
I want all the spaces in my site to have the same permissions
First, you should change the default space permissions, so that when a new space is created, it
automatically gets your desired permissions.
To change the default space permissions:
1. Go to > General Configuration > Space permissions.

2. Choose Edit permissions.
3. Add groups, and grant permissions in the usual way then save your changes.
Any new spaces created will get these permissions by default.
For existing spaces, it is a little more laborious. You'll need to go to the space permissions screen in each
space, and set your desired permissions manually.
If you have Confluence Data Center you can slightly speed up this process by applying the permissions from
one space to multiple spaces. This is done on a group by group or user by user basis. There is no way to
copy an entire set of permissions from one space to another. See Inspect permissions.
I want to give external people access to my space
If you don't want to make your site public, but you need to give people outside your company, such as a
customer or contractor, access to your site, you will need to create user accounts for these people. We
recommend creating a group specifically for these people, so that it is easy to remove their access later
when it is no longer needed.
Your company is hosting a huge event, and you want to be able to collaborate with staff at Super Events,
an external events company, in Confluence, rather than relying on email.
1. Create a group called super-events-staff

2. Grant this group the Can use global permission.
3. Create a user account for each Super Events person you'll be working with.
4. Add these users to the super-events-staff group only. Remove them from confluence-
users, and any other default group to make sure they don't see any spaces they shouldn't. They
should only be a member of super-events-staff.
5. Create a space for the event, and set the permissions for your internal staff.
6. Give the super-events-staff group permission to add pages, comments, and attachments
only.
7. Send the space URL and usernames to your contacts at Super Events, and start collaborating.
By confining these users to a single group, they won't see any spaces, or other content that they don't
have permission to see, such as Confluence Questions. However, they will be able to see things like the
people directory.
Lock things down
I want to check what a person can access in Confluence
In Confluence Server there is no easy way to do this. You will need to find out which groups the user is a
member of, and then manually check the permissions for each space.
In Confluence Data Center you can Inspect Permissions to find out what a user can view.
I need to prevent someone from accessing Confluence
The best way to do this is to disable the person's user account. They will not be able to log in. See Delete or
Disable Users to find out how to do this.
I need to prevent specific people from viewing a space
If you have Confluence Data Center, Inspect permissions for the person and the space, to find out exactly
how they are being granted permission. If you have Confluence Server, you will need to see what groups
have permission, then manually check if the person is a member of that group.
If their permission was granted as an individual, simply go to the space permissions and change their
permissions. If their permission was granted via a group, you'll need to decide whether to remove them from
the group, or to change the whole group's permissions.
I want to prevent people from seeing my work in progress
First, check who can view your page. It may be that only you, or your team can see the page due to space
permissions.
If you do need to lock it down further, the simplest way to do this is restrict the page, so that only you, or your
team, can view it. See Page Restrictions to find out how to do this.
Once you're ready to share your work, remove the restrictions. A notification won't be sent when you remove
the restrictions. Notifications are only sent at the point you publish the page (this means that if you restrict a
page to yourself, and publish it, anyone who is watching the space for new pages won't ever get a
notification).
I want to prevent people seeing part of a space
The simplest way to do this is to use Page Restrictions. This is particularly useful when the pages are a work
in progress, and will eventually be opened up for more people to view at a later date.
In this example, a user wants to keep all the pages relating to a sensitive new project private, until the
information can be shared with the whole organisation.
Here's what they would do:
1. Create a page called "Secret project" and restrict it to just the people working on the project.
2. Create or move any pages relating to the project to be a child of "Secret project". The view
restriction will be inherited.
This approach is not foolproof. It requires people to remember to create future sensitive pages under the
restricted parent page, and to avoid moving pages to a parent that is unrestricted. If the content is sensitive,
and will always be restricted, consider moving it to a different space, and use space permissions to control
who can see the pages.
I want share one page but keep the rest of the space private
This can be tricky, and introduces complexity that may be a problem later, because you are forcing
Confluence to work in a way that is opposite to the way it is intended to be used.
Essentially you would need to organise your page hierarchy so that all pages are restricted, except the one
you want to share. You would then change the space permissions to open up the space. You can then check
who can view a page to make sure you've achieved the desired result.
In this example, a user wants to keep the work in their personal space private, but make their "What I'm
working on" page available for their manager and team to view.
Here's what they would do:
1. Create a page called "Private work" and restrict this page to themselves. Only they can see this
page.
2. Move all the pages in the space that should remain private to be a child of "Private work".
3. Create a page called "Open work". Move the "What I'm working on" page to be a child of this page.
4. Change the space permissions so that their manager and team can view the space.
Important things to note:
This approach is not foolproof. It requires the user to remember to create future sensitive pages
under the restricted parent page, and to avoid moving pages to a parent that is unrestricted.
Any blog posts or other non-page content created in the space would be visible, because the page
restrictions only apply to pages that are a child of "Private work".
Delegate administration tasks
I want to delegate space administration to a specific group of people
The best way to do this is to create a specific space administrators group. The benefit of using a group is
that you can easily add and remove members, without needing to touch the space permissions for the
spaces themselves.
If you need to create a sensitive space, that these people shouldn't be able to view or administer, simply edit
the space permissions for that space, and remove the group's permissions.
Create a group, and give it a recognisable name like space-administrators.

Add the people you want to be space admins as members of this group.
Grant this group space admin permissions in the default space permissions, so all new spaces will
be created with this permission.
Go to every existing space and manually grant this group space admin permissions. If you have
Confluence Data Center you can use Inspect permissions to speed up this step.
I want to control who can create spaces
You can set which groups or individuals can create spaces in Global Permissions.
If you choose to limit who can create spaces, we recommend granting this permission to a group of
champions, who can handle requests, create the spaces, and work with stakeholders to set up their space
permissions in the most appropriate way for your organisation. These people don't need to be Confluence
Administrators, they just need the Create Space global permission.
The big questions
What permissions should I give people?
This is going to depend on your organisation, and the type of work you are doing in Confluence. If
collaboration is your goal, we recommend giving people full Add, Delete, and Restrict permissions, and
granting Space Admin permissions to a handful of people, who can act as champions in the space, to
perform tasks like creating templates, or customising the view.
In some industries you may need to prevent people from deleting or restricting content, for auditing or
compliance reasons. If this is the case for your organisation, consider updating the default space
permissions so that all new spaces are created with your ideal permissions.
The main use-case for your Confluence site also has an impact on how you will structure your permissions.
Find out about using confluence for Technical Documentation, Knowledge Base articles, your Intranet, or Sof
tware Teams.
What should I do when someone leaves my team?
If most spaces in your site are open, chances are you don't need to do anything. However it's good practice
to change the person's group memberships to match their new role. This might happen automatically, via
your external user directory, or you may need to search for the user, and change their group memberships
manually.
Once you've changed their group memberships, if you're a Confluence administrator and you have
Confluence Data Center you can Inspect permissions to check what spaces the person still has access
to, then edit their permissions for each space on the fly, to remove any individual permissions.
What should I do when someone leaves my organisation?
If someone leaves your organisation, usually you would disable their user account, either in Confluence, or
in your external user directory.
You may want to tidy up any individual permissions they've been granted (just to reduce the number of
people listed in your space permissions screens), but unfortunately there's no easy way to do this. If you're a
Confluence administrator, and you have Confluence Data Center, you can Inspect permissions to check
what spaces the person still has access to, then edit their permissions for each space on the fly, to remove
any individual permissions.
Add-ons and integrations
Confluence has a wide range of features on its own, but you can also
Related pages:
extend those features with Marketplace apps, and by integrating
Confluence with other applications. Integrating with Jira applications can Use Jira
really take your Confluence experience to the next level by improving the applications and
way your teams track vital work, and plan and release new products. Confluence
together
If there's an extra piece of functionality you need, the Atlassian Marketplace
is the place to look for useful Confluence apps. Whether you need to create Use a WebDAV
diagrams, like the ones you can create with Gliffy, or you want to make Client to Work with
awesome mockups and wireframes with Balsamiq, there are heaps of great Pages
apps in the marketplace. You may even find a really useful app you never Gadgets
knew you needed, but now can't live without. Request
Marketplace Apps
In this section:
Use Jira applications and Confluence together

Use Hipchat and Confluence together
Request Marketplace Apps
Use a WebDAV Client to Work with Pages
Mail Archives
Gadgets
Use Jira applications and Confluence together
Confluence and Jira are like bacon and eggs; coffee
On this page:
and cake; Simon and Garfunkel. Separately, they're
great, but together, they're amazing!
For every project or team
If your Confluence and Jira sites are connected Display issues on a page
using Application Links, you can display and create Create reports and charts
Jira issues and more from within Confluence. Create issues from inside
Confluence
What you can do with Confluence and Jira depends Move between Jira and Confluence
on the Jira application and version you have. Find For software teams
out about the required applications and versions Define your requirements
later in this page. Manage your sprints
For service desk teams
Want to learn how to integrate Confluence Cloud Provide self help resources for your
and Jira Software Cloud? Check out this guide. customers
Create knowledge base articles
Allow any active user to see
For every project or team knowledge base spaces
Jira applications required
Display issues on a page
You can display Jira issues on a Confluence page

using the Jira Issues macro. Display a single issue,
a list of issues, or show the total number of issues.
The simplest way to add a Jira issue to Confluence

is to paste a Jira URL on a Confluence page.
<yourjirasite.com>/browse/CONF-
1234 will insert the Jira Issues macro and
display a single issue.
<yourjirasite.com>/issues/?
filter=56789 will insert the Jira Issues
macro and display a list of issues
matching the saved filter.
<yourjirasite.com>/issues/?
jql=project%20%3D%20CONF will
insert the Jira Issues macro and display a
list of issues matching the Jira search.
Alternatively, you can add the Jira Issues Macro to the page and search for issues directly:
1. In the editor choose Insert > Jira Issue.

2. Follow the prompts in the macro browser to choose a project and search for an issue – you can even
use JIRA Query Language (JQL).
Once you've added the macro, you can customize how the issue or list of issues appears on the page,
including how much information to display, how many issues, and more.
Create reports and charts
Reporting on information stored in Jira is simple in Confluence. In addition to the Jira Issues Macro, you can
use the Jira Report blueprint or Jira Chart macro to show information from your Jira application visually. It's
the best way to give your stakeholders a snapshot of your team or project's progress.
You can:
Use the JIRA Report blueprint to create a Change Log or Status report.
Use the Jira Chart Macro to display data as a chart, including pie charts, created vs resolved, and two
dimensional charts.
Use JIRA Gadgets to display detailed Jira reports and charts on pages.
Create issues from inside Confluence
You can create issues while viewing a page or from the within the editor. This is really useful if you use
Confluence for planning and gathering requirements.
To create an issue when viewing a page:
1. Highlight some text on your page and choose the Create Jira issue icon that appears above the
highlighted text.
2. Enter your server (if you have multiple Jira sites connected to Confluence), project, issue type and d
escription. Your highlighted text will populate the issue summary automatically.
3. Choose Create.
The issue will be created in Jira and added to your page. If your text is in a table, you'll have the option to
create multiple issues using text from the same column.
If you don't see a popup when you highlight text, check that Text Select is enabled in your profile settings.
To create an issue in the editor:
1. In the editor choose Insert > Jira Issue > Create new issue.
2. Enter your server (if you have multiple Jira sites connected to Confluence), project, issue type,
summary, and description.
3. Choose Insert.
The issue will be created in Jira and added to your page.
There are some limitations when creating Jira issues from Confluence. The Jira Issues macro or Create Jira
Issue dialog will notify you if it's unable to create an issue in the selected project. You can find out more in
the Jira Issues Macro page.
Move between Jira and Confluence
Whenever you add a link to JIRA issues in Confluence, or link to a Confluence page from your Jira
application, the Jira Links button appears at the top of the Confluence page. This makes it really easy to
jump from Confluence to Jira and vice versa, speeding up your workflow.
The number on the Jira Links button indicates the total number of issues, epics, and sprints connected to
that page, regardless of whether you have permission to view them. The dropdown, however, will only show
details of issues, epics, and sprints that you have Jira permissions to view.
The button doesn't detect links from issues displayed in the Jira Issues macro in table format.
For software teams

Here's some suggestions to help you get the most out of Confluence and Jira Software and unleash the
potential in your agile development team.
Define your requirements
Confluence is the perfect place to start defining your requirements. You can use the Product Requirements
Blueprint to capture your requirements, then create your Jira epic and other issues right from the
requirements page in Confluence.
Here's how it works:
1. Create a Confluence page using the Product Requirements Blueprint.

2. Choose the placeholder text 'Link to Jira epic or feature' and choose Create new issue to create your
epic in Jira.
3. Collaborate with your team to define your stories and save the page.
4. Highlight text on your requirements page and choose the Create Jira issue link to create stories
in Jira, and automatically link them to your epic.
5. Track the progress of the stories from the Confluence page or from within Jira.
The tight integration between Confluence and Jira Software means you can easily access issues from the
Confluence page and see their status at a glance, and from within Jira Software you can see links to related
Confluence pages. All the information you need is right there.
Manage your sprints
There's often a lot of material in Confluence that provides useful context for your team during a sprint. These
might be requirements documents, designs, tech specs, customer research and more. By linking these
pages to epics, you make them easy for your team to find during the sprint.
Here's how you can use Confluence to support your sprint from within Jira Agile:
In Jira Software, create a Confluence page to plan your sprint. The page is created using the Meeting
Notes Blueprint – a handy template that helps capture the details you need – and is automatically
linked to the sprint.
In an epic, link to useful Confluence pages, including requirements, designs, and more.
Report on your progress to stakeholders using the JIRA Report blueprint in Confluence.
Use the Retrospective Blueprint in Confluence at the end of your sprint to take stock of what went well
and not so well.
For people who work mostly in Jira Software, the integration means that useful Confluence pages are only a
click away.
For service desk teams
Provide self help resources for your customers
If you use Jira Service Desk, you can help your customers resolve their issues without creating a request by
connecting your Service Desk project to a knowledge base in Confluence. You'll need Confluence 5.10 or
later.
If you use Jira Service Desk Cloud, you won't be able to connect your project to a knowledge base space on
a Confluence Server or Data Center site. You can only connect to a Confluence Cloud site. Read about how
to migrate from Confluence Server to Cloud.
In Service Desk, head to Project settings > Knowledge base to connect or create a Confluence space.
When Service Desk customers search in the Customer Portal, pages in the linked knowledge base space
will be suggested, allowing customers to help themselves.
Create knowledge base articles
The Knowledge Base space blueprint, along with templates for how-to and troubleshooting articles make
creating new knowledge base articles super simple for your Service Desk agents.
The templates used in the how-to and troubleshooting blueprints are completely customizable too. Set up
the template with all your standard information and let your agents take it from there.
Allow any active user to see knowledge base spaces
If your Confluence instance is not public, you can still make a knowledge base space available via the
customer portal.
When you link your Jira Service Desk project to a Confluence space, you can choose to allow all active
users and customers to see pages in the linked space, even if they don't have a Confluence license. These
people get very limited Confluence access.
Unlicensed users can:
View pages via the Jira Service Desk customer portal.

Follow a URL to a page and then navigate within the linked space.
Unlicensed users can't:
Like, comment on or edit pages (or be granted permission to do this).

See the dashboard, user profiles, the people directory or space directory.
Search the whole site.
This permission can only be enabled via Jira Service Desk, but you can revoke access to the whole site or to
particular spaces via Confluence's global permissions or space permissions.
Allowing all active users and customers to view a space will override all existing space permissions, so
any logged in, licensed Confluence user will also be able to see the space (regardless of their group
membership). This is due to the way Confluence inherits permissions.
Jira applications required

As you've seen, Confluence has many integration points, some of which are only available in particular Jira
applications or versions.
This matrix outlines the specific Jira applications you'll need for each feature. We've also included the
minimum legacy Jira Server version (plus any add-ons) that you'll need if you're not using the latest Jira
applications.
Feature Jira Jira Jira Service Minimum legacy

Core Software Desk version
Display issues using Jira issues macro Jira 4.3
Display issue and project information Jira 5.0

using Jira chart macro
Display issue and project information Jira 5.0

using the Jira Report blueprint
Create an issue from Jira issues macro Jira 4.3
Create issues by highlighting text on a Jira 6.3.1

Confluence page
Create issue by highlighting text on a Jira 6.3.1 and

Confluence page and automatically link Jira Agile 6.3.5
issues to an epic
Link and create Confluence pages from Jira 6.3.1 and

epics and sprints Jira Agile 6.3.5
View linked issues with the Jira links Jira 6.3.1

button in Confluence
Create a space using the Software Jira Software 7.0

Project space blueprint
Use a Confluence space as a Jira 5.2 and

knowledge base in the customer portal Jira Service Desk
1.0
Allow Service Desk customers to view Jira Service Desk

knowledge base articles without a 3.1
Confluence license
Search for an existing Confluence page Jira 4.3

within the Jira link dialog
Delegate user management to Jira Jira 4.3
Add a Jira gadget to a Confluence page Jira 4.3
That's it? Time to jump into Confluence and give some of these great features a try with your team or
project.Want to find out more about how to connect your Jira application to Confluence? Check out Integratin
g Jira and Confluence.
Use Hipchat and Confluence together
Hipchat is a group messaging and video chat app
On this page:
for team communication.
Connect a Confluence space to a Hipchat room to Connect Confluence and Hipchat

get instant updates about changes in the space, Connect spaces to rooms
send realtime notifications to the room, and share Send space notifications to Hipchat
what you've been working on with your team. Get Confluence in your Hipchat sidebar
Need to chat? See from Confluence if
someone's online on Hipchat
We ended support for the
Spice up your pages with Hipchat
Hipchat integration plugins in
emoticons
Confluence 7.0
Create Hipchat rooms from Confluence
We have discontinued development on all Invite users to Hipchat from Confluence
chat products. Hipchat Cloud services were
shut down in February 2019, and Hipchat
Data Center and Server will reach end of
life in 2019 and 2020 respectively.
Hipchat plugins are now disabled by default

for new installations. This will have no
impact on existing installations, and can be
easily enabled if required.
If you're not using Hipchat, you can reduce

clutter in your global and space
administration screens by disabling the
following plugins now:
Atlassian Hipchat integration plugin

Atlassian Hipchat integration plugin
core
Confluence Hipchat emoticons plugin
Confluence Hipchat integrations
plugin
Confluence Hipchat plugin
Connect Confluence and Hipchat

You’ll need to be a site admin with global
permissions for both Confluence and Hipchat to set
up the initial connection between Confluence and
your Hipchat group. Go to > General
Configuration > Hipchat Integration and choose C
onnect Hipchat.
Connect spaces to rooms
If you're a space admin, connect your space to a Hipchat room by going to Space Tools > Integration > Hip
chat and selecting which rooms you'd like to connect. A space can be connected to as many Hipchat rooms
as you like, and a Hipchat room can be connected to multiple spaces.
Send space notifications to Hipchat

When choosing which rooms to connect, you can also choose which notifications you'd like to send to each
room.
1. Pick a room: choose a Hipchat room to send notifications to.

2. Decide what to send: select the type of notifications to send to the room.
Notifications appear in realtime, and clicking on them takes you straight to Confluence.
You can choose different notification settings for each space-room connection. A design team working on a
specific project could choose to get updates from that project's space whenever a page is updated, so they
can keep close track of its progress. From their team space, though, they might choose to be notified only
when there’s a new a blog post, so they’re up to date on important team news but don't get interrupted by
any other changes in that space.
Change the notification settings whenever you like by going to Space Tools > Integration > Hipchat, and
clicking on Edit Notifications next to the room name.

Want to keep something private? Don't worry, rooms are never notified about the creation or update
of any content with view restrictions on it.
Get Confluence in your Hipchat sidebar

Find content you've viewed or worked on in Confluence in your Hipchat sidebar, so you can easily resume,
share or discuss work with your team. Once a space has been linked to a room, you can find this in your
sidebar either under the space name or, if you have multiple spaces linked to your room, under the name of
your instance.
Select the name of your space or instance, then follow the prompts to authenticate your account. This will let
you open up a Confluence glance in your sidebar. Switch tabs to view either all Updates from the space
linked to that room, or My Work from across Confluence.
The My Work tab lets you filter all the content from Confluence that you've been Mentioned in, Recently
Worked on, Recently Visited or Saved for later. Now, when you want to share an important piece of
information with your team, ask them to review your work or collaborate with you, you can find and link them
to relevant content directly from Hipchat.
Need to chat? See from Confluence if someone's online on Hipchat
Got questions about something someone else has worked on? Once your Confluence instance is linked to
your Hipchat group, you can hover over a user mention or a byline in Confluence to see if the user is
available in Hipchat. Green for available, yellow for away, or red for do not disturb.
Spice up your pages with Hipchat emoticons
In the editor go to Insert > Emoticons to bring your pages to life with emoticons. You can also type
them right into the editor like this (success) .
Create Hipchat rooms from Confluence

Setting up a new team or project? Create a new Hipchat room at the same time, through Confluence. If
you're a space admin, go to Space Tools > Integration > Hipchat and instead of selecting an existing room
in the dropdown, type in the name of the new room you want to create and hit Add.
Invite users to Hipchat from Confluence

If you're a global admin for both Confluence and Hipchat, you can send users Hipchat invites directly from
Confluence. Go to > General Configuration > Hipchat Integration > Invite users to Hipchat.
You'll need at least one space integrated with a room to see the Invite users link.
Request Marketplace Apps
The Atlassian Marketplace website offers hundreds of apps that the administrator of your Atlassian application
can install to enhance and extend Confluence. If the app request feature is enabled for your Confluence
instance, you can submit requests for apps from the Marketplace to your Confluence administrator.
The 'Atlassian Marketplace for Confluence' page provides an integrated view of the Atlassian Marketplace from
within your Confluence instance. The page offers the same features as the Marketplace website, such as
searching and category filtering, but tailors the browsing experience to Confluence.
This in-product view of the Marketplace gives day-to-day users of the Atlassian applications, not just
administrators, an easy way to discover the apps that can help them work. When you find an app of interest,
you can submit a request with just a few clicks.
Submit an app request

To browse for add-ons in the Atlassian Marketplace, follow these steps:
1. Choose your profile picture at top right of the screen, then choose Atlassian Marketplace.
2. In the Atlassian Marketplace page, use the search box to find apps or use the category menus to browse
or filter by type, popularity, price or other criteria. You can see what your fellow users have requested by
choosing the Most Requested filter.
3. When you find an app that interests you, click Request to generate a request for your administrator.
4. Optionally, type a personal message to your administrators in the text box. This message is visible to
administrators in the details view for the app.
5. When ready, click Submit Request.

6. Click Close to dismiss the 'Success!' message dialog box.
At this point, a notification appears in the interface your administrators use to administer apps. Also your request
message will appear in the app details view, visible from the administrator's 'Find New Apps' page. From there,
your administrator can purchase the app, try it out or dismiss requests.
Update an app request

After submitting the request, you can update your message at any time. Click the Update Request button next
to the listing in the Atlassian Marketplace page to modify the message to your administrator.
The administrator is not notified of the update. However, your updated message will appear as you have
modified it in the details view for the app immediately.
Use a WebDAV Client to Work with Pages
Create, move and delete pages and attachments in Confluence using a file manager like Finder (OS X),
Explorer (Windows) or Dolphin (Linux) or other WebDav compatible local client like CyberDuck.
For example, if you need to delete a lot of pages you can bulk delete them in your local file manager (like Finder
or Explorer), rather than one by one in your browser.
Access to Confluence through a native client is provided by the WebDav plugin. Your administrator may have
disabled the WebDav plugin, or may have restricted the actions that you can perform using a local client. See Co
nfiguring a WebDAV client for Confluence for more information on how to set it up.
Manage pages and files in a native client

Accessing Confluence through a native client is useful for performing bulk actions. Before you can start creating
and moving things around, it's useful to understand how the content is organized.
The hierarchy in the file system looks like this:
Type of space (global or personal)

Space (folder name is the spacekey)
Homepage (and other top level pages)
Child pages (folder name is the name of the page)
Attachments (filename of the attachment)
Essentially the file structure is the same as the page tree in your space. Here's how the Confluence
demonstration space looks in Finder.
1. Space key
2. Page title
3. Attached file
Here's some things you might choose to do in a local client, rather than in your browser:
Move pages to another space

Select the page folders, and drag them into the other space's folder (drag them from Space A to Space B)
Delete multiple pages
Select all the page folders you want to delete and delete them.
Delete multiple attachments from a page
Navigate down to the page folder, select the attachments you want to delete and delete them.
Upload multiple attachments
Navigate to the page folder, and drag the files into the folder (note you can attach multiple files through
the insert dialog as well).
Mail Archives
Confluence allows you to collect and archive mail within each space. It's
Related pages:
useful for storing the email messages that relate to a particular project – you
can put them in the same Confluence space as the content for that project. Spaces
Add a Mail Account
You can download mail from one or more POP or IMAP accounts, or import
mail from an mbox file on your local system or on the Confluence server.
You need space administration permissions to manage the mail archives.
Confluence mail archiving is an optional feature. This means that

the 'Mail' options may be disabled and will therefore not appear in
the Confluence user interface. Mail archiving features are contained
in a system app. To activate mail archiving features in Confluence,
enable the app – go to > Manage apps then choose System in
the drop down, and enable the Confluence Mail Archiving Plugin.
To see archived mail:
Go to a space and choose Space tools > Integrations > Mail

Choose a message to see its contents, or choose Next, Previous
and other options to navigate around the mail archives.
Manage mail archives:

Add a Mail Account
Delete and Restore Mail
Import Mail from an mbox
Screenshot: Viewing a message in the mail archive
Notes
Only site spaces – not personal spaces – can store mail archives. See Spaces for information on site
and personal spaces.
You can also search the mail messages and their attachments. See Search.
Confluence mail archiving is an optional feature. This means that the 'Mail' options may be disabled
and will therefore not appear in the Confluence user interface. Mail archiving features are contained in
a system app. To activate mail archiving features in Confluence, enable the app – go to > Manage
apps then choose System in the drop down, and enable the Confluence Mail Archiving Plugin.
Add a Mail Account
When you add a mail account, you're configuring Confluence to download
On this page:
mail from that account and archive it within the space.
You need space administration permissions to add a mail account. See Spa Add a mail account
ce Permissions Overview. Fetching Mail
Notes
Note: Confluence will remove email messages from an email account
when it transfers them to the mail archive. You must therefore configure Related pages:
Confluence to poll a clone email account rather than the actual account.
For example, to archive the actual account [email protected] to your Mail Archives
Confluence Sales space, you must first create a clone account such as con How do I check
[email protected] that contains the same email content. which spaces have
email accounts?
How to disable
Add a mail account automatic mail
polling
Step 1. Create a clone email account on the mail server
1. Add a new email account on the mail server with the clone email
address.
2. Copy all existing email messages from the actual account to the
clone account.
3. Set up the actual account to bcc sent email messages to the clone
account.
4. Set up the actual account to forward received email messages to the
clone account.
Step 2. Configure Confluence to archive the clone account
1. Go to the space and choose Space tools > Integrations from the bottom of the sidebar.
2. Choose Mail Accounts > Add mail account.
3. Enter configuration details for the account:
Account Name: Enter a name for this account by which it will be known in Confluence.
Description: Provide a description for this account (optional).
Protocol: Choose from POP, IMAP, POPS or IMAPS.
Hostname: Enter the host name of the mail server on which the account resides.
Port: Don't edit this field. The mail server's port number will be displayed by default.
Username: Enter a username that has permission to retrieve mail from this account.
Password: Enter the account's password.
4. Choose Test Connection to verify the details
5. Choose Create to add the account to Confluence
For each mail account you add, you can perform these actions in the Mail Accounts tab:
Edit: Change the configuration settings for the mail account.

Remove: Remove the account permanently.
Disable/Enable: Temporarily disable the account, or enable a disabled account.
Fetching Mail
Confluence automatically fetches mail from the server once every 30 minutes. You can manually retrieve
new mail from the configured mail accounts by selecting the Mail tab and choosing Fetch new mail.
You need to be a space administrator to manually retrieve mail. See Space Permissions.
Notes
Only site spaces – not personal spaces – can store mail archives. See Spaces for information on site
and personal spaces.
Once mail is fetched it will be removed from the server.
Delete and Restore Mail
To delete mail from a space, you need 'Delete Mail' permission.
Related pages:
Only a space administrator can delete all email messages in the space Mail Archives
simultaneously. Add a Mail Account
To delete mail from a space:
1. Go to a space and choose Space tools > Integrations > Mail

A list of email messages in the space is displayed in reverse
chronological order.
Delete an individual email message by choosing the trash
icon beside it.
Delete all email messages within the space by choosing Delet
e All.
Email messages deleted using the 'Delete All' option can't be restored.
Space administrators can restore deleted email messages, provided they were deleted individually.
To restore deleted mail:
2. Choose Trash
You'll see a list of email messages and other content deleted from the space.
3. Choose Restore beside the email message you want to restore.
Import Mail from an mbox
Confluence allows you to import mail from mbox files located either on your
Related pages:
local system or in a specified location on the Confluence server. Confluence
will store the imported email messages in the space's mail archive. Mail Archives
Add a Mail Account
You need to be a space administrator to import mail for a space. See Space
Permissions.
NB: You may need to enable the Confluence Mail Archiving Plugin as it
is disabled by default.
To import mail from an mbox file:

1. Go to the space and choose Space tools > Integrations from the bottom of the sidebar.
2. Choose Mailbox Import.
To import from a location on your file system: Browse to the location of the mbox file, select the
file and then choose Import.
To import from the Confluence server: Enter the location of the mbox file on the server, then
choose Import.
Notes
Only site spaces can store mail archives. Personal spaces cannot. See Spaces for an explanation of
site spaces and personal spaces.
For security reasons mail can only be imported from a specified location in the Confluence server's
file system. We recommend administrators create a folder in their Confluence home directory, add
the system property confluence.mbox.directory and specify the location for mailboxes to be
imported from . Mail cannot be imported from the server until this system property is set. See Configuri
ng System Properties.
Gadgets
Gadgets allow you to add dynamic content to a Confluence page or Jira
On this page:
application dashboard. Confluence can display gadgets that support the Op
enSocial specification, including third party gadgets.
Add a Confluence
gadget to a page
For more information about Atlassian gadgets, see the introduction to
Add a Jira gadget
Atlassian gadgets and the big list of Atlassian gadgets.
to a page
Add a Confluence
To see a list of available gadgets in your Confluence site go to Help > Avail
gadget to your Jira
able Gadgets.
application
dashboard
Add a Confluence gadget to a page

We ended support for the following Confluence gadgets in Confluence 7.0:
Confluence Page Gadget

Activity Stream Gadget
Confluence QuickNav Gadget
These gadgets no longer appear in the macro browser and can't be added to a page. Any gadget already on
a page, or used in another application like Jira, will still work.
The Confluence News gadget was removed entirely in Confluence 7.0. This gadget displayed news from
Atlassian and hadn't been working for some time.
If you're wanting to display information within Confluence, we recommend using the following macros as an
alternative:
Include Page macro

Recently Updated macro
Livesearch macro
Add a Jira gadget to a page

For displaying basic Jira information, such as issues and charts, we recommend using the Jira Issues Macro
and Jira Chart Macro as these macros have better performance and are easier to configure than gadgets.
If the Jira information you want to display is not available from either of these macros a gadget will likely do
the trick.
To add a Jira Gadget to a Confluence page:
In the editor go to Insert > Other Macros.

Select the gadget you wish to add, and use the preview area to configure the gadget.
Choose Insert.
If you don't see any Jira Gadgets in the macro browser, ask your Confluence administrator to add
the Jira Gadget urls to the list of authorized external gadgets in Confluence, and check that the
application link between Confluence and your Jira application is configured correctly.
Add a Confluence gadget to your Jira application dashboard

To add a Confluence gadget to your Jira dashboard:
1.
1. Go to the dashboard by selecting the Dashboard link in the header.

2. On the dashboard, Click Add Gadget.
3. Use the gadget wizard to choose the gadgets you want to add.
If you don't see any Confluence gadgets in the Jira gadget directory, ask your Jira administrator to
add the gadget URLs as follows.
To add a Confluence gadget to your Jira application's gadget directory:
1. In Confluence, go to Help > Available Gadgets and copy the gadget URL for the gadget you
want to make available in Jira.
2. In Jira, go to the dashboard and choose Add Gadget.
3. Choose Manage Gadgets or Add Gadget to Directory (depending on your Jira application
and version)
4. Paste in the Confluence gadget URL and choose Add Gadget.
The gadget will now be available from the Jira Gadget Directory.
Activity Stream Gadget
We ended support for this gadget in Confluence 7.0
The gadget no longer appears in the macro browser and can't be added to a page.
Any gadget already on a page, or used in another application like Jira, will still work.
The activity stream gadget is similar to the recently updated macro and shows a list of the most recently
changed content within your Confluence site.
In addition to showing a list of most recently changed content, the activity stream gadget also groups activities
by separate date, and provides an RSS feed link to its content in the top-right corner.
Activity Stream Gadget Properties
Properties are settings for Confluence gadgets that allow the user to control the content or presentation of data
retrieved by the gadget. These are similar to a Confluence macro's parameters. The table below lists relevant
properties for this gadget.
These properties are located in the preview panel in the macro browser.
Property Required? Default Description
Title Yes None Adds a title to the top of the Activity Stream.
Global No None Allows you to add filters to the gadget including:

filters
space
username
update date
Jira issue key (if your Confluence instance is integrated with a
Jira application)
Available Yes All If you have application links to other sites, Jira or another
streams Confluence site, you can choose to include activity from those
streams also.
Display No 10 Specify the maximum number of results to be displayed. A maximum

options: of 10 results will be displayed by default. The maximum value that
limit this property can accept is 100.
Display No Never Specify the time interval between each 'refresh' action undertaken by
options: /false the activity stream gadget. A refresh makes the activity stream
Refresh gadget reflect any new activity that has been conducted on the
Interval Confluence site.

The Confluence page gadget allows you to show

On this page:
content from a page on your Confluence site in a
gadget. You can optionally configure the gadget to
display links to view and/or edit the page on your Confluence Page Gadget Properties
Confluence site. The page gadget can also be Working Macros
displayed in canvas view, so that it takes up all of
the space provided by your dashboard.
Macros that work with the page gadget

Please note, not all macros work with the page gadget. Please refer to the Working Macros section
below for more information.
Screenshot: The Confluence page gadget displaying a sample page
Confluence Page Gadget Properties

Properties are settings for Confluence gadgets that allow the user to control the content or presentation of
data retrieved by the gadget. These are similar to a Confluence macro's parameters. The table below lists
relevant properties for this gadget.
Property Required? Default Description
Space No None Specify the space that your desired page is located in. Suggestions
will display in a dropdown when you start typing.
(Note, this property is only used to make searching for pages
easier. It is not required.)
Page Yes None Specify the page that you want to display in your gadget.
Suggestions will display in a dropdown when you start typing.
Show No Yes Select whether to display a link to view the page on your
View Link Confluence site. Clicking the link will open the page in Confluence.
Show No No Select whether to display a link to edit the page on your Confluence
Edit Link site. Clicking the link will open the page for editing in Confluence.
Refresh No Never Specify the time interval between each 'refresh' action undertaken
Interval /false by the page gadget. A refresh makes the activity stream gadget
reflect any new activity that has been conducted on the Confluence
site.
Working Macros
The Confluence page gadget will only render a subset of the macros that are used in Confluence correctly.
Refer to the table below for the list of macros that work and do not work with the page gadget and known
limitations.
Some of the issues with macros in the page gadget can be worked around, if you are comfortable
developing in Confluence. Please see Troubleshooting Macros in the Page Gadget for more
information.
Key:
Works with the page gadget
* Partially works with the page gadget
Does not work with the page gadget
Macro Works Limitations

with
page
gadget?
Activity You cannot have another gadget embedded within the Confluence Page Gadget
Stream
Anchor * Opens in a new page

(within a
page)
Attachments N/A
Blog Posts N/A
Chart N/A
Children N/A
Display
Content N/A
By Label
Content N/A
By User
Excerpt N/A
Gallery N/A
Include N/A
Page
Info N/A
Labels List N/A
Livesearch N/A
Note N/A
Metadata N/A
Metadata N/A
Summary
Pagetree N/A
Search
Pagetree N/A
Panel N/A
Quick Nav You cannot have another gadget embedded within the Confluence Page Gadget
Recently N/A
Updated
RSS Feed N/A
Section & N/A

Column
Spaces N/A
List
Table of * Works, however links will be opened in a new browser window when clicked.
Contents
Team See here for the Improvement Request:

Calendars
for CONFSERVER-51407 - Make Team Calendars display in a Confluence
Confluence
Page Gadget, for use on a JIRA Dashboard GATHERING INTEREST
Server
View File * Works, but you may need to refresh the gadget the first time (see CONF-19932).
(PDF or
PPT)
Widget * Only works for some content:

Connector
Works: blip.tv, Episodic, Flickr, Google Calendar, presentations on Google
Docs, MySpace Video, Scribd, Skitch.com, SlideRocket, SlideShare,
Viddler, Vimeo, YouTube, Dailymotion, Metacafe, FriendFeed, Yahoo
Video, Wufoo HTML Form Builder
Does not work: FriendFeed, Google Gadgets, Google Video (consumer
service discontinued), Twitter, Widgetbox, DabbleDB, BackType
Confluence QuickNav Gadget

The QuickNav Gadget allows you to add the quick navigation functionality to search your Confluence site.
To search Confluence using a QuickNav Gadget, type the name of a page, blog post, person, file, or space
into the search box, and choose from the list of results displayed.
If you don't immediately see what you need, hit Enter or choose the 'Search for' option at the bottom of the
search results to go to the advanced search page. Learn more about searching Confluence.
Screenshot: Using the QuickNav Gadget
You can also search for administrative options in the QuickNav Gadget. For example, type 'general'
into the search field to go to the General Configuration screen.
More information about the QuickNav Gadget:
The QuickNav Gadget returns matches based on the title only, not the content of the page or file.
Matching items are grouped by type, so that you can quickly find the type you want. Confluence
shows a maximum of 3 admin options, 6 pages and/or blog posts, 2 attachments, 3 people and 2
spaces.
Items are ordered with the most recently updated first.
Permissions determine the admin options that appear in the search results. You'll only see the options
you have permission to perform.
Confluence QuickNav Gadget Properties
This gadget has no properties and cannot be customized.

Confluence use-cases
This section describes some specific use cases for Confluence.
Using Confluence for technical documentation

A technical communicator's guide to using Confluence – see Develop
Technical Documentation in Confluence.
Setting up a knowledge base

A support engineer's guide to using Confluence as a knowledge
base – see Use Confluence as a Knowledge Base. You can also
check out our handy guides on writing how-to and troubleshooting
articles.
Setting up an intranet
A quick guide to setting up an intranet – see Use Confluence as your
Intranet.
Confluence for software teams

A series of blog posts to help your agile team get the most out of
Confluence. See Confluence for Software Teams.
On this page:
Confluence is a flexible platform with a range of features and Marketplace
apps that can help you capture, distribute, and update your technical
documentation. Below are some tips to help you get your technical Create your
documentation site started, and to save you time and effort managing your Documentation
documentation's life cycle. Space
Save time by re-
For another great overview of how you can use Confluence for using content
documentation check out Rock the Docs from our solution partner, K15t. Use page templates
Draft your work
Create your Documentation Space Use links and
anchors
Creating spaces in Confluence is quick and easy. All you need to do to get Useful macros
your documentation started is choose Spaces > Create space from the Keep track of page
Confluence header. To make things even easier, choose the updates
'Documentation Space' option in the create space dialog; it'll give you a Customize PDF
custom home page with a search box (the livesearch macro) to search just export
your documentation space, a recently updated macro, and a few other Other useful tools
goodies. and apps
Documentation
Give your space a name, and Confluence will automatically create the theme
home page and space key for it (change the space key if you're not happy (discontinued)
with the one Confluence chooses for you). Feel free to customize the home
page at any time; what it looks like is completely up to you! Related pages:
Spaces
Save time by re-using content

If there's something you're going to use multiple times in your
documentation space – whether it's a word, sentence or paragraph; an
image; a product version number; or anything else – you can create it once
and include it on as many pages as you like (or use it in the header and/or
footer). Inclusions not only save you typing the same thing many times, they
also make it easier when things change – it's much better to update the info
in one place, than 47!
There are 3 macros that allow you to re-use content:
The Excerpt macro to define a re-usable section, or 'excerpt', on a page – add content inside this
macro, and you can reuse it on as many pages as you like.
The Excerpt Include macro (excerpt-include) to include the contents of an excerpt on another
page.
The Include Page macro (include) to include the entire content of a page on another page.
For example, let's say you create release notes for each major release of your product, and you want to
include the intro from each release notes page on a 'what's new' page. Place each release notes intro in an E
xcerpt macro, then add an Excerpt Include macro for each set of release notes to the what's new
page. Your intros will magically appear on the what's new page, and if you update the release notes it'll
automatically update the what's new.
1. Excerpts: the intros to these pages are in excerpt macros.

2. Excerpt include: these are excerpt include macros.
Another example is one of the ways we use the Include Page macro. Whenever the ellipsis ( ) appears
in our documentation – for example, go to > Copy – it's actually an Include Page macro. We have a
page with just that image on it, so we can include it whenever we need an ellipsis.
Why do we do use an Include Page macro for one tiny image? Well, just in case that UI element is ever
changed. If we attach the image to every page, there might be 50 pages we need to update when things
change; if we use an Include Page macro, we update once and it's changed everywhere. Doing it this way
also allows us to know how many pages we're using the image on. By going to > Page Information, we
can see how many incoming links there are to this page, and that tells us how many pages use the image.
Create an inclusions library (optional)
You can include content from any Confluence page, but you may want to create an 'inclusions library' to hold
content that's specifically for re-use. The inclusions library isn't a specific feature of Confluence; the pages in
the inclusions library are just like any other Confluence page. This is just a technique you can use if you
want a place to store content that's specifically for re-use.
To create your inclusions library:
1. Choose Create and create a new page in your space

2. Enter a suitable title. We use '_ConfluenceInclusions' (the underscore before the title helps to let
people know this page is special)
3. Enter some content and save the page
We enter text explaining the purpose of the inclusions library and how to re-use the content
4. Choose Space tools > Reorder pages and drag your new page above the space homepage
5. Go to your new inclusions page and choose Create to add child pages containing your re-usable
content
Because you've moved the pages to the root of the space, they won't appear in the page tree in the
sidebar. The pages will be picked up by other searches though, as they're normal Confluence pages.
1. Inclusions library location: drag your inclusions library here, above the rest of your documentation.
Use page templates

Creating one or more page templates can be a real time-saver if you're creating a lot of pages with the same
layout. If you're constantly adding the same macros, like panels and table of contents, save yourself from
RSI and put them into a template – you can start with one, but make as many as you need to maximize your
efficiency.
To create a page template that's available in all spaces:
1. Go to > General Configuration

2. Select Global Templates and Blueprints from the list on the left
3. Choose the Add global page template button at the top-right
4. Create your template page and choose Save
For detailed info on page templates, see Create a Template.
To get to Global Templates and Blueprints , or any other admin page quickly, hit / on your
keyboard and start typing the name of the admin page you're looking for.
Draft your work
When you're creating a new page in your documentation, you'll likely want to do it over time, saving as you
go, and have a select few people review it to provide feedback. A loose description of this workflow is 'draft,
review, publish'.
You don't want any half-finished pages being seen by your users, and most documentation needs to be
reviewed before it's finalized, so here's a technique for drafting pages and allowing for review:
1. Create a page and restrict its permissions

For example, you might restrict viewing to a group of people such as your team, or a few select
individuals. On a public site, you might restrict viewing to staff members, so that the general public
can't see the page.
2. Write your page content
3. Share the page with your reviewers and ask them for feedback (make sure you haven't restricted
them from seeing the page!)
The reviewers can add comments to the bottom of the page or highlight text to add a comment inline.
If you give them permission, they can also edit the page content directly.
4. Publish the page when ready, by doing the following:
a. Delete any comments on the page
b. Remove page restrictions so that your audience can see it
You've now published your page. The space permissions and site permissions now determine who can see
and/or update the page.
Use links and anchors

Add links
In any documentation site, it's essential to be able to link from one page to another, and often to specific
sections on a page. You can add any URL to a Confluence page and Confluence will automatically detect
it and turn it into a link.
If you paste the URL for another page in your Confluence site, Confluence will display the link text as the
page name and turn it into a relative link, meaning if the name of the page changes, Confluence will adjust
the link so it doesn't break.
Add and link to anchors
The anchor macro allows you to create anchors in your documentation, which can be linked to from
anywhere. I've added an anchor at the top of this page so you can click to go back to the top.
To add a macro and link to it from the same page:
1. Type {anchor in the editor, select the anchor macro and give your anchor a name (top in my
example)
2. Select the text that'll link to the macro and hit Ctrl+K (Windows) or Cmd+K (Mac) (this opens the link
dialog)
3. Choose Advanced from the options on the left and type # followed by your anchor name (#top in my
example)
Check out our documentation for links and anchors to get the full rundown on linking to anchors on other
pages and other anchor goodness.
Useful macros
Confluence ships with a great range of macros, and there are a few that are particularly useful in technical
documentation. Here's a few:
Table of contents macro
The Table of Contents macro helps people navigate lengthy pages by summarizing the content structure and
providing links to headings used on the page. The best part is, you don't need to do anything except add the
macro; once you've added it, it'll automatically detect headings and add them to the table of contents.
Tip, Note, Info, Warning, and Panel macros
Often when creating documentation, there are elements of a page that you want to highlight or draw the the
viewers' attention to. Confluence ships with the Tip, Info, Warning, Note and Panel macros, which will help
you focus a viewer's attention on a particular part of your content.
Tip of the day

Use the tip macro to give your readers handy hints!
Keep track of page updates

In Confluence, it's quite usual for a number of different people to update a single page. Technical writers
need to know what happens to our documents, both during review and after publication.
Watch pages or the space
So that you know when changes are made, it's a good idea to watch pages or even the entire space. That
way, when changes are made to pages you're watching, or someone comments on them, you'll get an email
notification letting you know who changed what.
Whenever you're on a page in your documentation space, choose the Watch button at the top-right of the
page. From there, you can choose to watch just that page, or all pages in the space.
View page history
Confluence creates a new version of the page every time someone edits the page. The page history shows
all the versions, with date, author, and any comments made on the update.
To view page history, go to the page and choose > Page History
On the page history view, you can:
View the content of a specific version of the page.

Revert to (restore) a specific version.
Select any two versions and ask for a comparison, to see what has changed between those two
versions.
Take a look at Page History and Page Comparison Views for a detailed explanation.
Show a list of contributors
If you want to see at a glance who's updated a page or pages, you can add the contributors macro. This
macro displays a customizable list of people who've contributed by creating, editing, or, optionally,
commenting on the page.
Customize PDF export

If you're planning to provide a PDF version of your documentation – whether it be for email, download, print,
or any other form of delivery – you can customize the look of the PDF by adding a title page, header, and
footer.
The process you take depends on whether you're trying to customize the PDF export for one space or for
your whole site, so, if you're keen to make these changes, take a look at our page on Customize Exports to
PDF for more detailed instructions.
Other useful tools and apps

Confluence is already a great tool for technical documentation, but you can still add to it depending on your
documentation and workflow needs. Here are some useful apps available on the Atlassian Marketplace, most
of which we use ourselves, which can extend the functionality of Confluence.
New apps are hitting the marketplace all the time. This is by no means an exhaustive list!
Scroll Versions (supported by vendor)
Scroll Versions, by K15t, allows you to tie versions of your documentation to versions of your product, so that
when a new version of your product ships you can publish that version of your documentation. Create as
many versions of your documentation as you like, make the changes you need to, and keep them up your
sleeve until release time. You can even publish different variations of your documentation – like if you have
versions of your documentation for different operating systems – to different spaces or Confluence instances.
Copy Space (unsupported)
The Copy Space add-on, by Atlassian Labs, does what its name suggests; it allows a space administrator to
copy a space, including the pages within the space. Great for when you want a space template that you can
copy to create other spaces.
This app is also useful when you need to archive a copy of a current space at a particular point in time, like
when you're moving from one version of your product to the next – copy the space, give it a new name, and
keep it wherever you like, all without losing the existing space.
At this point this plugin won't copy page history, blog posts and email.
Scroll PDF Exporter (supported by vendor)
If you're going to produce a PDF of your documentation space, wouldn't you like it to be professionally
formatted? The Scroll PDF Exporter, by K15t, lets you style single pages or whole spaces for export, using
handy PDF templates.
Gliffy (supported by vendor)
Create diagrams, wireframes, flowcharts and more with Gliffy. Gliffy features a highly intuitive drag-and-drop
interface, and allows you to export your diagrams in multiple formats, including: JPEG, PNG and SVG. Add
Gliffy flowcharts, UI wireframes, and network diagrams directly to your Confluence pages to communicate
your ideas visually, making them easy to understand and faster to spread through your team.
Lucidchart (supported by vendor)
Lucidchart is available in versions for Cloud and Server, and allows you to create and insert diagrams within
your Confluence Cloud environment. Quickly draw flowcharts, wireframes, UML diagrams, mind maps, and
more inside our feature-rich editor.
The server version also comes with a free Visio viewer, so you can view Microsoft Visio (.vsd) files, Visio
stencils (.vss) and it also supports exporting back to Visio.
Documentation theme (discontinued)

Confluence historically provided a theme specifically for documentation. This theme was removed in Conflue
nce 6.0.
A number of the original Documentation theme features, such as headers, footers and the ability to add
custom content to the sidebar, are available in Confluence's more modern default theme, which make it a
great choice for your documentation space.
A knowledge base is a repository for how-to and troubleshooting information. Knowledge Bases are
commonly used by IT Support teams, but can be useful for procedural and troubleshooting information in
any organization or team.
Learn more about how a knowledge base helps your team work smarter
What do people want out of a knowledge base? Using an IT Support team as an example:
Customers want fast access to a solution, and relevant search results.

Help desk staff want to be able to create new articles quickly.
Help Desk team leads wants the space to be self curating, and do not want to spend a lot of time
manually organizing content.
Everyone wants a way to be notified when articles they are interested in have been updated or
important notices are added.
Create a knowledge base space

You'll need the Create Space global permission to do this.
To create your knowledge base space:
1. Choose Spaces > Create space > Knowledge base space

2. Choose Space Tools > Permissions to set permissions for the space, including anonymous access
3. Choose Create > How-to or Troubleshooting and follow the prompts to create your first knowledge
base article
The knowledge base space blueprint includes everything you need to get started, including article templates,
and a pre-configured homepage with Livesearch and Content By Label macros.
Page labels are essential in knowledge base spaces. These are used to add topics to your articles, and
allows your knowledge base to become self-organizing over time.
Users will generally find articles by searching, and using the topic navigation on the homepage and end of
each article, rather than navigating through a tree-like page hierarchy.
When starting off your knowledge base space, it's a good idea to brainstorm a few topics to get started.
Customize your knowledge base space
You'll need Space Admin permissions to do this.
To make it easy for your users to create knowledge base articles, such as your help desk or support team,
we recommend customizing the how-to and troubleshooting article templates to make them relevant for your
organization. The more guidance and structure you can put in your template, the faster it will be for your
team to create great articles.
To edit the article templates:
1. Go to Space Admin > Content Tools > Templates.

2. Edit the How-to or Troubleshooting article templates.
3. Add headings and instructional text (choose Template > Instructional Text).
You can also add additional templates, such as a policy or procedure page templates.
We also recommend customizing the look and feel of your space. Simple changes like a space logo and
welcome message can make a huge difference.
To change the look and feel:

Add a space logo and useful shortcuts to the sidebar (choose Space Tools > Configure Sidebar)
Edit the homepage to add a custom welcome message.
Edit the color scheme (choose Space Tools > Look and Feel > Color Scheme).
Provide communication and notification options

Channels of communication with your audience, internal or external, are essential in a good knowledge
base. Here are some out-of-the-box options:
Blog - blog updates and important notices, and encourage people to watch for new blogs in your
space.
Watch - encourage people to watch pages that interest them, or watch the entire space.
Comments - allow logged in users (or even anonymous users) to comment on knowledge base
articles. This is a simple way to connect with your end users.
RSS - create an RSS feed and add the link to your knowledge base homepage (choose Help > Feed
Builder). Alternatively encourage users to create their own feed - useful if they want to keep up with
particular topics (labels), rather than receive notifications for the whole space.
Integrating your knowledge base with other Atlassian products

If your Confluence site is connected to another Atlassian product (via an application link), you can make use
of these great integration features:
If you use any Jira application - add a JIRA Issues macro to your troubleshooting article to provide
quick access to known issues. This has the added advantage of automatically updating when an
issue is resolved or its status changes. One simple way to do this would be to add some labels to Jira
to indicate the issue should appear in the knowledge base (for example 'printer-kb'), and then add a
Jira Issues macro with a query like 'label = 'printer-kb and status <> resolved'' on all articles with the
printer topic.
If you use Jira Service Desk - link a Confluence space to be used as a knowledge base. Users
(including those without a Confluence license) can search your knowledge base directly from within
the Service Desk customer portal. You can connect Jira Service Desk with Confluence 5.10 or later.
If you use Questions for Confluence Server - add a Questions list macro to troubleshooting
articles, to highlight the top questions with the same topic as the article, and an Ask a Question button
to the knowledge base homepage.
Extending your knowledge base with Marketplace apps

The Atlassian Marketplace has a large number of apps for Confluence. A common addition to Knowledge
Base spaces is a survey or form tool, which enables you to get feedback on the usefulness or usability of
your knowledge base articles.
Search for 'knowledge base' on Marketplace and see if there is an app that's right for your knowledge base.
Your intranet is the hub of your organization. When choosing your intranet platform, you need to ensure that
the system is simple enough for non-technical users, information and content can be shared easily, and
access is restricted to those within your organization.
Confluence has a host of great out-of-the-box features that allow you to share and collaborate with your
colleagues, while keeping your information secure. Share things like procedures, specifications and
important files – or organize company events and functions – and get your teams working together. It's one
place to share, find, and collaborate to get work done.
Create your community

It's quick and easy to add users to your Confluence site. Allow people to add themselves as users of the site;
invite people to sign up by sending them an invitation link; add new users manually; or use an existing
directory – like an LDAP directory – for authentication and to manage users and groups.
Whichever way you choose, you can quickly build a community of Confluence users and give them access
to your intranet; you'll also have a ready-made people directory.
Match your company branding

Upload your company logo, and Confluence's auto look and feel will change the color scheme to match. It'll
make your intranet feel more familiar to your colleagues, and help with adoption.
A space for everything, and everything in its space

A Confluence space is essentially a container for a group of pages and blog posts with related content.
When you're starting out with Confluence, the easiest way to organize things is to create a space for each
team or department within your organization. Each team's space is then a place for them to create and share
pages, blog posts, meeting notes, files, and much more – and becomes the place to go for team members to
get the information they need.
Just choose Spaces > Create space from the header, and Confluence provides a list of space blueprints to
help get you started.
Each space can have its own color scheme and has a customizable home page, which you can edit to suit
your purpose – like displaying and tracking team goals and displaying a list of team members. Use the built-
in 'Team Space' template to automatically add all members of the team to the homepage, to help everyone
get to know each other.
You can set permissions for each space, so if there's sensitive information that should only been seen by
certain users or groups, it's easy to secure it with Confluence.
Don't feel restricted to creating spaces for teams though; you can also create spaces for projects (large or
small), events, and anything else where you want to collect information under a common heading or
permissions structure.
Once you have some spaces set up, create some pages and blog posts to give your colleagues an example
of how Confluence can be used, then invite them to create their own pages and blogs.
Add a personal space

Every Confluence user, including you, can also create their own personal space; it can be a place to keep
your own work, add shortcuts to your most used content, and you even get your own blog for sharing your
ideas and opinions with the rest of your organization (or just those that you want to see them).
Create pages, meeting notes and more

You can create pages for anything you want in Confluence - meeting notes, project plans, decisions, and
more. Pages are editable so others can contribute and keep them up to date after you create them. Choose
Create from the Confluence header and choose a blank page, or use a template to get you started.
Type your page, change its layout, add images and links, and do it all without any specialist skills or training.
You can also attach files – allowing everyone in a team access to assets that are critical to the project – like
mockups and requirements. You and your colleagues can like the page, and comment on it to start a
conversation about the content.
Confluence also offers a series of useful built-in page blueprints, which help you with the content and
formatting of the page. The meeting notes and decisions blueprints are two that can be really useful when
others need to be in-the-know about what happened, and why it happened.
Avoid the reply-all and blog about it

Each space you create in Confluence has its own blog, where you and your teams can share news and
events, discuss important projects and developments, or congratulate a teammate for a special effort;
blogging is a great way to foster company culture and celebrate achievements across your organization.
You can watch any blog to make sure you get updated when there's a new post. Blog posts are
automatically organized by date, and grouped by year and month, so they're also easy to find.
Share stuff that matters

If you need to be sure that the right people see a page or blog post, Confluence offers a range of ways to
make sure you can get their attention. Type the @ symbol and the name of a Confluence user to mention the
m in a page, blog post, or comment. They'll get an email notification that you've mentioned them, with a link
to the page, post or comment.
There's also a Share button at the top right of every page. Type the name or email address of a user or
group and send them a short message with a link to the content you're sharing.
Watch and learn

Don't miss out on important updates. Watching spaces, pages, and blogs is a great way to stay up-to-date
with what's happening in your own team, or any other team or person you need to keep up with. When you
watch something, you'll get email updates when changes are made or a comment is added.
The Confluence dashboard also has a recent activity feed, which allows you and your team to see what's
trending throughout the company or in your network.
Let team collaboration take on a life of its own
If you want to communicate in-the-moment, Hipchat – our private service for chat, video, and screen sharing
– is built for teams. Share ideas and files in persistent group chat rooms, or chat 1-1 for that personal touch.
Hipchat integrates with Confluence, so you can get real-time notifications in Hipchat whenever new
information is shared in Confluence pages and blogs.
Got a question (that's not rhetorical)? Why not ask your team? Questions for Confluence is an add–on for
Confluence that gives you knowledge sharing with your own Q&A service. Run company-wide polls to gauge
reaction to a new marketing initiative, or let people vote on the venue for the Christmas party. Ask questions,
get answers, and identify experts.
You can also try Team Calendars for Confluence for organizing and sharing team events, leave, and other
important appointments. Embed each team's calendar on their home page so that everyone knows what's
happening, and when.
Confluence for Software Teams
Welcome to the Software Team's guide to using Confluence.
Check out the articles in this collection:
How to write product How to build a release Creating insightful customer

requirements planning page interview pages
Create sprint retrospective How to make better decisions How to document releases
and demo pages (like a BOSS) as a development team and share release notes
Use blogs to share your development How to create technical and

team's progress onboarding documentation
Like what you see? Start creating these pages and more in
Confluence!
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
Download the Confluence documentation
Delete or Disable Users
in PDF format.
Restore Passwords To Recover
Admin User Rights
Edit User Details Other resources
Change a Username
Managing Site-Wide Permissions and Confluence installation and upgrade guide
Groups
Configuring User Directories Confluence Knowledge Base
Single sign-on for Confluence Data
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 Webhooks
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
Auditing in Confluence
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
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
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
Notifications from Atlassian
Getting Started as Confluence Administrator
If you're just starting out as Confluence
administrator, this page is for you. You'll find this On this page:
page useful if your Confluence site is brand new, or
if you're learning to administer an existing site.
Quick access to admin functions via search
How to administer and configure
Confluence is a Java-based web application. For
Confluence
the supported environments, there's an installer that
Getting started on a new Confluence site
will set up an application server and copy the
Getting to know an existing Confluence site
application files to the designated directories on
your server machine. If you prefer, you can install
Confluence from a zip file. See the Confluence
Installation Guide for details.
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:
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
On this page:
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 Confluence user management
logged-in users. See Setting Up Public Access. Authentication
Seraph
XML-RPC and SOAP authentication
Managing 500+ users across Atlassian
Password authentication
products?
SAML single sign-on
Find out how easy, scalable and effective it
can be with Crowd!
Related pages:
See centralized user management.
Confluence user management

You can add users to Confluence, and then assign
them permissions that determine their access to the
content and administrative functions in your
Confluence site. You can also collect users into
groups, and assign the permissions to groups for
easier management. See the following topics:

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.
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 Single sign-on for Confluence Data Center for more information.
There are a number of ways to add users to Confluence:
On this page:
By user signup: If user signup is enabled on your Confluence site,
people can add themselves as users of the site. Allow user signup
Via an invitation link: You can invite people to sign up by sending Manage user
them an invitation link. You can copy and paste the link, or prompt signup notifications
Confluence to send the link in an email message. Invite people to
By adding users manually: If you have Administrator or System sign up
Administrator permission, you can manually add new users. Reset the invitation
Via an external user directory: See Configuring User Directories. link
Add users manually
You may also be interested in information about allowing anonymous users Notes
access to your site. Anonymous users don't count against your Confluence
license totals. Related pages:
Manage Users
Allow user signup Setting Up Public
Access
If you enable user signup, a 'Sign Up' option will appear on the Confluence Configuring a
screens. The option will be on the login screen, and also in the header on Server for
public sites. People can choose the option to create their own usernames Outgoing Mail
on Confluence.
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 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:

2. Select the User Signup Options tab
3. Remove the tick from Notify administrators by email when an account is created
4.
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:

2. Select the Invite Users tab
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
Add users manually

To add a new user:

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
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 GATHERING IMPACT and CONFSERVER-13479 GATHERING IMPACT
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
external directories, or delete it entirely.
Delete, disable, or
unsync?
Disable a user
account
Unsync a user
account
Delete a user
account
Delete from
an internal
Confluence
directory or
read/write
external
directory
Delete from
a read-only
external
directory, or
multiple
external
directories
How deleted
users
appear to
other people
Only remove
access to
Confluence
Limitations when
deleting a user
account
Free text is
not
anonymised
Data stored
in
Synchrony
is not
deleted
immediately
Personal
spaces are
not deleted
Workbox
notifications
don't
disappear
immediately
Data stored
by third-
party apps
is not
deleted
Related pages:
Manage Users
Configuring User
Directories
Managing 500+ users across Atlassian products?

Find out how easy, scalable and effective it can be with Crowd!
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:

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.
When a user account is deleted:

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.
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.
To disable a user account:
1.
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.
It's important to note that the person's content is not removed when you delete their account. Find
out about limitations and what personal information may need to be removed manually.
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
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.
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 immediately
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.
From Confluence 7.0 we provide two scheduled jobs for removing Synchrony data:
Synchrony data eviction (soft)

Synchrony data eviction (hard)
The soft eviction job runs regularly in the background. The hard eviction job is available for when you need
to remove Synchrony data more aggressively, for example after you have deleted a user, and is disabled by
default.
See How to remove Synchrony data to learn more about how these jobs work.
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.
If space permissions prevent you from accessing the user's personal space, a member of the confluence-
administrators super group will be able to access the space. They can then grant another user permission to
administer the space, or delete it themselves.
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.
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 mode to recover your admin user rights.
Use recovery
If you know the admin username, and it has a valid email address, you can mode to restore
reset the password using the forgot password link on the log in screen. access
We'll 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
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
Related pages:
2. Do either of the following: Delete or Disable
Users
Choose Show all users to list everyone in the 'confluence- Adding or
users' or 'users' group Removing Users in
Enter a username, full name or email address in the Find User Groups
field and hit Search Add and Invite
Users
If you're already viewing someone's profile, choose Ad
minister User in the sidebar.
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.
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.
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.
Confluence-
Each active users must have a unique username, so no two active users managed users
can have the same username. You can, however, assign the username of a Users managed in
disabled user to another active user. an external
directory
The procedure for changing a username depends on where you manage Notes
your users. See Configuring User Directories for more info.
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:

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
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 Related pages:
permissions at site level and at space level, as well
as page-level restrictions. Confluence Security Overview and
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.

products?
can be with Crowd!
Confluence Groups for Administrators
Grouping users in Confluence is a great way to cut down the work required
On this page:
when managing permissions and restrictions.
Groups can be used when setting: Default groups

Create a new group
global permissions Delete a group
space permissions Confluence-
page restrictions. administrators
super group
If your site has a lot of users, using groups can really simplify your About multiple user
permissions management over time. directories
Related pages:
Manage Users
Global Permissions
Overview
Default groups
The two default groups in Confluence are:
confluence-users - this is the default group into which all new users are usually assigned. In most
sites this is the group that provides the permission to log in to Confluence.
confluence-administrators – this super group grants the highest level of administrator
permissions. Members of this can view all pages, including restricted pages. While they can't edit
existing pages, they can add, delete, comment, restore page history, and administer the space. They
can also access the admin console and perform all administrative tasks.
Create a new group

To add a new group:
1. Go to > General Configuration > Groups.

2. Choose Add Group.
3. Enter a name for your group and choose Save. Group names must be lower case.
You're now ready to start adding users to the group.
Delete a group
To delete a group:

2. Choose Delete next to the group you want to remove.
Deleting a group removes all permission restrictions associated with it. This means that members of this
group may loose access to spaces that use this group to grant their permissions, and pages / blogs that are
only only restricted to this group will become available to all confluence users.
If you have Confluence Data Center, you can Inspect permissions to find out which spaces are using this
group, before you delete it.
Confluence-administrators super group

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're not. Granting a user or a
group Confluence administrator global permission allows access to a sub-set of administrative functions.
Granting membership to the confluence-administrators group grants the highest possible
permissions, with complete access to all content and administration functions.
To find out more about what the various levels of administrator can do, see Global Permissions Overview.
About 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.
Adding or Removing Users in Groups
Confluence Groups are a great way to cut down the
On this page:
work required when managing permissions and
restrictions.
Add people to a group
You can edit group membership in two places: Remove people from a group
About multiple directories
From the group management screen
From the user management screen for a Related pages:
particular user
Manage Users
You need Confluence Administrator or System Confluence Groups
Administrator global permission to do this. Global Permissions Overview
Add people to a group

To add members to a group from the Groups screen:

2. Choose the group.
3. Choose Add Members.
4. Type the username of the person you want to add to the group. You can add multiple usernames,
separated by a comma.
5. Choose Add to add members to the group.
Screenshot: Adding members
You can also change a user's group membership in the user management screen. Navigate to the user, then
choose Edit groups, and select the groups the person should be a member of.
Remove people from a group

To remove members from a group:

2. Choose the group.
3. Choose the Delete user from group icon next to the user you want to remove.
You can also change a user's group membership in the user management screen. Navigate to the user, then
choose Edit groups, and deselect the groups.
About 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.

Global Permissions determine what a user can do
On this page:
at a site level, including whether they can log in,
create spaces, or administer the site.
Overview of global permissions
Unsure about the best way to set Grant global permissions
permissions in your site? Check out our Per Revoke global permissions
missions best practices guide. System Administrator and Confluence
Administrator permissions compared
Troubleshooting
Overview of global permissions

The following global permissions can be granted to groups and individuals.
Global Description
Permission
Can Use This is the most basic permission that allows users to log in to this Confluence site. Users
with this permission contribute to your licensed users count.
Personal Allows the user to create a personal space. The space key will be their username.
Space
Create Allows the user to create new spaces in your site. When a user creates a space they are
Space(s) automatically granted admin permissions for that space.
Confluence Allows the user to access the Confluence administration console, and perform basic
Administrator administrative tasks such as adding users, changing group memberships, and changing
the colour scheme of the site.
See the detailed comparison of administrator permissions below.
System Allows the user to access the Confluence administration console and perform all
Administrator administrative tasks.
See the detailed comparison of administrator permissions below.
Grant global permissions

To grant global permissions to a user or group:
1. Go to > General Configuration > Global Permissions

3. Do one of the following:
a. Enter a group name in the Grant browse permissions field in the Group section
b. Enter a username in the Grant browse permissions field in the Individual Users section
4. Choose Add.
5. The user or group will appear in the list. Select the permissions you want to grant.
6. Choose Save all.
Screenshot: Editing global permissions

Revoke global permissions

To revoke the global permissions for a user or group:
1. Go to > General Configuration > Global Permissions

3. Locate the user or group you want to edit, and deselect all checkboxes.
4. Choose Save all.
If you are attempting to revoke permissions for an individual user, and they are not listed, you will need to
check which groups they are a member of, and remove them from any groups that grant the global
permission.
System Administrator and Confluence Administrator permissions compared

The table below lists the parts of the admin console that can be accessed by people with the Confluence
Administrator and System Administrator global permissions.
Members of the confluence-administrators super group have System Administrator global

permissions by default, as well as the ability to view all spaces and pages.
Admin Confluence administrator System administrator

console
Configuration
General Configuration, except: General Configuration
Base URL Further configuration
Connection timeout Backup Administration
Further configuration, except: Languages
Remote API Shortcut Links
Languages External Gadgets
Shortcut Links Global Templates and Blueprints
Global Templates and Blueprints Recommended Updates Email
Recommended Updates Email Mail Servers
Configure Code Macro, except User Macros
add new languages In-app Notifications
WebDAV Configuration Spam Prevention
PDF Export Language Support
Configure Code Macro
Office Connector
WebDAV Configuration
Marketplace
Find new apps Find new apps
Manage apps, Manage apps
except:
Upload an app.
Users &
security Users Users
Groups Groups
SSO 2.0 SSO 2.0
Security Configuration, except: Security Configuration
External user management Global Permissions
Append wildcards to user and group Space Permissions
searches Inspect Permissions (Data Center)
Enable Custom Stylesheets for Spaces User Directories
Show system information on the 500 Whitelist
page
RSS settings
XSRF Protection
Attachment download security
Global Permissions
Space Permissions
Inspect Permissions (Data Center)
Look and feel

Themes Themes
Color Scheme Color Scheme
Site Logo and Favicon Layouts
PDF Layout Stylesheet
PDF Stylesheet Site Logo and Favicon
Sidebar, header and footer PDF Layout
Default Space Logo PDF Stylesheet
Sidebar, header and footer
Default Space Logo
Custom HTML
Upgrade
Latest upgrade report Latest upgrade report
Plan your upgrade
Administration
Macro Usage Mobile apps
Audit Log Collaborative Editing
Content Indexing Maintenance (Data Center)
License Details System Information
Application Links (OAuth only) Macro Usage
Application Navigator Audit Log
Rate limiting (Data Center)
Backup & Restore
Content Delivery Network (Data
Center)
Content Indexing
Mail Queue
Scheduled Jobs
Cache Management
License Details
Logging and Profiling
Application Links
Application Navigator
Analytics
Troubleshooting and support tools
Clustering (Data Center)
Atlassian
Cloud Migration assistant Migration assistant

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're not. Granting a user or a
group Confluence administrator global permission allows access to a sub-set of administrative functions.
Granting membership to the confluence-administrators group grants the highest possible
permissions, with complete access to all content and administration functions.
When you install Confluence you'll be prompted to create a system administrator account. This user will be a
member of the confluence-administrators super group.
What can members of this group do?
This group provides the highest level of permission in your site, and these permissions can't be
edited. People in this group can:
perform all administrative tasks

access all spaces
access all pages, including pages with view 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 are visible if the user has the page URL, or in the:
page tree in the sidebar

pages index page
reorder pages screen
page tree macro
content by user macro
Members of this group can't edit pages by default. They need to grant themselves space permissions, or add
themselves to the page restrictions in order to edit.
Should I use the confluence-administrators group?
Some organisations use the confluence-administrators group extensively, while others choose to
limit its membership to just one special admin account, to limit the number of people who can see all content
by default. System administrators can perform all the same administrative tasks, so membership of this
group is not a requirement.
If you do decide not to use this group, be aware that the group can't be deleted, and that people with System
Administrator global permissions can add themselves to this group.
Troubleshooting
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.
If you're unable to log in to Confluence as an administrator (for example, you've lost the administrator
password) you can start Confluence in recovery mode to recover your admin user rights. See Restore
Passwords To Recover Admin User Rights.
Setting Up Public Access
If you use Confluence for documentation, as a
On this page:
knowledge base, you might want to make your site
public. This means people don't need to log in to
use Confluence. Allow anonymous access to the site
Disable anonymous access to the site
Allow anonymous access to a space
Alternatives to making your site public
Related pages:
Configuring Captcha for Spam Prevention

Allow anonymous access to the site

If you want to make your site visible to anyone, including people who have not logged in, you must enable
anonymous access at site level.
To enable anonymous access to your site:
1. Go to > General Configuration > Global permissions.

3. In the Anonymous Access section, select the Can use checkbox. You can also choose whether to
allow anonymous users to see user profiles.
4. Choose Save All.
Disable 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.
Any spaces that granted permissions to anonymous users will still be available to all logged in users, until
you remove these permissions from each space.
Allow anonymous access to a space

Allowing anonymous access to your site does not automatically allow people who are not logged in to see all
the spaces in your site.
Space administrators must grant anonymous users permissions on a space by space basis. See Make a
Space Public to find out how to do this.
Alternatives to making your site public

You can allow people to sign up for usernames themselves, and choose other options for user signup and
invitations. See Add and Invite Users.
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.
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.
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,
username, password, email address and other Configuring User Directories in Confluence
personal information. Group information includes Connecting to a Directory
the name of the group, the users that belong to the Updating Directories
group, and possibly groups that belong to other
groups. Related pages:
The internal directory stores user and group Add and Invite Users
information in the Confluence database. You can Managing Site-Wide Permissions and
also connect to external user directories, and to Groups
Atlassian Crowd and Jira applications as directory
managers.

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.
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
The internal directory stores user and group
On this page:
information in the Confluence database.
Overview Overview
Diagram of Possible Configuration
The internal directory is enabled by default at
installation. When you create the first administrator Related pages:
during the setup procedure, that administrator's
username and other details are stored in the
How to Reenable the Internal Directory (Kn
internal directory.
owledge base article)
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
On this page:
LDAP directory for authentication, user and group
management.
Overview
Connecting to an LDAP Directory in
Confluence
products?
Server Settings
Schema Settings
can be with Crowd!
Permission Settings
Adding Users to Groups
Automatically
Advanced Settings
Overview User Schema Settings
Group Schema Settings
An LDAP directory is a collection of data about Membership Schema Settings
users and groups. LDAP (Lightweight Directory Diagrams of Some Possible Configurations
Access Protocol) is an Internet protocol that web
applications can use to look up information about Related pages:
those users and groups from the LDAP server.
We provide built-in connectors for the most popular
LDAP directory servers:
Microsoft Active Directory

Apache Directory Server (ApacheDS)
Apple Open Directory
Fedora Directory Server
Novell eDirectory
OpenDS
OpenLDAP
OpenLDAP Using Posix Schema
Posix Schema for LDAP
Sun Directory Server Enterprise Edition
(DSEE)
A generic LDAP directory server
When to use this option: Connecting to an LDAP

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:

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:
6.
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
Director Select the type of LDAP directory that you will connect to. If you are adding a new LDAP
y Type connection, the value you select here will determine the default values for many of the options
on the rest of screen. Examples:

OpenDS
And more.
Hostna The host name of your directory server. Examples:

me
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 Check this if the connection to the directory server is an SSL (Secure Sockets Layer)
SSL connection. Note that you will need to configure an SSL certificate in order to use this setting.
Userna The distinguished name of the user that the application will use when connecting to the
me 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
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.
Addition This value is used in addition to the base DN when searching and loading users. If no value is
al User supplied, the subtree search will start from the base DN. Example:
DN
ou=Users
Addition This value is used in addition to the base DN when searching and loading groups. If no value is
al supplied, the subtree search will start from the base DN. Example:
Group
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 LDAP users, groups and memberships are retrieved from your directory server and can only
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
Only, be modified via your directory server. You cannot modify LDAP users, groups or memberships
with via the application administration screens. However, you can add groups to the internal
Local directory and add LDAP users to those groups.
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 LDAP users, groups and memberships are retrieved from your directory server. When you
/Write 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
Default Option available in Confluence 3.5 and later, and JIRA 4.3.3 and later. This field appears if you
Group select the 'Read Only, with Local Groups' permission. If you would like users to be
Member automatically added to a group or groups, enter the group name(s) here. To specify more than
ships 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 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.
Manage If true, you can activate and deactivate users in Crowd independent of their status in the
User directory server.
Status
Locally
Filter If true, user accounts marked as expired in ActiveDirectory will be automatically removed. For
out cached directories, the removal of a user will occur during the first synchronization after the
expired account's expiration date.
users
Note: This is available in Embedded Crowd 2.0.0 and above, but not available in the 2.0.0 m04
release.
Use Enable or disable the use of the LDAP control extension for simple paging of search results. If
Paged paging is enabled, the search will retrieve sets of data rather than all of the search results at
Results 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 option
Referrals 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.
Naive If your directory server will always return a consistent string representation of a DN, you can
DN enable naive DN matching. Using naive DN matching will result in a significant performance
Matching 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 synchronization to
Increme be queried when synchronizing a directory.
ntal
Synchro Please be aware that when using this option, the user account configured for
nization 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".
Synchro Synchronization is the process by which the application updates its internal store of user data
nization to agree with the data on the directory server. The application will send a request to your
Interval directory server every x minutes, where 'x' is the number specified here. The default value is
(minutes) 60 minutes.
Read The time, in seconds, to wait for a response to be received. If there is no response within the
Timeout specified time period, the read attempt will be aborted. A value of 0 (zero) means there is no
(second limit. The default value is 120 seconds.
s)
Search The time, in seconds, to wait for a response from a search operation. A value of 0 (zero)
Timeout means there is no limit. The default value is 60 seconds.
(second
s)
Connect This setting affects two actions. The default value is 0.

ion
Timeout The time to wait when getting a connection from the connection pool. A value of 0 (zero)
(second means there is no limit, so wait indefinitely.
s) 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.
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 directory
Attribute tree structure. Example:
cn
User The attribute field to use when loading the user's first name. Example:
First
Name givenName
Attribute
User The attribute field to use when loading the user's last name. Example:
Last
Name sn
Attribute
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:
Passwor
d unicodePwd
Attribute
User The attribute used as a unique immutable identifier for user objects. This is used to track
Unique username changes and is optional. If this attribute is not set (or is set to an invalid value), user
ID renames will not be detected — they will be interpreted as a user deletion then a new user
Attribute 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.
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=*))
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
Diagrams of Some Possible Configurations
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
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 Configuring User Directories
to the pool for future use. This can improve
performance significantly.
To configure your LDAP connection pool:

3. Click 'LDAP Connection Pool Configuration' in the 'Additional Configuration' section.
Setting Description Default

Value
Initial The number of LDAP connections created when initially connecting to the pool. 1
Pool
Size
Preferred The optimal pool size. LDAP will remove idle connections when the number of 10
Pool connections grows larger than this value. A value of 0 (zero) means that there is
Size no preferred size, so the number of idle connections is unlimited.
Maximu The maximum number of connections. When the number of connections reaches 0
m Pool this value, LDAP will refuse further connections. As a result, requests made by an
Size application to the LDAP directory server will be blocked. A value of 0 (zero) means
that the number of connections is unlimited.
Pool The length of time, in seconds, that a connection may remain idle before being 30
Timeout removed from the pool. When the application is finished with a pooled connection,
(seconds 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 Only these protocol types will be allowed to connect to the LDAP directory server. plain
Protocol If you want to allow multiple protocols, enter the values separated by a space. ssl
Valid values are: (Both
plain
plain and ssl)
ssl
Pool Only these authentication types will be allowed to connect to the LDAP directory simple
Authentic server. If you want to allow multiple authentication types, enter the values
ation 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
On this page:
Microsoft Active Directory, you will need to install an
SSL certificate, generated by your Active Directory
server, onto your Confluence server and then install Prerequisites
the certificate into your JVM keystore. 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
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.
4. On the Select Server Roles page, select the Active Directory Certificate Services check box. Click
Next twice.
5.
5. On the Select Role Services page, select the Certification Authority check box, and then click Next
.
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.
8.
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. 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.
11. After verifying the information on the Confirm Installation Selections page, click Install.
12. Review the information on the results screen to verify that the installation was successful.
Step 2. Obtain the Server Certificate

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.
atlassian.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:
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
5. Restart the application to take up the cacerts changes.

6.
6. You may now change 'URL' to use LDAP over SSL (i.e. ldaps://<HOSTNAME>:636/) and use the 'Sec
ure 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
directory server:
sudo keytool -importcert -keystore ./jre/lib/security/cacerts -file server-certificate.crt
Password:
MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE

Mac OS X
1. Navigate to the directory in which Java is installed. This is usually
cd /Library/Java/Home
directory server:
sudo keytool -importcert -keystore ./jre/lib/security/cacerts -file server-certificate.crt
Password:
MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE

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
directory that uses LDAP for authentication only. Overview
There is an option to create users in the internal Connecting Confluence to an Internal
directory automatically when they attempt to log in, Directory with LDAP Authentication
as described in the settings section. Server Settings
Copying Users on Login
Overview Schema Settings
Advanced Settings
An internal directory with LDAP authentication offers User Schema Settings
the features of an internal directory while allowing Group Schema Settings
you to store and check users' passwords in LDAP Membership Schema Settings
only. Note that the 'internal directory with LDAP Diagrams of Possible Configurations
authentication' is separate from the default 'internal
Related pages:
directory'. On LDAP, all that the application does is
to check the password. The LDAP connection is
read only. Every user in the internal directory with
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
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:

3. Add a directory and select type 'Internal with LDAP Authentication'.
4. Enter the values for the settings, as described below.
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:
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
Director Select the type of LDAP directory that you will connect to. If you are adding a new LDAP
y Type connection, the value you select here will determine the default values for some of the options
on the rest of screen. Examples:

OpenDS
And more.
Hostna The host name of your directory server. Examples:

me
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 Check this box if the connection to the directory server is an SSL (Secure Sockets Layer)
SSL connection. Note that you will need to configure an SSL certificate in order to use this setting.
Userna The distinguished name of the user that the application will use when connecting to the
me 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 This option affects what will happen when a user attempts to log in. If this box is checked, the
User on user will be created automatically in the internal directory that is using LDAP for authentication
Login 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 Whenever your users authenticate to the application, their attributes will be automatically
User updated from the LDAP server into the application. After you select this option, you won't be
attribute able to modify or delete your users directly in the application.
s on
Login 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 be
Group automatically added to a group or groups, enter the group name(s) here. To specify more than
Member one group, separate the group names with commas. Each time a user logs in, their group
ships 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
Synchro This field appears if you select the Copy User on Login checkbox. If this box is checked,
nize group memberships specified on your LDAP server will be synchronized with the internal
Group directory each time the user logs in.
Member
ships 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)
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. If
Paged paging is enabled, the search will retrieve sets of data rather than all of the search results at
Results 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 option
Referrals 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
Additiona This value is used in addition to the base DN when searching and loading users. If no value is
l User supplied, the subtree search will start from the base DN. Example:
DN
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=*))
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 directory
Attribute tree structure. Example:
cn
User The attribute field to use when loading the user's first name. Example:
First
Name givenName
Attribute
User The attribute field to use when loading the user's last name. Example:
Last
Name sn
Attribute
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

Note: this section is only visible when both Copy User on Login and Synchronize Group Memberships
are 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
are enabled.
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 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
Diagrams of Possible Configurations
Diagram above: Confluence connecting to an LDAP directory for authentication only.
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
for authentication. Connecting Confluence to Crowd for User
Management
Connecting Confluence to Crowd for User Connecting Confluence to Jira applications
for User Management
Management
Troubleshooting
Atlassian Crowd is an application security
framework that handles authentication and
Related pages:
authorization for your web-based applications. With
Crowd you can integrate multiple web applications Configuring User Directories
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.

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.
4. Add a directory and select type 'Atlassian Crowd'. Enter the settings as described below.
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:
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
Applicati The name of your application, as recognized by your Crowd server. Note that you will need to
on define the application in Crowd too, using the Crowd administration Console. See the Crowd
Name documentation on adding an application.
Applicati The password which the application will use when it authenticates against the Crowd
on framework as a client. This must be the same as the password you have registered in Crowd
Password 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
Read The users, groups and memberships in this directory are retrieved from Crowd and can only
Only be modified via Crowd. You cannot modify Crowd users, groups or memberships via the
application administration screens.
Read The users, groups and memberships in this directory are retrieved from Crowd. When you
/Write 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 Enable or disable support for nested groups. Before enabling nested groups, please check to
Nested see if the user directory or directories in Crowd support nested groups. When nested groups
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 synchronization
Increme will be retrieved when synchronizing a directory. Note that full synchronization is always
ntal executed when restarting Fisheye.
Synchro
nization
Synchro Synchronization is the process by which the application updates its internal store of user data
nization to agree with the data on the directory server. The application will send a request to your
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:
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:
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
Applicati The name used by your application when accessing the Jira server that acts as user manager.
on Note that you will also need to define your application to that Jira server, via the 'Other
Name Applications' option in the 'Users, Groups & Roles' section of the 'Administration' menu.
Applicati The password used by your application when accessing the Jira server that acts as user
on manager.
Password
Jira Permissions
Setting Description
Read The users, groups and memberships in this directory are retrieved from the Jira server that is
Only acting as user manager. They can only be modified via that JIRA server.
Advanced Jira Settings
Setting Description
Enable Enable or disable support for nested groups. Before enabling nested groups, please check to
Nested see if nested groups are enabled on the JIRA server that is acting as user manager. When
Groups 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.
Synchron Synchronization is the process by which the application updates its internal store of user data
ization to agree with the data on the directory server. The application will send a request to your
Diagram above: Confluence, JIRA and other applications connecting to Crowd for user management.
Diagram above: Confluence connecting to JIRA for user management.
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.
Error Message Cause
error.jirabaseurl. Connection refused. Check if an This may be because:

connection. instance of Jira is running on the
refused given url Jira url is incorrect
Jira instance is not running on the specified
url.
Jira instance running on the specified url is
not 4.3 or later.
error. Failed to establish application link Unable to create an application link between
applicationlink. between Jira server and Jira and Confluence. This may be because:
connection. Confluence server.
refused 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. This is not a valid url for a Jira A runtime exception has occured. Refer to the
not.valid application. 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 to internal user management as described
below. If your Confluence instance has only a few Option 1 – Manually Recreate Users and
users, it is easier to recreate the users and groups Groups in Confluence
in Confluence manually. If you have a large number Option 2 – Transfer Crowd/Jira application
of users and groups, it is more efficient to migrate Users and Groups to the Confluence
the relevant users and groups into the Confluence Database
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-
users 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. 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:
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
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. 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.
For example, you may have an internal directory
and you may also connect to an LDAP directory Overview
server and/or other types of user directories. When Configuring the Directory Order
you connect to a new directory server, you also Effect of Directory Order
need to define the directory order. Login
Permissions
Avoid duplicate usernames across directories. If Updating Users and groups
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.

products?
can be with Crowd!
Overview
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 permissions to view spaces and pages (if they are a member a group in a user directory that was
previously being ignored by Confluence).
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:
The REST resource supported JSON and XML. You'll need to be a system administrator and logged in to
do this.
# 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:
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:
The application has permission to update both directories.
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
On this page:
as a member of another group. Groups in such a
structure are called nested groups. Nested groups
simplify permissions by allowing sub-groups to Enabling Nested Groups
inherit permissions from a parent group. Effect of Nested Groups
Login
This page describes how Confluence handles Permissions
nested groups that exist in one or more of your Viewing lists of group members
directory servers. Adding and updating group
membership
Enabling Nested Groups Examples
Example 1: User is member of sub-
You can enable or disable support for nested group
groups on each directory individually. Go to the 'Use Example 2: Sub-groups as
r Directories' section of the Confluence members of the jira-developers
Administration Console, edit the directory and group
select 'Enable Nested Groups'. See Configuring Notes
User Directories.
Related pages:
Notes: Configuring User Directories
Before enabling nested groups for a specific
directory type in Confluence, please make
sure that your directory server supports
nested groups.
Please read the rest of this page to
understand what effect nested groups will
have on authentication (login) and
permissions in Confluence, and what
happens when you update users and groups
in Confluence.
You can't edit the directory you are currently
logged in via. This means that in most cases
you need to log in with an administrator
account stored in the internal directory.
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
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
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
On this page:
cache of directory information (users and groups) in
the application database, to ensure fast recurrent
access to user and group data. A synchronization Affected Directory Types
task runs periodically to update the internal cache How it Works
with changes from the external directory. Finding the Time Taken to Synchronize
Manually Synchronizing the Cache
Configuring the Synchronization Interval
Unsynced users
Related pages:
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.
ad only, with local groups.
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.
Note for Confluence Data Center: The sync will take place on a single node of the cluster to
update the database. This may make it seem like automatic synchronization will not be
happening, but the task is assigned to one of the nodes.
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

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 Conflu
ence 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
On this page:
understand each directory type at a glance. We
have kept the diagrams simple and conceptual, with
just enough information to be correct. Confluence Internal Directory
Confluence with Read/Write Connection to
Some things that we do not attempt to show: LDAP
Confluence with Read-Only Connection to
In most cases, we do not attempt to show LDAP, with Local Groups
that you can have multiple directory types Confluence Internal Directory with LDAP
mapped to Confluence at the same time. We Authentication
illustrate that fact in just the first two LDAP Confluence with LDAP Authentication,
diagrams. Copy Users on First Login
We have not included a diagram for Confluence Connecting to Jira
Confluence's legacy connection to Jira Confluence Connecting to Jira and Jira
database. Connecting to LDAP
We do not attempt to show all of the possible Confluence and Jira Connecting to Crowd
configurations and layered connections that
are available now that you can use Jira as a Related pages:
directory manager.
Confluence Internal Directory
Diagram above: Confluence using its internal directory for user management.
Confluence with Read/Write Connection to LDAP

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
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.
Confluence Connecting to Jira
Diagram above: Confluence connecting to JIRA for user management.
Confluence Connecting to Jira and Jira Connecting to LDAP
Diagram above: Confluence connecting to JIRA for user management, with JIRA in turn connecting to LDAP.
Confluence and Jira Connecting to Crowd
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
On this page:
limitations that apply to user management in
Confluence.
General Recommendations
General Recommendations Recommendations for Connecting to LDAP
Optimal Number of Users and
Avoid duplicate usernames across directories. If Groups in your LDAP Directory
you are connecting to more than one user directory, Redundant LDAP is Not Supported
we recommend that you ensure the usernames are Specific Notes for Connecting to
unique to one directory. For example, we do not Active Directory
recommend that you have a user jsmith in both Recommendations for Connecting to Jira
'Directory1' and 'Directory2'. The reason is the for User Management
potential for confusion, especially if you swap the Single Sign-On Across Multiple
order of the directories. Changing the directory Applications is Not Supported
order can change the user that a given username Custom Application Connectors are
refers to. Not Supported
Custom Directories are Not
Be careful when deleting users in remote Supported
directories. Load on your JIRA instance
JIRA Cloud applications not
If you are connecting to an LDAP directory, a Crowd supported
directory or a Jira directory, please take care when Recommendations
deleting users from the remote directory. If you
delete a user that is associated with data in Related pages:
Confluence, this will cause problems in Confluence. Connecting to an LDAP Directory
Connecting to Crowd or Jira for User
If a user who has created content is deleted from an Management
external directory, and an account is then re-created
with the same username, it will automatically be re- Configuring User Directories
associated with that content. This is intentional, so
that if a directory sync problem occurs, users are
correctly re-associated with their content.
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 GATHERING IMPACT an
d CONFSERVER-13479 GATHERING IMPACT f

or 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:

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.
Your environment Recommendation
Up to 10 000 (ten thousand) Choose the 'LDAP' or 'Microsoft Active Directory' directory type. You
users, 1000 (one thousand) 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 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.
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 for
directory connector to define your own storage 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
user management includes connections to Active Troubleshooting the Connection to your
Directory, other LDAP servers, Atlassian Crowd or a External User Directory
Jira application for user management. The Problems During Initial Setup
information on this page is provided in addition to Complex Authentication or Performance
the more general page on Troubleshooting Problems
Problems and Requesting Technical Support.
Related pages:
The cause of such problems may be:
Troubleshooting Problems and Requesting
The LDAP server is not responding. Technical Support
The application password is incorrectly Configuring User Directories
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:

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.
properties.
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:
###
# 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.
Single sign-on for Confluence Data Center
We provide the functionality for Confluence Data
On this page:
Center to connect to your preferred identity provider
(IdP) so that you can provide your users with a
single sign-on (SSO) experience.
This only handles authentication. Application access

and any required authorizations, such as ensuring
that users belong to the appropriate groups/roles
and have the necessary permissions, should be
configured in the user directory and/or the
application itself.
The way you configure SSO depends on the protocol your IdP uses:
For SAML based identity providers, see SAML single sign-on for Atlassian Data Center applications
For OpenID based identity providers, see OpenID Connect for Atlassian Data Center applications
For Atlassian Crowd, see Crowd SSO 2.0
Looking for a cross-domain SSO solution?
Atlassian Crowd 3.4, with its Crowd SSO 2.0 feature, offers one solution for Server, Data Center, and
Cloud applications and setting it up takes only minutes.
Are you are ready for the change? See Crowd SSO 2.0
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.
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
more. Create a User Macro
Edit a user macro
User macros are created and managed within Delete a user macro
Confluence itself, you do not need to develop an Best practices
app (plugin). You will need some coding skills Example user macros
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 Description
details
field
Macro This is the name of the macro, as it appears in the code.

name
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 This is the title that will appear in the macro browser and auto-complete.
Title
Descrip This is the description that will appear in the macro browser. The macro browser's search will
tion pick up matches in both the title and description.
Categor Select one or more macro browser categories for your macro to appear in.
ies
Icon Enter an absolute URL (for example http://mysite.com/mypath/status.png) or path

URL relative to the Confluence base URL (for example /images/icons/macrobrowser
/status.png) if you want the macro browser to display an icon for your macro.
Docum If you have documentation for your macro, enter the URL here.
entation
URL
Macro Specify how Confluence should process the body before passing it to your macro.
Body
Process The macro body is the content that is displayed on a Confluence page. If your macro has a
ing 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 '$bo
dy'.
Each parameter variable you use must have a matching metadata definition. Use @param t
o 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 @param 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 User
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:

2. Click Edit next to the relevant macro
3. Update the macro details
4. Click Save
Delete a user macro

To delete a user macro:

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.
#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

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
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:
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
Macro Title No Print
Description Hides text from printed output.
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.
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 stylish
name
Macro Stylish
Title
Descripti Applies colour and size to text.

on
Documen You can leave this field blank

tation
URL
Macro Rendered
body
processi
ng
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>
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
Macro Title Formatted Panel
Description Creates a panel preformatted with specific colors
Categories Formatting
Documentation You can leave this field blank

URL
Macro body Escaped

processing
Template Enter the code below in the template field. See below for a more detailed
explanation of the code below.
## @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: @param defines the metadata for your macro parameters.
title=Title|type=st
ring|desc=Title @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.
<ac:structured- This calls the Confluence Panel macro.

macro ac:name="
panel"> 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: Sets the parameters for the macro: the background color, border style,
name="titleBGColor" border color, border width and title color.
>#ccc</ac:
parameter> To discover the names of the parameters for a Confluence macro, view
<ac:parameter ac: the storage format as described above.
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: Enters the value stored in the 'Title' parameter into the title section of the
name="title">$! macro.
paramTitle</ac:
parameter> The ! tells the macro to leave the title blank, when there is no data in the
"Title" parameter.
<ac:rich-text- Users can enter data that is stored in the body of the macro. This line
body>$body</ac: enables the macro to access and store the body content passed to your
rich-text-body> macro.
</ac:structured- This command marks the end of the macro.

macro>
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.
This page provides information about the code you Accessing your macro's body
can enter in a user macro template. Using parameters in your user macro
Objects available to your macro
Accessing your macro's body Controlling parameter appearance in the
editor placeholder
Use the $body object within your user macro
template to access the content passed to your Related pages:
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
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.
type
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 this 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- Offers a control allowing the user to search for a page or blog post. Example:
content
## @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
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, $parambar, Named parameters ("foo", "bar") passed to your macro. String
... $param<name>
$config The BootstrapManager object, useful for retrieving BootstrapM

Confluence properties. anager
$renderContext The PageContext object, useful for (among other things) PageConte
checking $renderContext.outputType xt
$space The Space object that this content object (page, blog post, Space
etc) is located in (if relevant).
$content The current ContentEntity object that this macro is a ContentEnti

included in (if available). tyObject
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.
getDescendants() 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.
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
parameter.
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-showValueInPlaceholder=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).
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.
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
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 Space
can further customize the appearance of a 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
quickly jump to their favorite spaces and pages. Editing the site welcome message
Using a page as the site landing page
Editing the site welcome message Advanced customizations
The site welcome message appears on the right Related pages:

hand side of the dashboard and is the perfect place
Save for later
to inject some of your organization's personality.
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.
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.
You can change: Changing the site logo

Changing the site icon (favicon)
the site logo Changing the default space logo
the default space logo for all spaces Changing a specific space logo
the space logo for individual spaces.
Related pages:
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:

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
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
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
spaces within it.
Reset your color
To change the site's color scheme: scheme after
uploading a site
1. Choose the cog icon , then choose General Configuration logo
2. Choose Color Scheme in the left-hand panel
3. Click Edit Related pages:
4. Enter standard HTML/CSS2 color codes, or use the color-picker Changing the Look
to choose a new color from the palette provided. and Feel of
5. Hit Save Confluence
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:

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.
Introduction
Introduction Considerations for
Using Custom CSS
Cascading Style Sheets (CSS) are an industry-standard way of styling a Getting Started
web page. The content of a page is rendered with HTML, and its look and CSS Resources
feel is determined by CSS files. You can upload a CSS text file, or simply
type in a stylesheet, and apply it to a space or even a whole Confluence Related pages:
site.
Basic Styling
Note: By default, only system administrators can edit the CSS for a space Tutorial
or for the site. To allow any user with Space Admin permissions to edit the Styling Fonts in
CSS for a space, go to > General Configuration > Security Confluence
Configuration and select Custom Stylesheets for Spaces.
Creating CSS styles that work seamlessly across different browsers is a

delicate task for basic web sites, and reasonably challenging when
customizing web applications like Confluence. It is important to test each
change that you make and ensure it works as expected in all areas of
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.
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:
2. Choose Stylesheet then Edit.
3. Paste your custom CSS into the text field.
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.
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 Quick-

CSS Editing Quick-Start Start
Tutorial: Changing
To edit a space's CSS style sheets: the Header
Background
1. Go to the space and choose Space tools > Look and Feel from the CSS Editing Tips
bottom of the sidebar Notes
3. Paste your custom CSS into the text field. Related pages:
4. Save your changes. The new CSS will be visible on all content pages
in the space. Styling Confluence
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.
#header .aui-header {
background-image:url('../download/attachments/658833839/header.png');
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.
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
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 Basic Styling Tutorial
sizes of a Confluence page, using a few lines of Styling Confluence with CSS
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.
To edit a space's stylesheet:
4. Save your changes. The new CSS will be visible on all content pages in the space.
.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-family: Times, "Times New Roman", serif;
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
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 Theme to
download and install other themes from The Atlassian Marketplace. a Space
Applying a Theme
Once a theme is installed it can be applied to the whole site or to individual to a Site
spaces. Creating a Theme
To see the themes installed in your site:
1. Go to > 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
will be applied by default to the new space. The space theme can then be
changed 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
a Space
1. Go to > 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
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
the look and feel of the whole Confluence site, or Editing a site decorator file
just an individual space. Using Velocity macros
When you edit a site layout, you'll be modifying the
default decorators in every space in your site, Related pages:
except for those that have already been edited in a
space. See Customize Space Layouts for more Velocity Template Overview
information on how to edit the decorators for a Basic Introduction to Velocity
single space. Customizing your Confluence Site
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.
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.
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:
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 Customizing Site and Space Layouts
functionally is changed, the default layouts are
modified to 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
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.

2. Select Layouts in the left-hand navigation panel. 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 4 for each layout whose customizations need to be reapplied.
If you have made space-specific layout customizations:
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
decorators. Decorator macros will not work inside normal confluence pages.
Macro Usage
#brea Draws the "You are here" breadcrumbs list, like the one found above the page name in the default
dcrum template.
bs()
#incl Includes a confluence page with the specified title. If you have 2 or more pages with the same title
udePa across multiple spaces, this macro will include the page belonging to the space you are currently
ge viewing.
(page
Title)
#sear Inserts a search box into the page, like the one to the far right of the breadcrumbs in the default
chbox template.
()
#glob Draws the global navigation bar, as found in the top right-hand corner of the default template. The
alnav navigation bar can be displayed in two modes:
bar
(type)
#glob Displays the navigation bar in its default mode: drawn as a table of links with colored backgrounds
alnav and mouse-over effects.
bar
("tab
le")
#glob Displays the navigation bar as series of text links separated by

alnav
bar |
("tex
t") characters.
#user Draws the user-specific navigation-bar. This bar contains the links to the user's profile and history,
navba or to the login and signup pages if the user is not logged in.
r()
#help Draws the help icon, and link to the Confluence help page.
icon()
#prin On pages where a printable version is available, draws the printable page icon, linking to the
table printable version of the page. Otherwise, draws nothing
icon()
#page When you are viewing a page in a Confluence space, draws the name of the space that page is in.
title Otherwise, writes the word "CONFLUENCE".The "class" argument is the CSS class that the title
(clas should be drawn in. Unless you have customized your Confluence installation's CSS file, you
s) should call this with "spacenametitle" as the class: #pagetitle("spacenametitle")
#powe Writes out the "Powered by Confluence" and Confluence version-number boilerplate found at the
redby bottom of the default template.
()
#bott Draws the fading shadow-effect found at the bottom of the content area in the default template.
omsha
dow()
#dash Inserts a link to the dashboard page.

board
link()
Custom Decorator Templates
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.
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.
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.
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
Logo
Notes: Velocity Template
Overview
Customizations to the Confluence login page will need to be Customizing Site
reapplied when you upgrade Confluence. Consider this before and Space Layouts
making drastic changes to the layout, and be sure to keep a list of Changing the Look
what you have changed for your upgrade process later. and Feel of
Please test your changes on a test Confluence site first. Confluence
Modify Confluence
Only administrators with access to the server where Confluence is running Interface Text
can modify the Confluence login page.
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.
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\atlassian\confluence\core\ConfluenceActionSupport.properties
3. Search for the text you wish to modify, replace it and save the file in <Confluence-
Install>\confluence\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
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

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
and Feel of
Confluence administrators can change the settings to customize the Confluence
behavior and the default content of their Confluence site:
Administering Site Templates

Changing the Site Title
Choosing a Default Language
Configuring the Administrator Contact Page
Configuring the Site Home Page
Customizing Default Space Content
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.
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:
Go to > General Configuration > Global Templates and Blueprints.

Select 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.

The site title appears in your browser's title bar. By default, it is set to 'Confluence'. The site title can't be empty.
To change the title of your Confluence site:
1. Go to > General Configuration.

2. Choose Edit at the top of the Site Configuration section.
3. Enter a new title for your site then choose Save.
Related pages:

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
Setting the default language Installing a Language Pack
To change the default language for the Confluence

site:
1. Choose the cog icon , then choose Gener

al 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
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 troubleshooting 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.
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
context, administrators are the members of the
Customizing the Administrator Contact
default administrators group.)
Message
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 Configuring Captcha for Spam Prevention
users may get to this page by clicking a link on an
error 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:

2. Choose General Configuration in the left-hand panel.
3. Choose Edit at the top of the 'Site Configuration' section.
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:

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,
rather than creating, pages in your site. However, Changing the Site Logo
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.
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
On this page:
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. Edit the default
home page for a
The default content in the template only appears for new spaces (those that blank space
are created after you have defined the content). Changes to the template Reset the original
do not affect existing home pages. default content
Edit the default home page for a blank space Related pages:
Spaces
To edit the default (blank) space content template:
Page Templates

2. Choose Global Templates and Blueprints in the left-hand panel.
3. Choose Edit next to 'Default Space Content' or 'Default Personal
Space Content' depending on whether you want to customize the
content for new site space or personal space home pages.
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:

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.
Give your site's landing page some personality by
On this page:
editing the site welcome message.
The site welcome message appears on the right Hints for using the template editor
hand side of the dashboard and is perfect for adding Allowing other people to edit the site
announcements, useful links, or a fun photo from welcome message
your last office party or team outing.
Related pages:
You'll need Confluence administrator permissions to
edit the site welcome message. Configuring the Site Home Page
To edit the site welcome message:
Confluence administrators can either click the Edit

link below the site welcome message on the
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
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

Managing Webhooks
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.
Cloud to Cloud integration

When adding the Cloud URL, use the https://instance.atlassian.net. If the https:// is not used, the
link will not be completed.
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.
You can view and manage in-app notifications and
On this page:
tasks in your Confluence workbox. In addition, you
can receive notifications from Jira applications and
other Confluence servers in your Confluence Which notifications are included?
workbox. To make this possible, your Confluence Configuring the polling intervals
server must be linked to the other server(s) via appli Including notifications from Jira
cation links. Stopping Jira applications from sending
notifications to Confluence
Possible configurations: Including notifications from another
Confluence server
Your Confluence server provides in-app Sending Confluence notifications to
notifications and displays them in its own another Confluence server
workbox. There are two sub-configurations Disabling workbox and in-app notifications
here: 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
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.

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
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 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 ConfluenceC
hatty. (The entry for ConfluenceChatty will appear here only if you have already configured Con
fluenceChatty to display in-app notifications.)
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 Confluence
Quiet above.
Screenshot: This Confluence server sends its in-app notifications to another Confluence server
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.
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
Jira application, and let the two applications work Installing Jira and Confluence 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 an
Confluence 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.
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.
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
Confluence pages using the gadget macro. Setting up a trust relationship with the
other application
There's two ways to register external gadgets: Subscribing to all of the application's
gadgets
Subscribe to all of the external Registering individual gadgets
application's gadgets: You can add all the Removing access to external 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.
Register the external gadgets one by one: Linking to Another Application
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. 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-
path/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.
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
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.
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
The Office Connector system app is bundled with Connector
Confluence, but a System Administrator can enable Configuring the Office Connector options
or disable parts of the Office Connector and can
configure options. Related pages:

Office Connector Limitations and Known
Enabling and disabling the Office Connector 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:

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.
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: Show Disabled If this option is enabled, the user will receive a warning when importing a
a warning before Word document. The warning will tell the user when they are about to
allowing a user overwrite existing content.
to perform an
import
Advanced Disabled Note: This feature requires a third party app.

Formatting
Options: Use the If this option is enabled, a Confluence page created from an imported
footnote macro Word document will use the {footnote} macro from Adaptavist to render
for Word any footnotes contained in the document. Note that you will need to install
footnotes the Content Formatting for Confluence app from Adaptavist to get this
macro.
Allow Disabled If this option is enabled, the Office Connector will use authentication
authentication tokens in the URL.
tokens in the
URL path This needs to be enabled to edit Office 2013 documents.
Temporary The The {viewfile} macro will cache data temporarily. This option allows you to
storage for Confluen set the location of the cache. Available settings are:
viewfile macro ce
Home Confluence home directory – The temporary file will be stored in
directory. your Confluence Home directory.
A directory specified in the directories.properties file –
You can specify a location by editing the Office Connector's directo
ries.properties file:
1. Locate the OfficeConnector-x.xx.jar file (where x.xx is the
version number) in your Confluence Home directory and copy it to
a temporary location
2. Unzip the JAR file and find the resources/directories.
properties file. The content of the file looks like this:
#Complete the following line to set a custom cache directory.

#If resetting to blank, don't delete anything before or
including the '='
com.benryan.confluence.word.edit.cacheDir=
3. Edit the last line, adding the path to your required temporary
location directly after the '=' character. For example:
On Windows:
com.benryan.confluence.word.edit.cacheDir=c:\my\path\
On Linux:
com.benryan.confluence.word.edit.cacheDir=/home/myusername
/my/path
4. Save the file, recreate the JAR and put it back in your Confluence
Home directory, overwriting the original JAR.
Maximum file 500 This is the maximum size of the cache used by the {viewfile} macro. (See
space for cache above.)
(MB)
Number of 6 This is the maximum number of threads used to convert PowerPoint,

Conversion Excel files or PDF slide shows. You can use this setting to manage
Queues Confluence performance, by limiting the number of threads so that the
Office Connector does not consume too many resources.
Click Manage Queues to view attachments that are still pending

conversion.
Managing Webhooks
Webhooks allow you to notify an application, or
On this page:
other external service, when certain events occur in
Confluence. For example, you can configure
webhooks to update an issue tracker, or trigger Securing the webhook
notifications in a chat tool. Create a new webhook
Triggering webhooks
Event payloads
Circuit breaking
A webhook consists of:
One or more events – such as page creation, or space removed. You can select multiple events to
trigger the webhook.
A URL – the endpoint where you want Confluence to send the event payloads when a matching event
happens.
Once created, Confluence will listen for these events, and send the event payload, in JSON format, to the
URL you specified.
Securing the webhook

Confluence uses webhook secrets to authenticate the payload. Combined with HTTPS, it helps ensure the
message transmitted is the one that Confluence intended to send, and that the contents were not tampered
with.
When you define a secret for a webhook, each request is signed via a Hash-based Message Authentication
Code (HMAC). The default for this algorithm is HMACSha256. The header X-Hub-Signature is defined and
contains the HMAC.
To authenticate the validity of the message payload, the receiver can perform the HMAC algorithm on the
received body with the secret as the key to the HMAC algorithm. If the results don't match, it may indicate
there was a problem with transmission that has caused the message payload to change.
Create a new webhook

You need Confluence Administrator or System Administrator global permissions to create a webhook.
To create a new webhook:
1. Go to > General Configuration >Webhooks.

2. Enter a title for your webhook.
3. Enter the URL of the application or server.
4. Enter a secret. This is a string of up to 255 characters that you define.
5. Select Test connection to check you can reach the application or server.
6. Choose the events that should trigger the webhook.
7. Select Active to make your webhook available immediately.
8. Select Create.
Screenshot: Creating a webhook to notify a chat application when a space is created or removed.
You can also create a webhook using the API. See Webhooks in the Confluence developer documentation.
Triggering webhooks
You can configure your webhook to be triggered by the following events.
Event Triggered when...
attachment_created a file is attached to a page or blog post
attachment_remov a file is deleted (sent to the trash) from the attachments page
ed
(not triggered when a version is deleted from the file history)
attachment_restored a file is restored from the trash
attachment_trashed a file is purged from the trash
attachment_updated a new file version of is uploaded directly or by editing the file
blog_created a blog post is published
blog_removed a blog post is deleted (sent to the trash)
blog_restored a blog post is restored from the trash
blog_trashed a blog post is purged from the trash
blog_updated a blog post is edited
blueprint_page_cre a page is created from a blueprint (such as meeting notes, decision, or how-to)
ated
comment_created a page comment, inline comment or file comment is made
comment_removed a page comment, inline comment, or file comment is deleted
comment_updated a page comment, inline comment, or file comment is edited
content_created a page, blog post, attachment (file), comment (page, inline, or file), or other file
(such as a space logo) is created or uploaded.
content_restored a page, blog post, or attachment (file) is restored from the trash
content_trashed a page, blog post, or attachment (file) is purged from the trash
content_updated a page, blog post, attachment (file), or comment (page, inline, and file) is edited.
content_permission a view or edit restriction is applied or removed from a page or blog post
s_updated
group_created a new group is created
group_removed a group is deleted
label_added an existing label is applied to a page, blog post, or space
label_created a label is added for the first time (did not already exist)
label_deleted a label is removed from the last page, blog post, or space, and so ceases to exist
label_removed a label is removed from a page, blog post, or space
page_children_reor the default ordering of pages is changed to alphabetical in the Space Tools >
dered Reorder pages tab
(is not triggered when you drag a page, or move a page, to change the page order)
page_created a page is published for the first time, including pages created from a template or
blueprint
page_moved a page is moved to a different position in the page tree, to a different parent page,
or to another space
page_removed a page is deleted (sent to the trash)
page_restored a page is restored from the trash
page_trashed a page is purged from the trash
page_updated a page is edited (triggered at the point the unpublished changes are published)
space_created a new space is created
space_logo_updated a new file is uploaded for use as the logo of a space
space_permissions space permissions are changed in the Space Tools > Permissions tab
_updated
(is not triggered when you edit space permissions using Inspect Permissions)
space_removed a space is deleted
space_updated the space details (title, description, status) is updated in the Space Tools >
Overview tab
theme_enabled a specific theme or default theme is applied to to a space or the whole site
user_created a new user account is created
user_deactivated a user account is disabled
user_followed someone follows a user
user_reactivated a disabled user account is enabled
user_removed a user account is deleted
Event payloads
Here's an example of the event payload for the page_trashed event. This is the raw data that's sent, in
JSON format, to your endpoint.
{
"timestamp":1596182511300,
"event":"page_trashed",
"userKey":"ff80818154ec9913015501e194f601d8",
"page":{
"id":309264476
}
}
You'll note that the content is comprised mostly of IDs. This is to ensure that identifiable information is not
stored by third party services, or leaked to users who do not have permission to see it.
Once received, you can use the REST API to interpret these IDs. See Confluence Server Rest API.
Circuit breaking
To help protect your Confluence site, any webhooks that fail consistently, are skipped for a period of time. By
default, if a webhook fails five times, it is considered unhealthy and is skipped, initially for 10 seconds. If it
continues to fail, it will be gradually shipped for longer periods, up to 10 hours.
A webhook may also be skipped if there are too many webhooks in flight. If there are 500 webhooks being
invoked, further requests will be skipped until the number in flight drops below 500.
Managing your Confluence License
Your license entitles you to run Confluence and be
On this page:
eligible for support and upgrades for a specified
period. It also defines the number of users who are
entitled to use Confluence. Viewing your license details
Updating your license
To quickly check the status of your license you can Understanding the user count for your
go to > General Configuration > Troubleshooti license
ng and support tools. Exceeding your licensed user count
Reducing your user count
You'll need need Confluence Administrator or Downgrading your license
System Administrator permissions to view and edit Finding your Support Entitlement Number
your license. (SEN)
What happens when your maintenance or
subscription expires
Viewing your license details
To view your Confluence license:
Related pages:
Upgrading Beyond Current Licensed Period
2. Choose License Details in the left-hand
Confluence installation and upgrade guide
panel.
The License Details page tells you:
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.
If you run Data Center in a cluster, 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
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.
What happens when your maintenance or subscription expires
Server licenses
If you have a Confluence Server license, your maintenance entitles you to access Atlassian support, and
upgrade Confluence.
When your maintenance expires, you can still use Confluence, but you'll no longer be able to contact
Atlassian support, or upgrade to a version of Confluence released after your maintenance expiry date.
Data Center licenses
Confluence Data Center is offered as a subscription (also known as a fixed term license), which includes
access to support and version upgrades.
If your subscription expires, Confluence will become read-only, which means you'll be able to view pages,
but not create or edit them.
Our licensing policy can change from time to time, so it's best to check our Purchasing and Licensing FAQ
for the latest information.
Need more information about your Server or Data Center license? Get in touch
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 System
Administrator permissions. and Marketplace
Apps
Database Configuration Integrating
Site Backup and Restore Confluence with
Attachment Storage Configuration Other Applications
Confluence Data Model Getting Started as
Finding Unused Spaces Confluence
Data Import and Export Administrator
Import a Text File Confluence
Auditing in Confluence administrator's
guide
This document provides information on connecting
On this page:
Confluence to an external database.
Choosing an external database

Choosing an external database About the embedded H2 database
Database setup
Note: Take time to choose your database wisely. Database drivers
The XML backup built into Confluence is not suited Database connection methods
for migration or backup of large data sets. If you Database troubleshooting
need to migrate later, you may need to use a third
party database migration tool. Related pages:
Below is more information on selecting and Database JDBC Drivers
migrating to an external database: Supported Platforms
Embedded H2 Database
Migrating to a Different Database Managing Confluence Data
Supported Databases
Database Troubleshooting
About the embedded H2 database

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 > Troubleshooti
ng 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
Configuring Confluence Data Center to work with Amazon Aurora
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
On this page:
supported databases.
Due to licensing constraints, we are not able to bundle MySQL or Oracle Adding your
database drivers with Confluence, so you will need to manually download database driver
and install the driver listed below before you can set up Confluence. (MySQL and
Oracle)
If you use PostgreSQL or Microsoft SQL Server, the drivers are bundled Supported drivers
with Confluence, so you're ready to.
Adding your database driver (MySQL and Oracle) Related pages:
The Confluence setup wizard will stop you at the Database configuration Database
step if it can't find an appropriate driver for the database you select. Configuration
Supported
To make your database driver available to Confluence: Platforms
1. Stop Confluence.
2. Download and extract the appropriate driver from the list below.
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.
The setup wizard will return to the database configuration step, and you're
back on your way.
Supported drivers
Database Driver JDBC Notes More
bundled? drivers information
PostgreSQL Postgres We recommend that you use the bundled Database

JDBC JDBC 4 driver. Setup for
driver PostgreSQL
download If you want to use a later driver, you can
(latest) download it from the PostgreSQL website.
Microsoft Microsoft We recommend that you use the bundled Type Database
SQL JDBC 4 JDBC driver. setup for
Server Driver for Microsoft
SQL Server If you decide to use a later version, we may not SQL Server
download 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 5.7 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.48
driver.
You can't use the latest driver (8.x) with

Confluence and MySQL 5.7.
MySQL 8.0 Connector\J Due to licensing constraints, MySQL drivers Database

8.0 driver are not bundled with Confluence. setup for
download MySQL
Confluence is currently tested with the 8.0.18
driver.
Oracle JDBC Due to licensing constraints, Oracle drivers are Database

driver not bundled with Confluence. setup for
downloads Oracle
For Oracle 12c R2 use the 12.2.0.x driver
(ojdbc8.jar)
For Oracle 19c you can use either ojdbc8.jar or

ojdbc10.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.
This page provides instructions for configuring
On this page:
Confluence to use an Oracle database.
Before you start

Before you start 1. Install Oracle
2. Create database user
See Supported Platforms to check your 3. Install Confluence
version of Oracle is supported. You may 4. Download and install the Oracle thin
need to upgrade your database before driver
installing Confluence. 5. Enter your database details
If you're switching from another database, 6. Test your database connection
including the embedded evaluation database, Troubleshooting
read Migrating to Another Database before
you begin. Related pages:
You'll need an experienced Oracle
Known Issues for Oracle
database administrator (DBA) to set up and
maintain 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
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
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 Field Description

type
Simple Hostna This is the hostname or IP address of your database server.

me
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
By Databas The database URL is entered in this format:

connection e URL jdbc:oracle:thin:@//<HOST>:<PORT>/<SERVICE>
string
<SERVICE> can be either the SID or Service Name. For example: jdbc:
oracle: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 Userna This is the username of your dedicated database user. In the example above,
me this is confluenceuser.
Both Passwo This is the password for your dedicated database user.
rd
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:
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))(Presentation=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
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.
There's a known issue when running Oracle with Native Network Encryption that can cause
Confluence to become unresponsive. See CONFSERVER-60152 NEEDS TRIAGE for more
details and Confluence Unresponsive Due to High Database Connection Latency for some suggested
mitigation strategies.
This page provides instructions for configuring Confluence to use a
On this page:
PostgreSQL database.
Before you start Before you start

1. Install
See Supported Platforms to check your version of PostgreSQL is PostgreSQL
supported. You may need to upgrade your database before installing 2. Create a
Confluence. database user and
If you're switching from another database, including the embedded database
evaluation database, read Migrating to Another Database before you 3. Install
begin. Confluence
4. Enter your
database details
5. Test your
database
connection
Troubleshooting
Related pages:
Database
Configuration
Known issues for
PostgreSQL
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.
If you are running PostgreSQL on Windows use the equivalent character type and collation for
your locale, for example English_United States.1252
In Linux systems, if the locale is not utf8, include LC_CTYPE as utf8 during database creation.
You can use pgAdmin as an alternative to the command line to complete this step.

The Confluence setup wizard will guide you through the process of connecting Confluence to your
database. Be sure to select "My own database".

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 is co
name nfluence
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 sslmode=require para

meter in the database URL. For example:
jdbc:postgresql://localhost:5432/confluence?
sslmode=require
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.

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
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
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.
On this page:
Confluence to use a Microsoft SQL Server database.
Before you start Before you start

1. Install SQL Server
Check the following before you start: 2. Create a database and database user
See Supported Platforms to check your 4. Enter your database details
version of SQL Server is supported. You may 5. Test your database connection
need to upgrade your database before Database driver changes
installing Confluence. Troubleshooting
If you're switching from another database,
including the embedded evaluation database, Related pages:
read Migrating to Another Database before
you begin.
Known issues for SQL Server
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.
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
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.


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
name confluence
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.

connection URL jdbc:sqlserver://<hostname>:<port>;
string databaseName=<database>
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.

Confluence can connect to your database server

the database collation and isolation level is correct
your database user has appropriate permissions for the database
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.
On this page:
Confluence to use a MySQL database.
Before you start

Before you start 1. Install MySQL Server
2. Configure MySQL Server
See Supported Platforms to check your 3. Create database and database user
version of MySQL is supported. You may 4. Install Confluence
need to upgrade your database before 5. Download and install the MySQL driver
installing Confluence. 6. Enter your database details
If you're switching from another database, Use a JDBC connection (default)
including the embedded evaluation database, Use a JNDI datasource
read Migrating to Another Database before 7. Test your database connection
you begin. Upgrade your database and driver
Troubleshooting
Confluence will not work on MySQL
variants such as MariaDB (CONFSERVER- Related pages:
29060) and Percona Server (CONFSERVE
R-36471)
Database Troubleshooting for MySQL
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 .
These instructions apply to Confluence 7.3 and later. Using an earlier version? See Database Setup
For MySQL in Confluence 7.2 and earlier.
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
as 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
and 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
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 utf8mb4:
[mysqld]
...
character-set-server=utf8mb4
collation-server=utf8mb4_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.
[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 utf8mb4 COLLATE utf8mb4_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.
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 follow the steps below for your MySQL version.
MySQL 5.7
1. Stop Confluence.
2. Head to Database JDBC Drivers and download the appropriate driver. The driver file will be called
something like mysql-connector-java-5.1.xx-bin.jar
process.
MySQL 8.0
You can't use MySQL 8.0 with Confluence 7.1 or earlier.
1. Stop Confluence.
2. Head to Database JDBC Drivers and download the appropriate driver for MySQL 8. The driver file will
be called something like mysql-connector-java-8.0.xx-bin.jar
3.

process.


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

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.

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.
Upgrade your database and driver

If you upgrade MySQL you may also need to upgrade the database driver Confluence uses to connect to
your database. Always use the driver recommended on the Database JDBC Drivers page.
Before you begin, back up your database, Confluence installation directory and Confluence home directory.
We strongly recommend you test your changes in a staging environment first.
To upgrade your database driver:
1. Stop Confluence.
2. Go to <installation-directory>/confluence/WEB-INF/lib/ and delete your existing driver. It will be called
something like mysql-connector-java-x.x.xx-bin.jar
3. Drop the new driver .jar file in your <installation-directory>/confluence/WEB-INF/lib dir
ectory.
4. Upgrade your MySQL server.
If you're using a datasource connection, you may need to also update the driver classname in the
datasource.
Troubleshooting
wrong folder.
If you get the following error message, verify that you have 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)'
The following page contains common issues encountered when setting up your MySQL database to
work with Confluence: Database Troubleshooting for MySQL
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
The embedded H2 database is used by default using DB Visualizer
when you choose the Trial installation path. Connect to the embedded H2
database using the H2 console
Remote connections
Migrate to a supported external database
Related pages:
directories
The embedded database files are stored in your Confluence home directory <confluence-home>
/database.
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 > Troubleshooti
ng 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.

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.
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\h2-x.x.x.jar.
Remote connections
Remote connections to the embedded H2 database are not permitted. You can only connect to H2 from the
server on which Confluence is installed.
Plugin vendors can connect remotely when Confluence is running in dev mode, but admins should not use
this as a workaround, and instead should migrate to a supported external database.
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
On this page:
Confluence data from your existing database to
another database. The instructions are designed
primarily for migrating from an evaluation to a Limitations of database migration
production database. Database migration
Migrating to an Amazon Aurora database
Method one – standard procedure
Large data sets will require third party
Step 1: Take note of your
database migration tools.
Marketplace apps
Step 2: Back up your data
This page covers the following scenarios: Step 3: Set up the new database
Step 4. Install Confluence (same
Moving from the embedded, trial database to version number) in a new location
a supported external database. Step 5. Download and install the
Moving from one external database to database driver if necessary
another, for example from Oracle to Step 6. Run the Confluence setup
PostgreSQL (provided your dataset is not wizard and copy your data to your
large) new database
Upgrading to a new version of the same Step 7. Re-install your Marketplace
external database. Note: you don't need to apps
migrate your data if you're upgrading the Step 8. Check settings for new
database in place. machine
Method two – for installations with a large
volume of attachments
Before you start
Step 1: Take note of your
If you are moving your database from one
Marketplace apps
server to another you can change the JDBC
URL in <confluence-home>
Step 3: Set up the new database
/confluence.cfg.xml (if you are using
Step 4. Install Confluence (same
a direct JDBC connection) or in the
version number) in a new location
definition of your datasource (if you are
Step 5. Download and install the
connecting via a datasource).
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:
directories
Limitations of database migration

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 Atl
assian 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.
Migrating to an Amazon Aurora database

If you plan to migrate to an Amazon Aurora database, see Configuring Confluence Data Center to work with
Amazon Aurora. This guide explains how to migrate to an Amazon Aurora cluster and connect it to
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.
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.
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. 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.
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
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.
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
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.
Confluence uses UTF-8 character encoding, so New installations

your database will also need to be configured to use Existing installations
UTF-8 (or the equivalent for your database, for
example, AL32UTF8 for Oracle databases, or Related pages:
utf8mb4 for MySQL).
Troubleshooting Character Encodings
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
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:

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:
2. Extract databaseSubsystemContext.xml from the confluence-x.x.x.jar that is in confluence

/WEB-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:
<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 databaseSubsystemCo
ntext.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>
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"
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
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
On this page:
database. With this type of connection, Confluence asks the application
server (Tomcat) for your database connection information.
New Confluence
If you'd prefer to use a JDBC connection see the guide for your database: installation
Existing
Database Setup for PostgreSQL Confluence
Database Setup for SQL Server installation
Database Setup For MySQL Upgrading
Database Setup for Oracle Confluence with a
datasource
Direct JDBC is the most common way to connect Confluence to your Known issues
database and is the easiest method when it comes time to upgrade
Confluence. 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">


3.
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).

username="<database-user>"
password="<password>"
url="jdbc:postgresql://<host>:5432/<database-name>"
maxTotal="60"
maxIdle="20"
validationQuery="select 1"/>

driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://<host>:1433;database=<database-name>"
maxTotal="60"
maxIdle="20"
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.
If you are using the 5.1.x driver (for MySQL 5.6 or 5.7):

driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://<host>:3306/<database-name>?useUnicode=true&characterEncoding=utf8"
maxTotal="60"
maxIdle="20"
defaultTransactionIsolation="READ_COMMITTED"
validationQuery="Select 1"/>
If you're using the 8.0.x driver (for MySQL 8):

driverClassName="com.mysql.cj.jdbc.Driver"
url="jdbc:mysql://<host>:3306/<database-name>?useUnicode=true&characterEncoding=utf8"
maxTotal="60"
maxIdle="20"
defaultTransactionIsolation="READ_COMMITTED"
validationQuery="Select 1"/>

driverClassName="oracle.jdbc.OracleDriver"
url="jdbc:oracle:thin:@<host>:1521:<SID>"
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.
Here are the configuration properties for Tomcat's standard data source resource factory (org.
apache.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:
<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.
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.
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.
<property name="hibernate.setup"><![CDATA[true]]></property>
<property name="hibernate.dialect"><![CDATA[net.sf.hibernate.dialect.PostgreSQLDialect]]><
/property>
<property name="hibernate.connection.datasource"><![CDATA[java:comp/env/jdbc/confluence]]><
/property>
<property name="hibernate.dialect"><![CDATA[net.sf.hibernate.dialect.SQLServerIntlDialect]]><
/property>
/property>
<property name="hibernate.dialect"><![CDATA[com.atlassian.hibernate.dialect.MySQLDialect]]><
/property>
/property>
<property name="hibernate.dialect"><![CDATA[com.atlassian.confluence.impl.hibernate.dialect.
OracleDialect]]></property>
/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.
Known issues
There's a known issue where Synchrony does not start if Confluence connects to the database
using a datasource. See
CONFSERVER-60120 - Synchrony not starting with datasource after upgrade to Confluence
7.5.2 , 7.6.0 , 7.6.1 & 7.6.2 CLOSED
for more information and a workaround.
There's a known issue when running Oracle with Native Network Encryption that can cause
Confluence to become unresponsive. See CONFSERVER-60152 NEEDS TRIAGE for more
details and Confluence Unresponsive Due to High Database Connection Latency for some suggested
mitigation strategies.
Configuring Confluence Data Center to work with
Amazon Aurora
On this page:
Deploying Confluence Data Center with Amazon Aurora

Connecting an existing Quick Start deployment to Amazon Aurora
Manually setting up an Amazon Aurora Database
AWS documentation
Connecting Confluence Data Center to a new Amazon Aurora database
Step 1: Shut down Confluence Data Center
Step 2: Update the database URL each Confluence node uses
Step 3: Configure collaborative editing
Step 4: Restart Confluence
Confluence Data Center supports the use of a single-writer, PostgreSQL-compatible Amazon Aurora clustered
database. A typical production-grade cluster includes one or more readers in a different availability zone. If the
writer fails, Amazon Aurora will automatically promote one of the readers to take its place. For more information,
see Amazon Aurora Features: PostgreSQL-Compatible Edition.
Deploying Confluence Data Center with Amazon Aurora

To create a new Confluence Data Center deployment with Amazon Aurora,we recommend that you use the AW
S Quick Start for Confluence . This Quick Start lets you configure a PostgreSQL-compatible Amazon Aurora
cluster with one writer and two readers in separate availability zones. See Running Confluence Data Center in
AWS for more information.
Connecting an existing Quick Start deployment to Amazon Aurora

If you deployed Confluence Data Center using the Quick Start before 11 June 2019, you won’t be able to
connect it to a new Amazon Aurora cluster. The Quick Start version prior to that date applied some settings that
are incompatible with Aurora.
Instead, you’ll have to migrate your existing data to a new Confluence Data Center deployment:
1. Use the latest AWS Quick Start for Confluence to create a new Confluence Data Center deployment.
2. Shut down Confluence on the application nodes of both old and new deployments. If you use a
standalone Synchrony cluster, shut down all the nodes in that cluster too.
3. Migrate your data from the old deployment to the new one:
EFS: EFS-to-EFS Backup explains how you can use an easy-to-deploy backup solution to perform
a backup of your old EFS and restore it in the new deployment.
Database: Migrating Data to Amazon Aurora PostgreSQL contains instructions for migrating from
Amazon RDS to a PostgreSQL-compatible Amazon Aurora cluster.
Once you finish the migration, re-start Confluence on all application nodes in the new deployment. If you use a
standalone Synchrony cluster, re-start all its nodes.
We strongly recommend you rebuild your content index after performing a migration, to ensure Confluence
search works as expected.
Manually setting up an Amazon Aurora Database

Confluence Data Center specifically supports the use of an Amazon Aurora cluster with the following
configuration:
It must have only one writer, replicating to one or more readers.

Your PostgreSQL engine must be version 11.
Check Supported Platforms for more details.
AWS documentation
AWS has some helpful guides for setting up an Aurora database and migrating to it:
Modular Architecture for Amazon Aurora PostgreSQL: a Quick Start that guides you through the
deployment of a PostgreSQL-compatible Aurora Database cluster. This cluster is similar to the one set
up by the AWS Quick Start for Jira (one writer and two readers, preferably in different availability zones).
Upgrading the PostgreSQL DB Engine for Amazon RDS: shows you how upgrade your database engine
to a supported version before migrating it to Amazon Aurora.
Migrating Data to Amazon Aurora PostgreSQL: contains instructions for migrating from Amazon RDS to a
PostgreSQL-compatibleAmazon Aurora cluster.
Best Practices with Amazon Aurora PostgreSQL: contains additional information about best practices
and options for migrating data to a PostgreSQL-compatible Amazon Aurora cluster.
Amazon also offers an AWS Database Migration Service to facilitate a managed migration. This service offers
minimal downtime, and supports migrations to Aurora from a wide variety of source databases.
If you deployed Confluence Data Center through our AWS Quick Start before 11 June 2019, you can’t
connect it to a new Amazon Aurora cluster. Rather, you’ll need to re-deploy Confluence Data Center
using our updated Quick Start and migrate your data across. See Connecting an existing Quick Start
deployment to Amazon Aurora for more information.
Connecting Confluence Data Center to a new Amazon Aurora database

After deploying an Aurora cluster and migrating your database to it, you’ll need to properly connect it to
Confluence. This will involve updating the database URL used by Confluence Data Center.
Confluence Data Center should point to the the Aurora cluster writer endpoint URL, and include the targetSer
verType parameter. This parameter allows Confluence to target the writer database instance, which ensures
the application can reconnect to it after a failover.
Your database URL will look something like this:
jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?targetServerType=master
If you deployed your Aurora cluster through the Modular Architecture for Amazon Aurora PostgreSQL
Quick Start, you can find then the cluster writer details from the Outputs tab in AWS. The RDSEndpoin
tAddress and RDSEndpointAddressPort values will be your CLUSTER_WRITER_ENDPOINT and CL
USTER_WRITER_PORT , respectively.
The following steps will walk you through the process of connecting Confluence and Aurora.
Step 1: Shut down Confluence Data Center
To safely reconfigure Confluence Data Center’s database connection, we recommend a full outage. To do this,
stop Confluence on all application nodes.
If you have a standalone Synchrony cluster, stop Synchrony on each node there.
Step 2: Update the database URL each Confluence node uses
How you perform this step depends on how Confluence currently connects to your database.
If you use a direct JDBC connection
1.
1. On the first node, edit the <local-home>/confluence-cfg.xml file.

2. Update the hibernate.connection.url property with your cluster writer endpoint URL as follows:
<property name="hibernate.connection.url">jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:
<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?targetServerType=master
3. Repeat this change on all other nodes.

4. Start Confluence, one node at a time.
This change must be made in the local home directory on each node, not in the copy of the confluenc
e-cfg.xml that can be found in the shared home.
If you use a datasource connection
1. Stop Confluence on all nodes.

2. On the first node, edit the <install-directory>/conf/server.xml file.
3. Update the url parameter in the datasource Resource element with your cluster writer endpoint URL as
follows:

url="jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?
targetServerType=master"
maxTotal="60"
maxIdle="20"
4. Repeat this change on all other nodes.

5. Start Confluence, one node at a time.
Step 3: Configure collaborative editing
Synchrony, the engine that powers collaborative editing, can be deployed in two different ways, which affects
how you pass the database URL:
1. Managed by Confluence - Confluence will automatically launch a Synchrony process on the same
node, and manage it for you.
2. Standalone Synchrony cluster - You deploy and manage Synchrony standalone in its own cluster with
as many nodes as you need. This is the default method when you deploy Confluence in AWS using our
Quick Start.
If Synchrony is managed by Confluence, you don't need to do anything. Confluence will pass the URL to
Synchrony for you.
If you run a Standalone Synchrony cluster, you will need to provide the cluster writer endpoint URL in your
startup script. This script will be either <synchrony-home>/start-synchrony.sh or start-synchrony.
bat, depending on your operating system. Edit your script as follows:
start-synchrony.sh (Linux)
DATABASE_URL="jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?
targetServerType=master"
start-synchrony.bat (Windows)
set DATABASE_URL=jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?
targetServerType=master
See Set up a Synchrony cluster for Confluence Data Center for more information about setting up Synchrony
standalone cluster.
If you run Synchrony as a Linux service, you'll need to reinstall the service.
Step 4: Restart Confluence
After making the necessary database URL updates, you can now restart Confluence on each application node,
one node at a time.
If you have a standalone Synchrony cluster, restart it on each of the cluster’s nodes.
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
directory backups. We don't recommend you rely solely on this backup method for your production site.
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 Confluence Cloud Migration
Assistant 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
directory backups. Establishing a production system backup
solution
Establishing a production system backup Which files need to be backed up?
How do I back up?
solution
How do I restore?
Other processes
We recommend establishing a robust database
backup strategy:
Related pages:
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?

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.
properties 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 Atl
assian 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
If you have a Confluence Server license, Performing manual backups
the scheduled XML backup happens every Scheduled XML backups in Confluence
day at 2:00am by default. Data Center
If you have a Confluence Data Center
license, 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
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).
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:
<property name="admin.ui.allow.daily.backup.custom.location">true</property>
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
directory. You can change where the zipped XML files are saved by changing the location of your <Conflue
nce-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
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.
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
Related pages:
up 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.
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.
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
On this page:
XML site export file into an existing Confluence
site.
Before you start
If you want to import data into a new site, see restori Import a Confluence site
ng from backup during setup. Troubleshooting
Note about using site exports as backups
You need System Administrator permissions in
order to perform this function.
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
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:

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)
3. Select your site export file under Import from home directory
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?
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
On this page:
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 Export and import
described below. compatibility
Importing a space
You need System Administrator permissions in order to restore a space from Confluence
from an XML zip file. Cloud
Importing a space
Export and import compatibility from Confluence
Server or Data
To find out which versions your current Confluence version can accept Center
Upload a
space exports from, go to > General Configuration > Backup and
site or
Restore.
space
export file
If you need to import a space from Confluence 5.3 or earlier, you'll need to f
Import from
ollow a workaround.
the home
To find out what is included in an XML export, see Export Content to Word, directory
PDF, HTML and XML. Groups and
permissions
Troubleshooting
You can't import into an earlier version of Confluence. Workaround for
restoring spaces
For example, if you export a space from Confluence 5.9, you can't from Confluence
import it into Confluence 5.5. 5.3 and earlier
If your export is from Confluence Cloud, you can only import it into Related pages:
Confluence 6.0 or later.
Restoring a Site
Importing a space from Confluence Cloud

As the way users are managed is different in Confluence Cloud there are a few more considerations 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.
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:

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.

3. Select your space export file under Import from the Home Directory.
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.
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.
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:
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.
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
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
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:

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.
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.

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.
Confluence.
Troubleshooting failed XML site backups
XML site backups are only necessary for Related pages:
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?
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.properties an
d add this to the bottom and save:
log4j.logger.com.atlassian.hibernate.extras.XMLDatabinder=DEBUG, confluencelog
log4j.additivity.com.atlassian.hibernate.extras.XMLDatabinder=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.
9. Do a search for 'ObjectNotFoundException'. You should see an error similar to this:
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.
property: type
property: group
property: expiry
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.hibernate.
ObjectNotFoundException:
08 No row with the given identifier exists: 2535, of class: com.atlassian.confluence.core.
ContentEntityObject
09 at net.sf.hibernate.ObjectNotFoundException.throwIfNull(ObjectNotFoundException.java:24)
10 at net.sf.hibernate.impl.SessionImpl.immediateLoad(SessionImpl.java:1946)
11 at net.sf.hibernate.proxy.LazyInitializer.initialize(LazyInitializer.java:53)
12 at net.sf.hibernate.proxy.LazyInitializer.initializeWrapExceptions(LazyInitializer.java:
60)
13 at net.sf.hibernate.proxy.LazyInitializer.getImplementation(LazyInitializer.java:164)
14 at net.sf.hibernate.proxy.CGLIBLazyInitializer.intercept(CGLIBLazyInitializer.java:108)
15 at com.atlassian.confluence.core.ContentEntityObject$$EnhancerByCGLIB$$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.toGenericXML(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.
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 table needs 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 to 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.
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.propertyset.

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 Reoccurring
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 On this page:
migrating to a new database. Upgrading
Confluence, Setting up a test server or Prod
Common problems
uction Backup Strategy is better done with
Resolve Errors When Attempting To
an SQL dump.
Restore An XML Backup
Troubleshooting "Duplicate Entry"
Seeing an error when creating or importing a site or for key "cp_" or "cps_"
space backup? Troubleshooting "Duplicate Key"
related problems
Problem Solution Troubleshooting "net.sf.hibernate.
PropertyValueException: not-null"
Exception while See Troubleshooting failed related problems
creating backup XML site backups To Help Prevent this Issue from
Recurring
Exception while See instructions below
importing backup Related Topics:
Common problems
To upload and import a small site:


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/
and 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:
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.
Troubleshooting "Duplicate Entry" for key "cp_" or "cps_"
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:
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
cp1.ID <> cp2.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.ID <> cp2.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);
Remove all matching entries and perform the export again.
Troubleshooting "Duplicate Key" related problems
could not insert: [bucket.user.propertyset.BucketPropertySetItem#bucket.user.propertyset.

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
As of 16 July 2019, usernames are no longer included in space exports from Confluence Cloud.
Email addresses will be included, regardless of profile visibility settings, if the person performing the
export is a Site Admin.
Email matching is available in selected Confluence versions. See below for more information.
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 have been 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 there is no username, we will attempt to match users by their email
address. To reduce the risk of making restricted pages visible to the wrong person, imported content will 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 marked private, and the space was
exported by someone who is not a Site Admin, the email address would not be included in the export).
Email matching is only available in the following Confluence Server and Data Center versions:
6.6.14 and any later 6.6 Long Term Support release version
6.13.5 and any later 6.13 Long Term Support release version
6.15.4 and later
In all other versions content will be attributed to 'unknown user' if we're unable to match by username.
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 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.
You may need to restore some permissions to the space, if any users or groups aren't present if your
destination site.
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
First step is to make sure the space has at least one space administrator. To do this:

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.
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
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.
By default Confluence stores attachments in the
On this page:
home directory (e.g. in a file system).
If you have upgraded from an earlier Confluence Attachment storage methods

version you may still be storing attachments in your Local file system
database or WebDAV, and should consider Database (deprecated)
migrating to a supported storage method. WebDav (deprecated)
Migrating to a supported attachment
storage option
Related pages:
Attachment storage methods

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.
We recommend migrating to storing attachments in the file system.
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.

persistence.dao with level DEBUG. See Configuring Logging for more information.
To migrate, follow the steps below:
1.
1. Go to > General Configuration > Attachment storage.

2. Click Edit to modify the configuration.
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
If you're already storing attachments in a file system, the Attachment Storage option won't appear in the
admin console - this is because you're already using the only supported storage method, and don't need to
migrate.
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:

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) and PowerPoint (.pptx)
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)
Note that this is based on the size of the file when it's uncompressed. As .xlsx and .docx files are
compressed, text extraction may fail even though the size of the file appears to be under the limit.
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.
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
officeconnector.powerpoint.extractor.maxlength
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:
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
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
the data model.
Database diagrams
Notes: Database tables and references
Authentication
The Hibernate mapping files are the Content
authoritative reference for the Confluence Clustering
data model. These are the *.hbm.xml files System information
which you will find in the main Confluence Spaces
JAR file (<CONFLUENCE- Appearance
INSTALLATION>\confluence\WEB- Miscellaneous
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.
Note that Marketplace apps can also add tables to your database.
Primary Primary Foreign Key Foreign Foreign Key Name Primary

Key Table Key Table Name Key Key
Name Column Column Name
Name Name
AUDITREC AUDITRECO AUDIT_AFFECTE AUDITRECO FK_AFFECTED_OBJ PRIMARY

ORD RDID D_OBJECT RDID ECT_RECORD _KEY_D
AUDITREC AUDITRECO AUDIT_CHANGE AUDITRECO FK_CHANGED_VAL PRIMARY

ORD RDID D_VALUE RDID UE_RECORD _KEY_D
CONTENT CONTENTID ATTACHMENTDA ATTACHMEN FKJNH4YVWEN0176 PRIMARY

TA TID QSVH4RPSRY2J _KEY_6
CONTENT CONTENTID BODYCONTENT CONTENTID FKMBYIAYESFP1EI PRIMARY

Q6GMOL3MK3YL _KEY_6
CONTENT CONTENTID CONFANCESTO DESCENDEN FKLMHSIPSWOL8IM PRIMARY

RS TID EQSG906IH62X _KEY_6
CONTENT CONTENTID CONFANCESTO ANCESTORID FKSQB1AF9H7FVQ PRIMARY

RS TGY73O8JDCUUE _KEY_6
CONTENT CONTENTID CONTENT PARENTCO FKAL6O8XWYPD4M PRIMARY

MMENTID DGID9B9NW1Q51 _KEY_6
CONTENT CONTENTID CONTENT PARENTCCID FKFIYHKA48C7E776 PRIMARY

QJ90KLBPM9Q _KEY_6
CONTENT CONTENTID CONTENT PREVVER FKK6KBB7SUQELO PRIMARY

J82NX7XDCD803 _KEY_6
CONTENT CONTENTID CONTENT PARENTID FKOXTT893WEUJK PRIMARY

YH0IICOXSM37V _KEY_6
CONTENT CONTENTID CONTENT PAGEID FKWJYN6091Q3L1G PRIMARY

L7BH143MA2A _KEY_6
CONTENT CONTENTID CONTENT_LABEL CONTENTID FKI8CVAHSU6D2Y2 PRIMARY

85VTRP4NHC3W _KEY_6
CONTENT CONTENTID CONTENT_PERM CONTENT_ID FK2BUUNK1HOR0I3 PRIMARY

_SET K0M3NT03HW1W _KEY_6
CONTENT CONTENTID CONTENT_RELA SOURCECO FKE2A00URQYXMY PRIMARY

TION NTENTID AJ3JOP48UB8QD _KEY_6
CONTENT CONTENTID CONTENT_RELA TARGETCON FKIPR00838MKLN69 PRIMARY

TION TENTID 9CIMD7RG17X _KEY_6
CONTENT CONTENTID CONTENTPROPE CONTENTID FK3FLY21XFK13RQ PRIMARY

RTIES H63TXW2T6K2V _KEY_6
CONTENT CONTENTID EXTRNLNKS CONTENTID FK5V5LW9X88VM27 PRIMARY

RVUBSC130NJY _KEY_6
CONTENT CONTENTID IMAGEDETAILS ATTACHMEN FK2301QICIUQ6SC3 PRIMARY

TID 2JAJ8TYSG3S _KEY_6
CONTENT CONTENTID LIKES CONTENTID FKBDOIWI70I7O3TC PRIMARY

7HPBU4VNLMY _KEY_6
CONTENT CONTENTID LINKS CONTENTID FKN8MYCKO8FRER PRIMARY

NE7BRH5NR1CSR _KEY_6
CONTENT CONTENTID NOTIFICATIONS CONTENTID FK_NOTIFICATIONS PRIMARY

_CONTENT _KEY_6
CONTENT CONTENTID SPACES SPACEDESC FK7NDEWMRL3HQ PRIMARY

ID CPWC8EYDN9MV8J _KEY_6
CONTENT CONTENTID SPACES HOMEPAGE FKJ4CU5838AQCB PRIMARY

W57WY7CKT0T7O _KEY_6
CONTENT CONTENTID TRACKBACKLINKS CONTENTID FK1TO6OMJL8NHE PRIMARY

VCJBVPT3ED7NT _KEY_6
CONTENT CONTENTID USERCONTENT_ TARGETCON FKPWGL85A266IIE5 PRIMARY

RELATION TENTID I0ADU8BDBCV _KEY_6
CONTENT_ ID CONTENT_PERM CPS_ID FKDE5WL1CUR1SE PRIMARY

PERM_SET 9281GC0DSAWTB _KEY_BF
CWD_APP_ ID CWD_APP_DIR_ APP_DIR_M FK_APP_DIR_GROU PRIMARY

DIR_MAPPI GROUP_MAPPING APPING_ID P_MAPPING _KEY_2A
NG
CWD_APP_ ID CWD_APP_DIR_ APP_DIR_M FK_APP_DIR_MAPP PRIMARY

DIR_MAPPI OPERATION APPING_ID ING _KEY_2A
NG
CWD_APPLI ID CWD_APP_DIR_ APPLICATIO FK_APP_DIR_GROU PRIMARY

CATION GROUP_MAPPING N_ID P_APP _KEY_5
CWD_APPLI ID CWD_APP_DIR_ APPLICATIO FKSTEKJ41875RGS PRIMARY

CATION MAPPING N_ID W8OTFFRAYHPL _KEY_5
CWD_APPLI ID CWD_APPLICATI APPLICATIO FK_APPLICATION_A PRIMARY

CATION ON_ADDRESS N_ID DDRESS _KEY_5
CWD_APPLI ID CWD_APPLICATI APPLICATIO FK_APPLICATION_A PRIMARY

CATION ON_ATTRIBUTE N_ID TTRIBUTE _KEY_5
CWD_DIRE ID CWD_APP_DIR_ DIRECTORY FK_APP_DIR_GROU PRIMARY

CTORY GROUP_MAPPING _ID P_DIR _KEY_AA
CWD_DIRE ID CWD_APP_DIR_ DIRECTORY FK_APP_DIR_DIR PRIMARY

CTORY MAPPING _ID _KEY_AA
CWD_DIRE ID CWD_DIRECTOR DIRECTORY FK_DIRECTORY_AT PRIMARY

CTORY Y_ATTRIBUTE _ID TRIBUTE _KEY_AA
CWD_DIRE ID CWD_DIRECTOR DIRECTORY FK_DIRECTORY_O PRIMARY

CTORY Y_OPERATION _ID PERATION _KEY_AA
CWD_DIRE ID CWD_GROUP DIRECTORY FK_DIRECTORY_ID PRIMARY

CTORY _ID _KEY_AA
CWD_DIRE ID CWD_GROUP_A DIRECTORY FK_GROUP_ATTR_ PRIMARY

CTORY TTRIBUTE _ID DIR_ID _KEY_AA
CWD_DIRE ID CWD_USER DIRECTORY FK_USER_DIR_ID PRIMARY

CTORY _ID _KEY_AA
CWD_DIRE ID CWD_USER_ATT DIRECTORY FK_USER_ATTR_DI PRIMARY

CTORY RIBUTE _ID R_ID _KEY_AA
CWD_GRO ID CWD_GROUP_A GROUP_ID FK_GROUP_ATTR_I PRIMARY

UP TTRIBUTE D_GROUP_ID _KEY_C
CWD_GRO ID CWD_MEMBERS CHILD_GRO FK_CHILD_GRP PRIMARY

UP HIP UP_ID _KEY_C
CWD_GRO ID CWD_MEMBERS PARENT_ID FK_PARENT_GRP PRIMARY

UP HIP _KEY_C
CWD_USER ID CWD_MEMBERS CHILD_USE FK_CHILD_USER PRIMARY

HIP R_ID _KEY_A3
CWD_USER ID CWD_USER_ATT USER_ID FK_USER_ATTRIBU PRIMARY

RIBUTE TE_ID_USER_ID _KEY_A3
CWD_USER ID CWD_USER_CR USER_ID FK2RFDH2AP00B8M PRIMARY

EDENTIAL_RECO HOLDSY1B785B _KEY_A3
RD
EXTERNAL ID EXTERNAL_MEM EXTENTITYID FKADLKFU6A03U8F PRIMARY

_ENTITIES BERS 8BS82LM4QLG1 _KEY_6D
GROUPS ID EXTERNAL_MEM GROUPID FK47K0FUDQNBNS PRIMARY

BERS BW0YW44UCSU2R _KEY_7D
GROUPS ID LOCAL_MEMBERS GROUPID FKI71UOMCF4F9SE PRIMARY

SIBDHSMFDBGH _KEY_7D
KEYSTORE KEYID TRUSTEDAPP PUBLIC_KEY FKM7N581Y7GROA PRIMARY

_ID 49TYGAPKMNFIV _KEY_4D
LABEL LABELID CONTENT_LABEL LABELID FK91V3V5NEMR532 PRIMARY

QQ4GLA9SJ9TF _KEY_44
LABEL LABELID NOTIFICATIONS LABELID FK4TCCRJAMRJVM PRIMARY

D2AOGL3HKLPFJ _KEY_44
OS_GROUP ID OS_USER_GROUP GROUP_ID FKM2O7638OJNKI0 PRIMARY

5I3U0N5OEPOP _KEY_DB
OS_USER ID OS_USER_GROUP USER_ID FK6W5BWO7289K9 PRIMARY

47EE5FWEC30JV _KEY_E6
PAGETEMP TEMPLATEID CONTENT_LABEL PAGETEMPL FK28KIFOKT21QD9 PRIMARY

LATES ATEID GES0Q0WV0FB9 _KEY_BC
PAGETEMP TEMPLATEID PAGETEMPLATES PREVVER FK4WGWY1DQCI8R PRIMARY

LATES CWAD4TNQBGLT8 _KEY_BC
SPACES SPACEID CONTENT SPACEID FKLMWEU06NFT59 PRIMARY

G7MW1I1MYORYS _KEY_92
SPACES SPACEID NOTIFICATIONS SPACEID FKMQE1PHE52XWQ PRIMARY

C4HK4IB8P9EH6 _KEY_92
SPACES SPACEID PAGETEMPLATES SPACEID FK18A1D37PVQ2O9 PRIMARY

HU5X3TPS97MX _KEY_92
SPACES SPACEID SPACEPERMISSI SPACEID FKBI3X723M8FBGO PRIMARY

ONS KO3S84F9ODDL _KEY_92
TRUSTEDA TRUSTEDAP TRUSTEDAPPRE TRUSTEDAP FKJOFK5643721EFT PRIMARY

PP PID STRICTION PID OW3NJWR73AA _KEY_DDB
USER_MAP USER_KEY CONTENT CREATOR FK_CONTENT_CRE PRIMARY

PING ATOR _KEY_13
USER_MAP USER_KEY CONTENT LASTMODIFI FK_CONTENT_LAS PRIMARY

PING ER TMODIFIER _KEY_13
USER_MAP USER_KEY CONTENT USERNAME FK_CONTENT_USE PRIMARY

PING RNAME _KEY_13
USER_MAP USER_KEY CONTENT_LABEL OWNER FK_CONTENT_LAB PRIMARY

PING EL_OWNER _KEY_13
USER_MAP USER_KEY CONTENT_PERM CREATOR FK_CONTENT_PER PRIMARY

PING M_CREATOR _KEY_13
USER_MAP USER_KEY CONTENT_PERM LASTMODIFI FK_CONTENT_PER PRIMARY

PING ER M_LASTMODIFIER _KEY_13
USER_MAP USER_KEY CONTENT_PERM USERNAME FK_CONTENT_PER PRIMARY

PING M_USERNAME _KEY_13
USER_MAP USER_KEY CONTENT_RELA CREATOR FK_C2CRELATION_ PRIMARY

PING TION CREATOR _KEY_13
USER_MAP USER_KEY CONTENT_RELA LASTMODIFI FK_C2CRELATION_ PRIMARY

PING TION ER LASTMODIFIER _KEY_13
USER_MAP USER_KEY EXTRNLNKS CREATOR FK_EXTRNLNKS_C PRIMARY

PING REATOR _KEY_13
USER_MAP USER_KEY EXTRNLNKS LASTMODIFI FK_EXTRNLNKS_LA PRIMARY

PING ER STMODIFIER _KEY_13
USER_MAP USER_KEY FOLLOW_CONN FOLLOWEE FK_FOLLOW_CONN PRIMARY

PING ECTIONS ECTIONS_FOLLOW _KEY_13
EE
USER_MAP USER_KEY FOLLOW_CONN FOLLOWER FK_FOLLOW_CONN PRIMARY

PING ECTIONS ECTIONS_FOLLOW _KEY_13
ER
USER_MAP USER_KEY LABEL OWNER FK_LABEL_OWNER PRIMARY

PING _KEY_13
USER_MAP USER_KEY LIKES USERNAME FK_LIKES_USERNA PRIMARY

PING ME _KEY_13
USER_MAP USER_KEY LINKS CREATOR FK_LINKS_CREATOR PRIMARY

PING _KEY_13
USER_MAP USER_KEY LINKS LASTMODIFI FK_LINKS_LASTMO PRIMARY

PING ER DIFIER _KEY_13
USER_MAP USER_KEY LOGININFO USERNAME FK_LOGININFO_US PRIMARY

PING ERNAME _KEY_13
USER_MAP USER_KEY NOTIFICATIONS CREATOR FK_NOTIFICATIONS PRIMARY

PING _CREATOR _KEY_13
USER_MAP USER_KEY NOTIFICATIONS LASTMODIFI FK_NOTIFICATIONS PRIMARY

PING ER _LASTMODIFIER _KEY_13
USER_MAP USER_KEY NOTIFICATIONS USERNAME FK_NOTIFICATIONS PRIMARY

PING _USERNAME _KEY_13
USER_MAP USER_KEY PAGETEMPLATES CREATOR FK_PAGETEMPLAT PRIMARY

PING ES_CREATOR _KEY_13
USER_MAP USER_KEY PAGETEMPLATES LASTMODIFI FK_PAGETEMPLAT PRIMARY

PING ER ES_LASTMODIFIER _KEY_13
USER_MAP USER_KEY SPACEPERMISSI CREATOR FK_SPACEPERMIS PRIMARY

PING ONS SIONS_CREATOR _KEY_13
USER_MAP USER_KEY SPACEPERMISSI LASTMODIFI FK_SPACEPERMIS PRIMARY

PING ONS ER SIONS_LASTMODIFI _KEY_13
USER_MAP USER_KEY SPACEPERMISSI PERMUSER FK_SPACEPERMIS PRIMARY

PING ONS NAME SIONS_PERMUSER _KEY_13
NA
USER_MAP USER_KEY SPACES CREATOR FK_SPACES_CREA PRIMARY

PING TOR _KEY_13
USER_MAP USER_KEY SPACES LASTMODIFI FK_SPACES_LAST PRIMARY

PING ER MODIFIER _KEY_13
USER_MAP USER_KEY TRACKBACKLINKS CREATOR FK_TRACKBACKLIN PRIMARY

PING KS_CREATOR _KEY_13
USER_MAP USER_KEY TRACKBACKLINKS LASTMODIFI FK_TRACKBACKLIN PRIMARY

PING ER KS_LASTMODIFIER _KEY_13
USER_MAP USER_KEY USER_RELATION SOURCEUS FK_RELATION_U2U PRIMARY

PING ER SUSER _KEY_13
USER_MAP USER_KEY USER_RELATION TARGETUSER FK_RELATION_U2U PRIMARY

PING TUSER _KEY_13
USER_MAP USER_KEY USER_RELATION CREATOR FK_U2URELATION_ PRIMARY

PING CREATOR _KEY_13
USER_MAP USER_KEY USER_RELATION LASTMODIFI FK_U2URELATION_ PRIMARY

PING ER LASTMODIFIER _KEY_13
USER_MAP USER_KEY USERCONTENT_ SOURCEUS FK_RELATION_U2C PRIMARY

PING RELATION ER USER _KEY_13
USER_MAP USER_KEY USERCONTENT_ CREATOR FK_U2CRELATION_ PRIMARY

PING RELATION CREATOR _KEY_13
USER_MAP USER_KEY USERCONTENT_ LASTMODIFI FK_U2CRELATION_ PRIMARY

PING RELATION ER LASTMODIFIER _KEY_13
USERS ID LOCAL_MEMBERS USERID FKRCUYOPTNAD1P PRIMARY

OS41GP1B1F3PI _KEY_4D4
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_member Mapping the membership of users to groups.

ship
cwd_direct The user directories in your Confluence site. Examples of directories are the Confluence
ory internal directory, or an LDAP directory.
cwd_applic The applications (Jira, Confluence, and so on) defined in the authentication framework.
ation
Content
This section describes the tables involved in storing content. Content is the information that Confluence
users are storing and sharing.
Table Description
attach The binary data for attached files. This table is only used in older Confluence versions where
mentda Confluence was configured to store attachments in the database. Otherwise, attachments are
ta stored in the local file system.
attach Metadata for the files attached to Confluence pages.

ments
bodyco The content of Confluence pages. No version information or other metadata is stored here.
ntent 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.
conten Arbitrary text labels for content.

t_label
label The other half of the content_label system.
conten Content-level permissions objects.

t_perm
conten A one-to-many mapping for content items and their permissions, with added metadata.
t_perm
_set
pagete The back end of the templates feature.

mplates
likes The pages and other content liked by a particular user.
follow A mapping of users who are following other users.

_conne
ctions
Clustering
The following table contains information about clustered Confluence sites.
Table Description
clust Normally, this table only contains one row. The value of the safetynumber is what Confluence
ersaf uses to find out whether another Confluence site is sharing its database without being part of the
ety cluster.
journ The journal service keeps the search index in synch across each Confluence node.
alent
ry
System information
These tables store data related to the status and configuration of the Confluence site.
Table Description
confver Used by the upgrade system to determine what to expect from the database, so as to
sion negotiate upgrades.
plugind A record of the plugins that have been installed, and when.
ata data is a blob of the actual plugin JAR file. This is principally cluster-related.
diagnos The diagnostics tool continuously checks for symptoms or behaviours that we know may
ticaler contribute to problems in your site. Events are stored for a limited amount of time in this table.
ts
Spaces
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_pro Arbitrary association of entities and properties.

pertye
ntry
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.
extrnl Referral links.

nks
hibern Used by the high/low ID generator – the subsystem which generates our primary keys.
ate_un
ique_k If you interfere with this table, you may not be able to create objects in Confluence.
ey
indexq Manages full-content indexing across the system. The table generally contains the last 12
ueueen hours (approximately) of updates, to allow re-syncing of cluster nodes after restarts.
tries
keysto Used by the trusted apps framework to store the server's private key, and other servers' public
re keys.
links Tracks links within the server (that is, across and within spaces).
notifi Stores page- and space-level watches.

cations
trackb Trackback links.

acklin
ks
confan Used to speed up permissions checks, by allowing quick lookup of all a page's ancestors.
cestors
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:
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:
Confluence Administrator's Guide
Import a Text File
Confluence allows you to import text files from a directory on the
Related pages:
Confluence 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
Confluence
Site Backup and
The text file may contain plain text, HTML or Confluence Restore
storage format
You need to be part of the confluence-administrators
group or a System Administrator to import text files
You can import pages from disk into site spaces, but not into
personal spaces
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:
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

Auditing in Confluence
The audit log allows administrators to look back at changes that have been
On this page:
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. Main differences
between auditing in
The feature is available in both Server and Data Center, however its scope Server and Data
is more extensive in Data Center. Center
View the audit log
With a Data Center license, Space admins can also view the audit log for View the space
their specific space. audit log (Data
Center)
Search and filter
the audit log
Edit log settings
Access the audit
log file (Data
Center)
Integrate with
external software
(Data Center)
Audit log and
migration
Auditing and the
REST API
Main differences between auditing in Server and Data Center

The auditing feature works differently in Confluence Server and Confluence Data Center.
Functionality Available in Server Available in Data Center
Coverage areas Yes Yes

(fewer coverage areas than
Data Center)
Selecting coverage areas No (only Base or Off) Yes
Setting database log retention Yes Yes
Storing audit logs in two locations No Yes
Integrating with 3rd party monitoring No Yes

tools
Exporting latest 100,000 results Yes Yes
Filter by category and summary No Yes
Exporting filtered results Yes Yes
Space level audit log No Yes
View the audit log

To view the global audit log in Confluence:

2. Select Audit log
3. Select an event to expand it and see details.
Different details will be shown depending on the event itself. These can include:
IP address – IP address of the user who performed the action. This is not recorded for system-
generated events.
Load balancer/proxy IP address – IP address of the load balancer or proxy server that forwarded
the request.
Node ID – unique ID of the cluster node where the action was performed.
Method – depending on how the action was performed, this will be either Browser (end user) or
System (system process).
View the space audit log (Data Center)

System admins, Confluence admins and space admins can also access audit logs for a specific space, if
they have permission to administer that space.
The space audit log records events related to space permissions and configuration, user actions within the
space, and some events related to space security (for example, events related to accessing and granting
permissions to restricted pages with a particular space).
To view the audit log for a specific space, go to Space tools > Audit log.
Search and filter the audit log

You can search the log by keyword, and narrow your results by date, author, and space. If you have a Data
Center license you can also filter by category and summary.
To speed up the search, we only search the most recent 1 million events. After this search is
performed, you can choose to run a full database search. If you have a large or busy Confluence
site, running a full search can take a while.
Can't find a specific event?
Changing coverage level changes the individual events that are logged. If you can't find a specific event, it
might be because coverage level was changed, and these events were not logged for a period of time.
Check the audit log configuration events to determine if this might be the case.
Edit log settings

In the audit log settings you can decide how long you want to retain the logged events in the database, and
the areas from which you want to collect the logs.
Update database retention
The database retention is limited by the retention period, with a maximum of 10 million records.
To update the database retention period:
1.
1. Select more options > Settings.

2. Enter the period of time. This can be in days, months or years.
3. Select Save.
If you choose a long retention period, it can affect the size and performance of your database. Learn more
about setting an optimal retention period for your Confluence instance.
If you decide to lower the retention period, all the events that exceed the newly set period will be deleted,
and disappear from the page. It's a good idea to create a backup before you lower the retention period.
If you migrated from a previous Confluence version, your default retention period is 20 years. If you have a
new Confluence installation, it’s 3 years.
Select events to log
The events that are logged are organized in categories that belong to specific coverage areas.
For example, import and export-related events are logged in the Import/Export category, that belongs to the L
ocal configuration and administration coverage area. For all coverage areas and events logged in each
area, see Audit log events in Confluence.
To adjust the coverage:
1. Go to more options > Settings.

2. In the Coverage level drop-down, select the level to log the events you need, or Off to stop collecting
events from a particular area.
Coverage level definitions
Coverage levels reflect the number and frequency of events that are logged. Some coverage levels are only
available with a Data Center license.
Coverage Definition
level
Off Turns off logging for this coverage area.
Base The lowest level of coverage. Logs only the core events. Base coverage provides a
minimum level of insight into your site’s activity. If you have a Confluence Server license,
this is the only coverage level available.
Advanced Logs all the events covered in Base, plus additional events.
(Data
Center Advanced coverage provides a more detailed record of your site’s activity.
only)
Full (Data The highest level of coverage available. Logs all events in Base and Advanced.
Center
only) Depending on your site's activity, setting your coverage level to Full can generate a large
volume of events, which can impact your database and disk space.
Export the audit log

You can export up to 100,000 latest or filtered events as a CSV file. If you have more than 100,000 events,
only the 100,000 newest events are included in the export.
To export the audit log:
1. Go to Audit log, then choose Export.

2. Select to export the latest 100,000 or filtered results.
3. Confirm by clicking Export.
Space admins can also export from the space level audit log.
Access the audit log file (Data Center)

For Confluence Data Center, each node has its own log, which can be found in the <local-home>/log
/audit directory. The log is stored as a JSON file.
Confluence creates a new log file every 24 hours, or once the current one reaches 100 MB, whichever
occurs first. For more details on log rotation, see Audit Log Integrations in Confluence.
Change the audit log file retention
You can choose how many audit log files to store in the local home directory on each node. By default we
store 100 files. Make sure you've provisioned enough disk space for these files, especially if you have set
the logging level to Advanced or Full.
To change the file retention setting:
1. Go to > General Configuration > Audit log.

2. Select Settings.
3. Enter the maximum number of files to be stored and select Save.
Once a node reaches the log file retention limit, the oldest one is deleted. If you need to keep these logs, for
example for compliance purposes, you may want to manually back up the files in this directory on a regular
basis, or send them to a third party logging platform. See Audit Log Integrations in Confluence.
Integrate with external software (Data Center)

You can use the log file to integrate with third-party tools such as ELK, Splunk, Sumologic, and Amazon
CloudWatch. For more information on integrations, see Audit Log Integrations in Confluence.
Audit log and migration
Migrate database
If you have more that 10 million events stored in your database, and you move to a new database, only the
latest 10 million will be migrated, and the remaining data will be removed.
To have access to your older events, you can create a backup before you migrate and access the data in the
backup.
Migrate from a previous Confluence version
Migrating audit log records can take a while, depending on the size of the audit log and your database.
Auditing and the REST API

The audit log can also be accessed via the REST API.
Audit Log Events in Confluence
This page outlines the auditing events available in Confluence Server and Data Center, and which events fall
into each coverage level.
For more information about how auditing works, see Auditing in Confluence.
On this page
Definitions
Global configuration and administration
User management
Permissions
Local configuration and administration
Security
End user activity
Definitions
Coverage area
A coverage area is a grouping of events related to a similar theme.
Coverage area Definition
Global configuration Logs instance or system admin activity around instance administration or
and administration configuration such as platform changes or upgrades to global settings.
User management Logs activity around users, groups, memberships, and roles, such as adding
and removing users and groups.
Permissions Log activity around local and global permissions and configurations such as
changing to anonymous access or updating group permissions.
Local configuration Logs admin activity around spaces, such as creating or deleting a space.
and administration
Security Logs user actions related to security such as authentication, or granting access
to a restricted page.
End user activity (Da Logs end user activity on your site, such as user actions on a page (creating,
ta Center only) editing, commenting), searching, or viewing pages.
Category
A category is a grouping of related events. Categories can belong to multiple coverage areas.
Category names change over time. You may find your audit log contains some categories not described on
this page. These are usually associated with events logged prior to Confluence 7.5.
Coverage level
Coverage levels allow you to control which events are logged. Some levels are only available with a Data
Center license.
Coverage Definition
level
Off Turns off logging for this coverage area.

Base The lowest level of coverage. Logs only the core events. Base coverage provides a
minimum level of insight into your site’s activity. If you have a Confluence Server
license, this is the only coverage level available.
Advanced Logs all the events covered in Base, plus additional events.
(Data
Center Advanced coverage provides a more detailed record of your site’s activity.
only)
Full (Data The highest level of coverage available. Logs all events in Base and Advanced.
Center
only) Depending on your site's activity, setting your coverage level to Full can generate a
large volume of events, which can impact your database and disk space.
Global configuration and administration
Category: Global administration
Coverage level Events logged
Base Mail server created

Mail server deleted
Mail server edited
Max cache size changed
Licence updated
Global settings changed
Site import
Site export
Site logo changed
Favicon changed
Favicon reset to default
Custom stylesheet added
Custom stylesheet removed
Theme changed
Custom decorator modified
Color scheme modified
Color scheme type changed
Security configuration updated
Advanced Mobile apps configuration updated

Read-only mode configuration changed
Banner configuration changed
Collaborative editing mode changed
Synchrony restarted
Mail queue flushed
Mail queue: error queue re-sent
Mail queue: error queue deleted
Whitelist turned on
Whitelist turned off
Whitelist URL added
Whitelist URL removed
Whitelist URL updated
Security configuration updated
Application navigator link added
Application navigator link removed
Application navigator link updated
Scheduled job enabled
Scheduled job disabled
Scheduled job edited
Scheduled job run manually
Application link created
Application link edited
Application link removed
Rate limiting settings updated
Rate limiting exemption added
Rate limiting exemption removed
Rate limiting exemption edited
CDN configuration
Full No events
Category: Apps
Base App installed

App uninstalled
App enabled
App disabled
App module enabled
App module disabled
Advanced No events
Full No events
Category: Page templates
Base Page template updated

Page template created
Page template deleted
Advanced No events
Full No events
User management
Category: Users and groups
Base User created

User deleted
User renamed
User details updated
User requested password reset
Group created
Group deleted
User added to group
User removed from group
User directory created
User directory deleted
User directory updated
Advanced User was invited to join site
Full No events
Permissions
Category: Permissions
Base Space permission removed

Space permission added
Global permission removed
Global permission added
Advanced No events
Full No events
Local configuration and administration
Category: Pages and blogs
Base Page hierarchy copy started

Page hierarchy delete started
Advanced No events
Full No events
Category: Import / export
Base Space import

Space export
Space exported to PDF
Advanced No events
Full No events
Category: Spaces
Base Space created

Space deleted
Space archived
Space unarchived
Space trash emptied
Space logo uploaded
Space logo enabled
Space logo disabled
Space logo deleted
Unknown update to space logo
Space configuration updated
Advanced No events
Full No events
Security
Category: Auditing
Base Audit log search performed

Audit log exported
Audit log configuration updated
Advanced No events
Full No events
Category: Authentication
Base No events
Advanced Secure admin access granted

Secure admin access request failed
Secure admin access dropped
User authorized external application access via OAuth tokens
User de-authorized external application access via OAuth token
User login failed*
Full User login successful

User logout
Category: Users and groups
Base No events
Advanced Forgot password feature triggered

Forgot password feature triggered for unknown user
Full No events
Category: Security
Base No events
Advanced User tried to access restricted page

User requested access to restricted page
User requested access to restricted blog
Owner of the page authorized access
Owner of the blog authorized access
Full No events
*We only track User login failed events if the authentication does not involve a redirect to an
external identity provider. If a user tries to log in using SSO and fails, this event will not be logged.
Most identity providers track these events in their own audit logs.
End user activity

DATA CENTER ONLY
Category: Pages and blogs
Base No events
Advanced Blog post edit restriction added

Blog post edit restriction removed
Blog post view restriction added
Blog post view restriction removed
Blog post deleted
Blog post restored
Blog post purged from trash
Blog post version deleted
Page view restriction added
Page view restriction removed
Page edit restriction added
Page edit restriction removed
Page restored
Page deleted
Page version deleted
Page purged from trash
Attachment deleted
Attachment version deleted
Comment deleted
Page moved
Blog post moved
Page shared
Blog post shared
Full Page created

Page edited
Blog post created
Blog post edited
Comment created
Comment edited
Inline comment created
Inline comment edited
Attachment downloaded
Attachment uploaded
Category: Import / export
Base No events
Advanced Page exported to PDF

Blog post exported to PDF
Page exported to Word
Blog post exported to Word
Full No events
Audit Log Integrations in Confluence
Confluence Data Center writes audit logs to the database and a log file. By itself, the log file saves you the
effort of periodically exporting your audit logs from the database for long-term storage. However, the main
purpose of the file is to easily integrate Confluence Data Center to a third-party logging platform.
On this page:
Event coverage and log retention

Log file details
Integrating with logging agents
Event coverage and log retention

The Audit log settings menu controls the coverage of audit logs in both database and log file. However, this
menu does not control the log file's retention period.
The log file's retention is ultimately controlled by log rotation. We use basic log rotation to manage the
volume of logs. We automatically archive the audit log file when:
the node's time reaches 12:00 midnight, or

the audit log file reaches 100MB.
Once a node reaches the log file retention limit, the oldest one is deleted. By default the limit is 100 log files
(the current audit log file + 99 archives). Make sure you allocate enough disk space for these log files on
each application node. For the default setting of 100 files, you should allow 10GB.
Log file details

Confluence Data Center writes audit logs in real time to the home directory. Specifically, these logs are
written to the audit log file. On clustered Confluence Data Center deployments, each application node will
produce its own log file in its local home directory.
Location
To integrate the audit log file with a third-party logging platform, you'll need to know its exact location. This
may vary, depending on how you configured your home directory. For more information about the local
home directory, see Confluence Home and other important directories).
On a clustered Confluence Data Center deployment, the audit log file's directory should be the same on all
nodes.
See CloudWatch Logs Agent Reference for more information. If you want to see how we automate this via
Ansible, check out our deployment playbooks on https://bitbucket.org/atlassian/dc-deployments-automation
/src/master/.
File name
The audit log file name uses the following naming convention:
YYYYMMDD-XXXXX.audit.log
The XXXXX portion is a 5-digit number (starting with 00000) tracking the number of audit log files archived in
the same day (YYYMMDD). For example, if there are 5 archived log files today (January 1, 2020), then:
the oldest archived log file is 20200101.00000.audit.log

the current audit log file is 20200101.00005.audit.log
Format
Each audit log is written as a JSON entry to the audit log file. Every line in the file represents a single event,
allowing you to use regular expressions to do simple searches if needed.
Integrating with logging agents

Most enterprise environments use a third-party logging platform to aggregate, store, and otherwise manage
logs from all hosts. Logging platforms like AWS CloudWatch and Splunk use agents to collect logs from
every host in the environment. These agents are installed on each host, collecting local logs and sending
them back to a centralized location to be aggregated, analyzed, audited, and/or stored.
If your logging platform uses agents this way, you can configure each node's agent to monitor the audit log
file directly. Logging agents from most major platforms (including AWS CloudWatch, Splunk, ELK, and Sumo
Logic) are compatible with the audit log file.
Amazon CloudWatch Agent
We provide Quick Starts for Confluence Data Center for easy deployments on AWS. This Quick Start lets
you deploy Confluence Data Center along with an Amazon CloudWatch instance to monitor it.
To set up Amazon CloudWatch, use the Enable CloudWatch Integration parameter's default setting
(namely, Metrics and Logs). The Quick Start will then configure the Amazon CloudWatch Agent to
collect the logs from each node's audit log files. The agent will send these logs to a separate log group
named confluence-<aws-stack-id>-audit.
Our Quick Start also sets up a default dashboard to help you read the collected data, including logs from
each audit log file. Refer to Working With Log Groups and Log Streams for related information.
Manual configuration
If needed, you can also manually configure the Amazon CloudWatch agent to collect the audit log files.
To do this, set the following parameters in the Agent Configuration File:
file: set this to to <local home directory>/log/audit/*. Don't forget to set the absolute
path to the home directory.
log_group_name and log_stream_name: use these to send Confluence Data Center's audit logs to
a specific log group or stream.
Splunk Universal Forwarder
For Splunk Enterprise or Splunk Cloud, you can use the Splunk Universal Forwarder as your logging agent. T
his will involve installing the universal forwarder on each application node.
You'll also need to define each node's audit log directory as one of the forwarder's inputs. This will set the
forwarder to send all logs from the audit log directory to a pre-configured receiver. One way to define the
forwarder's inputs is through the Splunk CLI. For Linux systems, use the following command on each
application node:
./splunk add monitor <local home directory>/log/audit/*audit.log
Refer to the following links for detailed instructions on configuring the Splunk Universal Forwarder on each
node:
How to forward data to Splunk Enterprise

How to forward data to Splunk Cloud
Filebeat (for the ELK stack)
Within the ELK stack, you can use the Filebeat plugin to collect logs from each node's audit log files. Each
time a log is written to the current audit log file, Filebeat will forward that log to Elasticsearch or Logstash.
To set this up, install Filebeat first on each application node. Then, set the audit log file directory as a Filebeat
input. To do that, add its directory as a path in the filebeat.inputs section of each node's filebeat.
yml configuration file. For example:
filebeat.inputs:
- type: log
enabled: true
paths:
- <local home directory>/log/audit/
Sumo Logic installed collectors
If you have a Sumo Logic instance, you can use installed collectors to collect logs from each node's audit log
files. To do this, install a collector on each node first. Then, add <local home directory>/log/audit
/* as a Local File Source to each node's collector.
This section focuses on settings and configurations
Related pages:
within the Confluence application.
For guidelines on external configuration, see Config Confluence administrator's guide
uring a Confluence Environment.

Configuring the Confluence Search and Index
Configuring Mail
Other Settings
Scheduled Jobs
Configuring the Time Interval at which Drafts
are Saved
The System Information screen provides information about Confluence's
Related pages:
configuration, which plugins are in use, and the environment in which
Confluence has been deployed. Cache Statistics
Live Monitoring
To view your system information go to > General Configuration > Syste Using the JMX
m Information. Interface
Tracking
Notes: Customizations
Made to your
The handy memory graph helps you keep track of Confluence's Confluence
memory usage. Installation
Your system configuration information is helpful to Atlassian Support
when diagnosing errors you may face using Confluence. When
logging a support request or bug report, please provide as much
detail as possible about your installation and environment.
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.
Bootstrap 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.
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.
DatabaseExampleLaten Shows the latency of an example query performed against the Milliseconds
cy database
RequestMetrics
This MBean shows information related to system load and error pages served.
AverageExecutionTimeForLastTenRequ Average execution time for the last ten requests. Milliseconds
ests
CurrentNumberOfRequestsBeingServed Number of requests being served at this instant. Integer
ErrorCount Number of times the Confluence error page was Integer

served.
NumberOfRequestsInLastTenSeconds The number of requests in the last ten seconds. Integer
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.
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.
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.
AllJobNames Shows information on current scheduled jobs including the time they String
were last run
CurrentlyRunningJobNa Lists the scheduled jobs that are currently running List
mes
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:
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:

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. Related pages:
See notes below.
Page History and
If enabled, the space activity screen displays statistics on the activity in Page Comparison
each space. These include: Views
Watch Pages,
How many pages and blog posts have been viewed, added or Spaces and Blogs
updated over a given period. How do I get more
Which content is the most popular (most frequently viewed). statistics from
Which content is the most active (most frequently edited). Confluence?
Which people are the most active contributors/editors of content.
To view the activity in a space:
1. Go to the space and choose Space Tools at the bottom of the

sidebar
2. Choose Activity
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
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:

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
Related pages:
default. See notes below.
How do I get more statistics from
If enabled, the global activity screen displays Confluence?
statistics on the activity in your Confluence site. Cache Statistics
These include: View Space Activity
Live Monitoring Using the JMX Interface
How many pages and blog posts have been
viewed, added or updated over a given
period.
Which spaces are the most popular (most
frequently viewed).
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:

al Configuration
2. Choose 'Global Activity' in the
'Administration' section of the left-hand panel
(only appears if enabled - see below).
Screenshot: Global Activity

The top ten most popular and most active pages and/or blog posts will be listed, with a link to each.
Notes
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:

2. Choose System Information in the left-hand panel.
3. Scroll down to the section titled System Properties.
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
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\server.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
attribute 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.
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 Pro
xying Atlassian Server applications.
This information needs to be added in the Connector element at {CONFLUENCE_INSTALLATION}
\conf\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 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
Changing the indexing language to be used in your Confluence site may
Related pages:
improve the accuracy of Confluence search results, if the majority of the
content in your site is in a language other than English. Choosing a Default
Language
Confluence supports content indexing in: Installing a
Language Pack
Arabic Content Index
Brazilian Administration
Chinese How to Rebuild the
CJK Content Indexes
Custom Japanese From Scratch on
Czech Confluence Server
Danish
Dutch
English (default)
Finish
French
German
Greek
Hungarian
Italian
Norwegian
Persian
Romanian
Russian
Spanish
Swedish
To configure the indexing language:
1. Go to > 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:

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

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:

3. Choose Edit.
4. Deselect the Quick Search checkbox.
5. Choose Save.
Content Index Administration
The content index, also known as the search index,
On this page:
is used by search, the dashboard, some macros,
and many other places where we show information
about content in your Confluence site. View the index queue
Rebuild the search index
The search index is updated automatically as Location of search indexes
people get work done on your site. Changes, such Index recovery in a cluster
as a new page, comment, or edit to an existing Troubleshooting
page, aren't updated in the index immediately.
They're placed in a queue and regularly processed Related pages:
in batches (as often as every 5 seconds).
Scheduled Jobs
Search
Configuring the Confluence Search and
Index
View the index queue

It can take a while for the queue to process if there are thousands of changes to your site within a short
period.
To check the contents of the queue:
1. Go to > General Configuration > Content Indexing.

2. Select the Queue contents tab.
Here you can see the number of items in the queue, the last time the queue was processed, and how long it
took to process. This information is useful for troubleshooting if your users report issues with search,
dashboard activity feeds.
Rebuild the search index

There are some circumstances where you may need to reindex your site, for example, if your users report
issues with search, dashboard activity feeds, or if directed to as part of an upgrade.
To rebuild the search index:
1. Go to > General Configuration > Content Indexing.

2. Select Rebuild and follow the prompts to confirm you want to rebuild the index.
Screenshot: The Content Indexing screen showing information about the last time the index was rebuilt.
Propagate the search index to your cluster
If you're running Confluence in a cluster, once the index is rebuilt on the current node, we'll automatically
propagate the index files to all the other nodes in the cluster.
Screenshot: The Content Indexing screen showing progress as the index is propagated to each node in the
cluster.
The index files will only be propagated to nodes that have joined the cluster. If Confluence is not running on
a node, we won't be able to propagate the index to that node.
If there's a problem, you'll see an error with information about what went wrong, for example, if a node
becomes unavailable, or there's insufficient disk space to copy the index.
Impact on end users
Confluence will continue to use the existing index until the new index has been rebuilt successfully. Your
users can continue to search and use Confluence, but may experience some performance degradation. This
is because rebuilding the index increases the load on your server significantly.
Rebuilding the index can take several hours. The amount of time depends on the number, type, and size of
pages and attachments in your site, the amount of memory allocated, and disk throughput.
If you have a large site, there are some things you can do to reduce the impact on your users:
If you're running Confluence on a single node, kick off the rebuild on a weekend, or during a
scheduled maintenance window.
If you're running Confluence in a cluster, remove the node rebuilding the index from your load
balancer. Once propagation is complete, you can add the node back into the pool.
Disk space requirements
You'll need enough free disk space in your home directory (or local home directories if you're running
Confluence in a cluster) to temporarily accommodate two full copies of your index. This is because the
existing index is not removed until the new index is ready.
If you're running Confluence in a cluster, you'll also need enough free space in your shared home directory
to accommodate an additional index snapshot.
Location of search indexes

You can find the Confluence index in the <home-directory>/index directory.
If you're running Confluence in a cluster, a full copy of the Confluence indexes are stored in the <local-
home>/index directory on each Confluence node. A journal service keeps each index in sync.
If you need to see the contents of the search index for any reason, there is a tool you can use to browse the
index directly. See How to view the contents of the search index in Confluence Server and Data Center.
Index recovery in a cluster

If you run Confluence in a cluster, a snapshot of the search index is also stored in the shared home
directory. These snapshots are created by the Clean Journal Entries scheduled job which, by default, runs
once per day.
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. The journal service will then make any further
updates required to bring the index up to date.
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 the time Confluence waits for the snapshot to be generated using the confluence.
cluster.index.recovery.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.
The index recovery snapshot isn't used when you manually rebuild your index from the UI. The rebuild
process generates a brand new snapshot, before propagating it to other nodes in the cluster.
Troubleshooting
If you have problems rebuilding the search index, the following may help.
Can't rebuild the index
If you're unable to rebuild the index from the Confluence UI, or if you still have problems with search after
rebuilding the index, you may need to rebuild the index from scratch. The way you do this depends on
whether Confluence is running in a cluster:
How to Rebuild the Content Indexes From Scratch on Confluence Server

How to Rebuild the Content Indexes From Scratch on Confluence Data Center
Poor performance while rebuilding the index
If you experience stability problems while the index is being rebuilt, you can reduce the number of threads
Confluence should use to rebuild the index. Set the reindex.thread.count system property to define
the maximum number of threads that can be used.
If both reindex.thread.count and index.queue.thread.count are unset, we default to 4 threads.
Out of memory errors while rebuilding the index
If you experience out of memory errors while rebuilding the index, increasing the heap memory available to
Confluence may help. See How to fix out of memory errors by increasing available memory.
Rebuild index failed to propagate to other nodes in the cluster
This generally happens when there is not enough free disk space for the local home directory on each node
to accommodate two copies of the index. See Failed to propagate index in Confluence Data Center 7.7 and
later to find out how to re-try the propagation.
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. Confluence
Administrator's
To enable or disable OpenSearch autodiscovery: Guide

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

standard, 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.5 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 in all current spaces. The job runs daily.
The job ignores archived spaces, so if you suspect there is a problem with the ancestor table in a particular
archived space, you will need to change the status of the space to 'current', then run the job manually.
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.
confluence.pages.ancestors to INFO.
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.5 or earlier for more information.
Setting Up Confluence to Index External Sites
Confluence cannot easily index external sites, due
Related pages:
to the way Lucene search works in Confluence, but t
here are two alternatives: Setting Up an External Search Tool to
Index Confluence
1. Embed External Pages Into Confluence Configuring the Confluence Search and
2. Replace Confluence Search 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 External
Confluence user specifically for the search crawler Sites
to use. Grant this user view rights to all content you Configuring the Confluence Search and
wish to index, but deny that user all delete 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
Customizing Email Templates

Configuring your Confluence server to send email
On this page:
messages allows your Confluence users to:
Receive emailed notifications and daily Configuring Confluence to send email

reports of updates. messages
Send a page via email. Testing the email settings
You can personalize email notifications by Related pages:

configuring the 'From' field to include the name and
email address of the Confluence user who made the The Mail Queue
change. Setting Up a Mail Session for the
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.
1. Set up a mail server as described above.

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.
The simplest way to set up a mail server is 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) the following files from <confluence-install>\confluence\WEB-INF\lib to <c
onfluence-install>\lib
jakarta.mail-x.x.x.jar
javax.activation-x.x.x.jar
javax.activation-api-1.2.0.jar
(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"
/>
5. Go to > General Configuration > Mail Servers.
6. Select 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
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'
notification. Initial settings of
the defaults
If you have Confluence Administrator or System Administrator permissions, Configuring the
you can configure the default settings that determine how often the Recommended
Recommended Updates notification is sent. When new users are added to Updates notification
Confluence, the default settings will be applied to their user profiles. Disabling the
Recommended
Confluence users can choose their personal settings, which will override the Updates
defaults. See Email Notifications. notification for the
entire site
Initial settings of the defaults
Related pages:
When you install Confluence, the initial values of the default settings are as
Email Notifications
follows:
The default frequency is weekly.

If your Confluence site has public signup enabled, the
Recommended Updates notification is disabled by default. If public
signup is not enabled, the notification is enabled by default.
You can change the above settings, specifying a different default value for
the site.
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:

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
either try to resend them or delete them.
To view the mail queue:

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:
The information on this page does not apply to Confluence

Cloud.
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
character encodings to UTF-8 (or the equivalent
Configuring Confluence character 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.
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.
"€" 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 latin1 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
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
On this page:
content via a WebDAV client, such as 'My Network
Places' in Microsoft Windows. Provided that the
user has permission, they will be able to read and Introduction to Confluence's WebDAV
write to spaces, pages and attachments in Client Integration
Confluence. Users will be asked to log in and the Using a WebDAV Client to Work with
standard Confluence content access permissions Pages
will apply to the equivalent content available through Restricting WebDAV Client Write Access
the WebDAV client. to Confluence
Disabling Strict Path Checking
Mapping a Confluence WebDAV network Virtual Files and Folders
drive requires a set of specific criteria to be
met. For specific information, please see Wi Related pages:
ndows Network Drive Requirements.
Disabling and enabling apps
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.
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.
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' webdavs
(for example, webdavs://<confluence server url>/confluence/plugins/servlet
/confluence/default or webdavs://<confluence 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:

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:

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
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:

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
Screenshot: The Hidden Virtual Files and Folders Option
To enable or disable access to virtual files and folders:

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:

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
Shortcut links provide a quick way of linking to
On this page:
resources that are frequently referenced from
Confluence. When you create a shortcut link, you
assign a key to an URL so that, when editing, a user Creating shortcut links
can type just the key instead of the complete URL. Using shortcut links
Deleting shortcut links
Example: Creating a shortcut to Google
Most Google searches look like this: http://www.

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
/search?q=searchterms, they can just type [se
archterms@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:

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 link Type this Resulting URL Demonstration

to...
a issue CONF-1000@JIRA http://jira.atlassian.com/secure/QuickSearch.jspa? CONF-1000

searchString=CONF-1000
a Google Atlassian http://www.google.com/search? Atlassian

search Confluence@Google q=Atlassian+Confluence Confluence@Google
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 change how times and dates appear
throughout your Confluence site to suit your On this page:
organization's preferred date format.
Site date and time

Relative dates
Date lozenges
Related pages:
Site date and time

To change the time and date formats for your entire site:

2. Choose Edit.
3. Enter your preferred Time Format, Date Time Format and Date Format.
4. Choose Save.
Confluence uses the Java SimpleDateFormat class. Head to Java SimpleDateFormat to see all allowed
values, or use one of the common format examples below.
Format Example
dd MMMM yyyy 05 June 2019
MMMM d, yyyy June 5, 2019
d MMM yy 5 Jun 19
dd-MM-yy 05-06-19
d-M-yy 5-6-19
h:mm a 3:25 PM
HH:mm 15:25
Here's what the page history for the same page might look like with different date and time formats.
Relative dates
Some parts of Confluence use relative dates when the change happened recently. For example a comment
might have been added "yesterday", or a page modified "about 2 hours ago".
It's not possible to customize this format. Full dates are displayed in your preferred format once the change
is more than 1 day old.
Date lozenges
To insert a date lozenge, in the editor type // or choose > Date from the toolbar.
When you insert a date lozenge, the date format displayed depends on the language settings for the current
user. This means the lozenge will appear differently for different users.
The example below shows English, Italian, Polish, German, and Japanese date formats. The same format is
used for UK and US English.
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. Y
ou'll need System Administrator permissions to do this.
To enable the remote API:

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:
Related pages:
Threaded: Shows the comments in a hierarchy of responses. Each Comment on
reply to a comment is indented to indicate the relationships between pages and blog
the comments. posts
Flat: Displays all the comments in one single list and does not Confluence
indicate the relationships between comments. administrator's
guide
By default, comments are displayed in threaded mode. A Confluence
Administrator (see Global Permissions Overview) can enable or disable the
threaded view for the entire Confluence site.
To enable or disable the threaded view:

2. Select Further Configuration in the left-hand panel
3. Choose Edit
4. Select or unselect the Threaded Comments checkbox to enable or
disable threaded mode
5. Choose Save
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 a Default
'Language' options for users in their user settings. Language
Configuring
Confluence is available in these languages right out of the box: Indexing Language
Installing
eština (eská republika | Czech Republic) Marketplace apps
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)
You can make additional languages available by installing language pack

apps. You'll need to be a Confluence administrator to install a language
pack.
Installing additional language packs
We no longer provide community translations for Confluence. You can find a small number of third-party
language packs on the Atlassian Marketplace.
Showing User Interface Key Names for Translation

This feature is useful if you are troubleshooting 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.
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
/<subdirectories>, 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
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.
This page describes how to set Java properties and options on startup for
On this page:
Confluence.
See How to fix out of memory errors by increasing available memory Linux
for specific instructions for OutOfMemory Errors. Windows (starting
from .bat file)
Windows service
Confluence Data
Center deployed in
AWS
Verifying your
settings
Recognized
system properties
Related pages:
Recognized
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.
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):
1.
In the above example, the service name is Confluence260919000053.

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//Confluence260919000053

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:
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.
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 Effect

Value
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 If this system property is set, Confluence will ignore the contents of the confluence-
filesyste init.properties file, and use this property as the setting for the Confluence Home
m path 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
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/jmxContext.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
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 (def
ault 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.".
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 CO
NF-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
3.3 false Disables automatic minification of JavaScript and CSS resources served by Confluence.
index.queue.thread.count
3.3 See Sets the number of threads to be used for the reindex job. The value has to be in the
"Effect" 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.thread.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.thread.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
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 Captcha 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. Confluence
will change the UI language based on the browser headers. See documentation on how
users can choose a language preference.
upm.pac.disable
Univer false When this property is set to true, then UPM will not try to access the The Atlassian
sal Marketplace. This is useful for application servers that do not have access to the
Plugin Internet. See the UPM documentation.
Manag
er 1.5
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
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 Unable 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 viewx
ls macro. If empty, the maximum size defaults to 2Mb. See CONF-21043 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.
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 Generally a full reindex is not required when upgrading Confluence, but there may be
some occasions where an upgrade task will kick-off the reindex process.
Set this property to true, 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 concurrent 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
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
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
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. The check uses the uncompressed file size,
not the compressed size on disk in the case of .docx files.
See Configuring 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.
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
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 .pptx ) files in Confluence.
confluence.document.conversion.slides.defaultfontname.asian
5.8.7 TakaoP Set this property to change the default font for rendering asian fonts in Powerpoint ( .
Gothic ppt and .pptx ) files in Confluence.
confluence.document.conversion.slides.defaultfontname.symbol
5.8.7 Set this property to change the default font for rendering symbols in Powerpoint ( .ppt a
nd .pptx ) files in Confluence.
This is the font that will be used for bullets and other symbols when the font Symbol is
not found.
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 true which will allow Confluence to be
embedded in an <iframe> .
confluence.cluster.index.recovery.query.timeout
5.9.1 10 In Confluence Data Center, t he 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
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
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 synchrony.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 synchron
y.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) fallback 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.
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 Administering 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.cluster.bind.
From 6.0.4, Confluence Server will accept either reza.bind or synchrony.bind.
synchrony.context.path
6.0.0 /synchro This is the context path for Synchrony. There should be no need to change this in
ny Confluence Server, or when Synchrony is managed by Confluence.
confluence.pdfexport.permits.size
6.0.0 (number This property sets the number of concurrent PDF exports that can be performed. It
of cores) 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 (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. Cha
nge 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
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
00 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
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. See Configuring Attachment Size for more
info.
atlassian.image_filter.transform.max_data_size
6.2.2 16000000 Applying image effects to large images can cause out of memory errors. We prevent
users from applying image effects to images with a data size greater than 16MB.
Set this property, in bytes, to reduce the maximum data size. Note: this is the data size,
not the size of the file on disk.
atlassian.image_filter.transform.max.pixel
6.2.2 4000 Applying image effects to large images can cause out of memory errors. We prevent
users from applying image effects to images larger than 4000x4000 pixels.
Set this property, in pixels, to change the maximum image dimensions.
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
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 maximum number of people the User List macro can
6.7.1 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)
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 external 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.
6.12.
document.conversion.sandbox.request.time.limit.secs
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
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.
conversion.sandbox.memory.limit.megabytes
(formerly document.conversion.sandbox.memory.limit.megabytes)
This property limits the amount of heap memory each process in the external process
pool can consume.
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.
sandbox.error.delay.millis
6.10.0 50 This property sets how often (in milliseconds) document conversion errors are captured
for diagnostic purposes.
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.
conversion.sandbox.java.options
6.10.0 When a document or image 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 external process pool.
Use this property to override the default value of any of the following Confluence Server
system properties (introduced in 7.0.1), and pass new values directly to the JVMs in the
external process pool:
confluence.document.conversion.imaging.convert.timeout
confluence.document.conversion.imaging.enabled.tif
confluence.document.conversion.imaging.enabled.psd
diagnostics.os.check.period.secs
6.11.0 120 Set this property to change how often operating system diagnostics checks should be
performed (in seconds).
This property only applies to the Low free memory (OS-1001) and Low 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-1001).
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-1002).
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
6.11.0 60 This property applies to the HTTP request diagnostic alert (HTTP-1001). 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 (MACRO-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 should be performed (in
seconds).
This property only applies to the Thread memory allocation rate (JVM-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.allocation.monitoring.period.secs), should trigger this alert.
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 diagnostic alert data
that is older than 30 days (the limit set by diagnostics.alert.retention.period.days)
pdf.export.sandbox.disable
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.
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.
pdf.export.sandbox.memory.requirement.megabytes
6.12.0 64 In Confluence Data Center PDF exports are handled by the external 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.limit.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.
synchrony.eviction.soft.job.threshold.hours
7.0.1 72 This property changes the behaviour of the Synchrony soft eviction scheduled job.
It sets the minimum time, in hours, since a Synchrony change log was last modified, to
make it eligible to be cleaned up. By default, only Synchrony change logs last modified
more than 3 days ago, for pages/blogs that do not have an active editing session, will be
evicted.
synchrony.eviction.hard.job.threshold.hours
7.0.1 360 This property changes the behaviour of the Synchrony hard eviction scheduled job
It sets the minimum age, in hours, of content eligible to be evicted by the hard eviction
scheduled job. By default, all Synchrony data for any content that is 15 days or older will
be evicted by this job, regardless of whether it has been modified more recently.
7.0.1 30 When a complex image file (such as ICO, EMF, WMF, plus TIF and PSD if enabled) is
inserted into a page, thumbnails are generated of its contents, so it can be viewed inline
and previewed. This process is known to cause out of memory errors for large or
complex files.
This property sets the amount of time (in seconds) that Confluence will wait for
conversion to complete for an image file, before terminating the process.
This property applies to Confluence Server and Data Center. For Data Center also see D
ocument conversion for Confluence Data Center
confluence.document.conversion.slides.convert.timeout
7.0.1 30 When a presentation file (such as PPT, PPTX, POT) is inserted into a page, thumbnails
are generated of its contents, so it can be viewed inline and previewed. This process is
known to cause out of memory errors for large or complex files.
This property sets the amount of time (in seconds) that Confluence will wait for
conversion to complete for a presentation file, before terminating the process.
This property applies to Confluence Serve and Data Center. For Data Center see Docum
ent conversion for Confluence Data Center.
7.0.1 false When a file is inserted into a page, thumbnails are generated of its contents, so it can
be viewed inline and previewed. By default thumbnails are not generated for TIFF / TIF
as they're known to cause out of memory errors.
Set this property to 'true' to turn on thumbnail generation for TIFF files.
If enabled, a timeout will apply to this type of file. This is set by the confluence.document.
conversion.imaging.convert.timeout system property.
This property applies to Confluence Server and Data Center. For Data Center see Docu
ment conversion for Confluence Data Center
7.0.1 false When a file is inserted into a page, thumbnails are generated of its contents, so it can
be viewed inline and previewed. By default thumbnails are not generated for Photoshop
PSD files as they're known to cause out of memory errors.
Set this property to 'true' to turn on thumbnail generation for PSD files.
If enabled, a timeout will apply to this type of file. This is set by the confluence.document.
conversion.imaging.convert.timeout system property.
This property applies to Confluence Server and Data Center. For Data Center see Docu
ment conversion for Confluence Data Center.
officeconnector.powerpoint.extractor.maxlength
Confluence will only extract content from a PowerPoint presentation 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. See Configuring Attachment Size for
more info.
confluence.chart.macro.width.max
7.2.0 3000 Maximum width, in pixels, that a chart macro can be set to display on a page. If a higher
value is entered, the chart will automatically be reduced to this default.
confluence.chart.macro.height.max
7.2.0 3000 Maximum height, in pixels, that a chart macro can be set to display on a page. If a
higher value is entered, the chart will automatically be reduced to this default.
confluence.search.lucene.termFilterBitSetThreshold
7.2.0 20 Set this property to change the behaviour of the term filter in Confluence's Lucene
based implementation of search. A bitset is only created when the number of matched
documents times the threshold set in this property exceeds total number of documents.
This will reduce memory usage and improve Confluence performance. You shouldn't
need to change this threshold.
page-tree.partial-loading-batch-size
7.3.0 200 Confluence limits the number of pages that initially display at each level of the page
tree. This helps safeguard the performance of your site. Set this property to increase or
decrease the number of pages to initially display at each level of the page hierarchy.
page-tree.partial-loading.disable
7.3.0 false Confluence limits the number of pages that initially display at each level of the page
tree. This helps safeguard the performance of your site. Set this property to true if you
always want all pages to be displayed by default in the page tree.
confluence.word.import.maxsize
7.3.3 20 Sets the maximum uncompressed size, in megabtyes, of a Microsoft Word document
that can be imported into Confluence using the Import from Word feature. This is to
prevent very large files from causing out of memory errors.
gatekeeper.request-timeout.seconds
7.4.0 60 Some open-ended queries can take a long time to display when you Inspect
Permissions in a Confluence Data Center site with a lot of spaces and users. To avoid
this having an impact on your site, we have a timeout.
Set this property to change the length of the timeout, in seconds. You can't set this
lower than 30 seconds, or higher than 900 seconds (15 minutes).
plugin.audit.log.view.sysadmin.only
(formerly audit.log.view.sysadmin.only)
7.5.0 false Set this property to true to restrict the Audit Log page in Confluence Administration to
people with System Administrator global permissions. By default people with System
Administrator or Confluence Administrator global permission can access this feature.
This property applies to Confluence Server and Data Center.
This property was renamed in 7.7.0.
plugin.audit.file.max.file.count
7.5.0 100 In Confluence Data Center, audit events are written to an audit log file in the local home
directory. These log files are rotated once they reach the file size set by plugin.audit.file.
max.file.size.
Set this property to change the total number of audit log files to keep in the file system.
plugin.audit.file.max.file.size
7.5.0 100 In Confluence Data Center, audit events are written to an audit log file in the local home
directory.
Set this property to change the maximum file size, in megabytes, that a log file can
reach before the log is rotated.
NumberItemPerPageOfPaginatedListAction
7.5.0 30 Sets the number of items to be listed on the Undefined Pages and Restricted Pages
tabs in Space Tools before Confluence paginates the results.
Set this property to change the number of items to display per page.
CachingEnablingItemNumber
7.5.0 1000 The Undefined Pages tab in Space Tools provides a list undefined links to pages that do
not yet exist. As this list can be quite memory intensive to generate, the results are
cached.
Set this property to change the maximum number of undefined link references to cache.
CachingEnablingItemTimeout
7.5.0 5 The Undefined Pages tab in Space Tools provides a list undefined links to pages that do
not yet exist. As this list can be quite memory intensive to generate, the results are
cached.
Set this property to change the amount of time, in minutes, the results should be cached
(time to live).
confluence.event.duration_checker.threshold_in_seconds
7.6.2 60 When asynchronous events are generated faster than Confluence can process them,
we write a message to the application log to advise that we'll process each task
synchronously until the queue is cleared.
Set this property to change how often this message appears, in seconds.
confluence.mailserver.tls.hostname.verification.disabled
7.6.2 false Set this property to true if you need to disable TLS hostname verification for any
SMTP mail servers you've configured in Confluence. This is not recommended as it can
increase the risk of a Man In The Middle attack.
atlassian.image_filter.transform.max.pixel.drop_shadow
7.7.0 2000 Applying a drop shadow image effect to large images can cause out of memory errors.
We prevent users from applying a drop shadow to images larger than 2000x2000 pixels,
or the value set by atlassian.image_filter.transform.max.pixel (whichever is smallest).
Set this property, in pixels, to change the maximum image dimensions for drop shadow.
pagePropertiesReportContentRetrieverMaxResult
7.7.0 3000 The Page Properties Report macro displays a maximum of 3000 pages. Set this
property to decrease the maximum number of pages the macro can display. We don’t
recommend you increase this limit, as it can have a performance impact on your site.
confluence.webhooks.allow.all.hosts
7.7.0 false Set this property to true allow administrators to configure localhost URLs as a webhook
endpoint. This is disabled by default for security reasons because all ports on the same
network can be pinged by the UI.
On this page:
Confluence uses Apache's log4j logging service.
This allows administrators to control the logging
behavior and the log output file by editing a Finding the Confluence log files
configuration file. There are six log4j logging levels. Finding the log configuration file
Changing the destination of the log files
If you request help from Atlassian Support, we will Changing the size and number of log files
almost always ask for the Confluence application Changing the logging levels
logs. The easiest way to get these logs is to go to Specific Confluence logging options
> General Configuration > Troubleshooting Scanning log files for known problems
and support tools and follow the prompts to create
a Support Zip. 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
/atlassian-confluence.log. For example: c:/confluence/data/logs/atlassian-
confluence.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
/confluence-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.
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.
For more detailed information see Configuring log4j in Confluence to send specific entries to a different log
file in our Knowledge Base.
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.
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.
properties 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.
foo.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

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
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
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.translate
(SQLStateSQLExceptionTranslator.java:88)
caused by: java.sql.BatchUpdateException: Duplicate entry '1234' for key 1
at com.mysql.jdbc.ServerPreparedStatement.executeBatch(ServerPreparedStatement.java:647)
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.
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

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
types of jobs which can be scheduled cover: Accessing Confluence's scheduled jobs
configuration
Confluence site backups Running a job manually
Storage optimization jobs to clear Changing a job's schedule
Confluence's temporary files and caches Disabling or re-enabling a job
Index optimization jobs to ensure Viewing a job's execution history
Confluence's search index is up to date Types of jobs
Mail queue optimization jobs to ensure Cron expressions
Confluence's mail queue is maintained and
notifications have been sent. Related pages:
You'll need System Administrator permissions in Trigger Module

order to edit and manually run jobs. Configuring Backups
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
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.
Types of jobs
Here's a summary of some of the scheduled jobs that you may want to adjust.
Job Description Execution Default

Name Behavior Schedule
Back Up Performs a backup of your entire Confluence site. Per cluster At 2am
Confluence every day
Check For clustered Confluence installations, this job ensures that only Per cluster Every 30
Cluster one Confluence instance in the cluster writes to the database at seconds
Safety 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 Periodically clears journal entries that have already been Per cluster At 2am
Journal processed to ensure that its size does not grow indefinitely. every day
Entries
Clean Cleans up temporary files generated in the <confluence- Per node At 4am
Temporary home>/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 Clears notification errors in the mail error queue. A notification Per cluster At 3am
Expired error is sent to the mail error queue whenever the notification every day
Mail Errors fails to be sent due to an error.
Clear Clears all expired 'Remember Me' tokens from the Confluence Per cluster On the
Expired site. Remember Me tokens expire after two weeks. 20th of
Remember each
Me Tokens month
Email Emails a daily summary report of all Confluence changes to all Per cluster At 12am
Daily subscribers. every day
Reports 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 Flushes the Edge Index Queue so Confluence's search results Per node Every 30
Edge stay up to date. seconds
Index
Queue
Flush Flushes the local task queue. (These are internal Confluence Per node Every
Local tasks that are typically flushed at a high frequency.) minute
Task
Queue
Flush Mail Sends notifications that have been queued up in the mail queue. Per node Every
Queue This doesn't include batched notifications. Edit the Send minute
batched notifications job if you also want to change how often
notifications are sent for changes to a page or blog post.
Send Sends email notifications containing all changes to a page or Per cluster Every 10
batched blog post since the last time the job ran. Increase the time for minutes
notifications fewer emails or reduce the time if more immediate notifications
are important in your site.
Flush Flushes the task queue. (These are internal Confluence tasks Per node Every
Task that are typically flushed at a high frequency.) minute
Queue
Send Triggers sending recommended update emails to users. The job Per cluster Hourly
Recomme runs hourly, but users will receive the notification weekly or
nded daily, depending on the setting in their profile, at a time that
Updates matches their timezone.
Email
Purge Old Confluence stores the details of each scheduled job that is run Per cluster at 11pm
Job Run in the scheduler_run_details table in your database. In every day
Details 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.hours
and unsuccessful.jobs.ttl.hours.
Property When a page is created from a blueprint, some data is left Per cluster At 12am
Entry behind in the os_property table after the page is published. This every day
Gardening job cleans up leftover data, which could contain personally
identifiable information.
Clean up This job cleans up metadata stored about draft pages created Per cluster At 2:23am
unpublishe from blueprints, which could contain personally identifiable every day
d information.
Blueprint
Page
Entities
Synchrony Evicts Synchrony data for any content that has not been Per cluster Every 10
data modified in the last 3 days, and does not have an active editor minutes
eviction session. See How to remove Synchrony data for more
(soft) information.
Synchrony Evicts Synchrony data for any content that is 15 days or older, Per cluster Disabled
data regardless of whether it has been modified more recently. See H by default
eviction ow to remove Synchrony data for more information.
(hard)
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 Time Permitted Required?

cron interval 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.
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 Allows all URLs from the specified domain. https://www.example.

name com
Exact match Allows only the specified URL. https://www.example.

com/thispage
Wildcard Allows all matching URLs. Use the wildcard * character to https://*example.com
Expression replace one or more characters.
Regular Allows all URLs matching the regular expression. http(s)?://www\.

Expression example\.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

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:

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
Confluence saves a draft of your page once every thirty seconds by default.
Related pages:
Confluence administrators can configure how often drafts are saved.
Drafts
To set the time interval at which drafts are saved:

2. Click Further Configuration in the left-hand panel.
3. Edit the setting for Draft Save Interval.
This setting applies regardless of whether collaborative editing is on or off.

When collaborative editing is on, every keystroke is also saved by
Synchrony in real time.
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 Environment
Configuring Secure Administrator Sessions Confluence administrator's guide
Confluence Cookies
Best Practices for Configuring Confluence
Security
Hiding External Links From Search Engines
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 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
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
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, This is the default option. Use this option when you don't
for unproxied HTTP access to Confluence have a reverse proxy and are not enabling HTTPS.
HTTP - Proxying Confluence via Apache or Choose this option if you have a reverse proxy, but are not
Nginx over HTTP enabling HTTPS.
HTTPS - Direct connector with no proxy, for Choose this option if you want to use HTTPS without a
unproxied HTTPS access to Confluence. reverse proxy. HTTPS will be terminated at Tomcat.
HTTPS - Proxying Confluence via Apache or Use this option when you want to use a reverse proxy and
Nginx over HTTPS 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.
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:
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.
auth.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 CONFSERVER-16941 CLOSED .
Connecting to LDAP or Jira applications or Other
Services via SSL
This page documents configuration of SSL, Related pages:
rather than of Confluence itself. Atlassian
Configuring an SSL Connection to Active
will support Confluence with this
Directory
configuration, but we cannot guarantee to
Configuring Web Proxy Support for
help you debug problems with SSL. Please
Confluence
be aware that this material is provided for
Running Confluence Over SSL or HTTPS
your information only, and that you use it at
your own risk.
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:
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.
You can find additional documentation that explains Base configuration
how to use NGINX for the same purpose. 1 Set the context path
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 Compression
want to add Confluence (for example, http:// 6 Change the Confluence Base URL
www.example.com/confluence). Adding SSL
You have two or more Java applications, More information
each running in their own application server
on different ports, for example, http://exampl
e:8090/confluence and http://example:8080
/jira and want to make them both available
on the regular HTTP port (80) (for example,
at http://www.example.com/confluence and
http://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
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).

In XML a comment starts with , and is used to make sure only the relevant
portions of the file are read by the application.
Add  around the default connector. It should now look like this.


Uncomment the connector listed under the HTTP - Proxying Confluence via Apache or Nginx over HTTP
heading.
To uncomment a section, remove the  surrounding the connector.
Here's an example showing the default connector commented out, and the HTTP connector
uncommented. The headings remain commented out.



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:

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.
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.
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.
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.
example.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.
The configuration described on this page results in Step 1: Set the context path
a scenario where: Step 2: Configure the Tomcat connector
Step 3: Configure NGINX
External client connections with NGINX are Step 4: Restart Confluence and NGINX
secured using SSL. Connections between
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-
directory>/conf/server.xml, locate the "Context" definition:
<Context path="" docBase="../confluence" debug="0" reloadable="false">
and change it to:
<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).

In XML a comment starts with , and is used to make sure only the relevant
portions of the file are read by the application.
Add  around the default connector. It should now look like this.


Uncomment the connector listed under the HTTPS - Proxying Confluence via Apache or Nginx over
HTTPS heading.
To uncomment a section, remove the  surrounding the connector.
Here's an example showing the default connector commented out, and the HTTPS connector
uncommented. The headings remain commented out.


...

scheme="https" secure="true" proxyName="<subdomain>.<domain>.com" proxyPort="443"/>
Insert your proxyName and proxyPort as shown in the last line below:

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.
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-RSA-
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_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-

generator/ 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 allow users to use the Confluence mobile app with your site, and you have configured a
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, your config will look like this:
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-ECDSA-
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: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 / {
client_max_body_size 100m;
proxy_pass http://localhost:8090;
}
location /synchrony {
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
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
data are encrypted during transport to and from Step 1. Create or request an SSL certificate
Confluence. This is a good way to safeguard your Step 2. Modify your Confluence server.xml
Confluence data and user logins from being 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 base URL
to the protocol used to encrypt traffic. In most cases 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).
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. 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-
alsoCalledBundleCertificateInGoDaddy> -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. Edit <install-directory>/conf/server.xml.
2. Uncomment the following lines:
<Connector port="8443" maxHttpHeaderSize="8192"

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. Change the value of maxThreads to be at least 10 threads (or 25%) less than the size of your
database connection pool. 48 is usually about right. See HTTP MaxThreads configuration for more
information about this.
6. 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:
<Connector port="8443" maxHttpHeaderSize="8192"

maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
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.
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:

8443/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
/web.xml, as described above.
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.
xml 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"
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.NonLoginAuthenticator"
disableProxyCaching="true" securePagesWithPragma="false" />
Using Apache to limit access to the Confluence
administration interface
As well as limiting access to the Confluence administration console to users who really need it, and using strong
passwords, you can consider limiting access to certain machines on the network or internet. If you are using Apa
che web server, this can be done with Apache's Location functionality.
To limit access to admin screens to specific IP addresses in Apache:
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. In your Apache Virtual Host, add the following lines to restrict the administration actions to the Systems
Administrator.
Define segmentregex (?:;[^/]*)?(?:/)?(?:(?:;[^/]*)?(?:/)?)*

<LocationMatch (?i)/confluence${segmentregex}/admin>
Include sysadmin_ips_only.conf
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/plugins${segmentregex}/servlet${segmentregex}
/oauth${segmentregex}/consumers${segmentregex}/list>
</LocationMatch>
/oauth${segmentregex}/view-consumer-info>
</LocationMatch>
/oauth${segmentregex}/service-providers${segmentregex}/list>
</LocationMatch>
/oauth${segmentregex}/service-providers${segmentregex}/add>
</LocationMatch>
/oauth${segmentregex}/consumers${segmentregex}/add>
</LocationMatch>
/oauth${segmentregex}/consumers${segmentregex}/add-manually>
</LocationMatch>
/oauth${segmentregex}/update-consumer-info>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/pages${segmentregex}/templates${segmentregex}
/listpagetemplates.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/pages${segmentregex}/templates${segmentregex}
/createpagetemplate.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/spacepermissions.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/pages${segmentregex}/listpermissionpages.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/removespace.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/importmbox.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/viewmailaccounts.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/addmailaccount.action?>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/importpages.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/flyingpdf${segmentregex}
/flyingpdf.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/exportspacehtml.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/spaces${segmentregex}/exportspacexml.action>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/plugins${segmentregex}/servlet${segmentregex}/embedded-
crowd>
</LocationMatch>
<LocationMatch (?i)/confluence${segmentregex}/plugins${segmentregex}/servlet${segmentregex}/upm>
</LocationMatch>
This configuration assumes you're running Confluence with the context path '/confluence'. If you
are running with a different context path, or no context path, adjust the sample above accordingly.
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:

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-
20958 "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.
Authentication
Authentication cookies cookies
Other Confluence
Confluence uses Seraph, an open source framework, for HTTP cookie 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.
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.
The default time to live of this cookie is two weeks.
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-
INSTALLATION/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>259200</param-value>
</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
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.
Cooki Purpose Cookie Contents Expiry

e Key
confl Remembers the user's last chosen tab in the "list pages" The name of the last One year
uence section. selected tab. For from the
.list. example, list-content- date it
pages tree was set or
. was last
cookie updated.
confl Remembers the user's last chosen tab in the "browse The name of the last One year
uence space" section selected tab. For from the
. example, space-pages date it
brow was set or
se. was last
space updated.
.
cookie
confl Remembers the user's language chosen on the login A locale relating to the 360 days
uence page. This cookie relates to a feature that allows a user to chosen language. For from the
- change Confluence's language from (and including) the example, de_DE date it
langu login page, when the language presented to the user prior was set or
age to logging in is not appropriate. was last
updated.
AJS. Tracks which general tabs were last used or expansion One or more key-value One year
congl elements were last opened or closed. strings which indicate from the
omer the states of your last date it is
ate. general tab views or set or was
cookie expansion elements. last
updated.
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.
What is Fail2Ban?
We need a means of defending sites against brute-force login attempts. Fail2Ban is a Python application which
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.
Prerequisites
Requires Python 2.4 or higher to be installed

Requires Apache Reverse Proxy 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
# 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
[Definition]
failregex = <HOST>.*"GET /login.action
ignoreregex =
When opened in a viewport, the user will be redirected to: Proxy and HTTPS setup for Confluence.
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
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.
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.
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
being added, in the form of comments or new pages. Configuring Confluence Security
You can configure Confluence to deter automated

spam by asking users to prove that they are human
before they are allowed to:
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:

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:

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
wiki-spamming it's hoped that the practice will stop being cost-effective and eventually die out.
If you have confluence administrator permissions,
On this page:
you can configure Confluence to impose a
maximum number of repeated login attempts. After
a given number of failed login attempts (the default Enabling, Disabling and Configuring
is three) Confluence will display a Captcha form Captcha for Failed Logins
asking the user to enter a given word when Notes
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:

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

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.
confirmation.disabled system property to disable the password confirmation functionality on ad
ministrative actions, change of email address and Captcha for failed logins. See Recognized System
Properties.
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.
Read more about XSRF (Cross Site Request Forgery) at cgisecurity.com.
To configure XSRF protection for comments:

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:
Security
Confluence Administrator's
Guide
Developer documentation on
XSRF protection in Confluence
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:

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

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:

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.
A Confluence System Administrator can configure
On this page:
the following aspects of RSS feeds:
The maximum number of items that Notes

Confluence returns to an RSS feed request.
The maximum time period that Confluence Related pages:
allows to respond to an RSS feed request.
The RSS Feed Builder
Both of these are set in the 'Edit Security
Configuration' screen.
To configure RSS feeds:

al 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.
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:
SELECT bodycontentid,body FROM bodycontent WHERE contentid IN

(SELECT contentid FROM content WHERE contenttype='USERINFO')
ORDER BY bodycontentid DESC;
3.
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:
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

Starting Confluence Automatically on System Startup
Diagram: A Confluence installation

Confluence Home and other important directories
Confluence installation directory On this page:
The 'Confluence Installation directory' is the
directory where Confluence was installed. This Confluence installation directory
directory is also sometimes called the 'Confluence Confluence home directory
Install directory'. Changing the location of the home 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
/confluence-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'. We also refer to
this as the 'local home directory' in Data Center.
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
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 Purpose
directory
conflue This file contains all of the information necessary for Confluence to start up, such as:
nce.
cfg.xml Product license
Context path
Database details, such as location and connection pool settings
Paths to important directories
attachm This directory contains every version of each attachment stored in Confluence.
ents/
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.backup.dir prop
erty in confluence.cfg.xml.
bundled Confluence includes a set of bundled plugins. The bundled-plugins directory is where
- Confluence will unpack its bundled plugins when it starts up. This directory is refreshed on
plugins/ 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.
databas This is where Confluence stores its database when configured to run with the Embedded H2
e/ 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 pr
operty 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.
plugin- All Confluence plugins are stored in the database. To allow for quicker access to classes
cache/ 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 <confluence-home>
/confluence.cfg.xml and set the new location in the webwork.multipart.saveDir
property. Your new location can't be in the installation directory, as this will cause some
functions, such as download, to fail. We recommend you keep the temp directory in the local
home directory.
thumbna Stores temporary files for image thumbnails. This directory is essentially a thumbnail cache,
ils/ and files deleted from this directory will be regenerated the next time the image is accessed.
shared- This sub-directory is created in your home directory when you install Confluence Server. If
home/ you choose move to Data Center, you'll move the contents of this directory to a seperate
shared home directory, that is accessible to all nodes.
Cache files for some features, including Office document and PDF previews are also stored
in this directory (in both Server and Data Center).
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-
init.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
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
directory.
There's a known issue with setting a temp directory in Confluence. See

CONFSERVER-59613 - java.io.tmpdir has no effect on changing the installation temp directory
GATHERING IMPACT
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

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
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.
#!/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:
$ 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
/local/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:
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-
down:
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
RELATED TOPICS
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%
If you installed the Java Runtime Environment (JRE) or used the Confluence installer, replace JAVA_HOME
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
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
to 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
On this page:
improved performance. It is not a guide to
troubleshooting Confluence outages. Check Trouble
shooting Confluence hanging or crashing for help if Performance Data Collector
Confluence is crashing. Use the latest version of your tools
Avoid swapping due to not enough RAM
Like any server application, Confluence may require Being aware of other systems using the
some tuning as it is put under heavier use. We do same infrastructure
our best to make sure Confluence performs well Choice of database
under a wide variety of circumstances, but there's Database connection pool
no single configuration that is best for everyone's Database in general
environment and usage patterns. Database statistics and query analyzers
Cache tuning in Confluence and Apache
If you are having problems with the performance of Antivirus software
Confluence and need our help resolving them, you Enabling HTTP compression
should read Requesting Performance Support. Performance testing
Access logs
Performance Data Collector Built-in profiler
Application server memory settings
The Performance Data Collector is a server-side, Web server configuration
standalone application that exposes a number of Troubleshooting possible memory leaks
REST APIs for collecting performance data. It can
be used to collect data, such as thread dumps, disk
speed and CPU usage information, to troubleshoot
performance problems.
See How to use the Performance Data Collector for

more information.
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

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

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.
Before you change the size of your caches, it's Cache tuning example
important to take a baseline so you can measure Important caches
how effective each individual change is, and decide
whether they are needed.
On this page we'll take you through some example

statistics and discuss how you might be able to
improve Confluence performance by resizing these
caches.
If you just want to check your cache statistics, or

make a change to your cache config, see Cache
Statistics.
Cache tuning example
As an example of how to tune Confluence's caches, let's have a look at the following table:
Caches % Utilization % 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 evicted from the cache. Cache expiry can
be based on time or on frequency of use.
There's 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.
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.

CachedCrowdUserDao.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
Caches help reduce the load on your database, and
On this page:
can make some operations faster. Track the size
and hit ratio of each of Confluence's internal
caches, and adjust the cache size for better View cache statistics
performance. View cache statistics in a cluster
What the statistics mean
Cache types
Change the size of a cache
View cache statistics

To view cache statistics:
1. Go to > General Configuration > Cache Management.

2. Select Show Advanced View to see the full details.
Screenshot: Cache statistics screen showing the utilisation and effectiveness of a selection of caches.
View cache statistics in a cluster
If you're running Confluence in a cluster, this screen shows the statistics for the node you're currently on.
To view cache statistics for another node in the cluster:
1. Go to > General Configuration > Clustering.

2. Select > Cache statistics next to the node you want to view.
You will only be able to view the statistics. To flush a cache or adjust the size, you'll need to access the
Cache Management screen on each node directly.
What the statistics mean
Here's some information on how each number is generated.
Capacity =(Objects)/(Size)
Utilization
For example Percent Used = 4023 / 5000 = 80%
Effectiveness =(Hits)/(Hits + Misses)

:
For example Effectiveness = 374550 / (374550 + 140460) = 73%
Current / The number of entries in the cache / the number of total possible entries allowed (this is
Max Entries the size of the cache).
Current Heap memory (in MB) allocated to this cache (if applicable)
Heap Size
Hit / Miss / The number of reads accessing cache where required content was found / the number
Evicted 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.
Cache types
When running in a cluster, Confluence has three types of caches:
local - cache data is replicated on each node.

distributed - cache data is evenly partitioned across all Confluence nodes in the cluster (known as
replicate-via-copy).
hybrid - cache data is replicated on each node, and invalidated remotely by other nodes when things
change (known as replicate-via-invalidation).
The cache type is indicated with a lozenge beside the cache name in the advanced view.
Screenshot: Cache statistics advanced view showing the full details of each cache, including the cache type.
Change the size of a cache

Tuning the size of a cache can speed up Confluence (if the caches are too small), or reduce memory (if the
caches are too large). Larger caches will require more memory at runtime, so make sure you review the
memory allocation of the Confluence Java process and the physical memory available on your server.
You need System Administrator global permission to change the size of a cache.
To change the size of a cache:
1. Go to > General Configuration > Cache Management.

2. Select Show Advanced View.
3. Select Adjust Size next to the cache you want to change.
4. Enter the maximum number of items to be stored in the cache and select Submit.
The changes will take effect immediately. You don't need to restart Confluence.
Any changes to cache sizes are recorded in:
<home-directory>/shared-home/config/cache-settings-overrides.properties if
you run Confluence on a single server.
<shared-home>/config/cache-settings-overrides.properties if you run Confluence in
a cluster.
To reset the values back to the default, you can delete the cache-settings-overrides.properties fil
e and restart Confluence.
See Performance Tuning for a more general overview of tuning in Confluence.
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
of memory for its caches, but it should still be able Increasing the amount of memory
to run quite well in low-memory environments, with available to Confluence
the right tuning. Below are some tips on getting the Embedded database
most out of your Confluence site. Caching
Mail error queue
Increasing the amount of memory available Attachments
System backup and restore
to Confluence
Known issues that we do not have control
over
See Increasing JIRA Memory for details on how to
Confluence is taking long periods of time
increase the memory available to web application
to respond to some actions
servers typically used to run Confluence.
Related pages:
Embedded database
Performance Tuning
The embedded HSQL database that comes with Requesting Performance Support
Confluence essentially holds all your data in
memory while the Confluence server is running. If
you are running out of memory, you should consider
migrating 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 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.
Basic performance troubleshooting steps On this page:
Begin with the following procedures:
Basic performance troubleshooting steps
1. Go through the Troubleshooting Confluence Requesting basic performance support
hanging or crashing page to identify the Advanced performance troubleshooting
major known performance problems.
2. Proceed with the Performance Tuning tips to Related pages:
help optimize performance.
Confluence for Enterprise
Requesting basic performance support
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
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
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
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: filenameRegex
p = 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
Confluence down.
Enabling HTTP Compression

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.
The information on this page relates to memory management with Oracle's Hotspot JVM. These
recommendations are based on our support team's successful experiences with customers with large
Confluence instances.
Which garbage collector?

Confluence uses the garbage first garbage collector (G1GC) by default. This is the garbage collector we
recommend.
See Garbage First Garbage Collector Tuning in the Oracle documentation for useful information on tuning this
garbage collector.
We have also observed that G1GC performs better with a larger heap (2gb). See the information below about
how to increase your heap size gradually.
Don't use the Concurrent Mark Sweep (CMS) Collector with Confluence, unless advised by Atlassian
Support. It requires extensive manual tuning and testing, and is likely to result in degraded performance.
Use the right size 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.
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, see our Garbage Collection (GC) Tuning
Guide. This document was put together a few years ago, but has some useful information on 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
complete each action made on any Confluence Enabling Page-Request Profiling
page. If Confluence is responding slowly, an internal Profiling an Activity
timing trace of the slow page request can help to Example of a Profile
identify the cause of the delay. Start Confluence with Profiling Enabled
You will need access to the Confluence server to Related pages:

view a profile.
Enabling Page-Request Profiling Working with Confluence Logs
To see just the slow performing macros,

see Identifying Slow Performing Macros.
You need System Administrator global permissions to enable or disable profiling.
To enable or disable page profiling:
1. Go to > General Configuration > Logging and Profiling.

2. Choose Enable Profiling or Disable Profiling.
There is a known issue with the logging and profiling screen. See
CONFSERVER-58861 - Turning on profiling has no effect on generated logging
GATHERING IMPACT
As a workaround you can enable profiling manually:
1. Go to > General Configuration > Logging and Profiling

2. Under Add a new entry, paste the following into the Class/package name field
com.atlassian.util.profiling.Timers
3. Set the logging level to DEBUG.

4. Choose Add Entry.
To disable profiling, find the com.atlassian.util.profiling.Timers entry in the list and

choose Remove.
Screenshot: Changing Log Levels and Profiling

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.
[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()
[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.ConfluenceProfilingFilter</filter-class>
<init-param>


<param-name>activate.param</param-name>
<param-value>profile</param-value>
</init-param>
<init-param>


<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
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
rendering. Processed text: {create-space-button}
rendering. Processed text: {recently-updated-dashboard:dashboard|showProfilePic=true}
rendering. Processed text: {favpages:maxResults=10}
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
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 8192MB, 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
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 > General Configuration > Analytics.
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
Head to Collaborative editing to find out how your Change the editing mode
team can work together in real time on software What happens to existing drafts
requirements, meeting notes, retros, and any other when the mode changes?
Confluence page you can think of. Maximum editor limit
About Synchrony No version history in unpublished
drafts
Collaborative editing is powered by Synchrony Visibility of edits made by
which synchronizes data in real time. Synchrony is anonymous users
managed by Confluence, so administrators should Proxy and SSL considerations
rarely need to interact with it directly. SSL
Proxies
Synchrony runs on port 8091 by default, and an WebSockets
internal Synchrony proxy means that you shouldn't Change your Synchrony configuration
need to open this additional port. Start and stop Synchrony
Monitor Synchrony
How you connect to Synchrony will depend on your Accessing Synchrony logs
environment, and your Confluence license. See Pos Managing Synchrony data
sible Confluence and Synchrony Configurations.
Related pages:
To see your collaborative editing and Synchrony setup, head to > General Configuration > Collaborativ
e 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.
To change the editing mode:
1. Go to > General Configuration > Collaborative editing.

2. Choose Change mode.
3. Select either On or Off and choose Change.
Changing the editing mode is not trivial, so it is good to understand the implications of each mode.
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.
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. Consider turning collaborative editing on for the full
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).
It's a good idea to prompt your users to publish any shared drafts before you turn collaborative
editing off, as they will not be able to resume editing existing shared drafts or unpublished
changes.
What happens to existing drafts when the mode changes?
Users can always access any existing personal drafts and shared drafts from the Drafts page in their profile.
Whether they can resume editing the draft depends on the editing mode.
When collaborative editing is ON, users will be able to discard or resume editing any personal or shared
drafts. A personal draft will be converted to a shared draft when a user resumes editing.
When collaborative editing is OFF, users will be able to discard or resume editing any personal drafts. They
can't resume editing existing shared drafts, but can view and copy the contents of those drafts.
Shared drafts will only appear in a user's Drafts page if, when collaborative editing was on, they:
created a draft, and never published it

edited a published page, and did not publish their changes.
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.
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
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.
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-
synchrony.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-
home>/logs directory, with the Confluence application logs.
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).
To learn how to change the logging level, see Configuring Synchrony.
Managing Synchrony data

Each page and blog post has its own Synchrony change log, which contains a graph of all edits to that page
or blog post. In busy Confluence sites the database tables that store the Synchrony change logs can grow
very quickly, and because the change logs store all changes as they happen, they may retain personally
identifiable information, even after the page they relate to has been deleted.
We provide two scheduled jobs for removing Synchrony data:
Synchrony data eviction (soft)

Synchrony data eviction (hard).
The soft eviction job runs regularly in the background. The hard eviction job is available for when you need
to remove Synchrony data more aggressively, and is disabled by default.
See How to remove Synchrony data for more information on how these jobs work.
Possible Confluence and Synchrony Configurations
Synchrony is the engine that powers collaborative
On this page:
editing in Confluence.
There are a few different options for running Possible configurations for Confluence
Synchrony, and it is worth taking some time to Server
determine which option will best meet the needs of Possible configurations for Confluence
your organisation. Data Center
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).
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.
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.

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.
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.
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.
In most cases, two Synchrony nodes will be adequate for multiple Confluence nodes.
For a step-by-step guide to setting up your Synchrony cluster, see Set up a Synchrony cluster for
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.
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
changing the Synchrony port or memory settings, are made via system Passing
properties. How you pass these properties depends on whether Synchrony recognized system
is managed by Confluence, or deployed as a seperate cluster. properties to
Synchrony
In most cases, Synchrony is managed by Confluence. Common
configuration
If you have a Data Center license, you may choose to deploy and manage S changes
ynchrony standalone in a cluster, instead of allowing Confluence to Change the
manage Synchrony for you. See Possible Confluence and Synchrony logging level for
Configurations for more information. managed
Synchrony
Change the
logging level for
Synchrony
standalone
Troubleshooting
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
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.
properties 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.
If you're running 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 running Confluence in a cluster, we recommend you increase the maximum heap size to at least
2gb on each node.
Change the logging level for managed Synchrony

The logging level for managed Synchrony is set to INFO by default. If you find this too verbose, you can
decrease the logging level to WARN or ERROR.
To change the managed Synchrony logging level:
1. Create a file called synchrony-log4j.properties with the following content:
log4j.rootLogger=WARN, stdout
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target=System.out
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p [%t] [%c{4}] %m%n
In this example we'll set the logging level to WARN . Replace this with ERROR if you only want to log
errors.
2. Save the file. You can place the file anywhere, but we recommend your home directory (or shared
home) alongside the synchrony-args.properties file.
3. Edit your <home-directory>/synchrony-args.properties file. If you're running Confluence
in a cluster, this will be in your shared home directory.
4. Add the following line to tell Synchrony where to find your log configuration.
log4j.configuration=file://<path-to-file>/synchrony-log4j.properties
Replace <path-to-file> with your file path. In Linux this will be something like =file:///var
/confluence/local-home/synchrony-log4j.properties, for example.
5. In Confluence, go to > General Configuration > Collaborative editing and select Restart
Synchrony to pick up the changes.
Exclude the Confluence DEBUG prefix
Because Synchrony is managed by Confluence, the Synchrony logs include a prefix with information from
Confluence itself. You can omit this prefix to make the logs easier to read.
To omit the Confluence DEBUG prefix from the Synchrony logs:
1. Edit the <install-directory>/confluence/WEB-INF/classes/log4j.properties file.

2. Change the log4j.appender.synchronylog.layout.ConversionPattern line to remove %d
%p [%t] [%c{4}] as follows:
log4j.appender.synchronylog.layout.ConversionPattern=%m%n
3. Save the file, then restart Confluence to pick up the changes.
If you're running Confluence in a cluster, you'll need to repeat this process on each Confluence node.
Change the logging level for Synchrony standalone

If you choose to deploy and manage Synchrony standalone in a cluster, you can configure the logging
level in your start-synchrony script.
To change the Synchrony standalone logging level:
1. Create a file called synchrony-log4j.properties with the following content:
log4j.rootLogger=WARN, stdout
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target=System.out
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p [%t] [%c{4}] %m%n
log4j.category.com.hazelcast=INFO
log4j.category.hazelcast=INFO
In this example we want to set the logging level to WARN . Replace this with ERROR if you only want to
log errors. We keep the Hazelcast logging level at INFO so you can still see the Synchrony nodes
communicating with each other.
2. Save the file. You can place the file anywhere, but we recommend your Synchrony directory.
3. Edit your <synchrony-directory>/start-synchrony.sh or start-synchrony.bat file.
4. Add the following line in the Optional Overrides section to tell Synchrony where to find your log config:
log4j.configuration=file://<path-to-file>/synchrony-log4j.properties
5. Restart Synchrony to pick up the changes.
Repeat this process on each Synchrony node.
Troubleshooting
If you have a Data Center license, and Synchrony is managed by Confluence, we recommend storing
the synchrony-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.
properties 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:
managed by Confluence (recommended) Architecture overview

Confluence will automatically launch a Set up a Synchrony standalone cluster
Synchrony process on the same node, and 1 Provision your Synchrony nodes
manage it for you. No manual setup is 2 Create the Synchrony home
required. directory
Standalone Synchrony cluster (managed 3 Edit the start and stop scripts
by you) 4 Add additional Synchrony nodes
You deploy and manage Synchrony and configure your load balancer
standalone in its own cluster with as many 5 Start Confluence one node at a
nodes as you need. Significant setup is time
required. 6 Enable collaborative editing
Required properties for Synchrony
If you want simple setup and maintenance, we standalone
recommend allowing Confluence to manage Optional properties for Synchrony
Synchrony for you. If you want full control, or if standalone
making sure the editor is highly available is Run Synchrony standalone in an IPv6
essential, then managing Synchrony in its own environment
cluster may be the right solution for your Run Synchrony standalone as a service
organisation. 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 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.
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.
4. Make sure the Synchrony port (8091) is open. Ports used by Atlassian Applications has a good
summary of all ports Synchrony uses in Data Center. This is the only one that needs to be open.
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.
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>/synchrony/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.
url.
See How to check the status of Synchrony for Confluence Data Center for more info on how to check
Synchrony is running.
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.
Property Description
name
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 This is the URL for your Confluence database. For example jdbc:postgresql://yourse
_URL rver:5432/confluence . You can find this URL in <local-home>/confluence.cfg.
xml .
DATABASE This is the username of your Confluence database user.

_USER
DATABASE (Optional) This is the password for your Confluence database user. If your password
_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_PASSWORD. Any dots (".") in variable names
(identifiers) will need to be replaced with underscores ("_").
CLUSTER_ This determines how Synchrony should discover nodes. You'll be prompted to uncomment a
JOIN_PRO set of parameters for either:
PERTIES
TCP/IP
Multicast
AWS
Follow the prompts in the script for the values you need to enter for each of these.
DATABASE This is the path to your database driver file. If you're running Synchrony on its own node,
_DRIVER_ you'll need to copy your database driver to an appropriate location then provide the path to
PATH this location.
SYNCHRON This is the path to the synchrony-standalone.jar file you copied to this node.
Y_JAR_PA
TH
SYNCHRON This is the URL that the browser uses to contact Synchrony. Generally this will be the full
Y_URL URL of the load balancer Synchrony will run behind plus the Synchrony context path, for
example http://yoursite.com: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 You can choose to specify additional system properties. See the table below for recognised
_OVERRID Synchrony system properties.
ES
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 Default Description

name
cluster. 5701 This is Synchrony's Hazelcast port. Specify this property if you do not want to
listen. use port 5701 or if it is not available.
port
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.
synchron 25500 This is the Aleph binding port. Synchrony uses Aleph to communicate
y. between nodes. Specify this property if you don't want to use the default.
cluster.
base.
port
cluster. 224.2.2.3 If the cluster join type is multicast, you can specify an IP address for the
join. multicast group if you don't want to use the default.
multicas
t.group
cluster. 54327 If the cluster join type is multicast, you can specify a multicast port if you
join. don't want to use the default.
multicas
t.port
cluster. 32 If the cluster join type is multicast, this is the time to live threshold. The
join. default, 32, means the scope is restricted to the same site, organization or
multicas department. Specify this property if you want to use a different threshold.
t.ttl
cluster. If the cluster join type is AWS, this is your AWS access key.
join.
aws.
access.
key
cluster. If the cluster join type is AWS, you can authenticate by IAM role or Secret
join. key. This is your AWS secret key.
aws.
secret.
key
cluster. If the cluster join type is AWS, you can authenticate by IAM role or Secret
join. key. This is your AWS IAM role.
aws.iam
cluster. us-east-1 If the cluster join type is AWS, this is the AWS region your Synchrony nodes
join. will be running in.
aws.
region
cluster. If the cluster join type is AWS, and you want to narrow the members of your
join. cluster to only resources in a particular security group, specify the name of
aws. your AWS security group.
security
.group
join. cluster to only resources with particular tags, specify the AWS tag key.
aws.tag.
key
join. cluster to only resources with particular tags, specify the AWS tag key value.
aws.tag.
value
cluster. If the cluster join type is AWS, t his is the AWS endpoint for Synchrony to use
join. (the address where the EC2 API can be found, for example ' ec2.amazonaws.
aws. com ').
host.
header
cluster. 5 If the cluster join type is AWS, this is the joining timeout (in seconds).
join.
aws.
timeout
cluster. Defaults to This is the network interface Synchrony will use to communicate between
interfac the same nodes. Specify this property if you don't want to use the default, which uses
es value as SE the value of the required property Defaults to the same value as SERVER_IP
RVER_IP (also known as synchrony.bind).
synchron Defaults to This is the Aleph binding address. This should be set to the same value as cl
y. the same uster.interfaces.
cluster. value as SE
bind RVER_IP Specify this property if you did not use the default value for cluster.
interfaces.
synchron 8091 This is the HTTP port that Synchrony runs on. If port 8091 is not available,
y.port specify this property to choose a different port.
synchron Defaults to This is the context path for Synchrony. There should be no need to change
y. the context this.
context. path of SYN
path CHRONY_URL
hazelcas True If you're running Confluence in an IPv6 environment, you will need to set this
t. property to False.
prefer.
ipv4.
stack
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

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. Remove the the synchrony.service.url system property. This property tells Confluence where to
find your external Synchrony cluster.
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.com/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/v1
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. Set the synchrony.memory.max system property to increase the maximum heap memory available to
Synchrony to 2gb (or the amount of memory previously allocated to the Synchrony standalone service).
The way you set 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.memory.max=2g1 %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.memory.max=2g ${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.memory.max=2g
See Configuring System Properties for a step-by-step guide to passing system properties to Windows
services via the command line, Windows Registry, or in AWS.
5. Start Confluence on one node.
6. In Confluence, edit a page and check that you can successfully make changes.
7. 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.
Collaborative editing is powered by Synchrony
On this page:
which synchronizes data in real time. Under normal
circumstances it should not need to be managed
manually by an administrator. First steps
Check Synchrony is running
This page will help you troubleshoot problems with Check you can edit a page
Synchrony in your instance. Check the logs
Restart Synchrony
First steps Check port 8091 is available
Reverse proxy issues
Check Synchrony is running Forward proxy issues
Websocket issues
To check if Synchrony is running, go to > Gener SSL issues
al Configuration > Collaborative editing . Memory issues
Multiple Synchrony processes
Note: if you're running Confluence Data Center, this Mixed Synchrony modes in cluster
page will only be able to tell you if the current Incompatible browser extensions
Confluence node is connected to your Synchrony Firewall or anti-virus interference
cluster. You may want to use a third party Too many people in the editor
monitoring tool to help you monitor your Synchrony
cluster. See How to check the status of Synchrony Related pages:
for Confluence Data Center for more info.
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 to 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.

log and Synchrony specific logs at <home-directory>/logs/atlassian-synchrony.log .
Restart Synchrony
If Synchrony is managed by Confluence, go to > General Configuration > Collaborative editing and
choose Restart Synchrony.
If you run your own standalone Synchrony cluster, manually restart Synchrony on each node.
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:
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
/server.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:

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
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
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 the confluence.collab.edit.user.limit sy

stem property.
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.
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.
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.
The way you upgrade Confluence hasn't changed, but read-only mode can help you minimize the impact on
your 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
The Atlassian Companion app enables users to
On this page:
edit Confluence files in their preferred desktop
application, then save the file back to Confluence
automatically. 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. How to delete the Cache folder
Alternatives to the Atlassian Companion
app
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 clicks the Edit button in file preview, we prompt them to download and install the app. See Ed
it Files for details.
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.
Single sign-on considerations
If you've configured single sign-on (SSO) in such a way that your reverse proxy redirects the requests to
your SSO gateway, and only successfully authenticated requests ever reach Confluence, your users won't
be able to edit files using the Atlassian Companion app. This is because the Atlassian Companion app uses
JWT tokens to authenticate requests, and only Confluence can authenticate these requests, not your SSO
authenticator.
To make sure requests from the Atlassian Companion app can be authenticated, you should configure your
reverse proxy to always allow requests from the following URLs:
<base-url>/rest/token-auth/api/*
<base-url>/download/token-auth/attachments/*
<base-url>/plugins/servlet/imgFilter*
<base-url>/rest/analytics/1.0/publish/bulk (only necessary if you have opted in to
data collection)
If an unauthenticated user tries to access these URLs directly, they would be redirected to the Confluence
login screen. The wouldn't be able to access any content or download files while unauthenticated.
Content security policy (CSP) considerations
If you have a restrictive content security policy, your browser will refuse to launch companion, and you'll see
a content security policy error in the browser console. This error occurs because Confluence 7.3 and later
uses a hidden iframe to attempt to launch Companion's custom protocol (atlassian-companion). To
resolve this problem you will need to add atlassian-companion: to the default-src or frame-src lis
t. For example:
frame-src atlassian-companion:;
The content security policy is most commonly configured in your reverse proxy.
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 the link above downloads an .exe file instead of the MSI, copy the URL below into your browser to
download the file.
https://update-nucleus.atlassian.com/Atlassian-Companion/291cb34fe2296e5fb82b83a04704c9b4/latest/win32
/ia32/Atlassian%20Companion.msi
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.
Set trusted domains
In Companion 1.2.0 and later, set your Confluence URL as a trusted domain so users don’t have to select
'Trust this domain' when they edit a file for the first time.
System administrators have two options for setting trusted domains/sites before rolling out the Companion
app to all users. Either set an environment variable called COMPANION_TRUSTED_DOMAINS on each user's
computer, or pass the parameter COMPANION_TRUSTED_DOMAINS to the Microsoft Installer (MSI). Set
multiple trusted domains by using semicolons (;) as separators.
To set trusted domains when installing using the MSI:
msiexec /i "Atlassian Companion-1.1.0.msi" COMPANION_TRUSTED_DOMAINS=“https://confluence.atlassian.com;

https://support.atlassian.com;"
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:

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.
To disable the edit option from the Attachments page, Attachments macro and View File macros:

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
From Confluence 7.3 onwards, Atlassian Companion app should work in most session-based virtual
desktops.
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.
How to delete the Cache folder

If you’d like to free up disk space, it’s safe to manually delete the cache folder. Deleting individual files in the
cache folder may cause errors, so you should delete the entire Cache folder. If the cache folder is locked
while Companion App is running, quit Companion, delete the cache folder, then open Companion.
For Windows, Companion 1.0.0, go to C:\Users\admin\AppData\Roaming\Atlassian Companion\Cache.
For Windows, Companion 1.1.0, go to C:\Users\admin\AppData\Local\Atlassian Companion\Cache.
For Mac, Companion 1.0.0 and 1.1.0, go to Home/Library/Application Support/Atlassian Companion

/Cache.
Alternatives to the Atlassian Companion app

In some versions of Confluence, you can revert to the previous Edit in Office functionality. This is a
workaround for customers who are unable to use the Companion app in their environment.
To enable the legacy Edit in Office functionality:
1. Go to > General Configuration > Office Connector.

2. Choose Enable Edit in Office for all users and save your changes.
This will disable Companion app functionality for all users in the site.
Notifications from Atlassian
The Atlassian Notifications system app provides targeted in-app notifications in Confluence.
These notifications are mostly directed at administrators and provide information about things like new
Confluence versions, upcoming license renewals, and important security announcements.
To disable these notifications:

2. Search for Atlassian Notifications.
3. Expand the listing choose Disable.
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
A Long Term Support release is a feature release that gets backported critical security updates and critical
bug fixes during its entire two-year support window. If you can only upgrade once a year, consider upgrading
to a Long Term Support release. Learn more
Long Term Support releases were originally referred to as Enterprise Releases.
System Requirements
Downloads
Running Confluence in a Virtualized
Download the Confluence documentation
Environment
in PDF format.
Confluence Installation Guide
Installing Confluence Data Center Other resources
Installing Java for Confluence
Creating a Dedicated User Account on Confluence Release Notes
the Operating System to Run
Confluence Confluence administrator's guide
Confluence Setup 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
Bundled Tomcat and Java versions
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
servers.
Software requirements
See Supported Platforms for the full list of platforms Operating systems
that we support in this version of Confluence or Sup Application server
Databases
ported Platforms FAQ for details on our support Java
handling procedures. Antivirus considerations
Hardware requirements
Software requirements Hosted solutions – Confluence Cloud
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.
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 administrators can use this guide in combination with the free
On this page:
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. Minimum hardware
requirements
Peak visitors are the maximum number of browsers simultaneously making Example hardware
requests to access or update pages in Confluence. Visitors are counted specifications
from their first page request until the connection is closed and if public Server load and
access is enabled, this includes internet visitors as well as logged in users. scalability
Storage requirements will vary depending on how many pages and Maximum reported
attachments you wish to store inside Confluence. usages
Hard disk
requirements
Enterprise-scale Confluence sites
Private and
public
These recommendations are designed for small or medium sized
comparison
Confluence sites. For guidance on large or extra large sites, read
Professional
our enterprise-scale infrastructure recommendations.
assistance
Example site
We've also created load profiles to help you determine the size of
your site.
Related pages:
Confluence
Installation Guide
Managing
Minimum hardware requirements
Application Server
Memory Settings
The values below refer to the minimum available hardware required to run
Running
Confluence only; for example, the minimum heap size to allocate to
Confluence in a
Confluence is 1 GB and 1 GB for Synchrony (which is required for
Virtualized
collaborative editing). You'll need additional physical hardware, of at least
Environment
the minimum amount required by your Operating System and any other
applications that run on the server.
On small instances, server load is primarily driven by peak visitors, so

minimum system requirements are difficult to judge. We provide these
figures as a guide to the absolute minimum required to run Confluence, and
your configuration will likely require better hardware.
Here is our minimum hardware recommendation:
CPU: Quad core 2GHz+ CPU

RAM: 6GB
Minimum database space: 10GB
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
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 Spaces User Editors Editor Pages Page Attachments Comments

Case Accounts To Revisions
Viewer
Ratio
Online 140 11,500 1,000 9% 8,800 65,000 7,300 11,500

Docu
mentat
ion
Privat 130 180 140 78% 8,000 84,000 3,800 500

e
Intran
et
Comp 100 85,000 1,000+ 1%+ 12,500 120,000 15,000

any-
Wide
Collab
oration
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's a breakdown of the disk usage and memory requirements of 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
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
Summary Recommendations
Further help
Running Confluence in a virtual machine (VM)
requires specialized skills to set up and manage the Related pages:
virtualized environment. In particular, the
performance of Confluence can be affected by the Server Hardware Requirements Guide
activity of other VMs running on the same Confluence Installation Guide
infrastructure, as well as how you configure the Confluence Data Center
Confluence VM itself. AWS Quick Start (Data Center 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.
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 Confluence
Windows, Linux or OS X 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 or
Windows 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.
Docker docker.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. You can deploy it on your own infrastructure or a
Windows and Linux public cloud platform like AWS or Azure.
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.
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 Confluence
Windows, Linux or OS X 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 or
Windows 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.
Docker docker.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. You can deploy it on your own infrastructure or a
Windows and Linux public cloud platform like AWS or Azure.
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
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.
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.
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.
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.
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.
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!
Installing Confluence on Windows
In this guide we'll run you through installing
On this page:
Confluence in a production environment, with an
external database, using the Windows installer.
Before you begin
This is the most straightforward way to get your Install Confluence
production site up and running on a Windows server. 1. Download Confluence
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 account
9. Start using Confluence
Troubleshooting
Other ways to install Confluence:
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 Check the Supported Platforms page for the version of Confluence you are installing.
using a This will give you info on supported operating systems, databases and browsers.
supported
operating Good to know:
system?
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.
Do you Running Confluence as a service in Windows means that Confluence will automatically
want to start up when Windows is started.
run
Confluence If you choose to run Confluence as a service:
as a
Windows You must run the installer as administrator to be able to install Confluence as a
Service? 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 Confluence runs on port 8090 by default. If this port is already in use, the installer will
8090 and prompt you to choose a different port.
8091
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 To run Confluence in production you'll need an external database. Check the Supported
database Platforms page for the version you're installing for the list of databases we currently
set up and support. If you don't already have a database, PostgreSQL is free and easy to set up.
ready to
use? Good to know:
Set up your database before you begin. Step-by-step guides are available for Postgre
SQL, 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 You'll need a valid Confluence Server license to use Confluence.

have a
Confluence Good to know:
license?
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
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. Home 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
1. Choose Production installation.
2. Choose any apps you'd also like to install.
Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.
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.
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:
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.
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.
Choose to manage Confluence's users and groups inside Confluence or in a Jira application, such as Jira
Software or Jira Service Desk:
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.
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.
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 – 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.
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.
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
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 .
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
On this page:
external database, manually using a zip file.
Before you begin
This method gives you the most control of the Install Confluence
installation process. 1. Download Confluence
2. Create the installation directory
3. Create the home directory
4. Check the ports
5. Start Confluence
Set up Confluence
content
11. Create your administrator
Other ways to install Confluence: account
Troubleshooting
in no time.
Installer – install Confluence using the
Windows installer.
Linux – install Confluence on a Linux
operating system.
Before you begin

Before you install Confluence, there's a few questions you need to answer.
supported
system and
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 Running Confluence as a service in Windows means that Confluence will automatically
to run start up when Windows is started.
Confluence
as a You should use the Windows installer if you want to run Confluence as a Service.
Windows
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).
8091
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.
What To run Confluence in production you'll need an external database. Check the Supporte
database do d Platforms page for the version you're installing for the list of databases we currently
you plan 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.
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 You'll need a valid Confluence Server license to use Confluence.
a
license?
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.
Is your Before you install Confluence, check that you're running a supported Java version and
JRE_HOME that the JRE_HOME (or JAVA_HOME) environment variable is set correctly.
variable set
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
Download the zip file for your operating system – https://www.atlassian.com/software/confluence/download.
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.
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.
properties.
3. At the bottom of the file, enter the path to your <home directory>.
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.
To change the ports:
1.
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">
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).
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
menu.
Good to know:
backup.
installed.
Good to know:
applications.
Good to know:
Desk 3.0 or later.
<port>
go any further.
Troubleshooting
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.
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 Progra
ms 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
folder 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
On this page:
external database, using the Linux installer.
Before you begin
This is the most straightforward way to get your Install Confluence
production site up and running on a Linux server. 1. Download Confluence
Set up Confluence
content
Troubleshooting
Other ways to install Confluence:

in no time.
TAR.GZ – install Confluence manually from
an archive file.
Windows – install Confluence on a Windows
server.
Before you begin

Before you install Confluence, there are a few questions you need to answer.
supported
system?
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 Many Linux distributions don't include a suitable font config package by default, so you
Linux server will need to install one before you can run the Confluence installer.
have a font
config See Confluence Server 6.13 or later fails with FontConfiguration error when installing
package on Linux operating systems for commands to install a suitable package on several
installed? popular Linux distributions.
Do you Running Confluence as a service means that Confluence will automatically start up
want to run when Linux is started.
Confluence
as a If you choose to run Confluence as a service:
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.
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.
8091
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
Is your To run Confluence in production you'll need an external database. Check the Supported
database Platforms page for the version you're installing for the list of databases we currently
set up and support. If you don't already have a database, PostgreSQL is free and easy to set up.
ready to
use? Good to know:
Set up your database before you begin. Step-by-step guides are available for Postgr
eSQL, Oracle, MySQL, and SQL Server.
database.
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 You'll need a valid Confluence Server license to use Confluence.

have a
license?
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.
Install Confluence
Download the installer for your operating system – https://www.atlassian.com/software/confluence/download
1. Make the installer executable.
Change to the directory where you downloaded Confluence then execute this command:

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.
To use sudo to run the installer execute this command:
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).
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
1.
menu.
Good to know:
backup.
installed.
Good to know:
applications.
Good to know:
Desk 3.0 or later.
<port>
go any further.
Troubleshooting
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.
Installing Confluence on Linux from Archive File
On this page:
external database, manually using a zip file.
Before you begin
This method gives you the most control over the Install Confluence
installation process. 1. Download Confluence
4. Check the ports
5. Start Confluence
Set up Confluence
content
11. Create your administrator
Other ways to install Confluence: account
Troubleshooting
in no time.
Installer – install Confluence using the Linux
installer.
Windows – install Confluence on a Windows
server.
Before you begin

Before you install Confluence, there are a few questions you need to answer.
supported
system and
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 Running Confluence as a service means that Confluence will automatically start up
to run when your Linux server is started.
Confluence
as a service? You should use the Linux installer if you want 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.
8091
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
What To run Confluence in production you'll need an external database. Check the Supporte
database do d Platforms page for the version you're installing for the list of databases we currently
you plan 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.
database.
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 You'll need a valid Confluence Server license to use Confluence.
a
license?
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.
Is your Before you install Confluence, check that you're running a supported Java version and
JAVA_HOM that the JAVA_HOME environment variable is set correctly.
E variable
set 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_H
OME environment variable manually before installing Confluence.
Have you We strongly recommend running Confluence as a dedicated user.

created a
dedicated You should create this user before you begin, so that when creating the installation
user to run and home directories, you can give this user appropriate read and write permissions.
Confluence?
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
Install Confluence
Download the tar.gz file for your operating system - https://www.atlassian.com/software/confluence

/download.
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>.
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.
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-
directory>.
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>
1.
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>.
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>.
In this example we're changing ownership of the home directory and giving the user confluence
read, 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.
properties.
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.
You can edit the confluence.init.properties file any 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 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.
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">

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.
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>
2. Go to http://localhost:8090/ to launch Confluence in your browser (change the port if you've

updated the Connector port).
Check your JAVA_HOME variable is set correctly.

Set up Confluence
menu.
Good to know:
backup.
installed.
Good to know:
applications.
Good to know:
Desk 3.0 or later.

<port>
go any further.
Troubleshooting
Check your JAVA_HOME is set correctly.
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.
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
folder 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
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.
It's not possible to automate the database configuration step. This must be done via the setup wizard
in your browser.
Install Confluence in unattended mode

These steps cover where you have an existing Confluence installation.
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
for more info.
Create your own response.varfile
It is also possible to create your own response.varfile, rather than one generated by an existing
installation, if you are installing Confluence for the first time.
Example response.varfile
app.confHome=/var/atlassian/application-data/confluence6_15_5
app.install.service$Boolean=false
portChoice=custom
httpPort$Long=26112
rmiPort$Long=8001
launch.application$Boolean=false
sys.adminRights$Boolean=true
sys.confirmedUpdateInstallationString=false
sys.installationDir=/opt/atlassian/confluence6_15_5
sys.languageId=en
The following parameters can be included in the file.
Parameters Accepted Description

values
app.confHome This is the path to your target local home directory.
app.install. Determines whether Confluence should be installed as a service.

service$Boolean true
false
portChoice Determines whether Confluence should be installed with default

custom ports.
default
httpPort$Long If portChoice is custom, this sets the HTTP connector port in

Tomcat.
rmiPort$Long If portChoice is custom, this sets the Tomcat server port.
launch. Determines whether the installer should start Confluence once

application$Boolean true installation is complete
false
sys. Indicates whether the user running the installer has admin
adminRights$Boolea true privileges on the machine.
n=true false
sys. Set this to false for a fresh unattended installation. Set to true
confirmedUpdateInst true to perform an unattended upgrade.
allationString false
Always back up your existing site before attempting to upgrade.
sys.installationDir path to This is the path to your target installation directory for a new install,
install or existing installation directory to be upgraded.
directory
sys.languageId Default application language.
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">

<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 htt
p://example.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':
Modified conf/server.xml using ports 8020 and 8099
<Server debug="0" shutdown="SHUTDOWN" port="8020">

<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
If you installed Confluence as a service, you can Start Confluence Server and Stop Confluence Server
from the Windows Start menu.
You can't start or stop Confluence manually using the start-confluence.bat and stop-confluence.
bat file.
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:
To start Confluence run <installation-directory>\startup-bundled-jre.bat

To stop Confluence run <installation-directory>\shutdown-bundled-jre.bat
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
If you installed Confluence as a service, use one of the following commands to start, stop or restart
Confluence.
$ 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.sh
files.
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:
$ su -u <user>
Where <user> is the name of your dedicated user.
If you're using Ubuntu the command is a little different:
$ sudo su <user>
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.
atlassian.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
On this page:
Confluence Data Center in a Windows or Linux
Environment. You can run Data Center as a
standalone installation, or in a cluster, depending on Before you begin
your organisation's needs. Supported platforms
Requirements
This guide covers installing for the first time, with no Install Confluence Data Center
existing data. If you already have a Confluence Install Confluence Data Center in a cluster
Server instance, see Moving to Confluence Data Terminology
Center. Install and set up Confluence
Add more Confluence nodes
Security
Troubleshooting
Upgrading a cluster
Other ways to install Confluence Data Center:
AWS - hassle free deployment in AWS using our Quick Start

Azure - reference templates for Microsoft Azure deployment
Move to Data Center - for existing Confluence Server sites
Interested in learning more about Data Center? Find out more about the benefits of Confluence Data
Center.
Before you begin
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.
Requirements
To use Confluence Data Center 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 OAuth authentication if you have application links to other Atlassian products (such as Jira)
To run Confluence in a cluster you must also:
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). This must be a separate directory, and not located within the local home or install
directory.
Install Confluence Data Center

If your organization doesn't need high availability or disaster recovery capabilities right now, you can install
Confluence Data Center without setting up a cluster.
To install Confluence Data Center, without setting up a cluster, follow the instructions for Confluence Server:
Installing Confluence on Windows

Installing Confluence on Linux
The process is almost identical to an ordinary Confluence Server installation, just be sure to choose Standal
one after you've entered your Data Center license.
Install Confluence Data Center in a cluster

If your organization requires continuous uptime, scalability, and performance under heavy load, you'll want to
run Confluence Data Center in a cluster.
See Clustering with Confluence Data Center for a complete overview of hardware and infrastructure
considerations.
Terminology
In this guide we'll use the following terminology:
Installation directory – The directory where you installed Confluence.

Local home directory – The home or data directory stored locally on each cluster node (if Confluence
is not running in a cluster, 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.
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.
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. Follow the prompts to enter your Data Center license then choose Clustered as the deployment type.
4. The setup wizard will prompt you to configure the cluster, 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
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.
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

Role or 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 address
header where the EC2 API can be found, for example 'ec2.amazonaws.com').
Leave blank to use the default endpoint.
Securit Optional. Use to narrow the members of your cluster to only resources
y in a particular security group (specified in the EC2 console).
group
name
Tag Optional. Use to narrow the members of your cluster to only resources
key with particular tags (specified in the EC2 console).
and Ta
g value
5. Follow the prompts to set up your database and administrator account.

6. Confirm that you can log in to Confluence and everything is working as expected, then stop
Confluence on Node 1.

2. Copy Confluence to second node
To copy Confluence to the second node:
1. Shut down Confluence on node 1.

2. Copy the installation directory from node 1 to node 2.
3. Copy the local home directory from node 1 to node 2.
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
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
To test creating content you'll need to access Confluence via your load balancer URL. 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 URL, 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.
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:

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.
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 the following ports through the use of a
firewall and / or network segregation:
5801 - Hazelcast port for Confluence

5701 - Hazelcast port for Synchrony
25500 - Cluster base port for Synchrony
If you use multicast for cluster discovery:
54327- Multicast port for Synchrony (only required if running Synchrony standalone cluster)
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 upgrading an
On this page:
existing Confluence Server site to Confluence Data
Center.
Before you begin
Requirements
Supported platforms
App compatibility
Move from Confluence Server to
Set up your cluster
If you're installing Confluence for the first time (you don't have any existing Confluence data to migrate), see I
nstalling Confluence Data Center.
If you're wanting to switch back Confluence Server, 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
unlock any license-specific features.
Not sure if you should upgrade from Confluence Server to Data Center? Learn more about the benefits of
Before you begin
This guide applies to Confluence 7.2 or later. The migration process is different if you're running an
earlier version of Confluence. Check the instructions outlined in our previous migration guide.
Requirements
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 OAuth authentication if you have application links to other Atlassian products (such as Jira)
If you plan to run Confluence Data Center in a cluster there are some additional infrastructure requirements.
See Clustering with Confluence Data Center for more information.
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.
App compatibility
Apps extend what your team can do with Atlassian applications, so it's important to make sure that your
team can still use their apps after migrating to Data Center. When you switch to Data Center, you'll be
required to switch to the Data Center compatible version of your apps, if one is available.
See Evaluate apps for Data Center migration for more information.
Move from Confluence Server to Confluence Data Center

To move from Confluence Server to Confluence Data Center:

2. Choose License Details from the sidebar under the Administration heading
3. Enter your Confluence Data Center license key.
There's no need to restart Confluence. Data Center features such as read-only mode, SAML single sign-on,
and CDN will now be available.
Set up your cluster

If your organisation requires continuous uptime, scalability, and performance under heavy load, you'll want to
run Confluence Data Center in a cluster.
To find out more about clustering, including infrastructure requirements see Clustering with Confluence Data
Center.
If you're ready to set up your cluster now, head to Set up a Confluence Data Center cluster.
Upgrading Confluence Data Center
This page contains instructions for upgrading an
On this page:
existing Confluence cluster.
If you are not running Confluence in a cluster, follow 1. Back up

the instructions in Upgrading Confluence. 2. Download Confluence
3. Stop the cluster
In this guide we'll use the following terminology: 4. Upgrade the first node
5. Upgrade Synchrony (optional)
Installation directory – The directory where 6. Copy Confluence to remaining nodes
you installed Confluence. 7. Start Confluence and check cluster
Local home directory – The home or data connectivity
directory stored locally on each cluster node
(if Confluence is not running in a cluster, 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.
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.
Download the appropriate file for your operating system from https://www.atlassian.com/software/confluence
/download
3. 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.
4. 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.
5. 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:
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.
6. 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.
properties 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.
7. 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
(starting 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
On this page:
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. Adding a node
Removing a node
If you deployed Confluence Data Center on AWS Changing the node identifier
using the Quick Start, your Confluence and Moving to a standalone installation
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.
node.name system property to set the node identifier on each node so that it's easier for your users and
administrators to read.
See Configuring System Properties for more information on how to set the system property.
Moving to a standalone installation

If you no longer need clustering, but still want access to Data Center features, you can go back to a
standalone (non-clustered) Data Center installation.
In these instructions we'll assume that you'll use one of your existing cluster nodes as your new, standalone
installation. You'll also need to make some infrastructure changes as part of the switch.
We recommend completing this process in a staging environment, and running a set of functional tests,
integration tests, and performance tests, before making these changes in production.
Terminology

Local home directory – The home or data directory stored locally on each cluster node (if Confluence
is not running in a cluster, 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.
1. Shut down Confluence
Stop all cluster nodes before you proceed.
2. Configure your load balancer
Configure your load balancer to redirect traffic away from all Confluence nodes, except the node you plan to
use for your standalone installation.
If you no longer need your load balancer, you can remove it at this step.
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 you set up clustering).
2. Move the following directories and files from your <shared home> directory to the <local home>
/shared-home directory
config
confluence.cfg.xml
dcl-document
dcl-document_hd
dcl-thumbnail
3. Move the remaining contents of your <shared home> directory to the root of your <local home>
directory. Make sure your attachments directory is moved as part of this step.
Your cluster's shared home directory should now be empty.
Make sure you don't accidentally overwrite the confluence.cfg.xml in your local home directory. The
confluence.cfg.xml file from your shared home directory doesn't contain the same parameters as the
one in your local home directory.
4. Modify cluster properties
1. Take a backup of the existing <local home>/confluence.cfg.xml

2. Edit <local home>/confluence.cfg.xml
3. Change the setupType parameter to custom:
Before
<setupType>cluster</setupType>
After
<setupType>custom</setupType>
4. Remove any cluster properties. These begin with confluence.cluster.

Here are some example cluster properties that should be removed. These will vary depending on
how you configured your cluster.
confluence.cluster
confluence.cluster.address
confluence.cluster.home
confluence.cluster.interface
confluence.cluster.join.type
confluence.cluster.name
5. Save the file.
Start Confluence
Restart Confluence.
To confirm you're now running a standalone installation, go to > General Configuration > Cluste
ring.
The active cluster should no longer appear. Instead, you'll see information about getting started with
clustering, and the option to enable cluster mode.
Change Node Discovery from Multicast to TCP/IP or AWS
On this page:
To change from multicast to TCP/IP

To change from multicast to AWS
To change from TCP/IP to AWS
To change from TCP/IP to multicast
Reference of properties in the confluence.cfg.xml file
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 the 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 perform a safety backup before making manual edits 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> 
<property name="confluence.cluster.join.type">tcp_ip</property> 
Enter the address of each node, and separate each address with a comma. Please, make sure to remove the
brackets from around the IP addresses.
You can now restart your cluster nodes.
To change from multicast to AWS
Look for the following two lines in the confluence.cfg.xml file and remove them:
<property name="confluence.cluster.address">[multicast IP]</property>

<property name="confluence.cluster.join.type">multicast</property>
Depending on which type of credentials you are passing to Confluence, you will add one of the following two
blocks with your AWS configuration.
Option 1: For Access Key/Secret Key based credentials:

<property name="confluence.cluster.join.type">aws</property>
<property name="confluence.cluster.aws.host.header">[---VALUE---]</property>
<property name="confluence.cluster.aws.region">[---VALUE---]</property>
<property name="confluence.cluster.aws.tag.key">[---VALUE---]</property>
<property name="confluence.cluster.aws.tag.value">[---VALUE---]</property>
<property name="confluence.cluster.aws.access.key">[---VALUE---]</property>
<property name="confluence.cluster.aws.secret.key">[---VALUE---]</property>
Option 2: For IAM role based credentials:
<property name="confluence.cluster.aws.iam.role">[---VALUE---]</property>
To change from TCP/IP to AWS
Look for the following two lines in the confluence.cfg.xml file and remove them:
<property name="confluence.cluster.join.type">tcp_ip</property>
<property name="confluence.cluster.peers">[node 1 IP],[node 2 IP],[node 3 IP]</property>
Depending on which type of credentials you are passing to Confluence, you will add one of the following two
blocks with your AWS configuration.
Option 1: For Access Key/Secret Key based credentials:
<property name="confluence.cluster.aws.access.key">[---VALUE---]</property>
<property name="confluence.cluster.aws.secret.key">[---VALUE---]</property>
Option 2: For IAM role based credentials:
<property name="confluence.cluster.aws.iam.role">[---VALUE---]</property>
You can now restart your cluster nodes.
Note that if you're using a CloudFormation YAML template you need to make sure you have these appropriate
values as a minimum and they should be reflected on the AWS side as well. If you switch to AWS mode cluster
type, please also review Running Confluence Data Center in AWS and make sure you have the following set up
in your YAML:
Key: Cluster
Value: !Ref AWS::StackName
PropagateAtLaunch: true
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. 'multicast' or Pre-5.9 Data Center installations won't have this key. By
cluster.join. 'tcp_ip'or 'aws' default, if the key is missing, Confluence will choose multi
type cast
confluence. a single multicast IP This key is only used by confluence if confluence.

cluster. address cluster.join.type is set to multicast
address
confluence. a comma-separated There must be at least one address here. The addresses
cluster.peers string of IP addresses (no are the IP address of each node in the cluster, for example
spaces) <property name="confluence.cluster.peers">
[node 1 IP],[node 2 IP],[node 3 IP]<
/property>
This key is only used by confluence if confluence.

cluster.join.type is set to tcp_ip
Running Confluence Data Center in AWS
If you decide to deploy Confluence Data Center in a
On this page:
clustered environment, consider using Amazon Web
Services (AWS). AWS allows you to scale your
deployment elastically by resizing and quickly Non-clustered VS clustered environment
launching additional nodes, and provides a number Deploying Confluence Data Center in a
of managed services that work out of the box with cluster using the AWS Quick Start
Confluence Data Center. These services make it Advanced customizations
easier to configure, manage, and maintain your Launching the Quick Start from your
deployment's clustered infrastructure. own S3 bucket (recommended)
Amazon Aurora database for high
Interested in learning more about the benefits of availability
Data Center? Check out our overview of Synchrony setup
Confluence Data Center. Amazon CloudWatch for basic
monitoring and centralized logging
Auto Scaling groups
EC2 sizing recommendations
Customizing the AWS Quick Start's
CloudFormation templates
Supported AWS regions
Internal domain name routing with
Route53 Private Hosted Zones
Step 1: Create a new hosted zone
Step 2: Configure your stack to use
the hosted zone
Step 3: Link your DNS server to the
Confluence site’s VPC
Scaling up and down
Connecting to your nodes over SSH
Upgrading
Step 1: Terminate all running
Confluence Data Center application
nodes
Step 2: Update the version used by
your Confluence Data Center stack
Step 3: Scale up the number of
application nodes
Backing up
Migrating your existing Confluence site to
AWS
Non-clustered VS clustered environment

A single node is adequate for most Small or Medium size deployments, unless you need specific features
that require clustering (for example, high availability). If you have an existing Server installation, you can still
use its infrastructure when you upgrade to Data Center. Many features exclusive to Data Center (like SAML
single sign-on, self-protection via rate limiting, and CDN support) don't require clustered infrastructure. You
can start using these Data Center features by simply upgrading your Server installation’s license. For more
information on whether clustering is right for you, check out Atlassian Data Center architecture and
infrastructure options.
Deploying Confluence Data Center in a cluster 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 Confluence Data Center Quick Start's architecture:
The deployment consists of the following components:
Instances/nodes: One or more Amazon Elastic Cloud (EC2) instances as cluster nodes, running
Confluence.
Load balancer: An Application Load Balancer (ALB), which works both as load balancer and SSL-
terminating reverse proxy.
Amazon EFS: A shared file system for storing artifacts in a common location, accessible to multiple
Confluence nodes. The Quick Start architecture implements the shared file system using the highly
available Amazon Elastic File System (Amazon EFS) service.
Database: Your choice of shared database instance – Amazon RDS or Amazon Aurora.
Amazon CloudWatch: Basic monitoring and centralized logging through Amazon's native
CloudWatch service.
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/).
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, however, further customize your deployment through the
variables in the Ansible playbooks we use.
All of our AWS Quick Starts use Ansible playbooks to configure specific components of your deployment.
These playbooks are available publicly on this repository:
https://bitbucket.org/atlassian/dc-deployments-automation
You can override these configurations by using Ansible variables. Refer to the repository’s README file for
more information.
Launching the Quick Start from your own S3 bucket (recommended)
The fastest way to launch the Quick Start is directly from its AWS S3 bucket. However, when you do, any
updates we make to the Quick Start templates will propagate directly to your deployment. These updates
sometimes involve adding or removing parameters from the templates. This could introduce unexpected
(and possibly breaking) changes to your deployment.
For production environments, we recommend that you copy the Quick Start templates into your own S3
bucket. Then, launch them directly from there. Doing this gives you control over when to propagate Quick
Start updates to your deployment.
1. Clone the Quick Start templates (including all of its submodules) to your local machine. From the
command line, run:
git clone --recurse-submodules https://github.com/aws-quickstart

/quickstart-atlassian-confluence.git
2. (Optional) The Quick Start templates repository uses the directory structure required by the Quick
Start interface. If needed (for example, to minimize storage costs), you can remove all other files
except the following:
quickstart-atlassian-confluence
submodules
quickstart-atlassian-services
templates
quickstart-vpc-for-atlassian-services.yaml
templates
quickstart-confluence-master-with-vpc.template.yaml
quickstart-confluence-master.template.yaml
3. Install and set up the AWS Command Line Interface. This tool will allow you to create an S3 bucket
and upload content to it.
4. Create an S3 bucket in your region:
aws s3 mb s3://<bucket-name> --region <AWS_REGION>
At this point, you can now upload the Quick Start templates to your own S3 bucket. Before you do, you'll
have to choose which Quick Start template you’ll be using:
quickstart-confluence-master-with-vpc.template.yaml: use this for deploying

into a new ASI (end-to-end deployment).
quickstart-confluence-master.template.yaml: use this for deploying into an
existing ASI.
1. In the template you’ve chosen, the QSS3BucketName default value is set to aws-quickstart.
Replace this default with the name of your S3 bucket.
2. Go into the parent directory of your local clone of the Quick Start templates. From there, upload all the
files in local clone to your S3 bucket:
2. 7.7 Documentation
Confluence 4
aws s3 cp quickstart-atlassian-confluence s3://<bucket-name> --recursive

--acl public-read
3. Once you’ve uploaded everything, you’re ready to deploy your production stack from your S3 bucket.
Go to Cloudformation Create Stack. When specifying a template, paste in the Object URL of the
Quick Start template you’ll be using.
Amazon Aurora database for high availability
The Quick Start also allows you to deploy Confluence Data Center with an Amazon Aurora clustered
database (instead of RDS). This cluster will be PostgreSQL-compatible, featuring a primary database writer
that replicates to two database readers. You can also set up the writers and readers in separate availability
zones for better resiliency.
If the writer fails, Aurora automatically promotes one of the readers to take its place. For more information,
see Amazon Aurora Features: PostgreSQL-Compatible Edition.
If you want to set up an existing Confluence Data Center instance with Amazon Aurora, you’ll need
to perform some extra steps. See Configuring Confluence Data Center to work with Amazon Aurora
for detailed instructions.
Synchrony setup

By default, the Quick Start will configure Synchrony to be managed by Confluence. However, you can use
the Quick Start to configure standalone Synchrony. When you do, the Quick Start creates an Auto Scaling
group containing one or more Amazon EC2 instances as cluster nodes, running Synchrony.
For more information about Synchrony configuration, see Possible Confluence and Synchrony Configurations.
Managed mode is only available in 6.12 and later

If you plan to deploy a Confluence Data Center version earlier than 6.12, you can only use
Standalone mode. In the Quick Start, this means you should set your Collaborative editing
mode to synchrony-separate-nodes.
Amazon CloudWatch for basic monitoring and centralized logging
The Quick Start can also provide you with node monitoring through Amazon CloudWatch. This will allow you
to track each node's CPU, disk, and network activity, all from a pre-configured CloudWatch dashboard. The
dashboard will be configured to display the latest log output, and you can customize the dashboard later on
with additional monitoring and metrics.
By default, Amazon CloudWatch will also collect and store logs from each node into a single, central source.
This centralized logging allows you to search and analyze your deployment's log data more easily and
effectively. See Analyzing Log Data with CloudWatch Logs Insights and Search Log Data Using Filter
Patterns for more information.
Amazon CloudWatch provides basic logging and monitoring, but also costs extra. To help reduce
the cost of your deployment, you can disable logging or turn off Amazon CloudWatch integration
during deployment.
To download your log data (for example, to archive it or analyze it outside of AWS), you’ll have to
export it first to S3. From there, you can download it. See Exporting Log Data to Amazon S3 for
details.
Auto Scaling groups
This Quick Start uses Auto Scaling groups, but only to statically control the number of its cluster nodes. We
don't recommend that you use Auto Scaling to dynamically scale the size of your cluster. Adding an
application node to the cluster usually takes more than 20 minutes, which isn't fast enough to address
sudden load spikes.
If you can identify any periods of high and low load, you can schedule the application node cluster to scale
accordingly. See Scheduled Scaling for Amazon EC2 Auto Scaling for more information.
To study trends in your organization's load, you'll need to monitor the performance of your deployment.
Refer to Confluence Data Center sample deployment and monitoring strategy for tips on how to do so.
EC2 sizing recommendations
For Large or XLarge deployments, check out our AWS infrastructure recommendations for application,
Synchrony, and database sizing advice. For smaller deployments, you can use instances that meet
Confluence's system requirements. Smaller instance types (micro, small, medium) are generally not
adequate for running Confluence.
Customizing the AWS Quick Start's CloudFormation templates
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. Alternatively, you can customize the CloudFormation templates used
by the Quick Start to fit your needs. These templates are available from the following repository:
https://github.com/aws-quickstart/quickstart-atlassian-confluence
Supported AWS regions
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:
Americas
Northern Virginia
Ohio
Oregon
Northern California
Montreal
Europe/Middle East/Africa
Ireland
Frankfurt
London
Paris
Asia Pacific
Singapore
Tokyo
Sydney
Seoul
Mumbai
This list was last updated on 20 Jun 2019.
The services offered in each region change from time to time. If your preferred region isn't on this list, check
the Regional Product Services table in the AWS documentation to see if it already supports EFS.
AWS GovCloud is not for production

Our Quick Starts are also available on AWS GovCloud regions, but only for testing purposes. We do
not support any deployments on GovCloud regions resulting from this Quick Start.
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.
Internal domain name routing with Route53 Private Hosted Zones

Even if your Confluence site is hosted on AWS, you can still link its DNS with an internal, on-premise DNS
server (if you have one). You can do this through Amazon Route 53, creating a link between the public DNS
and internal DNS. This will make it easier to access your infrastructure resources (database, shared home,
and the like) through friendly domain names. You can make those domain names accessible externally or
internally, depending on your DNS preferences.
Step 1: Create a new hosted zone
Create a Private hosted zone in Services > Route 53. The Domain Name is your preferred domain. For the
VPC, use the existing Atlassian Standard Infrastructure.
Step 2: Configure your stack to use the hosted zone
Use your deployment’s Quick Start template to point your stack to the hosted zone from Step 1. If you’re
setting up Confluence for the first time, follow the Quick Start template as below:
1. Under DNS (Optional), enter the name of your hosted zone in the Route 53 Hosted Zone field.
2. Enter your preferred domain sub-domain in the Sub-domain for Hosted Zone field. If you leave it
blank, we'll use your stack name as the sub-domain.
3. Follow the prompts to deploy the stack.
If you already have an existing Confluence site, you can also configure your stack through the Quick Start
template. To access this template:
1. Go to to Services > CloudFormation in the AWS console

2. Select the stack, and click Update Stack.
3. Under DNS (Optional), enter the name of your hosted zone in the Route 53 Hosted Zone field.
4. Enter your preferred domain sub-domain in the Sub-domain for Hosted Zone field. If you leave it
blank, we'll use your stack name as the sub-domain.
5. Follow the prompts to update the stack.
In either case, AWS will generate URLs and Route 53 records for the load balancer, EFS, and database. For
example, if your hosted zone is my.hostedzone.com and your stack is named mystack, you can access
the database through the URL mystack.db.my.hostedzone.com.
Step 3: Link your DNS server to the Confluence site’s VPC
If you use a DNS server outside of AWS, then you need to link it to your deployment’s VPC (in this case, the
Atlassian Standard Infrastructure). This means your DNS server should use Route 53 to resolve all queries
to the hosted zone’s preferred domain (in Step 1).
For instructions on how to set this up, see Resolving DNS Queries Between VPCs and Your Network.
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.
For related information on configuring Confluence's base URL, see Configuring the Server Base URL.
Scaling up and down

To increase or decrease the number of Confluence or Synchrony cluster nodes:
1. Sign in to the AWS Management Console, use the region selector in the navigation bar to choose the
AWS Region for your deployment, and open the AWS CloudFormation console at https://console.aws.
amazon.com/cloudformation/.
2. Click the Stack name of your deployment. This will display your deployment's Stack info. From
there, click Update.
3. On the Select Template page, leave Use current template selected, and then choose Next.
4. On the Specify Details page, go to the Cluster nodes section of Parameters. From there, set your
desired number of application nodes in the following parameters:
a. Minimum number of cluster nodes
b. Maximum number of cluster nodes
5. Click through to update the stack.
Disabled Auto Scaling

Since your cluster has the same minimum and maximum number of nodes, Auto Scaling is
effectively disabled.
Setting different values for the minimum and maximum number of cluster nodes enables Auto
Scaling. This dynamically scale the size of your cluster based on system load.
However, we recommend that you keep Auto Scaling disabled. At present, Auto Scaling can't
effectively address sudden spikes in your deployment's system load. This means that you'll have to
manually re-scale your cluster depending on the load.
Vertical VS Horizontal scaling

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 very 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 Infrastructure recommendations for enterprise Confluence
instances on AWS for more details.
See the AWS documentation for more information on auto scaling groups.
Connecting to your nodes over SSH

You can perform node-level configuration or maintenance tasks on your deployment through the AWS
Systems Manager Sessions Manager. This browser-based terminal lets you access your nodes without any
SSH Keys or a Bastion host. For more information, see Getting started with Session Manager.
Access via Bastion host

You can also access your nodes via a Bastion host (if you deployed one). To do this, you'll need
your SSH private key file (the PEM file you specified for the Key Name parameter). Remember, this
key can access all nodes in your deployment, so keep this key in a safe place.
The Bastion host acts as your "jump box" to any instance in your deployment's internal subnets.
That is, access the Bastion host first, and from there access any instance in your deployment.
The Bastion host's public IP is the BastionPubIp output of your deployment's ATL-
BastionStack stack. This stack is nested in your deployment's Atlassian Standard Infrastructure
(ASI). To access the Bastion host, use ec2-user as the user name, for example:
ssh -i keyfile.pem ec2-user@<BastionPubIp>
The ec2-user has sudo access. SSH access is by root is not allowed.
Upgrading
Consider upgrading to a Long Term Support release (if you're not on one already). Enterprise releases get
fixes for critical bugs and security issues throughout its two-year support window. This gives you the option
to keep a slower upgrade cadence without sacrificing security or stability. Long Term Support releases are
suitable for companies who can't keep up with the frequency at which we ship feature releases.
Here's some useful advice for upgrading your deployment:
1. Before upgrading to a later version of Confluence Data Center, check if your apps are compatible with
that version. Update your apps if needed. For more information about managing apps, see Using the
Universal Plugin Manager.
2. If you need to keep Confluence Data Center running during your upgrade, we recommend using read-
only mode for site maintenance. Your users will be able to view pages, but not create or change
them.
3. We strongly recommend that you perform the upgrade first in a staging environment before upgrading
your production instance. Create a staging environment for upgrading Confluence provides helpful
tips on doing so.
When the time comes to upgrade your deployment, perform the following steps:
Step 1: Terminate all running Confluence Data Center application nodes
Set the number of application nodes used by the Confluence Data Center stack to 0. Then, update the stack.
If your deployment uses standalone Synchrony, scale the number of Synchrony nodes to 0 at the
same time.
1. In the AWS console, go to Services > CloudFormation. Select your deployment’s stack to view
its Stack Details.
2. In the Stack Details screen, click Update Stack.
3. From the Select Template screen, select Use current template and click Next.
4. You’ll need to terminate all running nodes. To do that, set the following parameters to 0:
a. Maximum number of cluster nodes
b. Minimum number of cluster nodes
5. Click Next. Click through the next pages, and then to apply the change using the Update button.
6. Once the update is complete, check that all application nodes have been terminated.
Step 2: Update the version used by your Confluence Data Center stack
Set the number of application nodes used by Confluence Data Center to 1. Configure it to use the version
you want. Then, update the stack again.
If your deployment uses standalone Synchrony, scale the number of Synchrony nodes to 1 at the
same time.
1. From your deployment’s Stack Details screen, click Update Stack again.
2. From the Select Template screen, select Use current template and click Next.
3. Set the Version parameter to the version you’re updating to.
4. Configure your stack to use one node. To do that, set the following parameters to 1:
a. Maximum number of cluster nodes
b. Minimum number of cluster nodes
5. Click Next. Click through the next pages, and then to apply the change using the Update button.
Step 3: Scale up the number of application nodes
You can now scale up your deployment to your original number of application nodes. You can do so for your
Synchrony nodes as well, if you have standalone Synchrony. Refer back to Step 1 for instructions on how to
re-configure the number of nodes used by your 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
starting up. 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. For more information, see AWS Backup.
Migrating your existing Confluence site to AWS

After deploying Confluence on AWS, you might want to migrate your old deployment to it. To do so:
1. Upgrade your existing site to the version you have deployed to AWS (Confluence 6.1 or later).
2. (Optional) If your old database isn't PostgreSQL, you'll need to migrate it. See Migrating to Another
Database for instructions.
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.
Important notes
When you create a cluster using the CloudFormation template, the database name is conflu
ence. 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
On this page:

How it works
Limitations
Preparing for your deployment
Migrating an existing site to Azure
Deploying Confluence Data Center to Azure via Azure marketplace
Deploying Confluence Data Center to Azure using the CLI
Securing your Azure deployment
Monitoring
If you decide to deploy Confluence Data Center in a clustered environment, consider using Microsoft Azure.
This platform allows you to scale your deployment elastically by resizing and quickly launching additional nodes,
and provides a number of managed services that work out of the box with Confluence Data Center. These
services make it easier to configure, manage, and maintain your deployment's clustered infrastructure.
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.

A single node is adequate for most Small or Medium size deployments, unless you need specific features that
require clustering (for example, high availability). If you have an existing Server installation, you can still use its
infrastructure when you upgrade to Data Center. Many features exclusive to Data Center (like SAML single sign-
on, self-protection via rate limiting, and CDN support) don't require clustered infrastructure. You can start using
these Data Center features by simply upgrading your Server installation’s license. For more information on
whether clustering is right for you, check out Atlassian Data Center architecture and infrastructure options.
How it works
Here's an architectural overview of what you'll get when deploying Confluence Data Center using the template:
The deployment contains one or more Azure standard VM instances as cluster nodes in a scale set. Each
cluster node runs Confluence Data Center and Synchrony. This way, you don't need to provision extra nodes to
enable collaborative editing.
The template also provisions an Azure Files storage account for the shared home. This shared home stores
attachments and other files accessible to the application cluster nodes. It's mounted as a SAN drive on each
node, and treated normally like any other file.
Standardized infrastructure
The Jira Data Center, Confluence Data Center, and Bitbucket Data Center templates deploy the following
infrastructure components identically:
Component Configuration
Bastion host This is a lightweight but highly secure Azure Linux VM that controls SSH access to the
application cluster nodes.
Application By default, this gateway is composed of two instances for high availability. It acts as a HTTP
Gateway /HTTPS load balancer for your scale set of application cluster nodes.
Monitoring The ARM templates configure Azure Monitoring to perform basic health and availability
monitoring to cluster nodes and database.
Database You can choose between Azure SQL Database (MS SQL Server-compatible) or Azure
PostgreSQL database. Either way, the database will be configured as service endpoints to
only allow traffic from the private network that the cluster nodes are in. This restricted traffic
setup helps enhance security.
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.
Preparing for your deployment

Before you begin, you should use the Confluence Data Center load profiles to determine the size of your
site. This information will help you choose the right infrastructure size during deployment.
You should also decide which Azure region is best for your site. Some services, such as such as Application
Insights and Azure SQL Analytics, may not be available in all regions. You can check this at https://azure.
microsoft.com/en-gb/global-infrastructure/regions/.
During the deployment you'll need:
Your database details, if you want to use an existing Azure database service. You'll need the database
URL, port, username, and password.
A Base64 encoded PFX certificate from a trusted Certificate Authority.
Details of your existing CNAME, if you don't want Azure to generate a random domain for you.
Migrating an existing site to Azure

To migrate, you will need to set up a new Confluence Data Center site in Azure, and then import content from
your old site. This approach ensures that your new site is created with optimum settings for Azure.
Here's a high level overview of the steps:
1. Back up your existing site, including your database and home directories.
2. Make a list of any Marketplace or other user-installed apps
3. Perform a full site export, excluding attachments if you have a large site. You can also turn on read-only
mode, to prevent users from making changes in your old site.
4. Deploy Confluence Data Center in Azure via the Azure Portal, or CLI, and test that Confluence is working
as expected.
5. Import your site export file. Make sure you know the administrator password for your existing site, as
you'll be logged out during the import.
6. Copy the contents of your /attachments directory to the equivalent directory in your shared home.
7. Install any apps.
8. Test your site.
At this point you can make the site available to your users, and tear down your old site.
Tips for a successful migration:
Do a trial run first - export your existing site, and import it into Azure to iron out any issues.
Because you're setting up your new site in parallel, your current Confluence site can remain accessible
throughout the process. If you're already running Confluence Data Center, use read-only mode to
prevent people making changes after you've exported the site.
Unless your existing site is small, exporting the site without attachments will keep the export file smaller.
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.
Confluence-specific parameters
Parameters Description
Confluence Specify the version of Confluence you'd like to install in full (for example, 6.14.0). Head to Con
Version fluence Release Notes for a list of all releases.
Confluence Provide a name and password for the initial Confluence administrator on your instance.
admin
credentials
Confluence Select the expected size of your site - trial, small, medium, large, extra large. This will
Cluster determine the number of Confluence application nodes, and the size of VMs to be
provisioned. Choose Change Size to override the defaults.
Standardized infrastructure parameters
The Jira Data Center, Confluence Data Center, and Bitbucket Data Center templates all share the same
parameters:
Subscription Your Microsoft Azure subscription type.
Resource If you have an existing resource group, you can use it, or create a new one.
group
Location This is the region where Azure will house your deployment.
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 Bitbucket nodes.
See Create and use an SSH public-private key pair for Linux VMs in Azure in the Microsoft
Azure documentation.
Database Choose between an Azure SQL Database, or Azure Database for PostgreSQL. Provide a
configuration 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.
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. See Monitoring for related information.
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.
Head to https://bitbucket.org/atlassian/atlassian-azure-deployment and check out the README to find out how
to to deploy using the CLI.
Required parameters
The deployment template requires a number of values to be provided in order to deploy your Confluence Data
Center instance.
confCluster To use recommended hardware options for the Confluence installation choose a size. Allowed
Size values:
trial
small
medium
large
enterprise
If set, all further Gateway, VM, DB size parameters will be ignored.
clusterSshP This is the SSH password you'll use to access your Confluence nodes.
assword
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.
confAdmin This is the password for your Confluence administrator's account.

UserPassw
ord
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.

value
confluence Latest This is the version of Confluence you want to install on your cluster nodes. Enter
Version 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.
customDow empty Use this URL to override standard Atlassian download url, for example to specify
nloadUrl 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 Choose between Azure SQL Server and Azure DB for PostgreSQL.
SQL DB
dbHost auto- The hostname of database server to be used if an external database is being used.
generated 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 confdata The database name to use if an external database is being used. This will be
base autogenerated if a new database is to be created.
dbSchema auto- The database schema to use if an external database is being used. This will be
generated autogenerated if a new database is to be created.
dbUsername confluen The username for the dedicated database user.

cedbuser
cname auto- This is the Canonical Name record (CNAME) for your organization. If you don't
generated 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.
sslBase64E The certificate to be used for SSL termination on the Azure Application Gateway.
ncodedPfx
Certificate
sslPfxCertifi The certificate password to be used for SSL termination on the Azure Application
catePasswo Gateway.
rd
jumpboxSs The SSH public key to use to access the bastion host (jumpbox)
hKey
confAdmin admin The username for the Confluence Administrator's account. Must be lowercase.
UserName
confAdmin Admin The full name of the Confluence Administrator's account.

UserFullNa Admin
me
confAdmin admin@ The email address of the Confluence Administrator user.

UserEmail example.
com
confAppTitle Atlassian The name of your Confluence site.

Confluen
ce
jumpboxSs confluen This is the SSH user you'll use to access the bastion host (jumpbox).
hUser ceadmin
clusterSshU confluen The SSH username to use to access the Confluence nodes from the bastion host
ser ceadmin (jumpbox). This is the only way you can access Confluence nodes.
enableEmai true Enable email alerts.

lAlerts
enableAppli true Enable Azure Application Insights.

cationInsigh
ts
enableAnal true Enable Azure Operational Insights.

ytics
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.
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.
Securing your Azure deployment

We recommend deploying Confluence with SSL. Our template will prompt you for a certificate and password.
Good to know:
HTTPS is terminated at the application gateway.

Your certificate should be from a trusted Certificate Authority. You should avoid self-signed certificates.
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 Men
u > 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
/confluence
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-
confluence.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.
Upgrading
Consider upgrading to a Long Term Support release (if you're not on one already). Enterprise releases get fixes
for critical bugs and security issues throughout its two-year support window. This gives you the option to keep a
slower upgrade cadence without sacrificing security or stability. Long Term Support releases are suitable for
companies who can't keep up with the frequency at which we ship feature releases.
Here's some useful advice for upgrading your deployment:
1. Before upgrading to a later version of Confluence Data Center, check if your apps are compatible with
that version. Update your apps if needed. For more information about managing apps, see Using the
Universal Plugin Manager.
2. If you need to keep Confluence Data Center running during your upgrade, we recommend using read-
only mode for site maintenance. Your users will be able to view pages, but not create or change them.
3. We strongly recommend that you perform the upgrade first in a staging environment before upgrading
your production instance. Create a staging environment for upgrading Confluence provides helpful tips on
doing so.
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.
Backing up and recovering from failures

We recommend you use the Azure native backup facilities where possible to make sure your data is backed up,
and you can easily recover in the case of a failure.
Database backups
We use Azure-managed database instances with high availability. Azure provides several excellent options for
backing up your database, so you should take some time to work out which will be the best, and most cost
effective option for your needs. See the following Azure documentation for your chosen database:
SQL Database: Automated backups

SQL Database: Backup retention
PostGreSQL: Backup concepts
Shared home backups
The shared home stores your your attachments, profile pictures, and export files. We create a general purpose
Azure storage account, configured with local redundant storage (LRS), which means there are multiple copies of
the data at any one time.
LRS provides a basic redundancy strategy for your shared home. As such, it shouldn't be necessary to take
regular backups yourself. If you need to take point-in-time backups, use snapshots.
Application nodes
The application nodes are VMs in an Azure Virtual Machine Scale Set. Each application node has a Confluence
installation directory and a local home directory containing things like logs and search indexes.
Like the shared home, application nodes are configured with local redundant storage. This means there are
multiple copies of the data at any one time.
If you've manually customised any configuration files in the installation directory (for example velocity
templates), you may also want to manually back these up as a reference.
Bastion host
As this VM acts as a jumpbox, and doesn't store any data it doesn't need to be backed up. If the VM becomes
unresponsive it can be restarted from the Azure Portal.
Application gateway
The application gateway is highly available. We deploy 2 instances by default. As with the bastion host, it
doesn't need to be backed up.
Disaster recovery
See Confluence Data Center disaster recovery to learn about how you can develop a disaster recovery
strategy. See also information in the Azure documentation about recovering from a region-wide failure Azure
resiliency technical guidance: recovery from a region-wide service disruption.
Moving from Data Center to Server
This page outlines how to switch from Confluence Data Center (clustered) to Confluence Server (non-
clustered). In these instructions we'll assume that you'll use one of your existing cluster nodes as your new, non-
clustered installation.
The steps involved will depend on whether you're running Confluence in a cluster.
Requirements
You need a Confluence Server license to switch back to Server.

Read-only mode must be turned off before you apply your Server license.
If you no longer need clustering, but still want access to Data Center features, you can go back to a non-
clustered (standalone) Data Center installation. See Moving to a standalone Data Center installation
Move from non-clustered Data Center to Server

If you are not running Confluence in a cluster, all you need to do is update your license to switch to
Confluence Server. Not sure? Go to > General Configuration > Clustering. If you see your cluster nodes
listed, then Confluence is running in a cluster.
1. Make sure read-only mode is turned off.

2. Go to > General Configuration> General Configuration
4. Enter your Confluence Server license key.
There's no need to restart Confluence. Data Center specific features such as read-only mode, SAML single sign-
on, and CDN will no longer be available.
How will the Data Center-only features be affected?
After changing from Data Center to Server, you’ll lose any features exclusive to Data Center. Here’s a summary
of how this will affect your current Confluence site:
Feature Result
SAML single sign- No longer available

on (SSO)
What happens:
SAML SSO login will no longer work (users will be redirected to a login screen
always)
Users who had a password on their Atlassian account before SAML SSO was
enabled will use that to log in.
Users who joined after SAML SSO was enabled will need to reset the password
for their Atlassian account when they next log in.
Content Delivery No longer available

network (CDN)
support What happens:
Any API calls related to the feature will be blocked

If you’ve already configured your CDN, then switch back to a Server license, the
CDN will continue to work until your Confluence instance is restarted.
Rate limiting No longer available
What happens:
Any configured limits that were set up before will no longer work. Users will have
unlimited external REST API requests the moment your license is downgraded.
Read-only mode No longer available
What happens:
/accessmode will continue to work

To option to switch on the feature will be disabled
Sandboxed No longer available

processes
Resource-intensive tasks will run in the same Java process, potentially causing
instability and performance issues.
Changes will take effect immediately on license downgrade.
Move from clustered Data Center to Server

If you are running Confluence in a cluster, you'll need to make some infrastructure changes as part of the
switch.
In these instructions we'll assume that you'll use one of your existing cluster nodes as your new, non-clustered
installation. This process applies to any clustered installation, including clusters with just one node.
1. Stop Confluence on all nodes except node 1
First, you must stop Confluence on every node except one, we'll refer to this as node 1. Don't make any other
changes at this stage.
Your home directory (configured in confluence\WEB-INF\classes\confluence-init.properties)

should still point to your local home directory.
2. Enter your Confluence Server license

3. Enter your Confluence Server license key
2. Stop Confluence on node 1
Stop Confluence on node 1. Confluence should not be running on any nodes.
At this point we also recommend configuring your load balancer to redirect traffic away from Confluence, as
Confluence will not be accessible until you complete the migration.
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 following directories and files from your <shared home> directory to the <local home>
/shared-home directory
config
confluence.cfg.xml
2.
dcl-document
dcl-document_hd
dcl-thumbnail
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.
Make sure you don't accidentally overwrite the confluence.cfg.xml in your local home directory. The con
fluence.cfg.xml file from your shared home directory doesn't contain the same parameters as the one in
your local home directory.
4. Start Confluence
Start Confluence. The setup wizard will prompt you to start the migration process.
Once migration is complete, you can make any changes to your load balancer or proxy to allow people to
access Confluence again.
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
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.
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
environment variable manually. See Setting the JAVA_HOME Variable in Windows for a step
by step guide.
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 Service
This information is only relevant if you're installing Confluence
manually on a Windows server. If you're using the installer, you Installing
don't need to do this. Confluence 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
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\Java\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.
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.
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.
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\jdk-11.0.4.11-hotspot\jre\bin\server\jvm.dll
4. Restart the Confluence Windows Service.

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/jdk-11.0.4.11-hotspot/. 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/jdk-11.0.4.11-hotspot/"; export JRE_HOME
If this line isn't present, exit this file and use the environment variable method below.
change to the new setjre.sh file.
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.
If upgrading to a major version, for example from Java 8 to Java 11, be aware that some Java arguments will
not be recognised in later versions. When you upgrade, make sure you apply your customisations manually,
don't simply copy over your old setenv.sh / setenv.bat file, or existing Java options if you run Confluence
as a service.
Creating a Dedicated User Account on the Operating
System to Run Confluence
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.
This is optional if you're evaluating Confluence, but is required for production installations. If you used the
Confluence installer on Linux, this user will be created automatically.
Create a dedicated user account
Linux
If your operating system is *nix-based (for example, Linux or Solaris), type the following in a console:
$ sudo /usr/sbin/useradd --create-home --comment "Account for running Confluence" --shell /bin/bash
confluence
Windows
If your operating system is Windows create the dedicated user account by 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.)
Alternatively, open the Windows 'Computer Management' console to add your 'confluence' user with its own
password.
Next, 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).
Allow the account to write to specific Confluence directories

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.
Linux
To achieve this in Linux run the following commands:
sudo chown -R confluence <confluence-home-folder>/

sudo chown -R confluence <confluence-install-folder>/logs
sudo chown -R confluence <confluence-install-folder>/work
sudo chown -R confluence <confluence-install-folder>/temp
The other install directories should be left as root as those are controlled by the installer and allow for future
upgrades:
sudo chmod -R u=rwx,g=rx,o=rx <confluence-install-folder>

sudo chmod -R u=rwx,g=rx,o=rx <confluence-home-folder>
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
completed installing Confluence.
1. Start the setup wizard
When you access Confluence in your web browser 2. Choose your installation type and apps
for the first time, you will see the Confluence Setup 3. Enter your license key
Wizard. This is a series of screens which will 4. Production installation: database
prompt you to supply some default values for your configuration
Confluence site. It will also offer some more 5. Production installation: external
advanced options for setting up data connections database
and restoring data from a previous installation. 6. Production installation: load content
7. Production Installation: restore data
from backup
1. Start the setup wizard 8. Set up user management
9. Connect to your Jira application
1. Start Confluence (if it is not already running) 10. Set up system administrator account
For Windows, go to Start > Programs > Conf 11. Setup is Complete
luence > Start Confluence Server.
Or, run the start-up script found in the bin
folder 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.
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 www.atlassian.com
/buy.
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
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
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:
comp/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.
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.
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:
Admin Groups – Specify one or more Jira groups whose members should have administrative
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.
If you are already using a Jira application, you can Connecting to a Jira application in the
choose to delegate user management to Jira, Setup Wizard
instead of separately maintaining your users in Troubleshooting
Confluence.
Related pages:
You'll be able to specify exactly which groups in
your Jira app should also be allowed to log in to User Management Limitations and
Confluence. Your license tiers do not need to be the Recommendations
same for each application. Connecting to Crowd or Jira for User
Management
It's possible to connect Confluence to Jira after
completing the setup process, but it's much quicker Confluence Setup Guide
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

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:
Admin Groups – Specify one or more Jira groups whose members should have administrative
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 Cause Solution

setup wizard
Failed to create The setup wizard failed to complete Follow the steps below to remove the
application link, registration of the peer-to-peer application link partial configuration then try the
or with Jira. Jira integration is only partially Connect to Jira step again.
configured.
Failed to
authenticate
application link
Failed to The setup wizard failed to complete Follow the steps below to remove the
register registration of the client-server link with Jira partial configuration then try the
Confluence for user management. The peer-to-peer link Connect to Jira step again.
configuration in was successfully created, but integration is
Jira for shared only partially configured.
user
management
Error setting The setup wizard successfully established the Fix the problem that prevented the
Crowd peer-to-peer link with Jira, but could not application from saving the
authentication persist the client-server link for user configuration file to disk then follow
management in your config.xml file. This the steps below to remove the partial
may be caused by a problem in your configuration before trying the
environment, such as a full disk. Connect to Jira step again.
Error reloading The setup wizard has completed the Restart Confluence. You should be
Crowd integration of your application with Jira, but is able to continue with the setup
unable to start synchronizing the Jira users wizard. If this does not work, contact
authentication
with your application. Atlassian Support for help.
java.lang. The setup wizard has not completed the Follow the steps below to remove the
IllegalStateExce integration of your application with Jira. The partial configuration and resolve any
ption: Could not links are only partially configured. The conflict with existing links then try the
create the problem occurred because there is already a Connect to Jira step again.
application in user management configuration in Jira for this
Jira/Crowd <application> URL.
(code: 500)
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'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
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.
In this guide we'll run you through using the installer
On this page:
to upgrade your Confluence site to the latest
Confluence version on Windows or Linux.
Before you begin
Upgrading to any later version is free if you have Plan your upgrade
current software maintenance. See our Licensing 1. Determine your upgrade path
FAQ to find out more. 2. Complete the pre-upgrade checks
3. Upgrade Confluence in a test
environment
Upgrade Confluence
4. Back up
After the upgrade
7. Copy your database driver
8. Reinstall the service (Windows
only)
9. Re-apply any modifications
10. Update your apps (add-ons)
11. Update your reverse proxy and
Other ways to upgrade Confluence: check you can access Confluence
Troubleshooting
Manually – upgrade without using the
installer.
Data Center – upgrade your Data Center
cluster.
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.
Which upgrade You can choose to upgrade using the installer, or manually using a zip or tar.gz
method is the file. In most cases the installer is the easiest way to upgrade your Confluence
best option? 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 EA
R/WAR distribution to deploy Confluence into an existing application server.
Are you eligible To check if software maintenance is current for your license, go to > General
to upgrade? 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 Check the Supported Platforms page for the version of Confluence you are
supported upgrading to. This will give you info on supported operating systems, databases
platforms and browsers.
changed?
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 Newer Confluence versions sometimes require changes to your environment,
make changes to such as providing more memory or adjusting your reverse proxy settings.
your
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
Create a custom upgrade plan
Planning an upgrade? You can instantly generate a tailored upgrade plan from within
Confluence. Head to > General Configuration > Plan your upgrade
You'll need to have a compatible version of the Troubleshooting and Support tools app installed. Lear
n more
1. Determine your upgrade path
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 7
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, and follow paths below.
4.0 to 4.3 Upgrade to 5.10.x, and follow paths below.
5.0 to 7.x Upgrade directly to the latest version of Confluence 7.
Confluence 7 is a major upgrade
Be sure to check the Confluence Upgrade Matrix, take a full backup, and test your upgrade in a non-
production environment before upgrading your production site.
Enterprise releases
A Long Term Support release is a feature release that gets backported critical security updates and critical
bug fixes during its entire two-year support window. If you can only upgrade once a year, consider upgrading
to a Long Term Support release. Learn more
Long Term Support releases were originally referred to as Enterprise Releases.
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).
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.
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 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 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.
You can find the location of your home directory in the <installation-directory>
/confluence/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.
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
1. Run the installer.
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.
Change to the directory where you downloaded Confluence then execute this command to make
the installer executable:
Next, run the installer – we recommend using sudo to run the installer:
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.
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
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.
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
/classes/confluence-init.properties.
All other customizations, including CATALINA_OPTS parameters in your <install-directory>/bin

/setenv.sh / setenv.bat files, need to be reapplied manually.
Any other configurations, customizations (including any other modifications in the <install-
directory>/conf/server.xml file), the path to your own Java installation in <install-
directory>/bin/setjre.sh, or setjre.bat, or additional files added to the installation directory
are not migrated during 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.
Edit the new file manually, rather than copying over the old file, as the default configuration in these
files may have changed between Confluence versions.
10. Update your apps (add-ons)
You can update any apps that are compatible with the new version of Confluence.
1. Go to
> Manage apps
2. Update your apps to the supported versions.
At this stage, it can be useful to clear your plugin cache. Learn how to do this
This is optional, but can be useful to avoid any issues with third-party apps and plugins.
11. 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 run
ning.
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.
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.
Space directory is empty after the upgrade
If you are upgrading from Confluence 6.3 or earlier, there's a known issue where spaces do not
appear in the space directory. You'll need to reindex your site after upgrading to fix this.
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
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:
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.
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
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
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-

The following properties that can be modified to allow finer control over the migration process:
Property Purpose Default
confluence.wiki.migration. The number of concurrent worker threads migrating 4

threads content
confluence.wiki.migration. The number of items migrated in each batch of work 500

batch.size
confluence.wiki.migration. The comment associated with the newly migrated "Migrated to

versioncomment version of each piece of content Confluence 4.0"
(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.

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:
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.UnknownMacroMigrationException: 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.UnknownMacroMigrationException: 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.MigrationException: 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. 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
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-
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.

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:

Re-running the migration
Notes
Related pages:
Migration from Wiki Markup to XHTML-Based Storage
Format
Page Templates
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.UnknownMacroMigrationException: 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.UnknownMacroMigrationException: 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 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.MigrationException: 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.
Upgrading Confluence Manually
In this guide we'll run you through upgrading your
On this page:
Confluence site to the latest Confluence version on
Windows or Linux using the zip / tar.gz file.
Before you begin
Upgrading to any later version is free if you have Plan your upgrade
current software maintenance. See our Licensing 1. Determine your upgrade path
FAQ to find out more. 2. Complete the pre-upgrade checks
3. Upgrade Confluence in a test
environment
Upgrade Confluence
4. Back up
6. Extract the file and upgrade
Confluence
After the upgrade
7. Reinstall the service (Windows
only)
9. Update your reverse proxy and
Other ways to upgrade Confluence: check you can access Confluence
Troubleshooting
Installer – the simplest way to upgrade
Confluence.
Data Center – upgrade your Data Center
cluster.
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 You can choose to upgrade using the installer, or manually using a zip or tar.gz
right upgrade file. In most cases the installer is the easiest way to upgrade your Confluence
method for you? 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 EA
R/WAR distribution to deploy Confluence into an existing application server.
Are you eligible To check if software maintenance is current for your license, go to > General
to upgrade? 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 Check the Supported Platforms page for the version of Confluence you are
supported upgrading to. This will give you info on supported operating systems, databases
platforms and browsers.
changed?
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 Newer Confluence versions sometimes require changes to your environment,
make changes to such as providing more memory or adjusting your reverse proxy settings.
your
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
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 7
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, and follow paths below.
4.0 to 4.3 Upgrade to 5.10.x, and follow paths below.
5.0 to 7.x Upgrade directly to the latest version of Confluence 7.
Confluence 7 is a major upgrade
Be sure to check the Confluence Upgrade Matrix, 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).
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.
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 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 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 and home directory.
You can find the location of your home directory in the <installation-directory>
/confluence/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.
Download the appropriate file for your operating system - https://www.atlassian.com/software/confluence

/download
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.
properties 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
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 are running Confluence on a different port (not the default 8090)
If you are not running Confluence on port 8090 update <Installation-
Directory>\conf\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.
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
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 run
ning.
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.
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.
In this guide we'll refer to this test environment as st Create a staging environment
aging. Additional configuration options
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.
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.
properties to point to your staging home directory.
4. Edit <home-directory>/confluence.cfg.xml or <installation-directory>/server.
xml to point to your staging database.
<property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/confluencestaging<
/property>

username="postgres"
password="postgres"
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.
-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 mysi
te.staging.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 Change the
server ID for an instance of Jira server 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:
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-
only 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:
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 Server and Data Center
7.7. Browsers
Operating systems
You should only use Confluence with a supported platform. Any Databases
platforms and versions not listed on this page are unsupported, Java
which means we don't test, fix bugs or provide assistance. Infrastructure
See End of Support Announcements for Confluence for upcoming
changes to supported platforms.
Go to > General Configuration > Troubleshooting and Related pages:
support tools to check your instance health. It looks at things like
your license validity, Tomcat version, basic database setup and Confluence
more. Installation Guide
Confluence Setup
Definitions: Guide
Supported - you can use Confluence Server and Data Center 7.7 with Server Hardware
this platform. Requirements
Guide
Limited - you can evaluate Confluence on this platform, but you can't use Supported
it to run a production Confluence site. Platforms FAQ
Deprecated - support for this platform will end in an upcoming release.

Browsers
Desktop browsers Good to know:
Microsoft Edge The Confluence setup wizard requires Javascript to be enabled while
installing Confluence. Learn more
Chrome Parts of Confluence won't display correctly if your browser window
size is less than 1024x768.
Firefox
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
Alpine Linux (3.5 and earlier)

MacOS / OSX (evaluation
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.6 Confluence will not work on MySQL variants such as:
MariaDB - see CONFSERVER-29060
PostgreSQL 10 Percona Server - see CONFSERVER-36471
Confluence can become unresponsive with Oracle's Native Network
Amazon Aurora Encryption - see CONFSERVER-60152 for mitigation options.
(Data Center only)
Good to know:
PostgreSQL 9.6
The embedded H2 database is for evaluation only. For production
MySQL sites, you'll need to use one of the supported external databases
listed on this page.
MySQL 5.7 The only supported Amazon Aurora config is a PostgreSQL-
compatible clustered database with one writer replicating to zero or
MySQL 8 more readers. Learn more
Oracle
Oracle 12c Release 2
Oracle 19c
Microsoft SQL Server
SQL Server 2016
SQL Server 2017
Azure SQL
Embedded database
H2 (evaluation only)
Java
Oracle JRE / JDK Known issues:
Java 1.8 Some Oracle Java versions have bugs that impact Confluence. You
can't run Confluence on Java 1.8.0_25 and 1.8.0_31 (see JDK-
Java 11 8059299) or Java 1.8.0_45 (see JDK-8068400).
Some AdoptOpenJDK versions have bugs that impact Confluence.
AdoptOpenJDK We recommend version jdk8u202 (see CONFSERVER-58784).
You can't run Confluence on the OPENJ9 JVM from AdoptOpenJDK.
Java 8 (HotSpot) Use the HotSpot JVM.
We use AdoptOpenJDK to replicate issues raised with OpenJDK. If
Java 11 (HotSpot) you’re using a different distribution of OpenJDK we’ll still provide
support for our products. However, if the bug is caused by a problem
in Java distribution, you'll need to contact the Java distributor for help.
Good to know:
You don't need to install Java if you plan to use the installer to install
Confluence, as a Java 11 JRE is bundled with Confluence (provided
by AdoptOpenJDK).
See Bundled Tomcat and Java versions to see which Java version
was bundled with your Confluence version.
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. See Bundled Tomcat and Java versions to see which
version of Tomcat was bundled with your Confluence version.
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.
Operating system support:
You should only install and use Confluence on operating system versions that have active vendor
support. For example, you can use Confluence on any Microsoft supported version of Windows,
unless specified otherwise above.
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
SQL Server 2014 No support in Confluence 7.5 ( announcement )

PostgreSQL 9.5
SQL Server 2012 No support in Confluence 7.4 ( announcement )
PostgreSQL 9.4 No support in Confluence 7.4 (announcement)

MySQL 5.6
Oracle 12c R1
Internet Explorer 11 No support in Confluence 7.5 ( announcement )
View File macros These macros are now fully supported ( updated announcement )
Most recent announcements first:
Deprecated databases for Confluence (11 December 2019)

Deprecated database for Confluence (11 December 2019)
Deprecated databases for Confluence (14 October 2019)
Deprecated browsers for Confluence (24 September 2019)
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 (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 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 Application Servers for Confluence (27 January 2010)
Deprecated Java Platforms for Confluence (27 January 2010)
Deprecated Web Browsers for Confluence (14 December 2009)
Deprecated databases for Confluence (11 December 2019)

Atlassian will not support the following databases in Confluence 7.5:
Microsoft SQL Server 2014

PostgreSQL 9.5
End of support means that Atlassian will not offer support for, or fix bugs related to, running Confluence 7.5 or
later with this database.
Confluence 7.4 is the last version that will support these databases.
Confluence 7.4 and earlier versions will continue to work with these databases, however we will not fix
bugs affecting these databases after the end-of-life date for your version of Confluence.
Confluence 7.5 and later will not be tested with these databases.
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 database for Confluence (11 December 2019)

Atlassian will not support the following database in Confluence 7.4:
Microsoft SQL Server 2012
later with this database.
Confluence 7.3 is the last version that will support Microsoft SQL Server 2012.
Confluence 7.3 and earlier versions will continue to work with Microsoft SQL Server 2012, however we
will not fix bugs affecting this database after the end-of-life date for your version of Confluence.
Confluence 7.4 and later will not be tested with Microsoft SQL Server 2012.
dot com.

Atlassian will not support the following databases in Confluence 7.4:
PostgreSQL 9.4
MySQL 5.6
Oracle 12c R1
later with these databases.
Confluence 7.3 is the last version that will support these databases.
Confluence 7.3 and earlier versions will continue to work with these databases, however we will not fix
Confluence 7.4 and later will not be tested with these databases.
dot com.
Deprecated browsers for Confluence (24 September 2019)

In 2015 Microsoft released Edge as the browser to supersede Internet Explorer, and in recent times Microsoft
has discouraged the use of Internet Explorer as a default browser. To allow us to continue to take advantage of
modern web standards to deliver improved functionality and the best possible user experience across all of our
products, we have decided to end support for Internet Explorer 11.
End of support means we will not fix bugs specific to Internet Explorer 11, and will begin to introduce features
that aren't compatible with this browser.
When is this happening?
Confluence 7.4 is the last version to support Internet Explorer. Confluence 7.4 will be an Enterprise
release.
Confluence 7.5 and subsequent versions will not support Internet Explorer 11.
What this means for you
We recommend switching to one of our supported browsers, such as Microsoft Edge, Google Chrome, or
Mozilla Firefox.
dot com.
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 CLOSED .
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.
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.
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.
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
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 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.
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.
Changes to features in Confluence (12 March 2019)
Shortcut links
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.
Thanks for your feedback on CONFSERVER-57610 NOT BEING CONSIDERED
We've heard you, and will not end support for Shortcut links in Confluence 7.0.
Trackback and external referrers
We will remove the trackback and referrers features completley in Confluence 7.0.
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.
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.
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.
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
Confluence 6.13 and later will not be tested with PostgreSQL 9.3.
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 and earlier versions will continue to work with PostgreSQL 9.2, however we will not fix
Confluence 6.8 and later will not be tested with PostgreSQL 9.2.
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 CLOSED .
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.
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.
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:
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.
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 CLOSED or contact us directly at eol-
announcement 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.
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.

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-
End of life announcement for database support
Database Support End Date
MySQL 5.5 After Confluence 5.10.x
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 CLOSED
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,
please comment on this issue CONFSERVER-38253 - Plans to remove status updates CLOSED .
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.
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 CLOSED .
Deprecated databases for Confluence (19 May 2015)

End of Life Announcement for Database Support
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
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
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.
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
for details of platform support for Confluence. If you have questions or concerns regarding this announcement,
End of Life Announcement for Java 7 Support
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.
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-

PostgreSQL 8.4
PostgreSQL 9.0
PostgreSQL 9.1 With the release of Confluence 5.7
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
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.
Tomcat 6.0.x When Confluence 5.6 is released, due in mid 2014
Tomcat 6.0.x notes:
Deprecated Databases for Confluence (2 December 2013)

PostgreSQL 8.3 When Confluence 5.5 is released, due in early 2014
PostgreSQL 8.3 notes:
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-
Deprecated Databases for Confluence (13 August 2013)

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.
Tomcat 5.5.x When Confluence 5.0 is released, due in early 2013
Tomcat 5.5.x notes:
Tomcat 6.0.x will still be supported in Confluence 5.0.
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
for details of platform support for Confluence. If you have questions or concerns regarding this announcement,
End of Life Announcement for Java 6 Support
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
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)

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.

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)

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).
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.
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.
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.
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.
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.
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.
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)

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
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)

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.
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.
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)

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.
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.
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)

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.
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.
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.

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.
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.
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.
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:

work with stated application servers. However, we will not fix bugs affecting JBoss application
servers.
Confluence 3.2 will not support JBoss application servers.
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.
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.
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.
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.
Bundled Tomcat and Java versions
This page lists the specific versions of Apache Tomcat and Adopt OpenJDK that we bundle with Confluence.
This information is useful if you want to check whether your Confluence version might be using a Tomcat or
Java version that's affected by a specific issue, vulnerability, or bug.
We also list the specific Java versions we use when testing Confluence, which can be handy if you don't run
Confluence with the bundled JRE.
Confluence 7.7
Confluence Tomcat Bundled JRE Tested JREs
7.7.2 9.0.33 Adopt OpenJDK 11.0.7_10 Oracle JDK 8u251

Oracle JDK 11.0.7
Adopt OpenJDK 8u232-b09
Note: 7.7.0 and 7.7.1 were internal releases.
Confluence 7.6

Oracle JDK 11.0.7

Oracle JDK 11.0.7

Oracle JDK 11.0.7
Confluence 7.5

Oracle JDK 11.0.7

Oracle JDK 11.0.7

Oracle JDK 11.0.7
Confluence 7.4

Oracle JDK 11.0.5

Oracle JDK 11.0.7

Oracle JDK 11.0.7

Oracle JDK 11.0.7
Note: Adopt OpenJDK 11.0.3 and 11.0.4 had known issues in Linux and Windows in 7.4.0.
Confluence 7.3

Oracle JDK 11.0.5

Oracle JDK 11.0.5

Oracle JDK 11.0.5

Oracle JDK 11.0.5

Oracle JDK 11.0.5
Confluence 7.2
7.2.0 9.0.27 Adopt OpenJDK 8u202b08 Oracle JDK 8u202

Oracle JDK 11.0.1
Adopt OpenJDK 11.0.1+13

Oracle JDK 11.0.1

Oracle JDK 11.0.1
Note: Java 11 is supported, but not bundled in Confluence 7.2.
Confluence 7.1

Oracle JDK 11.0.1

Oracle JDK 11.0.1

Oracle JDK 11.0.1
Note: Java 11 is supported, but not bundled in Confluence 7.1.
Confluence 7.0

Oracle JDK 11.0.1

Oracle JDK 11.0.1

Oracle JDK 11.0.1

Oracle JDK 11.0.1

Oracle JDK 11.0.1
Confluence 6.15
Note: There was a known issue with Adopt OpenJDK 8u222b10, which was bundled with Confluence 6.15.8
CONFSERVER-58784 CLOSED .
Confluence 6.14
Confluence 6.13
6.13.0 9.0.12 Oracle JDK 1.8.0_192 -
6.13.1 9.0.12 Oracle JDK 1.8.0_192 -
6.13.2 9.0.12 Adopt OpenJDK 8u192b12 Oracle JDK 1.8.0_192
6.13.3 9.0.12 Adopt OpenJDK 8u192b12 Oracle JDK 1.8.0_192
Note: There was a known issue with Adopt OpenJDK 8u222b10, which was bundled with Confluence 6.13.7
CONFSERVER-58784 CLOSED .
Confluence 6.12
Confluence Tomcat Bundled JRE
6.12.0 9.0.11 Oracle JDK 1.8.0_181
6.12.1 9.0.11 Oracle JDK 1.8.0_181
6.12.2 9.0.12 Oracle JDK 1.8.0_181
6.12.3 9.0.12 Oracle JDK 1.8.0_181
6.12.4 9.0.12 Oracle JDK 1.8.0_181
Confluence 6.11
6.11.0 9.0.10 Oracle JDK 1.8.0_162
6.11.1 9.0.10 Oracle JDK 1.8.0_162
6.11.2 9.0.11 Oracle JDK 1.8.0_181
Confluence 6.10
6.10.0 9.0.8 Oracle JDK 1.8.0_162
6.10.1 9.0.8 Oracle JDK 1.8.0_162
6.10.2 9.0.10 Oracle JDK 1.8.0_162
6.10.3 9.0.19 Oracle JDK 1.8.0_202
Confluence 6.9
6.9.0 8.0.51 Oracle JDK 1.8.0_162
6.9.1 8.0.51 Oracle JDK 1.8.0_162
6.9.2 8.0.52 Oracle JDK 1.8.0_162
6.9.3 8.0.52 Oracle JDK 1.8.0_162
Confluence 6.8
6.8.0 8.0.50 Oracle JDK 1.8.0_162
6.8.1 8.0.50 Oracle JDK 1.8.0_162
6.8.2 8.0.51 Oracle JDK 1.8.0_162
6.8.3 8.0.51 Oracle JDK 1.8.0_162
6.8.4 8.0.52 Oracle JDK 1.8.0_162
6.8.5 8.0.52 Oracle JDK 1.8.0_162
Confluence 6.7
6.7.0 8.0.48 Oracle JDK 1.8.0_162
6.7.1 8.0.48 Oracle JDK 1.8.0_162
6.7.2 8.0.48 Oracle JDK 1.8.0_162
6.7.3 8.0.50 Oracle JDK 1.8.0_162
Confluence 6.6
6.6.0 8.0.47 Oracle JDK 1.8.0_152
6.6.1 8.0.48 Oracle JDK 1.8.0_162
6.6.2 8.0.48 Oracle JDK 1.8.0_162
6.6.3 8.0.50 Oracle JDK 1.8.0_162
6.6.4 8.0.50 Oracle JDK 1.8.0_162
6.6.5 8.0.51 Oracle JDK 1.8.0_162
6.6.6 8.0.51 Oracle JDK 1.8.0_162
6.6.7 8.0.52 Oracle JDK 1.8.0_162
6.6.8 8.0.53 Oracle JDK 1.8.0_162
6.6.9 8.0.53 Oracle JDK 1.8.0_181
6.6.10 8.0.53 Oracle JDK 1.8.0_192
6.6.11 8.0.53 Oracle JDK 1.8.0_192
6.6.12 8.0.53 Oracle JDK 1.8.0_192
6.6.13 8.0.53 Oracle JDK 1.8.0_202
6.6.14 8.0.53 Oracle JDK 1.8.0_202
6.6.15 8.0.53 Oracle JDK 1.8.0_202
6.6.16 8.0.53 Oracle JDK 1.8.0_202
6.6.17 8.0.53 Oracle JDK 1.8.0_202
Confluence 6.5
6.5.0 8.0.47 Oracle JDK 1.8.0_144
6.5.1 8.0.47 Oracle JDK 1.8.0_144
6.5.2 8.0.47 Oracle JDK 1.8.0_152
6.5.3 8.0.51 Oracle JDK 1.8.0_162
Confluence 6.4
6.4.0 8.0.43 Oracle JDK 1.8.0_131
6.4.1 8.0.43 Oracle JDK 1.8.0_131
6.4.2 8.0.46 Oracle JDK 1.8.0_144
6.4.3 8.0.47 Oracle JDK 1.8.0_144
Confluence 6.3
6.3.0 8.0.43 Oracle JDK 1.8.0_131
6.3.1 8.0.43 Oracle JDK 1.8.0_131
6.3.2 8.0.43 Oracle JDK 1.8.0_131
6.3.3 8.0.43 Oracle JDK 1.8.0_131
6.3.4 8.0.43 Oracle JDK 1.8.0_131
Confluence 6.2
6.2.0 8.0.41 Oracle JDK 1.8.0_112
6.2.1 8.0.43 Oracle JDK 1.8.0_131
6.2.2 8.0.43 Oracle JDK 1.8.0_131
6.2.3 8.0.43 Oracle JDK 1.8.0_131
6.2.4 8.0.43 Oracle JDK 1.8.0_131
Confluence 6.1
6.1.0 8.0.41 Oracle JDK 1.8.0_112
6.1.1 8.0.41 Oracle JDK 1.8.0_112
6.1.2 8.0.41 Oracle JDK 1.8.0_112
6.1.3 8.0.41 Oracle JDK 1.8.0_112
6.1.4 8.0.43 Oracle JDK 1.8.0_131
Confluence 6.0
6.0.1 8.0.36 Oracle JDK 1.8.0_102
6.0.2 8.0.36 Oracle JDK 1.8.0_102
6.0.3 8.0.39 Oracle JDK 1.8.0_112
6.0.4 8.0.39 Oracle JDK 1.8.0_112
6.0.5 8.0.39 Oracle JDK 1.8.0_112
6.0.6 8.0.41 Oracle JDK 1.8.0_112
6.0.7 8.0.41 Oracle JDK 1.8.0_112
On this page:
Confluence 7.7
Confluence 7.6
Confluence 7.5
Confluence 7.4
Confluence 7.3
Confluence 7.2
Confluence 7.1
Confluence 7.0
Confluence 6.15
Confluence 6.14
Confluence 6.13
Confluence 6.12
Confluence 6.11
Confluence 6.10
Confluence 6.9
Confluence 6.8
Confluence 6.7
Confluence 6.6
Confluence 6.5
Confluence 6.4
Confluence 6.3
Confluence 6.2
Confluence 6.1
Confluence 6.0
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
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 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.
properties by changing the line starting with 'confluence.home='.
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 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
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
when you are ready? This page gives an overview
of the steps to follow. Step 1. Set up your evaluation Confluence
site
Assumptions: Step 2. Add users and content to your
evaluation site
This page starts with telling you how to install Step 3. Look for interesting Marketplace
an evaluation Confluence site. If you have apps as part of your evaluation
already finished evaluating Confluence, you Step 4. Set up your production Confluence
can safely skip steps 1 to 3. site
Your production installation will be an
installed version of Confluence, not a Related pages:
Confluence Cloud site.
You will evaluate Confluence on an installed Supported Platforms
version too, not a Confluence Cloud site. Add and Invite Users
Getting Started as Confluence
If you are using Confluence Cloud to evaluate Administrator
Confluence, please refer to the following guide Confluence installation and upgrade guide
when you want to move to an installed version: Migr
ate 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
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:

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
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
When opened in a viewport, the user will be redirected to: Plan your Confluence Server to Cloud migration.
This guide provides a high-level plan for migrating a self-hosted Confluence Server site to Confluence Cloud. It
covers enlisting your project team, evaluating technology options, ensuring that the current Confluence Server
site is ready for migration, and executing the migration.
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 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.
This includes apps from Atlassian, like Team Calendars for Confluence and Questions for
Confluence. 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 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 in 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.
b. Documentation
Confluence 7.7 3
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.
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 cloud site at the time you sign up for your first cloud product – for example, when
you first sign up for Jira Software Cloud or Confluence Cloud. The format for the site name is https://exam
ple.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 of the Atlassian Cloud users at your
company in one place, manage your users' accounts, and set up security features like SAML SSO.
Organizations are particularly helpful if your company manages more than one cloud site and wants
insight into all your sites, products, and the users who can access them. An organization is available for
every site and can be accessed at admin.atlassian.com. 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 up SSO, you'll need to
verify a domain for your organization. Note that SSO 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 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. Note that apps from Atlassian, like Team Calendars for Confluence and Que
stions for Confluence, aren't included in the migration.
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.atlassian.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 Confluence migrations, including their status and suggested workarounds.
Some known issues include the following:
CONFSERVER-57776 - Time is displaying differently after migrating from Server to Cloud

LONG TERM BACKLOG
If you've run into a different issue or need help to move forward with your migration, you can contact our Technic
al Support team or reach out to our Atlassian Community for advice.
Post-migration
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 Confluence 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.
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.
Need more help with strategy, best practices, or planning questions? Our migration 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.
On this page:
Pre-migration
Migration
Post-migration
Cloud Migration Assistant for Confluence
descr Step-by-step instructions on how to use the Confluence Cloud Migration Assistant to move your data
iption from Confluence Server or Data Center to Confluence Cloud.
The Confluence Cloud Migration Assistant is an app that helps you easily move content, users, and groups from
Confluence Server or Data Center to Confluence Cloud. Built and maintained by Atlassian, the app is free to
install and use.
With the app, 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 Confluence Cloud Migration Assistant
When you want to move users or data from Confluence Server or Data Center to Confluence Cloud.
When you want to assess your apps before moving from Confluence Server or Data Center to
Confluence Cloud.
When you want to run a test or trial migration from Confluence Server or Data Center to Confluence
Cloud.
When the Atlassian Support team has recommended using the app.
The Confluence Cloud Migration Assistant will not work for Jira products. You can download the Jira Cloud
Migration Assistant for Jira migrations to cloud.
Before you begin

Before attempting a test or production migration, ensure you've completed all of the steps for the
Confluence Cloud Migration Assistant in the pre-migration checklist. The checklist will help you prepare
yourself and your data for migration, and ensure you avoid common sources of migration failure.
Install the Confluence Cloud Migration Assistant app

If your Confluence Server site 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.
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 Confluence Cloud Migration Assistant app.
4. Choose Install and you're all set.
Alternatively, you can install it from the Atlassian Marketplace.
Once installed, you can access the migration assistant by going to Confluence Administration > look for the At
lassian Cloud category > select Migration Assistant.
If your Confluence Server site is behind a firewall, you'll need to allow access to the domain: atlassian.
com
Use the migration assistant to assess your apps

Carrying out an assessment of your apps helps you to establish which apps are needed for a migration.
You can find step-by-step instructions for this process in Assessing and migrating apps with the Confluence
Cloud Migration Assistant.
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 and cloud sites.
1. Check for group conflicts
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 site that has the same name as 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
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’ll need to make sure all groups across server and cloud have unique names
before running your migration.
The following groups manage admin access and are blacklisted. They will not be migrated at all: "site-
admins", "system-administrators", "atlassian-addons", "atlassian-addons-admin". Users in these groups
will still be migrated; if you want them to be in one of the blacklisted groups you’ll need to manually add
them after migration.
2. Check for space key conflicts
Before migrating, check that there are no spaces with the same space key between your server and cloud sites.
If a space from your server site has the same space key as a space in your cloud site your migration will fail.
This is because every space in Confluence Cloud must have a unique space key. If you find a conflict you can:
delete duplicate spaces from your cloud or server sites
reset your cloud site

choose not to migrate these spaces
If the migration assistant finds a conflict, the space will not migrate.
If a space key conflict is caused by a previous test migration you can reset your cloud site before migrating.
Use the app to set up and run your migration

Once you have the app installed, there are five key steps to set up and run your migration from server or Data
Center to cloud:
1. Connect to cloud
2. Choose what to migrate
3. Check for errors
4. Review your migration
5. Migrate
The sections below describe each step in detail and explain some common errors that you may come across. If
you have technical questions or issues while using the migration assistant, get in touch with our support team.
Running a test migration
We strongly recommend doing a trial run of your migration to a test or staging site before running your
final migration. Check out our guidance on testing your migration.
1. Connect to your destination Confluence Cloud site
You’ll be asked to add a name for your migration and choose which cloud site you would like to migrate to. You
need to be an admin in both your server and the destination cloud sites.
If you have already connected a cloud site, you should see it in the dropdown. If there is nothing there, you will
need to either connect a new cloud site or sign up for a new cloud license.
When you’re ready to go, check the box to allow Atlassian to move your data from your server site to your cloud
site. If you’re unable to grant Atlassian this access, you won’t be able to migrate with the migration assistant and
will need to do a space import instead.
If your Confluence Server site is behind a firewall, you'll need to allow access to the domain: atlassian.com.
You also might need to allow access to other Atlassian domains.
2. 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
Users and groups
You can choose to either migrate all or none of your users.
If you choose the migrate your users, the first time you do so all your users will be added to your cloud site.
Every migration, after the first, we will just link your data to the users that already exist in cloud. If you have a
large userbase we suggest following our recommendations.
When you migrate your users, they will be added to their groups when they get to cloud. You will need to review
and approve group permissions after you migrate. When you approve group permissions, your users will be
given Confluence access and will be added to your bill.
We won’t send an invitation to your users. To invite your users you can choose to send an invitation from the Ad
ministration space after you have migrated, or send a link for them to log in themselves.
Selecting no users
When you select none under users and groups, we will still migrate some user data connected to the
spaces you are migrating. This is to make sure that mentions, comments, and page history stay active.
User data that will be migrated every time includes:
full name
username (discarded after migration)
email address
We will only migrate this information for users directly connected to the spaces you are migrating.
We will not give these users product access or add them to any groups. They will appear in your cloud
site user list.
If you choose to migrate users later, their product and group access will be updated.
Other things to be aware of when migrating users and groups:
Users are migrated using email address as the source of truth. On subsequent migrations, the migration
assistant will link users by email address rather than re-migrating them. Check out our tips for migrating a
large number of users.
You must validate all your user accounts (email addresses) before migrating to cloud. Migrating unknown
user accounts can potentially allow unauthorized access to your cloud sites. For example, if you had
users in your server instance with emails that you don’t own, say “[email protected]”, you might be
inviting someone who owns “@example.com” to your site in cloud.
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 synchronizing it with your local
directory before migrating. This is to make sure that your users and groups are up to date before you
transfer any data.
Users with disabled status in your server site 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 site that has the same name as 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’ll need to set these
manually after migration.
If you have users that already exist in your destination cloud site and you choose to migrate users with
this app, the following will occur:
If a user has product access in cloud, but has disabled status in your server site, 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 site, they will
be granted product access through the migration process.
If you use Confluence as a knowledge base for Jira Service Desk, your Jira Service Desk users may
also be migrated along with your Confluence users. This will happen if you can see your Jira Service
Desk users in the cwd_user table in Confluence.
Spaces
If you want to migrate all or some of your spaces choose Select spaces from the options. You will then be able
to select what spaces you want to migrate. If you aren’t migrating any spaces you will be taken straight to check
for errors.
Select the spaces you want to add to your migration. You can filter the list or search for particular spaces, or
click Select all if you want to migrate everything at once. You won’t be able to migrate spaces with space keys
that already exist in your Confluence Cloud destination site.
If a space has a MIGRATED status, we have detected that you have already migrated this space to the same
cloud site.
If a space has a QUEUED status, it has already been added to a migration that is waiting to be run.
If you have lots of spaces and attachments or you are on Data Center, you might want to break the
migration up into a few smaller migrations. The migration assistant can be slow to load and process
tasks when there is a lot to manage.
When you've chosen all your spaces, select Add to migration.
3. Check for errors
In this step, the Confluence Cloud Migration Assistant will review your migration and check for common errors. It
will check if your:
migration assistant app is up to date

users have valid and unique email addresses
groups will merge through the migration process
spaces already exist in your cloud site
You may also encounter other issues during the migration process; this step only checks for the issues
mentioned here.
If there is a green tick then the check has passed. If you get a warning sign then you can continue, but you
need to be aware of a potential issue.
If a check comes back with a red error then you will need to resolve the error before you can run your
migration.
If you decide to Continue and fix later, you can come back to view the errors once you have saved your
migration.
Updating the app
The migration assistant may be out of date. If you get this error, you’ll need to update it before running any
migrations.
Users and groups errors
All users will need to have a valid and unique email address. If we detect invalid emails or multiple users with
the same email, you will get an error. You will need to fix these email addresses before you can run your
migration.
If you have chosen to migrate all users, we will check to see if you have any groups with the same name
already in your cloud site. If we find groups with the same name, we will merge the users from the server group
into the cloud group with the same name. You can continue with your migration without fixing this issue, but it’s
important to check that this won’t cause permission escalation.
The following groups manage admin access and are blacklisted. They will not be migrated at all: "site-
admins", "system-administrators", "atlassian-addons", "atlassian-addons-admin". Users in these groups
will still be migrated; if you want them to be in one of the blacklisted groups you’ll need to manually add
them after migration.
Space errors
If you’re migrating spaces we will check to see if there will be any space key conflicts. If you get an error you
can:
delete duplicate spaces from your cloud or server sites

reset your cloud site
choose not to migrate these spaces by removing them from your migration
You will need to resolve any space key conflicts before you can run your migration.
4. Review your migration
This is the final step in setting up your migration.
If everything looks correct and you want to start your migration, click Run. If you would like to start your
migration later or you still have errors to fix, click Save. If you choose to run your migration, it will still be saved
to your dashboard. There, you can view the progress and details of all your migrations.
5. Manage your migrations
Your saved migration will be listed on the migration dashboard, where you can view details or run it. You can
also check the status of a migration, monitor the progress, stop a migration that's currently running, or create a
new one.
You can create as many migrations as you need. At this time, migrations can't be edited or deleted, so if you
create a migration that can't be used, just create a new one.
Status definitions
SAVED Your migration is saved and ready to run.
RUNNING Your migration is currently in progress.
FINISHED All tasks in your migration have been completed.
STOPPED Your migration has been manually stopped. Once stopped, it can't be resumed. Any step
already in progress will first need to finish before the migration 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. 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.
After migrating
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.
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. (If you
have the Free plan, permissions can’t be modified; users and groups retain the same permissions that
they had on your original site.)
Add users to the generic groups if necessary. The generic groups are: "site-admins", "system-
administrators", "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. Go to Administration > Users > Show details and then Resend
invite. When they first log in 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.
Link your other Atlassian products by going to Settings > Application links.
Use the Jira macro repair to update any links to Jira. On your cloud site go to Settings > Jira macro
repair and follow the steps.
Confluence short links like https://confluence.example.com/x/PywS may not work after migrating.
Replacing them with internal links (or full URLs if they’re not in your Confluence site)\before migrating
should solve this issue.
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 migration planning guide.
More information and support

We have a number of channels available to help you with your migration.
For more migration planning information and FAQs, visit the Atlassian Cloud Migration Center.
Have a technical issue or need more support with strategy and best practices? Get in touch.
Looking for peer advice? Ask the Atlassian Community.
Want expert guidance? Work with an Atlassian Partner.
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
Server (a self-hosted Confluence site).
Before you begin
Minimum Confluence version
Not moving from Cloud to Server?
Features and app availability
Team Calendars and Questions data
These resources will help you plan your
Migration approach
migration from:
Infrastructure and database choice
Licenses
Confluence Server to Cloud
Account visibility
Confluence Server to Data Center
Migration steps
Confluence Server to Server
Step 1: Check your apps
Step 2: Install Confluence Server or
Data Center
Step 3: Export your Confluence
Cloud Site
Step 4: Import your Confluence
Cloud site export file
Step 5: Recover sys admin
permissions
Step 6: Install any apps
Step 7: Check your application links
Troubleshooting
Before you begin

There's a few things to understand before you begin this process. Ready to migrate? Skip to the migration
steps
Minimum Confluence version
You can migrate from Confluence Cloud to Confluence Server / Data Center 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 either latest version of Confluence, or the latest Enterprise Release. The Confluenc
e Upgrade Matrix will help you choose the right version for your organisation.
Features and app availability
Some Cloud features won't be available in Confluence Server or Data Center. The navigation and user
experience will also be different in some places. The core functionality of Confluence is the same however.
Marketplace apps are not automatically migrated. When you set up your Confluence Server or Data Center
site, you'll need to reinstall each of your apps.
Not all apps are available for both Cloud and Server / Data Center. When planning your migration, we
recommend you check that your essential apps are available for Server / Data Center in the Atlassian
Marketplace and make a list of the ones you'll need to reinstall.
Team Calendars and Questions data
Confluence Questions and Team Calendars data can't be migrated, as there is currently no way to export
this data from Confluence Cloud.
Migration approach
You can choose to migrate your entire site in one go, or to import your team's content, space by space.
A full site migration involves a full site export (backup), and importing this file into Confluence Server or
Data Center. Users and groups are included in this export. All spaces will be migrated, including archived
spaces and personal spaces.
See Migration steps below to find out how to do this.
A space by space migration involves exporting each space individually, and importing these files into
Confluence Server or Data Center one at a time. This means you can choose which spaces you want to
migrate, or migrate in stages over time. Users and groups are not automatically migrated. If you've
connected Confluence Server or Data Center to an external user directory, or have already populated your
new site with user accounts, we'll attempt to attribute content to the right people on import.
See Import a space from Confluence Cloud if you plan to migrate your spaces one by one.
Infrastructure and database choice
Where you choose to host Confluence Server or Data Center is up to you. See Supported Platforms to find
out which operating systems and databases are supported.
You can use any database listed on the Supported Platforms page, but you don't already have a database
server, we recommend PostgreSQL, which is what Confluence Cloud is run on.
Licenses
You will need a new license to migrate to Confluence Server or Data Center. Your existing Confluence Cloud
license can't be used. You can get a new license at https://my.atlassian.com. You'll also need new licenses
for any paid Marketplace apps.
Account visibility
In Confluence Cloud, people can choose not to make their profile information visible. This means when a
Cloud site is imported into Server, user account information such as their full name, may not be included.
As long as you are logged in as a Site Admin when you complete the site export, email addresses will
always be included, and used as the username when the user accounts are created. Users can then log in,
and update their profile to provide the missing information.
Migration steps
This page will guide you through a full site migration. See Import a space from Confluence Cloud if you
plan to migrate your spaces one by one.
Step 1: Check your apps
To check your apps are compatible:
1. In Confluence Cloud, go to Settings > Manage Apps.

2. Make a note of all User-installed apps.
3. Go to https://marketplace.atlassian.com and look up each app to see if a Server or Data Center
edition is available.
Step 2: Install Confluence Server or Data Center
The way you do this depends on whether you're migrating to Server or Data Center, and how you plan to
host the application.
See Confluence Installation Guide for links to all the installation options.
Step 3: Export your Confluence Cloud Site
To export your Confluence Cloud site:
1. Log in to Confluence Cloud as a Site Admin

2. In Confluence Cloud, go to Settings > Backup Manager
3. Follow the prompts to back up the site, and download the XML file.
The file will include all spaces and pages (including attachments), and all your users and groups.
Step 4: Import your Confluence Cloud site export file
Unless your site export file is quite small (less than 25mb) we recommend importing via the home directory
method.
The import will overwrite all spaces, pages, and user accounts in your site - including your
administrator account. You'll recover that account in the next step.
You should back up your database, home directory, and installation directory before you begin, in
case you need to roll back.

4. Make sure Build Index is checked so that your index is created automatically.
5. Choose Import.
See Restoring a Site for more information about the import process.
Step 5: Recover sys admin permissions
When you import a site export file, all user accounts are overwritten, including the system administrator
account that was created when you installed Confluence. Your existing Cloud Site Admin account will not
automatically have system administrator permissions for Confluence Server or Data Center.
To recover system administrator permissions:
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. Go to > User Management > Add Users.
6. Enter the details for your new system administrator account and hit Save. Make sure to use a strong
password.
7. Choose Edit Groups and select the confluence-administrators group. This is a super-group
that has system administrator permissions.
8. Log out, and confirm that you can successfully log in with your new account.
9. Stop Confluence.
10. Edit <installation-directory>/bin/setenv.sh or setenv.bat and remove the system
property.
11. Restart Confluence using your usual method (manually or by starting the service).
See Restore Passwords To Recover Admin User Rights for more information on this process.
Step 6: Install any apps
To re-install your apps:
1. Log in to Confluence Server or Data Center as an administrator.

3. Follow the prompts to search for or upload the apps you identified in step 1. You'll need to purchase
new licenses for these apps.
Remember that Team Calendars and Questions data is not included in your export, and cannot be migrated
from Cloud at this time.
Step 7: Check your application links
If you had multiple Cloud products, such JIRA Software, you may need to make some changes to the
application links.
To remove or update application links:
1. Go to > General Configuration > Application Links.

2. Follow the prompts to check and update any application links that are now pointing to the wrong
place.
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. See Alternative Methods of Deleting
Application Links in Confluence.
Troubleshooting
There are a few known issues that you might encounter when importing your Cloud site.
Can't load pages in your new site
If you experience problems loading pages after the import, head to > General Configuration to check
your base URL as the port may have changed.
User management admin screens are missing
This is a fairly uncommon problem caused by a dark feature flag that is included in your Cloud site export
file. See
CONFSERVER-35177 - User and Group Links Missing from Admin Console After Migrating From Cloud
to Server GATHERING IMPACT
for a workaround.
Jira issues macros are broken
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. See
APL-1144 - Allow relocation of application links even if the target application is still accessible. TO DO f
or a workaround.
You can also edit the XML file prior to importing it into Confluence Server or Data Center, or by bulk editing
those references in Confluence database. See How to bulk update JIRA Issue Macro to point to a different
JIRA instance .
Users' favourites (starred pages, or saved for later) are missing
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.
Some user accounts are missing or created without user details
Users in Confluence Cloud have the ability to change their profile visibility settings. To ensure all user data is
included in the export, ask a site admin to perform the export.
Data Center is Atlassian’s self-managed enterprise edition, built to support your organization’s evolving
needs as you grow.
Confluence Data Center includes advanced capabilities and services in several areas, including security and
compliance, user management, infrastructure automation, reliability, and more to help you easily manage
your enterprise-grade Confluence deployment.
Learn more about the benefits of Confluence Data Center on our website.
Data Center architecture

There are two different architectures available with your Confluence Data Center license:
Non-clustered (single node) Clustered
Run the Confluence Data Center application on a Run Confluence Data Center in a cluster with
single server, just like a Server installation. multiple application nodes, and a load balancer to
direct traffic.
This allows you to take advantage of Data Center-
only features without adding to your infrastructure. Clustering is designed for large, or mission-critical,
Confluence sites, allowing you to provide high
Learn more about Data Center features. availability, and maintain performance as you scale.
Learn more about clustering with Data Center.
Non-clustered Data Center (also known as Standalone, or single node) is only available in Confluence 7.2 or
later.
Get started
Install or upgrade Confluence Data Center
Install Confluence Data Center from scratch

Upgrade from Server to Data Center
Move from Data Center back to Server
Upgrade versions
Clustering with Confluence Data Center
Learn about clustering architecture and requirements

Set up a Data Center cluster
Add or remove application nodes
Turn off clustering (revert to a non-clustered Data Center installation)
Troubleshoot a clustering issue
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.
You can purchase a Data Center license or create an evaluation license at my.atlassian.com
Getting Started with Confluence Data Center
Data Center is a self-managed edition of
On this page:
Confluence, built for enterprises. It provides you
with additional deployment flexibility and
administrative control to help you easily manage 1. Define your requirements
mission-critical Confluence sites. 2. Provision your infrastructure
3. Plan your deployment
You can run Confluence Data Center in a cluster, or 4. Install and configure Confluence Data
as standalone (non-clustered) installation. This Center
guide applies to clustered Data Center installations. 5. Maintain and scale your Confluence
cluster
1. Define your requirements

Before you get started, it’s a good idea to define your organization’s goals and requirements. If you need
high availability, scalability, and performance under heavy load, you'll want to run Confluence Data Center
in a cluster.
To prepare, we recommend assessing:

the number of users you have
the amount of data you have
your expected usage patterns
the resources your organization has allocated to maintain your Confluence site.
For more information about 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
Infrastructure recommendations for enterprise Confluence instances on AWS
2. Provision your infrastructure

Once you've identified your organization's needs, you can prepare your clustered environment. Read our C
lustering with Confluence Data Center for important hardware and infrastructure considerations.
To help you get started with clustering, 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
3. 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.
4. Install and configure Confluence Data Center

Once your environment is ready, it's time to install and configure Confluence Data Center in a cluster.
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 M
oving 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.
5. Maintain and scale your Confluence cluster

Once you've deployed your Confluence Data Center cluster 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
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. If we manage Confluence for you, you'll have a Confluence
Cloud license.
Your Confluence license determines which features and infrastructure choices are available.
Feature comparison
Here’s a summary of available features for Confluence Server and Confluence Data Center. If you’re
interested in having Atlassian host and manage your products, see how a cloud plan compares on our Conflu
ence features page.
Core features Server Data Center

license 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. Learn 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. Le
arn more
Single sign-on
via Crowd 6.1 +
Use a SAML or OpenID Connect identity provider for authentication and
single-sign on. Learn more
Advanced permissions management

7.3 +
Inspect user and group permissions for auditing and troubleshooting
purposes. Learn more
High availability and performance at scale
Clustering
5.6 +
Run Confluence on multiple nodes high availability. Learn more
Content Delivery Network (CDN) support

7.0 +
Improve geo-performance for distributed teams. Learn more
Infrastructure and Control
Read-only mode
6.10 +
Limit what users can do in your site while you perform maintenance. Learn
more
Sandboxed processes
6.12 +
Run resource intensive tasks in external sandboxes for greater stability. Le
arn more
Rate limiting
7.3 +
Control how many external REST API requests users and automations
can make. Learn more
Advanced auditing
7.5 +
Access a wider range of audit events, and integrate with third-party
logging systems. Learn more
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

6.1 +
Use our Cloud Formation Templates to deploy Confluence on AWS. Learn
more
Azure template
6.6 +
Use our template to deploy Confluence on Azure. Learn more
How do you decide what's 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, and organizing 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? Learn more about Data Center
Clustering with Confluence Data Center
Confluence Data Center allows you to run a cluster
On this page
of multiple Confluence nodes, providing high
availability, scalable capacity, and performance at
scale. Is clustering right for my organization?
Clustering architecture
This guide describes the benefits of clustering, and Infrastructure and hardware requirements
provides you an overview of what you’ll need to run App compatibility
Confluence in a clustered environment, including Ready to get started?
infrastructure and hardware requirements.
Ready to get started? See Set up a Confluence

Data Center cluster
Is clustering right for my organization?
Clustering is designed for enterprises with large or mission-critical Data Center deployments that require
continuous uptime, instant scalability, and performance under high load.
There are a number of benefits to running Confluence in a cluster:
High availability and failover: If one node in your cluster goes down, the others take on the load,
ensuring your users have uninterrupted access to Confluence.
Performance at scale: each node added to your cluster increases concurrent user capacity, and
improves response time as user activity grows.
Instant scalability: add new nodes to your cluster without downtime or additional licensing fees.
Indexes and apps are automatically synced.
Disaster recovery: deploy an offsite Disaster Recovery system for business continuity, even in the
event of a complete system outage. Shared application indexes get you back up and running quickly.
Clustering is only available with a Data Center license. Learn more about upgrading to Data Center.
Clustering architecture
The basics
A Confluence Data Center cluster consists of:
Multiple identical application nodes running Confluence Data Center.

A load balancer to distribute traffic to all of your application nodes.
A shared file system that stores attachments, and other shared files.
A database that all nodes read and write to.
All application 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.
The image below shows a typical configuration:

Licensing
Your Data Center license is based on the number of users in your cluster, rather than the number of nodes.
This means you can scale your environment without additional licensing fees for new servers or CPU.
You can monitor the available license seats in the License Details page in the admin console.
If you wanted to automate this process (for example to send alerts when you are nearing full allocation) you
can use the REST API.
The following GET requests require an authenticated user with system administrator permissions. The
requests return JSON.
<confluenceurl>/rest/license/1.0/license Number of active users

/userCount
<confluenceurl>/rest/license/1.0/license Number of users you can add before

/remainingSeats reaching your license limit
<confluenceurl>/rest/license/1.0/license Maximum number of users allowed by your

/maxUsers 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
To run Confluence in a cluster, you'll need an additional home directory, known as the 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
When clustered, Confluence uses a combination of local caches, distributed caches, and hybrid caches that
are managed using Hazelcast. This allows for better horizontal scalability, and requires less storage and
processing power than using only fully replicated caches. See Cache Statistics for more information.
Because of this caching solution, to minimize latency, your nodes should be located in the same physical
location, or region (for AWS and Azure).
Indexes
Each individual Confluence application node stores its own full copy of the index. A journal service keeps
each index in sync.
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 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, you can rebuild the index on one node, and Confluence will
propagate the new index files to each node in the cluster.
See Content Index Administration for more information on reindexing and index recovery.
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.
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.
Uptime over data integrity
Cluster Hazelcast Effect

safety heartbeat
job
1 minute 1 minute You could have network interruptions or garbage collection pauses of up to
1 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 seconds You could have network interruptions or garbage collection pauses of up to

minutes 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
15 15 seconds Network interruptions or garbage collection pauses longer than 15 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/).
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
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, or region (for AWS and Azure)
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.
How many nodes?
Your Data Center license does not restrict the number of nodes in your cluster. The right number of nodes
depends on the size and shape of your Confluence site, and the size of your nodes. See our Confluence
Data Center load profiles guide for help sizing your instance. In general, we recommend starting small and
growing as you need.
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
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
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 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.
Additional requirements for database high availability
Running Confluence Data Center in a cluster removes the application server as a single point of failure. You
can also do this for the database through the following supported configurations:
Amazon RDS Multi-AZ: this database setup features a primary database that replicates to a standby
in a different availability zone. If the primary goes down, the standby takes its place.
Amazon PostgreSQL-Compatible Aurora: this is a cluster featuring a database node replicating to one
or more readers (preferably in a different availability zone). If the writer goes down, Aurora will
promote one of the writers to take its place.
The AWS Quick Start deployment option allows you to deploy Confluence Data Center with either one,
from scratch. If you want to set up an Amazon Aurora cluster with an existing Confluence Data Center
instance, refer to Configuring Confluence Data Center to work with Amazon Aurora.
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 <inst
all-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.
URL Expected content Expected HTTP Status
http://<confluenceurl>/status {"state":"RUNNING"} 200 OK
HTTP Status Response Description

Code entity
200 {"state":" Running normally

RUNNING"}
500 {"state":" An error state

ERROR"}
503 {"state":" Application is starting

STARTING"}
503 {"state":" Application is stopping

STOPPING"}
200 {"state":" Application is running for the first time and has not yet been
FIRST_RUN"} 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.

App compatibility
The process for installing Marketplace apps (also known as add-ons or plugins) in a Confluence cluster is
the same as for a standalone installation. 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?

Head to Set up a Confluence Data Center cluster for a step-by-step guide to enabling and configuring your
cluster.
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 Confluence has enough memory for the external process pool. In a clustered
Data Center installation, you'll need to do this for each cluster node. The pool contains two processes
(sandboxes) by default, so we recommend allowing an additional 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:
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.
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.
In Confluence Server, thumbnail generation is handled by Confluence, so the information on this page
does not apply.
Configure the external process pool

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:
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.
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.
Other system properties that affect document conversion

The system properties listed on this page apply specifically to the external process pool. However there are
some additional properties that apply in both Confluence Server and Confluence Data Center:
Use this property to enable document conversion for TIFF files. This is disabled by default.
Use this property to enable document conversion for Photoshop PSD files. This is disabled by default.
Use this property to change the default 30 second time limit which applies when performing document
conversion on complex image files (such as ICO, EMF, WMF).
confluence.document.conversion.slides.convert.timeout
Use this property to change the default 30 second time limit which applies when performing document
conversion on presentation files (such as PPT, PPTX).
To override the default value of these properties, you'll need to use the conversion.sandbox.java.
options system property to pass the property to the JVMs that make up the external process pool.
In this example we'll enable thumbnail generation for TIFF and PSD files.
1. Edit the <install-directory>/bin/setenv.bat file.

2. Add the following lines
set CATALINA_OPTS=-Dconversion.sandbox.java.options=-Dconfluence.document.conversion.imaging.
enabled.tif=true -Dconfluence.document.conversion.imaging.enabled.psd=true %CATALINA_OPTS%
You can pass multiple properties to the external process pool JVMs this way.
If you're running Confluence as a Windows Service or on AWS, see Configuring System Properties for how
to add this property.
In this example we'll enable thumbnail generation for TIFF and PSD files.
1. Edit the <install-directory>/bin/setenv.sh file.

2. Add the following lines. In this example we're enabling document conversion for TIFF and PSD files.
CATALINA_OPTS="-Dconversion.sandbox.java.options=-Dconfluence.document.conversion.imaging.enabled.
tif=true -Dconfluence.document.conversion.imaging.enabled.psd=true ${CATALINA_OPTS}"
You can pass multiple properties to the external process pool JVMs this way.
If you're running Confluence on AWS, see Configuring System Properties for how to add this property.
If you decide to increase the timeout for generating thumbnails in the external process pool using the document
.conversion.sandbox.request.time.limit.secs system property, you may also want to change the
timeout for complex image files or presentations using the system properties above. Alternatively you could
keep the default, and have these types of files fail sooner.
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.
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.
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.
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 clustered Confluence Data Center installations. This is to
ensure the integrity and performance of your cluster.
The current restricted functions are:
Restricted Data Center Explanation

function Status
Workbox Available
plugins 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.
Confluence Available The quick reload function notifies users when a new comment has been
Quick from 5.6.3 added to a page they are currently viewing.
Reload
Plugin
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 - Make quick reload plugin available in
Confluence Data Center CLOSED
for more info.
Application RESTRICTED When creating Application links to other applications (for example Jira) Basic
links HTTP and Trusted Applications authentication is not supported for
authenticati Confluence Data Center.
on:
All application links must use OAuth authentication in a cluster.
Basic
access
(http)
Trusted
Applicati
ons
Confluence DISABLED The Confluence Usage Stats plugin provides space activity information for a
Usage space (statistics). This is disabled by default in Confluence Server and
Stats plugin should not be enabled in Confluence Data Center.
Scheduled LIMITED On the Scheduled Jobs page in the Confluence Data Center administration
jobs history console you will not be able to access the last execution time or history for
and status 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 LIMITED Remember me on the log in page is enabled by default (and does not
me on by appear) to allow users to move seamlessly between nodes. You can use the
default cluster.login.rememberme.enabled system 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.
Set up a Confluence Data Center cluster
Confluence Data Center allows you to run a cluster of multiple Confluence
On this page
nodes, providing high availability, scalable capacity, and performance at
scale.
Clustering with
This guides walks you through the process of configuring a Data Center AWS and Azure
cluster on your own infrastructure. Before you begin
Set up and
You’ll need to be logged in as a System Administrator to do this. configure your
cluster
Not sure if clustering is right for you? Check out Clustering with Confluence Add more
Data Center for a detailed overview. Confluence nodes
Troubleshooting
We’re here to help
Clustering with AWS and Azure

You can also choose to deploy a Data Center cluster on public cloud
providers, like AWS (Amazon Web Services) and Azure. We have specific
guides and deployment templates to help you easily configure a cluster in A
WS or Azure. Check them out to find out what's required.
Before you begin
Clustering requirements
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 OAuth authentication if you have application links to other
Atlassian products (such as Jira)
To run Confluence in a cluster you must also:
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). This must be a
separate directory, and not located within the local home or install
directory.
See Clustering with Confluence Data Center for a complete overview of

hardware and infrastructure considerations.
Security
Ensure that only permitted cluster nodes are allowed to connect to the
following ports through the use of a firewall and / or network segregation:
5801 - Hazelcast port for Confluence

5701 - Hazelcast port for Synchrony
25500 - Cluster base port for Synchrony
If you use multicast for cluster discovery:
54327- Multicast port for Synchrony (only required if running

Synchrony standalone cluster)
Terminology

Local home directory – The home or data directory stored locally on
each cluster node (if Confluence is not running in a cluster, 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.
Set up and configure your cluster

We recommend completing this process in a staging environment, and
testing your clustered installation, before moving to production.
1. Back up
We strongly recommend that you backup your existing Confluence local

home and install directories and your database before proceeding.
You can find the location of your home directory in the <installation
-directory>/confluence/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.
2. Create a shared home directory
1. Create a directory that's accessible to all cluster nodes via the same
path. This will be your shared home directory.
2. In your existing Confluence home directory, move the contents of <lo
cal home directory>/shared-home to the new shared home
directory you just created. To prevent confusion, we recommend
deleting the empty <local home directory>/shared-home dire
ctory once you've moved its contents.
3. Move your <local home>/attachments> directory to the new <s
hared home>/attachments directory.
4. Enable cluster mode
Before you enable cluster mode, you should be ready to restart Confluence
and configure your cluster. This will require some downtime.
3. Choose Clustering from the sidebar.
4. Select Enable cluster mode.
5. Select Enable to confirm you’re ready to proceed.
5. Restart Confluence
Restart Confluence to configure your cluster. Once you restart, Confluence

will be unavailable until you’ve completed the set up process.
6. Configure your cluster
The setup wizard will prompt you to configure the cluster, 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
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.
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

Role choose to authenticate by IAM Role or Secret
or Key.
Secre
t Key
Region This is the region your cluster nodes (EC2

instances) will be running in.
Host Optional. This is the AWS endpoint for

head Confluence to use (the address where the EC2
er API can be found, for example 'ec2.amazonaws.
com'). Leave blank to use the default endpoint.
Secur Optional. Use to narrow the members of your

ity cluster to only resources in a particular security
grou group (specified in the EC2 console).
p
name
Tag Optional. Use to narrow the members of your

key cluster to only resources with particular tags
and T (specified in the EC2 console).
ag
value
If Synchrony is managed by Confluence, the same network settings will be

applied to Synchrony.
Follow the prompts to create the cluster.
When you restart, Confluence will start setting up the cluster. This can take
a few minutes. Some core components of Confluence will also change to
become cluster compatible. For example, Confluence will switch to a
distributed caching layer, managed by Hazelcast.
Do not restart Confluence until your cluster is set up, and Confluence is
back up and running.
Your Data Center license doesn’t restrict the number of nodes in your
cluster. To achieve the benefits of clustering, such as high availability, you’ll
need to add at least one additional cluster node.
We’ve found that typically between 2 and 4 nodes is sufficient for most
organizations. In general we recommend starting small and growing as
needed.
7. Copy Confluence to the second node
To copy Confluence to the second node:
1. Shut down Confluence on node 1.

2. Copy the installation directory from node 1 to node 2.
3. Copy the local home directory from node 1 to node 2.
Copying the local home directory ensures the Confluence search index, the
database and cluster configuration, and any other settings are copied to
node 2.
Copying the local home directory ensures the Confluence search index, the
database and cluster configuration, and any other settings are copied to
node 2.
Make sure your database has sufficient connections available to support the
number of nodes.
8. Configure your 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.
See Clustering with Confluence Data Center for further load balancer
guidance.
9. 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.

2. Wait for Confluence to become available on node 1
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.
10. Test your Confluence cluster
To test creating content you'll need to access Confluence via your load
balancer URL. 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 URL, 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 clu
ster panic. This can be fixed by troubleshooting the network
connectivity of the cluster.
11. Set up a Synchrony cluster (optional)
Synchrony is required for collaborative editing. You have two options for
running Synchrony with a Data Center license:

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.
You deploy and manage Synchrony standalone in its own cluster
with as many nodes as you need. Significant setup is required. See S
et 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.
Troubleshooting
If you have problems with the above process, check our cluster
troubleshooting guide.
We’re here to help
Need help setting up your cluster? There are a range of support services
available to help you plan and implement a clustered Data Center
installation.
An Atlassian Technical Account Manager can provide strategic

guidance. They work with you to develop best practices for
configuring, deploying and managing Confluence in a cluster.
The Atlassian Premier Support team can provide technical support.
Premier Support also offers health check analyses to validate the
readiness of your environment.
Atlassian Enterprise Partners offers a wide array of services to help
you get the most out of your Atlassian tools.
You can also ask questions in the Atlassian Community.
Confluence Data Center Performance
This document describes the performance tests we
On this page
conducted on clustered Confluence Data Center
within Atlassian, and the results of those tests. You
can compare these data points to your own Testing results summary
implementation to predict the type of results you Testing methodology and specifications
might expect from implementing Confluence Data How we tested
Center in a cluster 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
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 DCS- 4PORT SFP+ REAR-TO-FRONT AIR 2XAC 1

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

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 Clustering with Confluence Data Center. 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 benefits of
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,

access 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. We'll also assume you've already set up and configured your cluster. See Set up a Confluence Data
Center cluster.
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
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 Your standby site should have exactly the same version of Confluence installed as your
installation 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 The search index isn't a primary source of truth, and can always be recreated from the
Index 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
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:
Oracle: http://www.oracle.com/technetwork/database/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 There's no need for the configuration of the standby cluster to reflect that of the live cluster. It
cluster 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 Where we mention <confluencesharedhome> as the location of files that need to be

locations synchronized, we're referring to the shared home for the cluster. <confluencelocalhome>
refers to the local home of the node in the cluster.
Starting It's important to initially start only one node of the cluster, allow it to recover the search index,
the and check it's working correctly before starting additional nodes.
standby
cluster
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.
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, You need to ensure that no plugin updates or index backups occur during the test:
plugins and
indexes 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 <confluencelocalhome>
/confluence.cfg.xml file to avoid any conflict
3. Change the location of the shared home directory in the <confluencelocalhome
>/confluence.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 <confluencelocalhome>/confluence.cfg.xml
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.
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
Troubleshooting
If you encounter problems after failing over to your standby instance, check these FAQs for guidance:
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.
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.
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.
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
RPO Recovery Point How up-to-date you require your Confluence instance to be after a failure.
Objective
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.
If you're experiencing Cluster Panic messages in non-clustered installation Symptoms

of Confluence, visit the Knowledge Base article 'Database is being updated Didn't find a
by an instance which is not part of the current cluster' Error Message. solution?
You must ensure the clocks on your cluster nodes don't diverge, as it can Related pages:
result in a range of problems with your cluster.
Troubleshooting a
Data Center cluster
Symptoms outage
Below is a list of potential problems with Confluence Data Center, and their
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 which is not part of the current cluster'
errors on a stand-alone Error Message
Database is being updated by an instance Add multicast route, Check firewall, Cluster
which is not part of the current cluster Panic due to Multiple Deployments
errors 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 license Disable and re-enable the app in the
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
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.
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>
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
"Exception bootstrapping cluster:Shared home directory is not configured correctly" Error during
Confluence Data Center startup
Recovering from a Data Center cluster split-brain
Starting Confluence node fails with 'Port [5801] is already in use and auto-increment is disabled.
Hazelcast cannot start' error
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
Hazelcast CANNOT start on this node. No matching network interface found.
Cluster Panic due to Multicast Traffic Communication Problem
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
This page provides a starting point for investigating Investigate common root causes
outages in your cluster. Garbage collection
Database connections
Establish the originating node Network connectivity
Still having trouble?
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. 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
as possible, to help their investigation.
Use a CDN with Atlassian Data Center applications
On this page:
Get started with CDN

How it works
How to determine whether a CDN will help your users
What is cached?
Planning your CDN implementation
Infrastructure requirements
Considerations for private instances
Marketplace apps and third party customizations
If your users are distributed across the world and experience poor performance when using Data Center
products, you may be able to improve their experience by using a Content Delivery Network (CDN). Common
CDNs include AWS CloudFront, Cloudflare, Akamai, and others.
CDN support is available in Data Center editions of:
Jira Software 8.3

Jira Service Desk 4.3
Confluence 7.0
Bitbucket 6.8.
Get started with CDN
Here's a quick summary of what's involved to enable your CDN in Confluence Data Center:
1. Use our template to spin up an AWS CloudFront distribution, or create an account with the CDN vendor
of your choice.
2. Update your load balancer and firewall to allow the CDN to reach your site.
3. In Confluence Data Center, provide the CDN URL, and enable CDN support.
As end users access your site, static assets will be cached on the edge server closest to them, and served from
there until they expire. This means it might take some time before you can start measuring the impact of the
CDN, depending on when your users are online and accessing the site in each location. We don't provide the
ability to preload the cache, so assets will be cached as they are served for the first time.
See Configure your CDN for Confluence Data Center for the full step-by-step guide.
As always, we recommend testing this on your staging environment, before making any changes to your
production site.
How it works
Static assets (such as JavaScript, CSS, and fonts) are cached on edge servers provided by a CDN vendor that
are geographically closer to the user. This means when someone views a page, some of the assets needed to
display the page are delivered by a server in their region, rather than from your server, known as the origin
server. This can speed up page load times.
For example, if your server (known as the origin) is in Germany, a CDN can improve page load time by as much
as 50% for users located in Rio de Janeiro, as static assets can be served from an edge server in Brazil. If
you're new to CDNs and would like to learn more about how they work, CloudFlare provides a great
introduction, see https://www.cloudflare.com/learning/cdn/performance/.
It's important to note that using a CDN will not make your application inherently faster, what it will do is reduce
the load on your cluster, and reduce the latency experienced by some users, which should result in faster page
load times for users.
Tests on our internal dogfooding instances located in Gdask, Poland have shown the response time for the
View Issue action in Jira Data Center is ~50% faster for people accessing from US East, when CDN is enabled.
How to determine whether a CDN will help your users

A good starting point when assessing whether a CDN will help your users, is to take a look at the network
overhead experienced in your site.
Go to Content Delivery Network in the admin console of your Data Center application. On the Performance
tab you'll see the percentage of requests that had a transfer cost of more than one second. Put simply, the
higher the percentage, the more likely it is that your users requests are being affected by network conditions,
such as latency and connection quality.
This network statistic is a useful indicator of the network conditions your users experience when using the
product. If the percentage is high, it's likely that using a CDN will benefit your users in these conditions.
As users access pages in your site (for example a Confluence page, Jira issue, or Bitbucket pull request
page), we measure the amount of time the browser has to wait to get the content of that page. We then
subtract the time required to render the page on the server. This leaves us with the time it took to send the
request and retrieve the response.
This time is dependent mostly on the latency between the server and the browser, but also includes things
like SSL connection setup time.
This metric is collected on requests that don't use CDN, so it will continue to provide consistent statistics on
your network, even after you enable CDN.
You should also consider where your users are geographically located. For example, if your servers are located
in Frankfurt, and the majority of your teams are located in Germany and Austria, your team based in Malaysia
may be suffering from high latency, resulting in slow page load times.
Network diagnostic tools such as traceroute, ping, and mtr can be helpful to determine the amount of
latency being experienced.
In these examples we'll use traceroute to display some basic network statistics, including latency
information. Remember to replace yoursite.com with your base URL.
In Windows, open Command Prompt and enter the following:
> tracert yoursite.com
In Linux or Mac OS, open Terminal and enter the following:
$ traceroute yoursite.com
This will display the number of hops, and three latency times, in milliseconds, for each server. Average the
three figures to get the latency for that server.
The mtr command (my traceroute) is a useful combination of ping and traceroute. You will need to
install mtr to be able to use it in MacOS or Windows.
What is cached?
We only cache static assets served by a Data Center application or Marketplace app. These are things that are
only going to change when you upgrade your Data Center application or app. Dynamic content is not cached.
Here's a summary of what will be cached when you enable CDN:
Cached Not cached
CSS attached files

JavaScript pages or issues
Fonts personal information, including avatars
assets that are part of a theme
You shouldn't need to ever manually invalidate the cache, as we handle this when you upgrade your Data
Center product, or an app.
Planning your CDN implementation
Infrastructure requirements
You can use any origin pull CDN. You're responsible for any costs associated with your CDN.
We've prepared a CloudFormation template that you can use to configure Amazon CloudFront with minimal
effort. You can find all our AWS deployment resources in this repository https://bitbucket.org/atlassian/atlassian-
aws-deployment/src/master/templates/cdn/.
There are some other infrastructure requirements that you need to be aware of before you start:
HTTP/2 is highly recommended

Your load balancer, firewall, or proxy should allow HTTP/2 traffic. Using HTTP/2 will provide the best
performance for your end users. Check the documentation for your particular provider to find out how to
do this.
Firewall considerations
Your CDN must be able to access and cache static assets. If your instance is not publicly accessible will
you need to make some changes to your firewall to allow requests from the CDN to pass through. We
recommend using application firewalls instead of standard IP range filtering, as CDN IP ranges can
change without notice.
Considerations for private instances
If your site is publicly accessible on the internet, you should be able to enable CDN without any problems.
If your site is not publicly accessible you can:
configure your firewall to allow requests from your CDN to pass through. More information on how to do
this is provided in our step-by-step guides below.
set up your own caching servers closer to your users which will not require opening any traffic to the
internet, instead of using a CDN vendor. See How to configure Apache for caching and HTTP/2 to learn
more about this workaround.
Marketplace apps and third party customizations
Some marketplace apps or customizations may not be compatible with the CDN feature. A health check, on the
Content Delivery Network admin screen will let you know if any of your apps are not compatible.
See User-installed apps health check fails in Data Center when configuring CDN to find out what to do if any of
your apps are incompatible.
If you've developed your own plugin, see Preparing for Confluence 7.0 for information about the APIs you can
use to confirm your plugin is compatible.
Configure your CDN for Confluence Data Center
On this page:
Configure an internet facing load balancer (optional)

Add an internet-facing load balancer
Update your firewall rules for the internet-facing load balancer
Configure your CDN to cache assets
Enable CDN in Confluence
Configure CDN in Confluence via REST API
Troubleshooting
Frequently asked questions
If your users are distributed across the world and experience high latency when using Confluence Data Center,
you may be able to improve their experience by using a Content Delivery Network (CDN). Common CDNs
include AWS CloudFront, Cloudflare, Azure CDN, Akamai, and others.
Head to Use a CDN with Atlassian Data Center applications to learn about our CDN capabilities, and how to
assess whether it will improve your users' experience.
Once you're ready to start using a CDN, there are three main steps:
1. Configure an internet-facing load balancer (optional)

2. Configure your CDN.
3. Enable the CDN feature in Confluence.
Configure an internet facing load balancer (optional)

If your site is not publicly accessible, you'll need to make sure that your CDN can reach it, but only to access
and cache static assets. The way you do this depends on your particular load balancer and web application
firewall. Refer to the documentation for your load balancer and firewall for detailed guidance.
Add an internet-facing load balancer
Add an internet-facing load balancer to your setup. This is in addition to your primary load balancer. Your CDN
is the only entity that will interact with this load balancer. We recommend you:
Enable HTTPS - the traffic from this load balancer will be sent over the public internet and should be
encrypted.
Enable HTTP/1.1 - currently, the caching proxies and CDNs do not handle HTTP/2 well (or at all) on the
way to the origin.
For AWS deployments, you would set up an internet-facing application load balancer.
Update your firewall rules for the internet-facing load balancer
Unlike your primary load balancer, this internet-facing load balancer must be locked down to ensure that your
CDN can only pull data it is allowed to cache. When configuring your firewall rules we recommend:
1. The configuration should only allow requests for paths that start with "/s/". If your application is deployed
with a context path (for example yoursite.com/wiki or yoursite.com/jira) you will need to include it in the
path. All other requests must be blocked.
2. You can also choose to limit the allowed HTTP methods to GET, HEAD, OPTIONS.
For AWS deployments, you will configure a Web Access Control List (WebACL) in the Web Application Firewall
attached to your application load balancer. The condition to use is a "string match condition" applied to "URI".
To check that your setup is secure, perform the following manual tests:
1. A GET on https://internet-facing-proxy/ should return "403 FORBIDDEN".

2. A GET on https://internet-facing-proxy/s should return "403 FORBIDDEN".
3.
3. A GET on https://internet-facing-proxy/s/ should return "404 NOT FOUND".

4. A GET on https://internet-facing-proxy/s/. should return "403 FORBIDDEN".
5. A GET on https://internet-facing-proxy/s/../s/ should return "404 NOT FOUND".
Configure your CDN to cache assets

You'll need an account with a CDN provider. You're responsible for all costs associated with your CDN. We only
support serving static assets from a CDN at this time. This means page content, attached files, and personally
identifiable information, including things like user avatars, won't be cached by your CDN.
We've prepared a CloudFormation template that you can use to configure Amazon CloudFront with minimal
effort. You can find all our AWS deployment resources in this repository https://bitbucket.org/atlassian/atlassian-
aws-deployment/src/master/templates/cdn/.
If you choose not to use our template, define the following in your CDN configuration. This example is based on
AWS CloudFront.
Origin domain name This is your Atlassian application base URL, including the context path if you've
configured one.
For example: mycompany.com/confluence
Origin path Leave blank. There is no need to specify a path.
Allowed HTTP Optionally limit to: GET, HEAD, OPTIONS

methods
Viewer protocol redirect HTTP to HTTPS

policy
Object caching Use origin cache headers
Forward cookies None

This is important to make sure static assets are cached without the user context.
Query String Forward all, cache based on all

Forwarding and
Caching
HTTP protocols Must include HTTP/2
Error pages/Error The default error page caching time for CloudFront is 5 minutes. Consider
Caching Minimum lowering it to a value in the range of 10-30 seconds to decrease the time required
TTL (seconds) to recover from an outage.
Compress Objects Yes

Automatically
Using the default should be fine for most of the other settings.
You will need to adapt this information for your particular CDN provider. You should refer to the documentation
for your CDN for details, as we've found that terminology differs between CDNs.
Enable CDN in Confluence

Once you've configured your CDN, you can enable the CDN option in Confluence.
To turn on CDN:
1. Go to > General Configuration > Content Delivery Network.

2. Navigate to the Settings tab.
3. Set the status to On
4. Paste the URL generated by your CDN into the URL field and hit Validate.
5.
5. If successful, save your changes.
As end users access Confluence, static assets will be cached on the edge server closest to them, and served
from there until they expire. This means it might take some time before you can start measuring the impact of
the CDN, depending on when your users are online and accessing the site in each location.
Configure CDN in Confluence via REST API
You can also interact with the CDN feature using the following REST endpoint: <base-url>/rest/static-
asset-caching/configuration
GET - returns the current CDN status, and URL.

DELETE - deletes the existing configuration and reverts to the default state (CDN disabled, no URL).
This is useful if you can't access the UI because of a caching problem.
PUT - sets the CDN URL and status to the values passed in the body of the request as follows:
{
“enabled”: true,
“url”: “https://yourcdnurl.com”
}
Troubleshooting
Here are some common problems that you may encounter.
We only accept HTTPS CDN URLs

This is particularly important if you're using Azure CDN, as Azure CDN will mirror the same protocol as
the originating request, which means your Data Center application will need to be provisioned with
HTTPS.
Data Center application UI is inaccessible or not functional
Although unlikely, a misconfiguration of your CDN or a CDN service outage may mean your application's
UI is not accessible. If this happens, you will need to disable the CDN feature using the REST API, as
follows.
curl -v -u <admin username>:<admin password> -X DELETE http://<your-base-url>/rest/static-asset-

caching/configuration
This example uses Curl, but you can use any language. Don't forget to replace the username, password,
and base URL placeholders with your own details.
HTTP/2 disabled
Your load balancer, firewall, or reverse proxy should allow HTTP/2 traffic. Using HTTP/2 will provide the
best performance for your end users. See HTTP/2 health check fails in Data Center when configuring
CDN for more information.
User-installed apps may not be compatible
This warning is displayed when we detect that a Marketplace or other user-installed app is using a
deprecated method, which may result in assets being cached incorrectly. See User-installed apps health
check fails in Data Center when configuring CDN for more information on what to do if you see this
warning.
Frequently asked questions
Can I control what static assets are cached?
No, the application controls this. All requests for static assets are routed to the CDN. Requests for non-static
assets are routed directly to your product.
Is personally identifiable information cached?
User created content, usernames, mentions, avatars etc are not static assets, so are not cached. Your CDN
should also be configured to pull content from your product with cookies stripped to make sure it operates
without user context.
Is dynamic content such as batch.js cached?
Although dynamically generated, batch.js is considered static content, so is cached.
Improving instance stability with rate limiting
When automated integrations or scripts send
On this page:
requests to Confluence in huge bursts, it can affect
Confluence’s stability, leading to drops in
performance or even downtime. With rate limiting, How rate limiting works
you can control how many external REST API How to turn on rate limiting
requests automations and users can make and how Limiting requests — what it’s all about
often they can make them, making sure that your Adding exemptions
Confluence instance remains stable. Identifying users who have been rate
limited
Rate limiting is available for Confluence Viewing limited requests in the Confluence
Data Center. log file
Getting rate limited — user’s perspective
Other tasks
How rate limiting works

Here’s some details about how rate limiting works in Confluence.
Rate limiting targets only external REST API requests, which means that requests made within
Confluence aren’t limited in any way. When users move around Confluence, creating pages,
commenting, and completing other actions, they won’t be affected by rate limiting, as we’re seeing this as
a regular user experience that shouldn’t be limited.
Let’s use an example to better illustrate this:
When a user visits a space in Confluence, a number of requests are sent in the background —
these requests ask Confluence for the pages, blog posts, etc. Since this traffic is internal to
Confluence, it won’t be limited.
When the same user opens up the terminal on their laptop and sends a request (like the one
below) to get the contents of a space, it will be rate limited because it’s made outside of
Confluence.
curl -u user:password http://localhost:8090/rest/api/space/SPACEKEY/content
Authentication mechanisms
To give you more details on how we recognize which requests should be limited, we’re targeting external
HTTP requests with these authentication mechanisms:
Basic auth
OAuth
JSESSIONID cookie
Out of the many available techniques for enforcing rate limits, we’ve chosen to use token bucket, which
gives users a balance of tokens that can be exchanged for requests. Here’s a summary of how it works:
Users are given tokens that are exchanged for requests. One token equals one request.
Users get new tokens at a constant rate so they can keep making new requests. This is their Requests
allowed, and can be, for example, 10 every 1 minute.
Tokens are added to a user’s personal bucket until it’s full. This is their Max requests and allows them to
adjust the usage of tokens to their own frequency, for example 20 every 2 minutes instead of 10 every 1
minute, as specified in their usual rate.
When a user tries to send more requests than the number of tokens they have, only requests that can
draw tokens from the bucket will be successful. The remaining ones will end in a 429 error message (too
many requests). The user can retry those requests once they get new tokens.
Confluence tastes best when used with our other products like Jira. Technically, products like these are
external to Confluence, so they should be limited. In this case, however, we’re treating them as belonging
to the same user experience and don’t want to enforce any limits for requests coming from or to these
products.
The way it is now:
Server: Not limited in any way.

Cloud: There’s a known issue that applies rate limits to requests coming from/to cloud products.
We’re working hard to disable rate limits for cloud products and should make that happen soon.
For now, if you’re integrating Confluence with Jira cloud, you should make rate limits higher than
usual.
The general assumption is that Marketplace apps are installed on a Confluence instance, make internal
requests from within Confluence, and shouldn’t be limited. But, as always, it depends on how an app
works.
Internal: If an app in fact works internally, enhancing the user experience, it won’t be limited. An
example of such app would be a special banner that’s displayed in a Confluence space. Let’s say
this banner checks all pages that were created and shows this space’s winner — a user who’s
created the most pages in the last month. Traffic like that would be internal, not limited.
External: Apps whose requests are external to Confluence are limited. Let’s say we have an app
that displays a wallboard on TV. It asks Jira for details about boards, issues, assignees, etc. and
then reshuffles and displays them in its own way as the earlier mentioned wallboard. An app like
that sends external requests and behaves just like a user sending requests over a terminal.
It really depends on the app, but we’re assuming most of them shouldn’t be limited.
Rate limiting is available for Data Center, so you most likely have a cluster of nodes behind a load
balancer. You should know that each of your users will have a separate limit on each node (rate limits are
applied per node, not per cluster).
In other words, if they have used their Requests allowed on one node and were rate limited, they could
theoretically send requests again if they started a new session on a different node. Switching between
the nodes isn’t something users can do, but keep in mind that this can happen.
Whatever limit you’ve chosen (e.g. 100 requests every 1 hour), the same limit will apply to each node,
you don’t have to set it separately. This means that each user’s ability to send requests will still be
limited, and Confluence will remain stable regardless of which node their requests are routed to.
Setting the right limit depends on many factors, so we can’t give you a simple answer. We have some
suggestions, though.
Finding the right limit
The first step is to understand the size of traffic that your instance receives. You can do this by parsing
the access log and finding a user than made the most REST requests over a day. Since UI traffic is not
rate limited, this number will be higher than what you need as your rate limit. Now, that’s a base number
— you need to modify it further based on the following questions:
1. Can you afford to interrupt your users’ work? If your users’ integrations are mission-critical,
consider upgrading your hardware instead. The more critical the integrations, the higher the limit
should be — consider multiplying the number you found by two or three.
2. Is your instance already experiencing problems due to the amount of REST traffic? If yes, then
choose a limit that’s close to the base number you found on a day when the instance didn’t
struggle. And if you’re not experiencing significant problems, consider adding an extra 50% to the
base number — this shouldn’t interrupt your users and you still keep some capacity.
In general, the limit you choose should keep your instance safe, not control individual users. Rate limiting
is more about protecting Confluence from integrations and scripts going haywire, rather than stoping
users from getting their work done.
How to turn on rate limiting

You need the System Administrator global permission to turn on rate limiting.
To turn on rate limiting:
1. In Confluence, go to > General Configuration > Rate limiting.

2. Change the status to Enabled.
3. Select one of the options: Allow unlimited requests, Block all requests, or Limit requests. The
first and second are all about allowlisting and blocklisting. For the last option, you’ll need to enter
actual limits. You can read more about them below.
Make sure to add exemptions for users who really need those extra requests, especially if you’ve chosen
allowlisting or blocklisting. See Adding exemptions.
Limiting requests — what it’s all about

As much as allowlisting and blocklisting shouldn’t require additional explanation, you’ll probably be using the
Limit requests option quite often, either as a global setting or in exemptions.
Let’s have a closer look at this option and how it works:
1. Requests allowed: Every user is allowed a certain amount of requests in a chosen time interval. It
can be 10 requests every second, 100 requests every hour, or any other configuration you choose.
2. Max requests (advanced): Allowed requests, if not sent frequently, can be accumulated up to a set
maximum per user. This option allows users to make requests at a different frequency than their usual
rate (for example, 20 every 2 minutes instead of 10 every 1 minute, as specified in their rate), or
accumulate more requests over time and send them in a single burst, if that’s what they need. Too
advanced? Just make it equal to Requests allowed, and forget about this field — nothing more will be
accumulated.
Examples
Requests allowed: 10/hour | Max requests: 100
One of the developers is sending requests on a regular basis, 10 per hour, throughout the day. If they try
sending 20 requests in a single burst, only 10 of them will be successful. They could retry the remaining
10 in the next hour when they’re allowed new requests.
Another developer hasn’t sent any requests for the past 10 hours, so their allowed requests kept
accumulating until they reached 100, which is the max requests they can have. They can now send a
burst of 100 requests and all of them will be successful. Once they used up all available requests, they
have to wait for another hour, and they’ll only get the allowed 10 requests.
If this same developer sent only 50 out of their 100 requests, they could send another 50 right away, or
start accumulating again in the next hour.
Requests allowed: 1/second | Max requests: 60
A developer can choose to send 1 request every second or 60 requests every minute (at any frequency).
Since they can use the available 60 requests at any frequency, they can also send all of them at once or
in very short intervals. In such a case, they would be exceeding their usual rate of 1 request per second.

Setting the right limit depends on many factors, so we can’t give you a simple answer. We have some
suggestions, though.
The first step is to understand the size of traffic that your instance receives. You can do this by parsing
the access log and finding a user that made the most REST requests over a day. Since UI traffic is not
rate limited, this number will be higher than what you need as your rate limit. Now, that’s a base number
— you need to modify it further based on the following questions:
1. Can you afford to interrupt your users’ work? If your users’ integrations are mission-critical,
consider upgrading your hardware instead. The more critical the integrations, the higher the limit
should be — consider multiplying the number you found by two or three.
2. Is your instance already experiencing problems due to the amount of REST traffic? If yes, then
choose a limit that’s close to the base number you found on a day when the instance didn’t
struggle. And if you’re not experiencing significant problems, consider adding an extra 50% to the
base number — this shouldn’t interrupt your users and you still keep some capacity.
In general, the limit you choose should aim at keeping your instance safe, not to control individual users.
Rate limiting is more about protecting Jira from integrations and scripts going haywire, rather than stoping
users from getting their work done.
Adding exemptions
Exemptions are, well, special limits for users who really need to make more requests than others. Any
exemptions you choose will take precedence over global settings.
After adding or editing an exemption, you’ll see the changes right away, but it takes up to 1 minute to
apply the new settings to a user.
To add an exemption:
1. Go to the Exemptions tab.

2. Click Add exemption.
3. Find the user and choose their new settings.
You can’t choose groups, but you can select multiple users.
4. The options available here are just the same as in global settings: Allow unlimited requests, Block
all requests, or Assign custom limit.
If you want to edit an exemption later, just click Edit next to a user’s name in the Exemptions tab.
Recommended: Add an exemption for anonymous access
Confluence sees all anonymous traffic as made by one user: Anonymous. If your site is public, and your
rate limits are not too high, a single person may drain the limit assigned to anonymous. It’s a good idea to
add an exemption for this account with a higher limit, and then observe whether you need to increase it
further.
Identifying users who have been rate limited

When a user is rate limited, they’ll know immediately as they’ll receive an HTTP 429 error message (too
many requests). You can identify users that have been rate limited by opening the List of limited accounts
tab on the rate limiting settings page. The list shows all users from the whole cluster.
When a user is rate limited, it takes up to 5 minutes to show it in the table.
Unusual accounts
You’ll recognize the users shown on the list by their name. It might happen, though, that the list will show
some unusual accounts, so here’s what they mean:
Unknown: That’s a user that has been deleted in Confluence. They shouldn’t appear on the list for
more than 24 hours (as they can’t be rate limited anymore), but you might see them in the list of
exemptions. Just delete any settings for them, they don’t need rate limiting anymore.
Anonymous: This entry gathers all requests that weren’t made from an authenticated account. Since
one user can easily use the limit for anonymous access, it might be a good idea to add an exemption
for anonymous traffic and give it a higher limit.
Viewing limited requests in the Confluence log file

You can also view information about rate limited users and requests in the Confluence log file. This is useful
if you want to get more details about the URLs that requests targeted or originated from.
When a request has been rate limited you’ll see a log entry similar to this one:
2019-12-24 10:18:23,265 WARN [http-nio-8090-exec-7] [ratelimiting.internal.filter.RateLimitFilter]

lambda$userHasBeenRateLimited$0 User [2c9d88986ee7cdaa016ee7d40bd20002] has been rate limited
-- url: /rest/api/space/DS/content | traceId: 30c0edcb94620c83 | userName: exampleuser
Getting rate limited — user’s perspective

When users make authenticated requests, they’ll see rate limiting headers in the response. These headers
are added to every response, not just when you’re rate limited.
Header Description
X-RateLimit- The max number of requests (tokens) you can have. New tokens won’t be added to
Limit your bucket after reaching this limit. Your admin configures this as Max requests.
X-RateLimit- The remaining number of tokens. This value is as accurate as it can be at the time of
Remaining making a request, but it might not always be correct.
X-RateLimit- The time interval in seconds. You get a batch of new tokens every time interval.
Interval-
Seconds
X-RateLimit- The number of tokens you get every time interval. Your admin configures this as
FillRate Requests allowed.
retry-after How long you need to wait until you get new tokens. If you still have tokens left, it
shows 0; this means you can make more requests right away.
When you’re rate limited and your request doesn’t go through, you’ll see the HTTP 429 error message (too
many requests). You can use these headers to adjust scripts and automations to your limits, making them
send requests at a reasonable frequency.
Other tasks
Allowlisting URLs and resources
We’ve also added a way to allow whole URLs and resources on your Confluence instance using a system
property. This should be used as quick fix for something that gets rate limited, but shouldn’t.
For example, a Marketplace app added some new API to Confluence. The app itself is used from the UI,
so it shouldn’t be limited, but it might happen that Confluence sees this traffic as external and applies the
rate limit. In this case, you could disable the app or increase the rate limit, but this brings additional
complications.
To work around issues like this, you can allowlist the whole resource added by the app so it works
without any limits.
To allow specific URLs to be excluded from rate limiting:
1. Stop Confluence.
2. Add the com.atlassian.ratelimiting.whitelisted-url-patterns system property, and
set the value to a comma-separated list of URLs, for example:
-Dcom.atlassian.ratelimiting.whitelisted-url-patterns=/**/rest/applinks/**,/**/rest/capabilities,
/**/rest/someapi
The way you add system properties depends on how you run Confluence. See Configuring System
Properties for more information.
For more info on how to create URL patterns, see AntPathMatcher: URL patterns.
Allowlisting external applications
You can also allowlist consumer keys, which lets you remove rate limits for external applications integrated
through AppLinks.
If you're integrating Confluence with other Atlassian products, you don't have to allowlist them as this
traffic isn't limited.
1. Find the consumer key of your application.
a. Go to > General Configuration > Application Links.

b. Find your application, and click Edit.
c. Copy the Consumer Key from Incoming Authentication.
2. Allowlist the consumer key.
a. Stop Confluence.
b. Add the com.atlassian.ratelimiting.whitelisted-oauth-consumers system
property, and set the value to a comma-separated list of consumer keys, for example:
-Dcom.atlassian.ratelimiting.whitelisted-oauth-consumers=app-connector-for-confluence-
server
The way you add system properties depends on how you run Confluence. See Configuring
System Properties for more information.
c. Restart Confluence.
After entering the consumer key, the traffic coming from the related application will no longer be limited.
Adjusting your code for rate limiting
We’ve created a set of strategies you can apply in your code (scripts, integrations, apps) so it works with rate
limits, whatever they are.
For more info, see Adjusting your code for rate limiting.
Adjusting your code for rate limiting
Whether it’s a script, integration, or app you’re using — if it’s making external REST API requests, it will be
affected by rate limiting. Until now, you could send an unlimited number of REST API requests to retrieve data
from Confluence, so we’re guessing you haven’t put any restrictions on your code. When admins enable rate
limiting in Confluence, there’s a chance your requests will get limited eventually, so we want to help you prepare
for that.
Before you begin

To better understand the strategies we’ve described here, it’s good to have some some basic knowledge about
rate limiting in Confluence. When in doubt, head to Improving instance stability with rate limiting and have a look
at the first paragraph.
Quick reference
Success: When your request is successful, you’ll get a 2xx code.
Error: When your request fails, you’ll get a 4xx code. If you’re rate limited, it will be 429 (too many requests).
The following HTTP headers are added to every authenticated request affected by rate limiting:
Header Description
X-RateLimit- The max number of requests (tokens) you can have. New tokens won’t be added to
Limit your bucket after reaching this limit. Your admin configures this as Max requests.
X-RateLimit- The remaining number of tokens. This value is as accurate as it can be at the time of
Remaining making a request, but it might not always be correct.
X-RateLimit- The time interval in seconds. You get a batch of new tokens every time interval.
Interval-
Seconds
X-RateLimit- The number of tokens you get every time interval. Your admin configures this as
FillRate Requests allowed.
retry-after How long you need to wait until you get new tokens. If you still have tokens left, it
shows 0; this means you can make more requests right away.
Strategies
We’ve created a set of strategies you can apply in your code so it works with rate limits. From very specific to
more universal, these reference strategies will give you a base, which you can further refine to make an
implementation that works best for you.
1. Exponential backoff
This strategy is the most universal and the least complex to implement. It’s not expecting HTTP headers or any
information specific to a rate limiting system, so the same code will work for the whole Atlassian suite, and most
likely non-Atlassian products, too. The essence of using it is observing whether you’re already limited (wait and
retry, until requests go through again) or not (just keep sending requests until you’re limited).
Universal, works with any rate limiting system.
Doesn’t require too much knowledge about limits or a rate limiting system.
High impact on a Confluence instance because of concurrency. We’re assuming most active users will send
requests whenever they’re available. This window will be similar for all users, making spikes in Confluence
performance. The same applies to threads — most will either be busy at the same time or idle.
Unpredictable. If you need to make a few critical requests, you can’t be sure all of them will be successful.
Summary of this strategy
Here’s the high-level overview of how to adjust your code:
1. Active: Make requests until you encounter a 429. Keep concurrency to a minimum to know exactly when
you reached your rate limit.
2. Timeout: After you receive a 429, start the timeout. Set it to 1 second for starters. It’s a good idea to wait
longer than your chosen timeout — up to 50%.
3. Retry: After the timeout has passed, make requests again:
a. Success: If you get a 2xx message, go back to step 1 and make more requests.
b. Limited: If you get a 429 message, go back to step 2 and double the initial timeout. You can stop
once you reach a certain threshold, like 20 minutes, if that’s enough to make your requests work.
With this strategy, you’ll deplete tokens as quickly as possible, and then make subsequent requests to actively
monitor the rate limiting status on the server side. It guarantees you’ll get a 429 if your rate is above the limits.
2. Specific timed backoff
This strategy is a bit more specific, as it’s using the retry-after header. We’re considering this header an
industry standard and plan to use it across the Atlassian suite, so you can still be sure the same code will work
for Bitbucket and Confluence, Server and Cloud, etc. This strategy makes sure that you will not be limited,
because you’ll know exactly how long you need to wait before you’re allowed to make new requests.
Universal, works with any rate limiting system within the Atlassian suite (and other products using retry-
after) — Bitbucket and Confluence, Server and Cloud, etc.
Doesn’t require too much knowledge about limits or a rate limiting system.
High impact on a Confluence instance because of concurrency. We’re assuming most active users will send
requests whenever they’re available. This window will be similar for all users, making spikes in Jira
performance. The same applies to threads — most will either be busy at the same time or idle.
1. Active: Make requests and observe the retry-after response header, which shows the number of
seconds you need to wait to get new tokens. Keep concurrency level to a minimum to know exactly when
the rate limit kicks in.
a. Success: If the header says 0, you can make more requests right away.
b. Limited: If the header has a number greater than 0, for example 5, you need to wait that number
of seconds.
2. Timeout: If the header is anything above 0, start the timeout with the number of seconds specified in the
header. Consider increasing the timeout by a random fraction, up to 20%.
3. Retry: After the timeout specified in the header has passed, go back to step 1 and make more requests.
With this strategy, you’ll deplete tokens as quickly as possible, and then pause until you get new tokens. You
should never hit a 429 if your code is the only agent depleting tokens and sends requests synchronously.
3. Rate adjustment
This strategy is very specific and expects particular response headers, so it’s most likely to work for Confluence
Data Center only. When making requests, you’ll observe headers returned by the server (number of tokens, fill
rate, time interval) and adjust your code specifically to the number of tokens you have and can use.
It can have the least performance impact on a Confluence instance, if used optimally.
Highly recommended, especially for integrations that require high-volume traffic.
Safe, as you can easily predict that all requests that must go through will in fact go through. It also allows for
a great deal of customization.
Very specific, depends on specific headers and rate limiting system.
1. Active: Make requests and observe all response headers.

2. Adjust: With every request, recalculate the rate based on the following headers:
a. x-ratelimit-interval-seconds: The time interval in seconds. You get a batch of new
tokens every time interval.
b. x-ratelimit-fillrate: The number of tokens you get every time interval.
c. retry-after: The number of seconds you need to wait for new tokens. Make sure that your rate
assumes waiting longer than this value.
3. Retry: If you encounter a 429, which shouldn’t happen if you used the headers correctly, you need to
further adjust your code so it doesn’t happen again. You can use the retry-after header to make sure
that you only make requests when the tokens are available.
Customizing your code

Depending on your needs, this strategy helps you to:
By following the headers, you should know how many tokens you have, when you will get the new ones, and
in what number. The most useful headers here are x-ratelimit-interval-seconds and x-
ratelimit-fillrate, which show the number of tokens available every time interval. They help you
choose the perfect frequency of making your requests.
You can wait to perform complex operations until you’re sure you have enough tokens to make all the
consecutive requests you need to make. This allows you to reduce the risk of leaving the system in an
inconsistent state, for example when your task requires 4 requests, but it turns out you can only make 2. The
most useful headers are x-ratelimit-remaining and x-ratelimit-interval-seconds, which
show how many tokens you have right now and how long you need to wait for the new ones.
With all the information returned by the headers, you can create more strategies that work best for you, or
mix the ones we’ve described here. For example:
If you’re making requests once a day, you can focus on the max requests you can accumulate (x-
ratelimit-limit), or lean towards the remaining number of tokens if a particular action in Confluence
triggers your app to make requests (x-ratelimit-remaining).
If your script needs to work both for Confluence Data Center and some other application, use all headers for
Confluence and focus on the universal retry-after or request codes if the app detects different software.
Running Confluence Data Center on a single node
Data Center allows you to run Confluence in a cluster with multiple nodes, or on a single server (also known
as non-clustered, or standalone Data Center).
This page outlines the architecture and requirements of a non-clustered Confluence Data Center
deployment, as well as some of the benefits and considerations.
Architecture
The deployment architecture of a non-clustered Data Center deployment is the same as a Server
installation. Here’s what a typical setup looks like:
As you can see, Confluence Data Center deployed on a single node looks just as a Server installation, and
consists of:
Confluence Data Center, running on a single node

A database that Confluence reads and writes to
See Getting started as a Confluence administrator to learn more about single server Confluence
installations.
Requirements
Non-clustered Confluence Data Center installations have the same minimum requirements as a Confluence
Server installation. Check our Confluence System Requirements guide for a full overview of the supported
platforms and hardware you’ll need.
Benefits of running a non-clustered Data Center deployment

There are a range of reasons you may choose a single node Data Center. Some of the benefits include:
Keeping your existing infrastructure

Running on a single node means that you can upgrade from Server to Data Center without adding to
your infrastructure. In most cases, moving to Data Center will be as simple as updating your license.
Accessing Data Center-only features

Your Data Center license unlocks a suite of additional security, compliance, and administration
features to help you easily manage enterprise-grade Confluence site – like SAML single sign-on,
advanced permission management, rate limiting, and more. See the complete list
Unlike a Server installation, non-clustered Confluence Data Center installations are cluster-
compatible, which means you can still enable and configure clustering whenever you’re ready to
scale. Learn more about setting up a cluster.
Considerations
Non-clustered Data Center is the simplest setup, but it has some limitations. Just like a Server installation,
you’ll still have the application server as a single point of failure, so it can’t support high availability or
disaster recovery strategies.
Some deployments start to experience performance or stability issues once their size profile hits Large or
XLarge. Most clustered deployments provide you the flexibility to scale up your infrastructure to address
heavy loads (or even scale down to save costs during light loads). On AWS or Azure, you can also quickly
address most stability issues by replacing misbehaving nodes with fresh ones.
For more information about size profiles, see Data Center performance – sizing. We also explain our
own strategies for managing our clustered deployments in How Atlassians monitor their enterprise
deployments.

Confluence 7 7 0 CompleteGuide Compressed

Uploaded by

Copyright:

Available Formats

Confluence 7 7 0 CompleteGuide Compressed

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Confluence 7 7 0 CompleteGuide Compressed

Uploaded by

Copyright:

Available Formats

Documentation for Confluence 7.

Page Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Jira Chart Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Confluence Search Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539

Customizing a Specific Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747

Configuring Indexing Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902

Start Confluence Automatically on Windows as a Service . . . . . . . . . . . . . . . . . . 1039

Confluence Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1287

Tutorial: Navigate Confluence

Alana Baczewski Emma Silvetti William Vladinov

Your mission is broken up into the following components:

Get to know the dashboard

Those new recruits will be here tomorrow; we better get started!

1. Discover: see what's happening in your site.

What's in the sidebar?

1. Space shortcuts: link to Confluence pages or other pages on the web

Configure the sidebar

Try this out:

Find the keyboard shortcuts

The keyboard shortcuts are broken up into 3 categories:

General – Global, page and blog post shortcuts.

In this tutorial, we've:

Explored the anatomy of the dashboard

Just look at your team's adoring faces...

Your mission is broken up into the following components:

Enough about that; let's begin.

Create the space

Hit Save when you're happy with the home page.

A human mission to Mars has

Exploration of Mars has been a

Create your personal space

Create a Team space

Allow anonymous access

Teams in Space HQ, signing off.

How do I use a space?

Stay up to date with spaces

Watch a space to stay up-to-date with any changes.

Change the colors, logo, sidebar and homepage of that space.

Use Confluence as a Knowledge Base

Create a personal space

Create a site space

1. Hit Spaces > Create space in the header.

Linking related spaces

Your Confluence administrator can customize or disable particular

Knowledge base space

Software project space

Use Confluence as a Knowledge Base

Personal spaces always use your username as the space key.

Choosing a space key

View all spaces in Confluence

Edit space permissions

See Assign Space Permissions for more details.

Here's how it looks on the Permissions screen:

How space permissions work

Who is the space admin?

To find out who is an administrators in your space, either:

Go to Space Tools > Overview in the space.

Space admin superpowers

grant permissions to users and groups (and themselves)

Grant space permission