Confluence 4.1 Admin PDF DOC-20111215
Confluence 4.1 Admin PDF DOC-20111215
Confluence 4.1 Admin PDF DOC-20111215
4 Finding Unused Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 0.0.5 Important Directories and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 0.0.5.1 Confluence Home Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 0.0.5.2 Confluence Installation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 0.0.6 Installing a Language Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 0.0.7 Site Backup and Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 0.0.7.1 Production Backup Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 0.0.8 Configuring Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 0.0.8.1 User Submitted Backup & Restore Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 0.0.9 Manually Backing Up The Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 0.0.10 Migrating Confluence Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 0.0.11 Restoring a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 0.0.12 Restoring a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 0.0.12.1 Changing the version of a space backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 0.0.13 Restoring a Test Instance from Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 0.0.14 Restoring Data from other Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 0.0.15 Restoring Data from the Administration Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 0.0.16 Retrieve file attachments from a backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 0.0.17 Troubleshooting failed XML site backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 0.0.18 Troubleshooting XML backups that fail on restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 0.0.18.1 Migrating from HSQLDB to MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 0.0.19 Rebuilding the Ancestor Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 0.0.20 Viewing and Editing License Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 0.0.21 Viewing System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 0.0.21.1 Live Monitoring Using the JMX Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 0.0.21.2 Tracking Customisations Made to your Confluence Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 0.0.21.3 Viewing Site Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 0.0.21.4 Viewing System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 0.0.22 Installing Patched Class Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 0.0.23 Finding Your Confluence Support Entitlement Number (SEN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 0.1 Configuring Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 0.0.1 Site Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 0.0.1.1 Configuring the Site Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 0.0.1.2 Configuring the Administrator Contact Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 0.0.1.3 Editing the Site Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 0.0.1.4 Editing the Global Logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 0.0.1.5 Configuring the Server Base URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 0.0.1.6 Customising Default Space Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 0.0.1.7 Configuring the Destination of View Space Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 0.0.1.8 Editing the Site Welcome Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 0.0.1.9 Configuring the What's New Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
0.0.2 Configuring Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 0.0.2.1 Character encodings in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 0.0.2.2 Troubleshooting Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 0.0.2.2.1 "" Euro character not displaying properly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 0.0.2.2.2 MySQL 3.x Character Encoding Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 0.0.3 Configuring Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 0.0.3.1 Configuring a Server for Outgoing Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 0.0.3.2 The Mail Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 0.0.4 Optional Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 0.0.4.1 Attachment Storage Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 0.0.4.1.1 Hierarchical File System Attachment Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 0.0.4.2 Configuring a WebDAV client for Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 0.0.4.3 Configuring Quick Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 0.0.4.4 Enabling OpenSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 0.0.4.5 Enabling the Did You Mean Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 0.0.4.6 Enabling the Remote API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 0.0.4.7 Enabling Threaded Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 0.0.4.8 Enabling Trackback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 0.0.5 Other Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 0.0.5.1 Configuring Attachment Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 0.0.5.2 Configuring Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 0.0.5.3 Configuring HTTP Timeout Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 0.0.5.4 Configuring Indexing Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 0.0.5.5 Configuring Number Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 0.0.5.6 Configuring Shortcut Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 0.0.5.7 Configuring Time and Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 0.0.6 Configuring System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 0.0.6.1 Recognised System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 0.0.7 Configuring a Large Confluence Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 0.0.8 Configuring Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 0.0.9 External Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 0.1 Confluence Clustering Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 0.0.1 Technical Overview of Clustering in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 0.0.1.1 Cluster safety mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 0.0.2 Changing Datasources Manually in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 0.0.3 Cluster Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 0.0.3.1 Multicast Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 0.0.4 Clustering for Scalability vs Clustering for High Availability (HA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 0.0.5 Recommended network topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 0.0.6 Cluster Administration page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 0.0.7 Cluster Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 0.1 Configuring Confluence Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 0.0.1 Confluence Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 0.0.2 Configuring Secure Administrator Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 0.0.3 Using Fail2Ban to limit login attempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 0.0.4 Securing Confluence with Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 0.0.4.1 Using Apache to limit access to the Confluence administration interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 0.0.5 Enabling or Disabling Public Signup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 0.0.6 Managing External Referrers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 0.0.6.1 Excluding external referrers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 0.0.6.2 Hiding external referrers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 0.0.6.3 Ignoring External Referrers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 0.0.7 Best Practices for Configuring Confluence Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 0.0.8 Hiding the People Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 0.0.9 Configuring Captcha for Spam Prevention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 0.0.10 Hiding External Links From Search Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 0.0.11 Configuring Captcha for Failed Logins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 0.0.12 Configuring XSRF Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 0.0.13 User Email Visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 0.0.14 Anonymous Access to Remote API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 0.0.15 Running Confluence Over SSL or HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 0.0.16 Connecting to LDAP or JIRA or Other Services via SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 0.0.17 Configuring RSS Feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 0.1 Design and Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 0.0.1 Choosing a Default Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 0.0.2 Custom Decorator Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 0.0.3 Customising Look and Feel Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 0.0.3.1 Customising Colour Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 0.0.3.2 Customising Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 0.0.3.2.1 Adding a Navigation Sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 0.0.3.2.2 Upgrading Custom Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 0.0.3.3 Global Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 0.0.3.4 Importing Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 0.0.3.5 Modify Confluence Interface Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 0.0.3.6 Working With Decorator Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 0.0.3.7 Customising a Specific Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 0.0.3.8 Customising PDF or HTML Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 0.0.3.9 Customising the Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 0.0.3.10 Customising the eMail Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 0.0.3.11 Customising the Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
0.0.4 Themes Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.1 Applying a Theme to a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.2 Customising the Left Navigation Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.3 Modifying Look and Feel (for themes) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.3.1 Configuring the Theme Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.3.2 Including Cascading Stylesheets in Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.4 Creating a Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 Importing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1 Importing Content from another Wiki . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 Installing Plugins and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1 Installing and Configuring Plugins using the Universal Plugin Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.1 Checking Plugin Compatibility for Confluence Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.2 Configuring a Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.3 Disabling or Enabling a Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.4 Installing a Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.5 Uninstalling a Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.6 Upgrading your Existing Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.7 Viewing the Plugin Audit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.8 Viewing your Installed Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2 Plugin loading strategies in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3 Removing Malfunctioning Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4 Enabling and Configuring Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.1 Configuring a URL Whitelist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.2 Configuring the User List Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.3 Enabling HTML macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.3.1 Enabling the html-include Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4.4 Troubleshooting the Gallery Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.5 Adding, Editing and Removing User Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.5.1 Writing User Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.5.1.1 Best Practices for Writing User Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.5.1.2 Examples of User Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.5.1.3 Guide to User Macro Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.6 Configuring the Office Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 Operating Large or Mission-Critical Confluence Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1 Cache Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.1 Cache Performance Tuning for Specific Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.2 Confluence Cache Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2 Memory usage and requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3 Requesting Performance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.1 Access Log Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4 Troubleshooting Slow Performance Using Page Request Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.5 Compressing an HTTP Response within Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.6 Performance Testing Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.7 Garbage Collector Performance Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 Scheduled Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1 Setup Confluence To Index External Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2 Setup External Search Tool To Index Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 Working with Confluence Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1 log4j Logging Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1 Understanding User Management in Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2 Configuring User Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.1 Configuring the Internal Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.2 Connecting to an LDAP Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.2.1 Configuring the LDAP Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.2.2 Configuring an SSL Connection to Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.3 Connecting to an Internal Directory with LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.4 Connecting to Crowd or JIRA for User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.4.1 Reverting from Crowd or JIRA to Internal User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.5 Connecting to JIRA 4.2 or Earlier for User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.6 Managing Multiple Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.7 Managing Nested Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.8 Synchronising Data from External Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.9 Diagrams of Possible Configurations for User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.10 User Management Limitations and Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2.11 Requesting Support for External User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3 Confluence User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.1 Searching For and Managing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.2 Adding a New User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.3 Adding a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.4 Adding or Removing Users in Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.5 Changing Usernames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.6 Editing User Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.7 Global Groups Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.8 Global Permissions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.9 Removing a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.10 Removing or Deactivating a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.11 Setting up Anonymous Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
172 173 174 174 178 181 182 183 183 184 185 185 187 188 190 193 194 195 196 198 199 201 201 203 204 204 205 207 208 211 212 216 220 224 231 234 238 239 241 242 245 245 248 249 254 260 265 265 265 266 268 269 269 271 273 274 280 281 289 294 301 304 305 307 310 312 318 321 323 323 327 328 328 331 338 339 340 345 345 347
0.0.3.12 Viewing members of a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.13 Restoring Passwords To Recover Admin User Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.14 Resetting the Login Count for a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.4 Disabling the Built-In User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.1 Integrating Confluence with Other Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1 Configuring Application Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.1 Adding an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.2 Configuring Authentication for an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.2.1 Configuring Basic HTTP Authentication for an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.2.2 Configuring OAuth Authentication for an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.2.3 Configuring Trusted Applications Authentication for an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.2.4 Incoming and Outgoing Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.3 Editing an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.4 Making an Application Link the Primary Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.5 Relocating an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.6 Upgrading an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.7 Deleting an Application Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.8 Configuring Project Links across Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.8.1 Adding Project Links between Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.8.2 Making a Project Link the Primary Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.1.8.3 Deleting a Project Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.2 Configuring OAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3 Confluence and JIRA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.1 Installing Confluence and JIRA Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.2 Integrating JIRA and Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0.0.3.3 Setting Up Trusted Communication between JIRA and Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
347 348 351 351 352 353 353 355 357 358 360 362 362 363 364 364 367 368 368 370 370 371 372 372 373 374
Additional Resources Visit the Configuration Guide for documentation on configuring databases and application servers. The Confluence User's Guide has information on how to use Confluence as a collaborative tool. Go to Documentation Home for links to more resources.
Download You can download the Confluence Admin Guide in PDF, HTML or XML formats.
Site Administrator? The Confluence Administrator's Guide provides information to site administrators on how to manage their Confluence instances. If you still have a question that hasn't been answered, write and tell us about it.
Configuring Confluence
Site Configuration Configuring the Site Home Page Editing the Site Title Editing the Site Welcome Message Configuring the Destination of View Space Links Editing the Global Logo Configuring the Server Base URL Configuring HTTP Timeout Settings Configuring System Properties Customising Default Space Content Optional Settings Enabling the Remote API Enabling Trackback Enabling Threaded Comments Attachment Storage Configuration Configuring Attachment Size Display Settings Configuring Indexing Language Configuring Character Encoding Configuring Time and Date Formats Configuring Number Formats Configuring Shortcut Links
Backups Configuration Configuring Backups Scheduled Jobs Manually Backing Up The Site Restoring Data Restoring a Site Restoring a Space Restoring Data During Setup Restoring Data from the Administration Console Retrieve file attachments from a backup Restoring a Test Instance from Production Scheduled Jobs Scheduled Jobs Data Model Confluence Data Model
System Administration
System Configuration Viewing System Information Viewing and Editing License Details Cache Statistics Viewing Site Statistics System Administration Content Index Administration Upgrading Confluence Migrating Confluence Between Servers Migrate to Another Database Important Directories and Files Rebuilding the Ancestor Table Finding Unused Spaces Large Confluence Installations Operating Large or Mission-Critical Confluence Installations Configuring a Large Confluence Installation Overview of Confluence Clusters Cluster Administration page
Importing Data
Universal Wiki Converter Importing Pages from Disk
Mail Configuration
Configuring a Server for Outgoing Mail The Mail Queue
Security
Overview and Advisories Security Overview and Advisories Security Options Configuring Captcha for Spam Prevention Managing External Referrers Hiding external referrers Hiding External Links From Search Engines Excluding external referrers User Email Visibility Anonymous Access to Remote API Running Confluence Over SSL or HTTPS
User Management
Confluence User Management Global Groups Overview
Global Permissions Overview Setting up Anonymous Access Adding a New User Editing User Details Removing or Deactivating a User Enabling or Disabling Public Signup Adding or Removing Users in Groups Adding a Group Removing a Group Viewing members of a group Restoring Passwords To Recover Admin User Rights External User Management Understanding User Management in Confluence Configuring User Directories Connecting to an LDAP Directory Requesting Support for External User Management Crowd User Management Connecting to Crowd or JIRA for User Management JIRA User Management Connecting to Crowd or JIRA for User Management
Plugin Management
Confluence Plugin Guide Installing a Plugin Installing and Configuring Plugins using the Universal Plugin Manager Configuring the Office Connector Setting Up Trusted Communication between JIRA and Confluence Configuring a URL Whitelist Macros Adding, Editing and Removing User Macros Enabling HTML macros Enabling the html-include Macro Troubleshooting the Gallery Macro Configuring the User List Macro Working With Decorator Macros Writing Macros
Performance Tuning
Memory usage and requirements Configuring a Large Confluence Installation Performance tuning Enabling HTTP Compression Working with Confluence Logs Page Request Profiling Profiling using the YourKit Plugin
Character Encoding
Configuring Encoding Troubleshooting Character Encodings
Support
How to Get Support
Administration
Cache Statistics Confluence Data Directory Configuration Content Index Administration Finding Unused Spaces Important Directories and Files Confluence Home Directory Confluence Installation Directory Installing a Language Pack Site Backup and Restore Production Backup Strategy Configuring Backups User Submitted Backup & Restore Scripts Manually Backing Up The Site Migrating Confluence Between Servers Restoring a Site Restoring a Space Changing the version of a space backup Restoring a Test Instance from Production Restoring Data from other Backups Restoring Data from the Administration Console Retrieve file attachments from a backup Troubleshooting failed XML site backups Troubleshooting XML backups that fail on restore Migrating from HSQLDB to MySQL Rebuilding the Ancestor Table Viewing and Editing License Details Viewing System Information Live Monitoring Using the JMX Interface Tracking Customisations Made to your Confluence Installation Viewing Site Statistics Viewing System Properties Installing Patched Class Files Finding Your Confluence Support Entitlement Number (SEN)
Cache Statistics
Confluence provides statistics about its internal caches that allow you to track the size and hit ratio of each cache and tune it for better performance (if necessary). See Performance Tuningfor more information.
Configurable Caches
System administrators can change the sizes of Confluence's internal caches through the Administration Console and these changes will take effect without the need to first shut down and then restart Confluence. The maximum number of units for any of the defined cache regions can be adjusted individually. Note that larger cache sizes will require more memory at runtime, so you should review the memory allocation of the Confluence Java process and the physical memory available on your server.
To view the cache statistics: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'Cache Statistics' in the left-hand panel. There you will find a list of all objects cached within Confluence. 3. Click the 'Advanced' tab for more detail. Below is an example for one of the most frequently used caches, the 'Content Object' cache. Name Content Object Percent Used 80% Effectiveness 73% Objects / Size 4023 / 5000 Hit / Miss / Expiry 374550 / 140460 / 55044 Adjust Size Adjust Size Flush Flush
About the generated numbers: Percent Used : Effectiveness : Objects / Size: Hit / Miss / Expiry: Adjust Size =(Objects)/(Size)
=(Hits)/(Hits + Misses)
The number of entries in the cache / the number of total possible entries allowed (configurable).
The number of reads accessing cache where required content was found / the number of reads accessing cache where required content was not found / the number of objects evicted from the cache. Use this option to specify a different maximum cache size. Enter a new cache size and click the 'Adjust Size' button to set it. Flushes the cache.
Flush:
To calculate Effectiveness:
The clustered versions of Confluence use distributed cache called Tangosol Coherence.
Important note about clustered Confluence installations The cache configuration file is stored in a home directory of each cluster node. When a Confluence administrator changes a cache size, all running cluster nodes will automatically update their own configuration files in their respective home directories. However, if a cluster node is not running when an administrator adjusts a cache size, the /config/confluence-coherence-cache-config-clustered.xml file in its home directory will not be updated. Since cluster caches are configured by the first node to start, if a node with an outdated cache configuration is the first to start up, the whole cluster would end up using the configuration of that node. However, copying this file from one node to another would resolve this issue.
Performance Tuning
If you need to tune your application when under high usage, you may like to review this document for suggestions.
Related Topics
Page: Cache Performance Tuning Page: Viewing and Editing License Details Page: Cache Statistics Page: Viewing System Information Page: Cache Performance Tuning for Specific Problems Page: Confluence Cache Schemes
Windows Configuration
On Windows, this path:
C:\confluence\data
confluence.home=C:/confluence/data
Note that all backslashes (\) are written as forward slashes (/).
Linux/Solaris Configuration
On any Linux-based system, the property is defined using the normal directory syntax:
confluence.home=/var/confluence/
10
Symbolic links
If your confluence.home directory contains a symbolic link, you must define the absolute path.
Please note that there can be no symbolic links within the confluence.home directory. 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.
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'Content Indexing' under the heading 'Administration' in the left-hand panel.
11
In new Confluence installations, the 'Did You Mean' feature is not initially activated. To activate it, you first need to build its index by clicking its 'Build' button on this page.
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'Content Indexing' under the heading 'Administration' in the left-hand panel. 3. Click the 'Rebuild' button in either the 'Search Index' or 'Did You Mean Index' sections on this page, depending on the particular index you want to rebuild.
If one of these indexes has not yet been built, its button will indicate 'Build' instead of 'Rebuild). As shown in the image below, only one index can be (re)built at a time.
12
Slow Reindexing
Does the reindexing take a long time to complete? The length of time depends on the following factors: Number of pages in your Confluence instance. Number, type and size of attachments. Amount of memory allocated to Confluence. It may help to increase the heap memory allocation of Confluence by following the instructions in the JIRA documentation. If you are running an older version of Confluence and find that the index rebuild is not progressing, you may need to shut down Confluence, and restart it with the following Java system property set: bucket.indexing.threads.fixed=1. This will cause the re-indexing to happen in a single thread and be much more stable (but slower).
Page: Working with Macros Page: Creating a Lowercase Page Title Index Page: Content Index Administration Page: Configuring Indexing Language Page: Rebuild the Content Indices from scratch
13
SELECT spaces.spacename, MAX(content.lastmoddate) FROM content, spaces WHERE content.spaceid = spaces.spaceid GROUP BY spaces.spacename;
It returns a list of spacenames, and the last date and time at which any content was added or changed.
Alternatively, this one simply identifies spaces whose content hasn't changed since a specified date:
SELECT spaces.spacename FROM content, spaces WHERE content.spaceid = spaces.spaceid GROUP BY spaces.spacename HAVING MAX(content.lastmoddate) < '2006-10-10';
The result is a simple list of space names. It's also possible to present the information in a wiki page, using the SQL plugin, which can be installed using the Plugin Exchange. You'll also need to define a database resource in conf/server.xml and confluence/WEB-INF/web.xml, as described here. Having done so, you can use wiki markup code like the following, replacing confluenceDS with the name of your own local datasource:
h3. Space activity {sql:dataSource=confluenceDS|output=wiki} SELECT spaces.spacename AS Space, MAX(content.lastmoddate) AS LastModified FROM content, spaces WHERE content.spaceid = spaces.spaceid GROUP BY Space; {sql}
You can try the Chart plugin in combination with the SQL plugin to give more visually attractive results.
14
The 'Confluence Installation directory' is the directory into which the Confluence application files and libraries have been unpacked (unzipped) when Confluence was installed. Confluence does not modify or store any data in this directory. This directory is also sometimes called the 'Confluence Install directory'. Important Files and Directories confluence/WEB-INF/classes/confluence-init.properties : This file tells Confluence where to find the Confluence Home Directory. This file is modified by the administrator when installing Confluence. confluence/WEB-INF/classes/osuser.xml : This file is modified when connecting Confluence to an external user management system such as an LDAP server or JIRA instance in Confluence 2.0 and earlier. For more information, refer to Understanding User Management in Confluence. confluence/WEB-INF/classes/atlassian-user.xml : This file is modified when connecting Confluence to an external user management system such as an LDAP server or Crowd. For more information, refer to Understanding User Management in Confluence. confluence/WEB-INF/lib/ : This directory is used when deploying plugins, especially those plugins that cannot automatically be loaded through the Administration Console. confluence/WEB-INF/classes/log4j.properties : Confluence's logging configuration file. See Working with Confluence Logs. confluence/WEB-INF/classes/ehcache.xml : This is where you can configure the size of Confluence's internal caches confluence/WEB-INF/classes/styles/site-css.vm : Confluence's main stylesheet, modify at your own risk conf/server.xml : SSL configuration. Memory Settings The file used to edit JAVA_OPTS memory settings will depend on the method used to install Confluence, as well as the operating system used for your installation. Windows Users Confluence bin/setenv.bat Confluence Installer wrapperwin32.conf Mac/Linux Users Confluence bin/setenv.sh Confluence Installer wrapperosx.conf
15
regenerate thumbnails as required. velocity/ : Storage for customised page layouts, globally and per-space.
Database
All other data page contents, links, archived mail and so on is kept in the database. If you have configured Confluence to use the embedded HSQL database, 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.
Tip All of Confluence's persistent data is stored either in the Confluence Home Directory, or the database. If you have backup copies of both of these, taken at the same time, you will be able to restore Confluence from them (see Restoring Data from other Backups).
RELATED TOPICS
Confluence Home Directory Confluence Installation Directory The Embedded HSQLDB Database Database Configuration
confluence.cfg.xml
This file contains all of the information necessary for Confluence to start up, such as: Product license Context path Database details, such as location and connection pool settings Paths to important directories
attachments
This directory contains every version of each attachment stored in Confluence. This directory is not used when Confluence is configured to store attachments in the database. Attachments are always stored in the database in clustered instances of Confluence. Paths within this directory have the following structure:
16
/attachments/PAGE_ID/ATTACHMENT_ID/VERSION
You can specify an alternative directory for attachment storage by setting the attachments.dir property in confluence.cfg.xml.
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 property in confluence.cfg.xml.
bundled-plugins
Confluence ships with a set of bundled plugins. These are plugins written by the Atlassian and the Confluence community that we think provide useful and broadly applicable functionality in Confluence. The {{bundled-plugins)) directory is where Confluence will unpack its bundled plugins when it starts up. This directory is refreshed on every restart, so removing a plugin from this directory will not uninstall the plugin. It will simply be replaced the next time Confluence starts up.
database
This is where Confluence stores its database when configured to run with the HSQL embedded 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.
index
This is where Confluence stores its indexes for rapid retrieval of often used data. The Confluence index is used heavily by the application for content searching and recently updated lists and as such is critical for a running Confluence instance. It is important to note however that should the data in this directory be lost or corrupted, it can be restored by running a full reindex from within Confluence. This can take a long time depending on how much data is stored Confluence's database. An alternative directory may be specified for the index by setting the lucene.index.dir property in confluence.cfg.xml. As this is the most heavily accessed directory in the Confluence home directory you might want to consider hosting it on the fastest disk available. It would also be useful if the disk holding the Confluence index was not heavily used by any other application to reduce access contention.
plugin-cache
All Confluence plugins are stored in the Confluence database. To allow for quicker access to classes contained within the plugin JARs, Confluence will cache these plugins in the plugin-cache directory. This directory is updated as plugins are installed and uninstalled from the system and is completely repopulated from the database every time Confluence is restarted. Removing plugins from this directory does not uninstall them.
resources
The resources directory stores any space logos used in your Confluence instance. For each space with a space logo, there is a directory within resources named after the space's key. That directory contains the space's logo.
temp
The temp directory is used for various runtime functions such as exporting, importing, file upload and indexing. As the name suggests, and file in this directory is of temporary importance and is only used during runtime. This directory can be safely emptied when Confluence is offline. An alternative directory may be specified for temporary data by setting the webwork.multipart.saveDir property in confluence.cfg.xml.
thumbnails
When Confluence generates a thumbnail of an image (for example when the gallery macro is used), the resulting thumbnail is stored in this directory for quicker retrieval on subsequent accesses. This directory is essentially a thumbnail cache, and deleting files from this directory simply means the thumbnail will have to be regenerated on the next access.
RELATED TOPICS
Confluence Installation Directory Important Directories and Files The Embedded HSQLDB Database
17
RELATED TOPICS
Then press Enter. This will then cause each element of the user interface to display its special key name while Confluence is still in an interactive mode. This makes it easier to find the essential context for each key, which can then be searched on http://translations.atlassian.com where you can enter an appropriate translation for your custom language pack. The key names are displayed with a "lightning bolt" graphic between elements of the names. For example, the buttons will show up with elements shown like so:
18
For example, for the Browse button, the associated key system.space.menu can be found on http://translations.atlassian.com, allowing you to write a better translation for the term Browse, being able to see the full context of where the UI element belongs and what it means to the user. To turn off the translation view, add this code to the end of the Confluence URL:
RELATED TOPICS
By default, Confluence backs up all data and attachments once a day to a backup file. These files are called XML site backups, and are stored in the backups directory of Confluence home. You can also create XML site backups manually. This mechanism is intended for small to medium-sized deployments of Confluence. It is not intended for use with large deployments with lots of pages and attachments (see below). Restore your site from an XML site backup Manually create an XML site backup Configuring Backups User Submitted Backup & Restore Scripts XML site backups are fine for most small to medium-sized instances of Confluence, containing a few thousand pages and attachments. However, large instances of Confluence may find that backups become slow to create and use large amounts of disk space.
Creation Delay is the time it takes to create an XML site backup minus attachments. Disk Usage can be estimated by multiplying the frequency of your XML site backups by their current size.
Manual Backups
Confluence's Attachment Storage Configuration can be set to store attachments in the Confluence home directory, or in the database.
19
Database Backup Use your Database Administration Tool to create a backup of your Confluence database. If your database is storing your attachments, importing this later will restore all content. For instances with big attachments, please note that currently Confluence migrate attachments in a single transaction: CONF-9888. Attachment Backup If stored on the filesystem, attachments are placed under the attachments directory of your Confluence home directory. Copy this directory to create a backup of all attachments. To restore from these backups, please refer to Restoring Data from other Backups.
Related Topics
Other processes
XML backups are described and used for other processes in Confluence, like upgrading and moving servers. Using the backup strategy described here will work for those processes. Our upgrade guide does not require the use of an xml backup (an old upgrade procedure, and the JIRA upgrade guide use XML backups for upgrading), and our migrate server procedure - used to set up a test server - can leverage an sql dump as well. The only process that requires the XML backup is the database migration procedure. Large data sets will require third party database migration tools.
RELATED TOPICS
Configuring Backups
Confluence backs up your data regularly into a zipped XML file. By default, this backup is performed at 2.00 a.m. each day and the backup files are stored in the backups folder under the Confluence Home directory. The default naming convention for the backup files is ' backup-yyyy_MM_dd'. Confluence can write backups to both local and mapped network drives.
20
From the Backup Administration section of Confluence's administration console, you can: Include or exclude attachments in backups. Configure a different path to store backup files. (By default, this option is not available. See below for information about enabling the configuration option.) Change the naming format used for the files. You can also change the schedule of this backup using Confluence's scheduled jobs feature. You need to have System Administrator permissions in order to configure these options. On this page: Configuring Confluence Backups Enabling Backup Path Configuration Notes
21
If the value of the above configuration property is 'true', it will be possible to specify a backup path via the Confluence Administration Console. If the value of this property is 'false' or the property is not present in the configuration file, the backup path is not configurable.
Notes
Time is derived from the Confluence server
The time zone is taken from the server on which Confluence is running. To check the time according to the server, do the following: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'System Information' in the left-hand panel and look at the 'System Time'.
Page: Site Backup and Restore Page: Manually Backing Up The Site Page: Backup FAQ Page: Production Backup Strategy Page: Configuring Backups Page: User Submitted Backup & Restore Scripts
22
'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)
Or, using the older form of the tail command if your system does not support the standard form:
#!/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
23
#!/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
Related Topics
Site Backup and Restore Backup FAQ
Consider an Production backup strategy if your Confluence site is large or you are encountering problems with your automated backup.
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click 'Backup & Restore' in the 'Administration' section of the left-hand panel. Select 'Archive to backups folder' 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). Select 'Backup attachments' to include attachments in your backup. Click 'Backup'. Please note that this process will take a few minutes.
2. 3.
4. 5.
If you are running Confluence behind Apache 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.
24
this file.
Enabling the Download of the Backup File via the Administration Console
By default, it is not possible to retrieve the backup file via the Confluence Administration Console. This feature is disabled for security reasons. Administrators can enable this functionality by updating the relevant configuration property as described below. When enabled, you will be prompted to download the backup file when the backup process finished. However, we recommend that you turn the feature off in production environments. To enable download of the backup file from the Administration Console,
1. Edit the confluence.cfg.xml file found in the Confluence Home Directory. 2. Set the value of property admin.ui.allow.manual.backup.download to 'true' (without the quotation marks). 3. Restart Confluence.
If the value of the above configuration property is 'true', it will be possible to download the backup file after manually backing up the site via the Confluence Administration Console. If the value of this property is 'false' or the property is not present in the configuration file, you will need to retrieve the backup file from the file system on the Confluence server. By default, the value is 'false'.
RELATED TOPICS
Page: Site Backup and Restore Page: Manually Backing Up The Site Page: Backup FAQ Page: Production Backup Strategy Page: Configuring Backups Page: User Submitted Backup & Restore Scripts
25
Avoid upgrades while transferring If you are planning to switch databases, application servers or Confluence versions, firstly perform the application transfer in isolation, and test that it was successful before making other changes.
If you are changing the location of the home directory, open the Confluence install\confluence\WEB-INF\classes directory and edit confluence-init.properties by changing the line starting with 'confluence.home='.
3. Modify the location of your war file if need be. If using Tomcat, this is likely in /Conf/Catalina/localhost. You'll want to make sure the docbase attribute is pointing to the right location. 4. This next step is dependent on your database: a. Database configuration: i. For users of the internal database, the database content is stored inside the home directory. You should switch to an external database after the transfer is successful. ii. For external databases stored on another server: change the user account or datasource permissions so that the new server has the same network access permissions as the original. Then confirm from the new server that the hostname can be resolved and is listening for database connections on the expected port. iii. For external databases hosted locally (ie. localhost): on the original server, create a manual database backup using a native db dump backup tool. Copy the database backup to the new server. b. On the new server, install or upgrade the database version to match the original server. c. Import the database backup. d. Add a database user account with the same username and password as the original. e. Provide the user with the full access to the imported database. f. Use a database administration tool to confirm that the user can login from the localhost. g. To modify any database connection information, go to the Confluence home directory and edit confluence.cfg.xml. The connection URL is set under hibernate.connection.url. Ensure it does not point to your production database server. h. If you are using internal user management, skip this step. For users who have JIRA or LDAP integration, provide the new server with network or local access to the same hosts as the original. If this is a true test instance, set up a test of your JIRA instance or LDAP server so as not to disrupt production systems and change the server.xml or atlassian-user.xml files to point to the appropriate test servers. Note that it might be acceptable to use a production connection here, as users won't be logging on to the test system in high volume. i. If appropriate, make sure no emails are sent out from the test system. j. Start Confluence. k. Go to Administration > License Details and add your development license key. You can generate one at http://my.atlassian.com. There are more details in Getting a License for a Staging Environment. l. If you configured Confluence as a Windows service, repeat those instructions. m. Add your development license key. 5. Some customers have experienced problems with Confluence's search functions after performing a migration, or that the content of their {recently-updated} macro is not being updated correctly. Errors in the atlassian-confluence.log file corroborate such problems. Hence, to avoid these issues, it is strongly recommended that you perform a rebuild of your content indices after performing a migration.
26
1. Download the proper distribution (the same one you have from your original instance) from the Download Archive. 2. Copy your Confluence home (not install) directory from your original server (even if it was a different OS). 3. If you are changing the location of the home directory, open the Confluence install\confluence\WEB-INF\classes directory and edit confluence-init.properties by changing the line starting with 'confluence.home='. 4. For external databases stored locally, on the original server, create a manual database backup using a native db dump backup tool. 5. Copy the database backup to the new server. 6. On the new server, install or upgrade the database version to match the original server. 7. Import the database backup. 8. Add a database user account with the same username and password as the original. 9. Provide the user with the full access to the imported database. 10. Use a database administration tool to confirm that the user can login from the localhost. 11. To modify any database connection information, go to the Confluence home directory and edit confluence.cfg.xml. The connection URL is set under hibernate.connection.url. Ensure it does not point to your production database server. 12. If you are using internal user management, skip this step. For users who have JIRA or LDAP integration, provide the new server with network or local access to the same hosts as the original. 13. Copy server.xml, atlassian-user.xml, osuser.xml, any patches, and any other customized files velocity or properties files. If you are using internal user management, skip this step. For users who have JIRA or LDAP integration, provide the new server with network or local access to the same hosts as the original. If this is a true test instance, set up a test of your JIRA instance or LDAP server so as not to disrupt production systems and change the server.xml or atlassian-user.xml files to point to the appropriate test servers. Note that it might be acceptable to use a production connection here, as users won't be logging on to the test system in high volume. 14. If appropriate, make sure no emails are sent out from the test system. 15. Start Confluence. 16. Go to Administration > License Details and add your development license key. You can generate one at http://my.atlassian.com. There are more details in Getting a License for a Staging Environment. 17. If you configured Confluence as a Windows service, repeat those instructions. 18. Add your development license key. 19. Some customers have experienced problems with Confluence's search functions after performing a migration, or that the content of their {recently-updated} macro is not being updated correctly. Errors in the atlassian-confluence.log file corroborate such problems. Hence, to avoid these issues, it is strongly recommended that you perform a rebuild of your content indices after performing a migration.
Using XML data backups (only for small to medium sized installations)
If you're not yet using the Production backup strategy, you can migrate Confluence to a different server machine by creating an XML data backup as usual, and then importing that to Confluence on the new server. 1. Create an XML data backup from Confluence as follows: a. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. b. Select Backup & Restore. c. Check the Backup Attachments option and click Backup. Identify the version of Confluence that you are currently using. This is displayed at the bottom of each Confluence page. Download Confluence to the new server. Get the version of Confluence that you identified above, but for the operating system of the new server. You may be using either the latest Confluence version, or an older version. Install Confluence on the new server. Go to Administration > License Details and add your development license key. You can generate a license at http://my.atlassian.com. You can find more details in Getting a License for a Staging Environment. Restore your XML data backup from Administration > Backup and Restore. If appropriate, make sure that no email contact can be made with the test system. Some customers have experienced problems with Confluence's search functions after performing a migration, or that the content of their {recently-updated} macro is not being updated correctly. Errors in the atlassian-confluence.log file corroborate such problems. Hence, to avoid these issues, it is strongly recommended that you rebuild your content indices after performing a migration.
2. 3. 4. 5. 6. 7. 8.
Change 'SELECT' to '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, JIRA macro, etc.). If these write content, or create unwanted load on external systems, they should
27
Blog post on Moving Confluence from Windows to Linux Ricky Sheaves (calebscreek) has written an interesting blog post on Moving Confluence from Windows to (Ubuntu) Linux.
Merging instances
If you wish to merge two instances, you can consider using the remote import plugin. This plugin is currently unsupported. The supported method would be to export a space and then import each space one by one. The two instances of Confluence must be the same version.
Restoring a Site
CAUTION: Restoring a backup of an entire confluence site (consisting of multiple spaces) will: Wipe out all Confluence content in the database. Ensure that your database is backed up. Log you out after the restore process. Make sure you know your login details contained in the data being restored.
Atlassian suggests establishing the Production Backup Strategy for a production instance of Confluence as confluence xml backups are not recommended for non-evaluation instances.
Confluence supports backward compatibility for site backups. (But not for space backups). You can only successfully restore backups of a site from an older version of Confluence to a newer version of Confluence. For example, if you create a site backup in Confluence 2.4.3, it cannot be restored into a Confluence 2.2.2 instance. It can however, be restored into 2.4.5 or 2.5.x, because 2.4.5 and 2.5.x are newer versions of Confluence. There are two ways to restore a site from a backup file: 1. Restore a site from the Confluence Setup Wizard: This restores the data into a new instance of Confluence. 2. Restore a site from the Administration Console: This restores data into the current instance of Confluence. If your daily backup zips cannot be restored for whatever reason, but you have backups of both your database and your Confluence home directory, then it is still possible to restore from these backups.
Selective space restore not possible You cannot select a single space to restore from the entire site backup when the backup contains more than one space.
RELATED TOPICS
Page: Restoring Data from the Administration Console Page: Restoring a Space Page: Restoring a Site Page: Manually Backing Up The Site Page: Restoring from Backup During Setup
28
Restoring a Space
This page tells you how to import the contents of a Confluence space into another Confluence site, via an XML backup file. You can export the content of a space, including pages, comments and attachments. The process involves converting the data in the space into XML format. The end product is a zip file that contains XML file(s) and optionally, all the attachments in the space. To transfer this data to another Confluence site, you simply restore this zip file as described below. Confluence will only allow you to restore a space if there is not already a space by that name on the site. If you already have a space with the identical name, you will need to delete or rename the existing space before restoring the new one.
Cannot restore to a different major Confluence release Confluence only supports forward compatibility and backward compatibility for individual space import and export when executed within the same major version of Confluence instances. Restoration Data Must Share the Same Major Version Number This means that a space export created in a newer major version of Confluence cannot be imported into an older major version of Confluence. For example, if you create a space export in Confluence 2.4.5, it cannot be imported into a Confluence 2.2.2 instance. It can be however imported into 2.4.6. (because 2.2.2 and 2.4.5 are two different 'major' versions). Similarly, a space export created in 2.2.2 can not be imported into 2.4.5. However, it can be restored in 2.2.10 (since 2.2.2 and 2.2.10 belong to the same major version release). If such an operation is carried out, an error message similar to the one below will be displayed and the import action will be stopped. Screenshot: Major Version Clash on Space Restore
You need to have System Administrator permissions in order to perform this function. To restore a space,
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Backup and Restore' in the 'Administration' section of the left-hand panel. You can restore data in one of two ways: 1. Upload a zipped backup to Confluence: Browse for the backup file. Uncheck 'Build Index' if you want to create the index at a later stage. Click 'Upload and Restore'. 2. Restore a backup from the file system: Select the backup file from the form field displayed. If you do not see your backup file, make you sure that it has been copied into the /opt/java/src/confluence/deployments/conf.atlassian.com/home/restore directory. Uncheck 'Build Index' if you want to create the index at a later stage. Click 'Restore'.
RELATED TOPICS
29
Page: Restoring Data from the Administration Console Page: Restoring a Space Page: Restoring a Site Page: Manually Backing Up The Site Page: Restoring from Backup During Setup
Do not import a modified space backup on a production server. Import the modified space backup on a test server, then export from the test server to create a pristine space backup for the new version.
To change the version of a space backup, do the following: extract the space backup ZIP file edit exportDescriptor.properties in a text editor change the buildNumber to the buildNumber of the Confluence version you wish to import into zip up the modified contents of the backup into a ZIP file again. This will allow you to import a backup into a test instance of Confluence. After checking the imported space for errors, export it cleanly from the test server and import the fresh backup into your production server. If your import fails on the test server due to Hibernate errors, this indicates a schema incompatibility and cannot be worked around. You will need to restore your entire site on an old version of Confluence, and export the space from there. See the last section of Restoring a Space for details.
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.
30
Confluence 4.0 Documentation 5. 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.
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.
See also
Upgrading Confluence Migrating Confluence Between Servers Restoring to a Test Instance of Confluence from Production
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.
RELATED TOPICS
31
CAUTION: Restoring a backup of an entire Confluence site (consisting of multiple spaces) will do the following: Wipe out all Confluence content in the database. Ensure that your database is backed up. Log you out after the restore process. Make sure you know your login details contained in the data being restored.
Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'Backup and Restore' in the 'Administration' section of the left-hand panel. You can restore data in one of two ways: 1. Upload a zipped backup to Confluence: Browse for the backup file. Uncheck 'Build Index' if you want to create the index at a later stage. Click 'Upload and Restore'. 2. Restore a backup from the file system: Select the backup file from the form field displayed. If you do not see your backup file, make sure that it has been copied into the /opt/java/src/confluence/deployments/conf.atlassian.com/home/restore directory. Uncheck 'Build Index' if you want to create the index at a later stage. Click 'Restore'.
RELATED TOPICS
Page: Restoring Data from the Administration Console Page: Restoring a Space Page: Restoring a Site Page: Manually Backing Up The Site Page: Restoring from Backup During Setup
32
Before following the instructions for recovering attachments, please review how backups store file and page information.
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.
<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>
<object class="Page" package="com.atlassian.confluence.pages"> <id name="id">98</id> <property name="title"><![CDATA[Editing Your Files]]></property> ... </object>
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.
Following process is applicable to space export only. Site xml backups do not require page id to be updated manually due to the nature of persistent page_id's.
1. Unzip the backup directory and open entities.xml. 2. Go to the attachments directory and open any directory. The directory name is a page id. Each of the files in the directory is an attachment that must be renamed. 3. Search entities.xml for attachment objects with that page id. When one is found, locate the attachment id and filename. 4. Rename the file with that attachment id to the original filename and test it. 5. Find the next attachment id and rename it. Repeat for each file in the directory. 6. Once all files in the current directory are renamed to their original filenames, search entities.xml for the page id, eg directory name. Find the page object with that page id and locate its page title. 7. Rename the directory to the page title and move on to the next directory. Repeat for each un-renamed directory in the attachments directory. 8. To import each file back into Confluence, upload to the original page by attaching the file from within Confluence.
To obtain detailed information about lost attachments, location, name and type of the attachments, you may use the findattachments script
Seeing an error when creating or importing a backup? Problem Exception while creating backup Exception while importing backup Solution Follow instructions below Follow Troubleshooting XML backups that fail on restore instead
34
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.
5. 6. 7. 8.
Find your atlassian-confluence.log. Move or delete all existing Confluence logs to make it easier to find the relevant logging output. Restart Confluence and login. Begin a backup so that the error reoccurs. You must now check your log files to find out what object could not be converted into XML format. Open confluence-home/logs/atlassian-confluence.log. Scroll to the bottom of the file. 9. Do a search for 'ObjectNotFoundException'. You should see an error similar to this:
01 2005-08-24 00:00:33,743 DEBUG [DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing object: com.atlassian.confluence.core.ContentPermission with ID: 5 to XML. 02 2005-08-24 00:00:33,743 DEBUG [DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing property: type 03 2005-08-24 00:00:33,743 DEBUG [DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing property: group 04 2005-08-24 00:00:33,743 DEBUG [DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing property: expiry 05 2005-08-24 00:00:33,743 DEBUG [DOCPRIV2:confluence.importexport.impl.XMLDatabinder] Writing property: content 06 [DOCPRIV2:ERROR] LazyInitializer - Exception initializing proxy <net.sf.hibernate.ObjectNotFoundException: No row with the given identifier exists: 2535, 07 of class: com.atlassian.confluence.core.ContentEntityObject>net.sf.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 catalina.out, 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 tableneeds fixing. To work out what table an object maps to in the database, here's a rough guide: Pages, blogposts, comments --> CONTENT table attachments --> ATTACHMENTS table More information can be found in the schema documentation 12. Now you must find the primary key of the incorrect row in this table. In this case, you can check the first line and see that the row has a primary key of 5. 13. Each property is written to a column, so the last property that was being written has the incorrect value. The row being written to when the exception was thrown was CONTENT (line 5) with a value of 2535 (line 6). Now you know the column and value. This value
35
Confluence 4.0 Documentation 13. 2535 is the id of an entry that no longer exists. 14. Using a database administrative tool, login ot the Confluence database. Locate the row in the relevant table and correct the entry. Check other rows in the table for the default column value, which may be null, 0 or blank. Overwrite the invalid row value with the default. 15. Restart Confluence. 16. Attempt the backup again. If the backup fails and you are stuck, please lodge a support request with your latest logs.
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:
If migrating from HSQLDB to MySQL, you might have a better experience using the MySQL Migration Toolkit.
Seeing an error when creating or importing a site or space backup? Problem Exception while creating backup Exception while importing backup Solution Follow Troubleshooting failed XML site backups instead Follow instructions below
36
2006-07-13 09:32:33,372 ERROR [confluence.importexport.impl.ReverseDatabinder] endElement net.sf.hibernate.exception.ConstraintViolationException: could not insert: [com.atlassian.confluence.pages.Attachment#38] net.sf.hibernate.exception.ConstraintViolationException: could not insert: [com.atlassian.confluence.pages.Attachment#38] ... Caused by: java.sql.SQLException: ORA-01400: cannot insert NULL into ("CONFUSER"."ATTACHMENTS"."TITLE") at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.java:112) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:288)
This example indicates a row in your attachment table with ID = 38 that has a null title. 6. Go to the server that the backup was created on. You must have a copy of the database from which the backup was created. If you do not have this, use a DBA tool to restore a manual backup of the database. 7. Open a DBA tool and connect to the original database instance and scan the table names in the schema. You will have to modify a row in one of these tables. 8. To work out which table, open catalina.out, check the first line of the exception. To work out what table an object maps to in the database, here's a rough guide: Pages, blogposts, comments --> CONTENT table. attachments --> ATTACHMENTS table. 9. To correct the example error, go to the attachment table and find that attachment object with id 38. This will have a a null title. Give a title using the other attachments titles as a guide. You may have a different error and should modify the database accordingly. 10. Once the entry has been corrected, create the XML backup again. 11. Import the backup into the new version. 12. If the import succeeds, revert the changes made in your SQL logging to re-enable disable batched updates and turn off log SQL queries and log SQL queries with parameters. 13. Restart Confluence.
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:
37
SELECT * FROM CONTENT_PERM WHERE USERNAME IS NULL AND GROUPNAME IS NULL; SELECT cp.ID, cp.CP_TYPE, cp.USERNAME, cp.GROUPNAME, cp.CPS_ID, cp.CREATOR, cp.CREATIONDATE, cp.LASTMODIFIER, cp.LASTMODDATE FROM CONTENT_PERM cp WHERE cp.USERNAME IS NOT NULL AND cp.GROUPNAME IS NOT NULL; SELECT cps1.ID, cps1.CONTENT_ID, cps1.CONT_PERM_TYPE FROM CONTENT_PERM_SET cps1, CONTENT_PERM_SET cps2 WHERE cps1.ID <> cps2.ID AND cps1.CONTENT_ID = cps2.CONTENT_ID AND cps1.CONT_PERM_TYPE = cps2.CONT_PERM_TYPE ORDER BY cps1.CONTENT_ID, cps1.CONT_PERM_TYPE, cps1.CREATIONDATE ASC; SELECT cp.ID, cp.CP_TYPE, cps.CONTENT_ID, (SELECT scps.ID FROM CONTENT_PERM_SET scps WHERE scps.CONTENT_ID = cps.CONTENT_ID AND scps.CONT_PERM_TYPE = cp.CP_TYPE) AS suggested_cps_id FROM CONTENT_PERM cp, CONTENT_PERM_SET cps WHERE cp.CPS_ID = cps.ID AND cp.CP_TYPE <> cps.CONT_PERM_TYPE; SELECT DISTINCT cp1.ID, cp1.CP_TYPE, cp1.USERNAME, cp1.GROUPNAME, cp1.CPS_ID, cp1.CREATOR, cp1.CREATIONDATE, cp1.LASTMODIFIER, cp1.LASTMODDATE FROM CONTENT_PERM cp1, CONTENT_PERM_SET cps1, CONTENT_PERM cp2, CONTENT_PERM_SET cps2 WHERE cp1.CPS_ID = cps1.ID AND cp2.CPS_ID = cps2.ID AND cp1.ID <> cp2.ID AND cps1.CONTENT_ID = cps2.CONTENT_ID AND cp1.CP_TYPE = cp2.CP_TYPE AND cp1.USERNAME = cp2.USERNAME ORDER BY cp1.CPS_ID, cp1.CP_TYPE, cp1.USERNAME, cp1.CREATIONDATE; SELECT DISTINCT cp1.ID, cp1.CP_TYPE, cp1.USERNAME, cp1.GROUPNAME, cp1.CPS_ID, cp1.CREATOR, cp1.CREATIONDATE, cp1.LASTMODIFIER, cp1.LASTMODDATE FROM CONTENT_PERM cp1, CONTENT_PERM_SET cps1, CONTENT_PERM cp2, CONTENT_PERM_SET cps2 WHERE cp1.CPS_ID = cps1.ID AND cp2.CPS_ID = cps2.ID AND cp1.ID <> cp2.ID AND cps1.CONTENT_ID = cps2.CONTENT_ID AND cp1.CP_TYPE = cp2.CP_TYPE AND cp1.GROUPNAME = cp2.GROUPNAME ORDER BY cp1.CPS_ID, cp1.CP_TYPE, cp1.GROUPNAME, cp1.CREATIONDATE; SELECT * FROM CONTENT_PERM_SET WHERE ID NOT IN (SELECT DISTINCT CPS_ID FROM CONTENT_PERM);
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:
38
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.
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
RELATED TOPICS
Disclaimer
MySQL Migration Toolkit is released by the makers of MySQL and as such, problems with the software should be directed to them. Atlassian Support does not offer support for the Migration Toolkit, nor do we provide support for this migration path. These instructions are offered for strictly informational purposes, and your mileage may vary.
Backup Reminder Please backup your database and your home folder before attempting this.
Resources needed
Empty MySQL DB with appropriate credentials to allow creation, deletion, and insertion of tables and rows. A Windows machine that can both communicate to the Confluence server and the destination DB. MySQL Migration Toolkit HSQL Database Engine
39
1. 2. 3. 4. 5. 6.
Shutdown Confluence Make a copy of the confluence home folder for backup purposes Install the Migration Toolkit Unzip the hsqldb package. Copy the hsqldb.jar from hsqldb/lib into C:\Program Files\MySQL\MySQL Tools for 5.0\java\lib Start the MySQL Migration Toolkit
Source Database
40
Username: Password:
Destination Database
Please make sure that the computer that is running MySQL Toolkit is able to access the MySQL server and that the user listed has the ability to create, drop, insert, and update tables.
If your MySQL user has a $ character in the password (such as 'pa$sword'), please change the password or create a temporary account with full permissions. If you do not, the toolkit will throw an "Illegal group reference" error and you will not be able to proceed with the migration.
41
Connecting to Servers
You should see the toolkit trying to connect. If you have problems, please click on the advanced options and sql will show you debugging information. Click Advanced to see the log. If you see "Java Heap Space: Out of Memory", you can start the MySQL Migration Toolkit with a -Xmx flag to allocate more memory to the JVM. After this screen you should come to reverse engineering. Click next.
42
Click Next.
43
Click Show Details on both sections. For Migration Method for Type Schema, choose Multilanguage. For Migration Method for Type Table, choose Data Consistancy/Multilanguage Click Advanced. Check Enabled Detailed Mappings in Next Step
http://yoursite/admin/permissions/pagepermsadmin.action
RELATED TOPICS
44
On this page: Updating your License Details Viewing your License Details Downgrading your Confluence License
1. Log into Confluence as a user with Confluence Administrator or System Administrator permissions. 2. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 3. Click 'License Details' under the heading 'Administration in the left-hand panel. 4. Enter your new license details into the 'License' field and click the 'Save' button.
If you are running a Confluence cluster, you will need to: Update each server's Confluence license separately. Ensure that the new license has enough nodes to cover all servers that are currently running in your cluster. (To check the number of active servers in your cluster, see the Cluster Administration page.)
45
Click the 'Refresh' button to make sure you see the latest count. What type of license you have (e.g. Commercial, Academic, Community). How much time remains in your one-year support and upgrades period (for full licenses) or 30-day trial (for trial licenses). Your server ID, which: is generated when you install Confluence for the first time exists for the life of the Confluence instance survives an upgrade is held in the database is not bound to a specific license is the same for all servers in a cluster. To view the details of your Confluence license,
1. Log into Confluence as a user with Confluence Administrator or System Administrator permissions. 2. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 3. Click 'License Details' under the heading 'Administration in the left-hand panel.
Page: Viewing and Editing License Details Page: How Do I Find My License from the File System? Page: Getting a License for a Staging Environment Page: Cache Performance Tuning Page: Cache Statistics Page: Viewing System Information Page: Cache Performance Tuning for Specific Problems Page: Confluence Cache Schemes
The handy Memory Graph helps you keep track of Confluence's memory usage.
46
RELATED TOPICS
Cache Statistics Viewing Site Statistics Viewing and Editing License Details Viewing and Managing Installed Plugins Live Monitoring Using the JMX Interface Tracking Customisations Made to your Confluence Installation
Disable JMX
If you experience any problems during Confluence startup that are related to JMX, it is possible to disable the JMX registration process. Please place jmxContext.xml in your <confluence-install>/confluence/WEB-INF/classes folder to do so.
What is JMX?
JMX (Java Management eXtensions) is a technology for monitoring and managing Java applications. JMX uses objects called MBeans (Managed Beans) to expose data and resources from your application.
JDK_HOME/bin/
In this example, replace 'JDK_HOME' with the full system path to your Java directory.
4. Configuring JConsole
To configure JConsole: 1. Run the JConsole application. 2. You will be prompted to create a new connection. Choose remote process and enter the hostname of your Confluence instance and a port of your choosing.
47
To connect easily, add the startup parameters to setenv.bat or setenv.sh: -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=8086 -Dcom.sun.management.jmxremote.authenticate=false Port 8086 is unlikely to be used. Then, connect remotely using port 8086.
JConsole, or any JMX client, will not see applications which are not owned by the same user. For example under Windows, if an application is started as a service, it is the System User which owns the process, and not the Current User.
3. Click Connect. Note: Other JMX clients besides JConsole can read JMX information from Confluence.
This MBean shows information related to search indexing. Property name Flushing LastElapsedMilliseconds LastElapsedReindexing TaskQueueLength Function Shows state of cache (i.e. flushing, or not). Time taken during last indexing. Time taken during last re-indexing. Shows number of tasks in the queue. Values True/False Milliseconds Milliseconds Integer
SystemInformation
This MBean shows information related to database latency. It also contains most of the information presented on the System Information page. Property name DatabaseExampleLatency Function Shows the latency of an example query performed against the database. Values Milliseconds
RequestMetrics
This MBean shows information related to system load and error pages served. Property name AverageExecutionTimeForLastTenRequests CurrentNumberOfRequestsBeingServed ErrorCount NumberOfRequestsInLastTenSeconds Function Average execution time for the last ten requests. Number of requests being served at this instant. Number of times the Confluence error page was served. Obviously, the Number Of Requests In the Last Ten Seconds. Values Milliseconds Integer Integer 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.
48
Function The number of email messages Confluence has tried to send. The number of email messages sent successfully.
MailTaskQueue
This MBean shows information related to the email workload. Property name ErrorQueueSize Flushing FlushStarted RetryCount TaskSize Function Number of errors in the queue. Shows state (i.e. flushing, or not) Time that operation began. The number of retries that were performed. Number of email messages queued for dispatch. Values Integer True/False Time Integer Integer
SchedulingStatistics
This MBean shows information related to current jobs, scheduled tasks and the time that they were last run.
High CPU consuming threads
For Java 1.6, add the Top Threads Plugin to monitor whether CPU is spiking. Download it to a directory and run JConsole like this: JConsole -pluginpath /pathto/topthreads.jar This works only with JDK 1.6, but that can be on the remote machine if the server is running a lower version.
Please note, adding live monitoring to a production instance may itself have an impact on performance.
Related Topics
Viewing System Information Cache Statistics Viewing and Editing License Details Viewing and Managing Installed Plugins
49
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'System Information' in the 'Administration' section of the left-hand panel. 3. Scroll down to the section titled 'Modification'.
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. See issue CONF-20993.
RELATED TOPICS
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'Global Activity' in the 'Administration' section of the left-hand panel.
50
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. 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.
RELATED TOPICS
How Do I Get More Statistics From Confluence? Cache Statistics Viewing Space Activity Live Monitoring Using the JMX Interface Installing and Configuring Plugins
51
To see the system properties recognised by your Confluence installation: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select System Information in the 'Administration' section of the left-hand panel. 3. Scroll down to the section titled 'System Properties'.
http://<yourbaseurl>/admin/systemproperties.jsp
Editing Files within JAR Archives Where are the files that used to be in my Confluence installation directory?
52
Method 3: Atlassian Invoice Your Support Entitlement Number (SEN) appears on the third page of your Atlassian Invoice. See Finding Your Support Entitlement Number in the support space for more general information about how Atlassian Support uses this number.
Configuring Confluence
The pages listed below contain instructions on configuring Confluence. If you cannot find what you are looking for, try the search box in the left-hand navigation panel. Site Configuration Configuring the Site Home Page Configuring the Administrator Contact Page Editing the Site Title Editing the Global Logo Configuring the Server Base URL Customising Default Space Content Configuring the Destination of View Space Links Editing the Site Welcome Message Configuring the What's New Dialog Configuring Encoding Character encodings in Confluence Troubleshooting Character Encodings "" Euro character not displaying properly MySQL 3.x Character Encoding Problems Configuring Mail Configuring a Server for Outgoing Mail The Mail Queue Optional Settings Attachment Storage Configuration Hierarchical File System Attachment Storage
53
Configuring a WebDAV client for Confluence Configuring Quick Navigation Enabling OpenSearch Enabling the Did You Mean Feature Enabling the Remote API Enabling Threaded Comments Enabling Trackback Other Settings Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats Configuring Shortcut Links Configuring Time and Date Formats Configuring System Properties Recognised System Properties Configuring a Large Confluence Installation Configuring Logging External Gadgets
RELATED TOPICS
Tracking Customisations Made to your Confluence Installation Confluence Configuration Guide
Site Configuration
Configuring the Site Home Page Configuring the Administrator Contact Page Editing the Site Title Editing the Global Logo Configuring the Server Base URL Customising Default Space Content Configuring the Destination of View Space Links Editing the Site Welcome Message Configuring the What's New Dialog
Notes
The user's personal settings will override the global setting.
Related Topics
Page: Customising Default Space Content Page: Editing the Site Welcome Message Page: Editing the Global Logo
54
Page: Editing the Site Title Page: Configuring the Destination of View Space Links Page: Configuring the Site Home Page Page: Configuring the Server Base URL
To edit the administrator contact message: 1. 2. 3. 4. Go to the 'Administration Console' and click General Configuration in the left-hand panel. Click Edit at the top of the 'Site Configuration' section. Enter your text in the Custom Contact Administrators Message box. You can enter any text or Confluence wiki markup. Click Save.
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.
Customisation Examples
55
When entering the 'Custom Contact Administrators Message', you can use text and Confluence wiki markup. This is similar to entering your own text and markup for the 'Site Welcome Message'. For examples of the kind of customisations possible, take a look at the guide to editing the site welcome message.
Related Topics
Contacting Confluence Administrators Configuring Captcha for Spam Prevention
Related Topics
Page: Customising Default Space Content Page: Editing the Site Welcome Message Page: Editing the Global Logo Page: Editing the Site Title Page: Configuring the Destination of View Space Links Page: Configuring the Site Home Page Page: Configuring the Server Base URL
Related Topics
Page: Customising Default Space Content Page: Editing the Site Welcome Message
56
Page: Editing the Global Logo Page: Editing the Site Title Page: Configuring the Destination of View Space Links Page: Configuring the Site Home Page Page: Configuring the Server Base URL
To configure the Server Base URL: 1. 2. 3. 4. 5. In Confluence, open the 'Browse' menu and select 'Confluence Admin'. The 'Administration Console' will open. Click 'General Configuration' in the left-hand panel. Click the 'Edit' button next to 'Site Configuration'. Enter the new URL in the 'Server Base URL' text box. 'Save' your changes.
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
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 may also need to edit the web server's server.xml to reflect the new path.
RELATED TOPICS
Page: Customising Default Space Content Page: Editing the Site Welcome Message Page: Editing the Global Logo Page: Editing the Site Title Page: Configuring the Destination of View Space Links Page: Configuring the Site Home Page Page: Configuring the Server Base URL
57
To define default content for home pages in personal spaces: 1. Go to the 'Administration Console' and click 'Default Space Content' under 'Configuration' in the left panel. 2. The 'Space Home Pages' tab will open on the 'Default Space Content' page. Click the 'Personal Space Home Pages' tab. 3. Enter the content which you want to appear on the home page for new personal spaces. You can use special characters within the content as variables (place holders). Confluence will replace the curly brackets and digits with the corresponding information as shown below: {0} The space owner's full name. {1} The space owner's e-mail address. {2} Any personal information the space owner has entered on their user profile in the 'Information about me' section. 4. Click the 'Save' button. You can also undo all customisations of the default home page content, and go back to the default content as originally supplied with Confluence. To restore the original default content: 1. Go to the 'Administration Console' and click 'Default Space Content' under 'Configuration' in the left panel. 2. Select either the 'Space Home Pages' tab or the 'Personal Space Home Pages' tab, as required. 3. Click the 'Revert' button.
58
Related Topics
Page: Customising Default Space Content Page: Editing the Site Welcome Message Page: Editing the Global Logo Page: Editing the Site Title Page: Configuring the Destination of View Space Links Page: Configuring the Site Home Page Page: Configuring the Server Base URL
Related Topics
Page: Customising Default Space Content Page: Editing the Site Welcome Message Page: Editing the Global Logo Page: Editing the Site Title Page: Configuring the Destination of View Space Links Page: Configuring the Site Home Page Page: Configuring the Server Base URL
To edit the site welcome message: 1. 2. 3. 4. Go to the Administration Console and click General Configuration in the left-hand panel. Click Edit at the top of the Site Configuration section. Type into the Site Welcome Message box. You can enter text or Confluence wiki markup. Click Save.
On this page: The Default Site Welcome Message Example 1. Adding a Simple Welcome Message Example 2. Formatting your Welcome Message Example 3: Including Content from Another Page Example 4. Adding Blog Posts Filtered by Labels to your Welcome Message How We Use the Site Welcome Message at Atlassian Related Topics
59
By default, the site welcome message looks more or less like the screenshot below, starting with the words Welcome to Confluence and ending above the list of spaces. To restore the default site welcome message and remove your customised message, just delete the text in the Site Welcome Message text box. Provided that you have not customised Confluence, your Confluence users will see the default message if there is no text in the Site Welcome Message text box in your Administration Console. Screenshot: Site welcome message at top left of the dashboard
To produce the above welcome message, follow the step-by-step instructions above and add the following wiki markup into the Site Welcome Message text box:
h2. Welcome to the MyCompany Wiki New to MyCompany? [Find out about your induction|DS:Company Induction]. Otherwise, [have fun|DS:Have Fun], because you can't always work!
In our example, the links point to two pages in the Confluence Demonstration Space, 'DS'. If your Confluence site does not have a 'DS' space, the links will be broken. That's OK, because you will want to replace them with links to your own pages anyway. This is just an example.
60
To produce the above welcome message, follow the step-by-step instructions above and add the following wiki markup into the Site Welcome Message text box:
{panel} h2. Welcome to the MyCompany Wiki New to MyCompany? [Find out about your induction|DS:Company Induction]. Otherwise, [have fun|DS:Have Fun], because you can't always work! \\ \\ {panel} \\
In the above example we use the {include} macro to display the content from the given page. See the guide to the include macro. In our example, the space key 'DS' and the page name 'Dashboard Welcome Message' are variables. You can use any space and page you like. 4. Save the site welcome message. The dashboard will display the content of the page immediately. Similarly, if you or anyone else edits the page, the welcome message on the dashboard will change as soon as you save the page.
61
Summary of the procedure shown in the video: 1. Create a page containing the {blog-posts} macro. Choose to display only the blog posts that are labelled with 'dashboard-blog'. (This is just an example of a label. You can choose any label text you like.) See the guide to the Blog Posts macro. 2. Add the label to a blog post. (In the video, we just add the label to one blog post. You will probably want to add it to a number of posts.) 3. Edit your site welcome message to include the above page, using the include macro.
{include:STAFF:Extranet Homepage}
The include macro allows you to include the content an entire page onto another page. This particular page lives in the STAFF space, where anyone can edit it. It usually shows some amusing picture or company-wide notice. The featured photo generally changes once a week or so whenever someone feels like changing it. The page itself has over 600 edits by many different people. The page also includes an edit link, for quick access to change the welcome message. We have the Composition plugin installed which allows you to use the {float} macro.
62
Our wiki markup in the 'Extranet Homepage' page looks something like this:
!Clover Dukey.jpg|width=200! {nodisplay} This is the content that goes on the Extranet homepage, above the spaces list. NOTE: KEEP YOUR PICTURES SMALL (<80KB) -- USE JPG FOR PICTURES, WIDTH 400 {nodisplay} h4. Experimental blogroll: All posts labelled "extranet-dashboard" {blog-posts:content=titles|labels=extranet-dashboard|spaces=@all|max=10} If you want to promote a good post to stand out from the eac white noise, just add the label *extranet-dashboard*. To avoid inflation please use the label carefully. {float-right} ([edit me|http://extranet.atlassian.com/pages/editpage.action?pageId=603422736]) {float-right}
Related Topics
Page: Customising Default Space Content Page: Editing the Site Welcome Message Page: Editing the Global Logo Page: Editing the Site Title Page: Configuring the Destination of View Space Links Page: Configuring the Site Home Page Page: Configuring the Server Base URL
63
Notes
Related Topics
Configuring Encoding
Confluence allows the configuration of which character encoding is used to deliver pages.
64
While different character encodings are supported, we strongly recommend that UTF-8 is used. Confluence is heavily tested on UTF-8, and users are likely to have less problems with this encoding than others.
Mac Users Mac Users please note that MacRoman encoding is compatible with UTF-8. You do not need to change your encoding settings if you are already using MacRoman.
To avoid problems with character encoding, make sure the encoding used across the different components of your system are the same: Configuring Database Character Encoding Application Server URL encoding Confluence Character Encoding
If you are having problems with the character encoding in Confluence, please see the Troubleshooting Character Encodings page.
2. Incorrect/non-Unicode filesystem encoding - international filenames break attachment download/upload/removal (pre-2.2); exports break with international content or attachments. 3. Incorrect HTTP encoding - incorrect encoding selected by browser, resulting in incorrect rendering of characters. Changing browser encoding causes page to render properly. Broken URLs when linking to pages or attachments with non-ASCII characters.
66
Confluence instance. You will be required to copy and paste a line of text and submit a form. The test will take the text and pass it through Confluence, the application server and the database, and return the results. You should also test pasting some sample text (Japanese for example) if you are experiencing problems with a specific language. Example:
http://confluence.atlassian.com/admin/encodingtest.action
or
http://<host address>:<port>/admin/encodingtest.action
If the text displayed in the encoding test is different to what was entered, then there are problems with your character encoding settings.
67
MySQL 3.x MySQL 3.x is known to have some problems with the upper- and lower-casing of some characters, and may fail the last two tests. For more information, see MySQL 3.x Character Encoding Problems.
3. Requesting support
If there are still problems with character encoding after following the above steps, create a support request, and our support staff will aid in solving your problem. Entering in the following details will help us to identify your problem: Attach screenshots of the problem Attach the results of the encoding test (above) Select which application server (and version) you are using Select which database (and version) you are using Copy the contents of the System Information page into the 'Description' field
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.
68
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:
Solution
Configuring Mail
Configuring a Server for Outgoing Mail The Mail Queue Customising the eMail Templates
69
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 a subject prefix, if required. 5. Configuring the Host Address, User Name and Password: Manually enter your 'Host Address', 'User Name' and 'Password' details in the form fields displayed (recommended). OR Specify the 'JNDI location' of a mail session configured in your application server in the form field displayed.
Troubleshooting
70
If you experience problems with these configurations, please check that your <Confluence-Install>/confluence/WEB-INF/lib contains only one copy of the following JAR files: 1. activation-x.x.x.jar 2. mail-x.x.x.jar Ideally, these should be: activation-1.0.2.jar mail-1.3.2.jar (or later) You will then need to move these into the proper directory: Confluence distribution: Please move (not copy) the two jar files from the <Confluence-Install>/confluence/WEB-INF/lib directory to <confluence-install>/lib (for Confluence version 2.10 onwards) or <Confluence-Install>/common/lib (for earlier product versions) and restart Confluence.
Related Topics
Page: The Mail Queue Page: How do I configure Confluence to use GMail as the mail server Page: Configuring a Confluence Email Server for Email Notifications Page: Setting Up a Mail Session for the Confluence Distribution Page: Configuring a Server for Outgoing Mail
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Mail Queue' in the left-hand panel. This will display the emails currently in the queue. 3. Click 'Flush Mail Queue' to send all emails immediately. 4. Click '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 'Delete' them from here.
RELATED TOPICS
Page: The Mail Queue Page: How do I configure Confluence to use GMail as the mail server Page: Configuring a Confluence Email Server for Email Notifications Page: Setting Up a Mail Session for the Confluence Distribution Page: Configuring a Server for Outgoing Mail
Optional Settings
71
Attachment Storage Configuration Configuring a WebDAV client for Confluence Configuring Quick Navigation Enabling OpenSearch Enabling the Did You Mean Feature Enabling the Remote API Enabling Threaded Comments Enabling Trackback
By default, Confluence stores attachments in the attachments directory within the configured Confluence home folder. If you are looking to run Confluence Clustered, attachments must be stored in the database.
Database
Confluence gives administrators the option to store attachments in the database that Confluence is configured to use. Here are some reasons why, as an administrator, you may want to choose this storage system: Ease of backup. Avoiding issues with certain characters in attachment file names.
While storing attachments in the database can offer some advantages, please be aware that the amount of space used by the database will increase because of the greater storage requirements.
WebDAV
Confluence also allows administrators to set an external WebDAV repository as the location for attachment storage.
WebDAV attachment manager deprecated The option to store Confluence attachments on a WebDAV server has never worked in a useful fashion, and has not been maintained for many versions. The WebDAV attachment manager will be deprecated from Confluence 2.7, and will be removed from a later version of Confluence. If you store attachments on external WebDAV servers, we recommend that you migrate to file-system or database-backed attachment storage as soon as possible. Refer to CONF-9313 and CONF-2887. This DOES NOT affect the operation of the WebDAV plugin.
72
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.
When migrating attachments from your database to a filesystem, the attachments are removed from the database after migration. However, when migrating attachments from a filesystem to your database, the attachments remain on the filesystem after migration. If you wish to change this function's behaviour from 'copy' to 'move', please see CONF-14802 and cast your vote.
To perform a migration, follow the steps below: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'Attachment Storage' in the left-hand panel. The current configuration will be displayed.
Attachment storage configuration 3. Click the 'Edit' button to modify the configuration. 4. Select the storage system you desire.
Edit attachment storage 5. Click the 'Save' button to save the changes. 6. 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.
Migration warning
Troubleshooting
To enable debug logging for WebDAV attachment storage, add the following to the bottom of WEB-INF/classes/log4j.properties and restart Confluence:
73
RELATED TOPICS
Backup Confluence Home Before upgrading to Confluence 3.0, as with any upgrade you must ensure you have a backup of your Confluence home directory before you proceed.
74
5 6 7 8
The least significant 3 digits of the content id, modulo 250 The next 3 least significant digits of the content id, modulo 250 The full content id The full attachment id
Within the 8th level will be a file for each version of that attachment, named to match the version number e.g. 1 An example:
75
To find the directory where attachments for a particular space are stored, you can use the JSP findspaceattachments.jsp at the location <confluence url>/admin/findspaceattachments.jsp. This JSP requires a space key and returns the directory on the file system where attachments for that space are stored. Attachment D in the above diagram is stored in a slightly different structure. Attachments that are not conceptually within a space replace the level 2 - 4 directories with a single directory called 'nonspaced'. Examples of such attachments are the global site logo and also attachments on draft content.
INFO [main] [AbstractUpgradeManager] upgradeStarted Starting automatic upgrade of Confluence INFO [main] [UpgradeTask] isUpgradeNeeded The configured attachmentDataDao does not store attachment data on the file system so the HierarchicalFileSystemAttachmentUpgradeTask is not necessary. INFO [main] [AbstractUpgradeManager] upgradeFinished Upgrade completed successfully
Should migration be required, it will occur automatically during upgrade and the log will show output similar to this -
INFO [main] [UpgradeTask] doUpgrade Beginning HierarchicalFileSystemAttachmentUpgradeTask. Depending on the size of the attachment data this may take some time. INFO [main] [UpgradeTask] run 4023 pages may have attachments to be moved to a new hierarchical structure. INFO [main] [UpgradeTask] run 0 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run 500 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run 1000 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run 1500 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run 2000 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run 2500 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run 3000 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run 3500 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run 4000 of 4023 pages have had their attachments moved to the new structure INFO [main] [UpgradeTask] run Successfully moved the attachments for all 4023 pages to the new hierarchical structure. INFO [main] [UpgradeTask] doUpgrade Completed HierarchicalFileSystemAttachmentUpgradeTask. INFO [main] [AbstractUpgradeManager] upgradeFinished Upgrade completed successfully
It should be noted that for most implementations of Java, the migration to the new data structure involves moving the files (not copying them). Hence, there should not be a need to have additional disk space available. It also means that the migration should be relatively fast.
76
attachments for all pages to the new hierarchical structure.". Immediately preceding this message in the log will be entries for each page whose attachments could not be moved. The following table shows examples of these messages and offers some possible explanations. Example Message The configured attachment directory <directory name> could not be found or was not a directory. It is not possible to migrate the attachments to the new structure since files already exist which the attachment process may need to create. Description The configured Confluence attachment directory is not accessible. Check confluence home for the attachment directory and ensure the permissions are correct to allow reading and writing for this directory. Your attachments directory contains files or directories which the upgrade task wants to create. That is, a top level directory called ver003 containing directories or files with names containing up to 3 digits (e.g. 1, 213). This could be due to a previous failed attempt to migrate the attachments. You should restore a previous good copy of your attachments directory and remove any files or directories with this naming pattern before retrying. This is a normal message indicating that the attachment being migrated does not belong to a space e.g. global logo.
Couldn't find current Confluence content for the id <content Id>. The attachment is a non-spaced attachment (e.g. global logo, draft attachment, etc) and will be migrated to the nonspaced directory. Problem while accessing the database for content id content Id so its attachments will not be migrated. Could not create the new attachment directory directory.
It was not possible to access the database at this point during the migration. You will need restore your Confluence attachment directory from the backup and attempt the upgrade again, once the database is accessible again. The upgrade task could not create the new directory to contain the attachment being moved. Does the server user have sufficient permission to perform this operation in the indicated directory? Is there sufficient disk space? The upgrade task could not move the directory. Does the server user have sufficient permission to perform this operation in the indicated directory?
Failed to move the current attachment directory <some path> to the new location of <some other path>.
77
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 WebDAV clients, the current version of this plugin allows you to restrict write permissions to specific WebDAV clients selectively.
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'WebDav Configuration' under 'Configuration' in the left panel. The 'WebDAV Configuration' page is displayed. 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. The regex is added to the list of restricted WebDAV clients. You can repeat steps 3 and 4 to add a regex for each additional WebDAV client you want to restrict. 5. Click the 'Save' button to save the configuration changes.
To restore one or more restricted WebDAV client's write access permissions to your Confluence installation,
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click 'WebDav Configuration' under 'Configuration' in the left panel. The 'WebDAV Configuration' page is displayed. 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. Click the 'Remove selected regexes' button. The regexes you had selected are removed from the list of restricted WebDAV clients. Click the 'Save' button to save the configuration changes.
2. 3. 4. 5.
78
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'WebDav Configuration' under 'Configuration' in the left panel. The 'WebDAV Configuration' page is displayed. 3. Clear the 'Disable strict path check' check box. You can re-enable this option at a later point in time by simply selecting this check box. 4. Click the 'Save' button to save this configuration change.
By default, these options are hidden on the 'WebDAV Configuration' page. To make them visible, you must append the parameter ?hiddenOptionsEnabled=true to the end of your URL and reload the page. For example:
79
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click 'WebDav Configuration' under 'Configuration' in the left panel. The 'WebDAV Configuration' page is displayed. Amend your URL as described in the note above and reload the 'WebDav Configuration' page. Select or clear the check box options in the 'Virtual Files and Folders' section as required. Click the 'Save' button to save the configuration changes.
2. 3. 4. 5.
If you run into any problems with the procedures in this section, please refer to the Troubleshooting WebDAV page.
To map a Confluence WebDAV client network drive, your Confluence instance must be configured so that all of the following criteria is met: Uses HTTP (not HTTPS) Listens on port 80 (not 8080, which is the default port value used by the popular application server Apache Tomcat that runs many Confluence EAR / WAR installations, or 8090, the default for Confluence distributions) Has no context root There is an issue (WBDV-208) 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,
80
1. In Windows XP, go to My Computer -> Tools menu -> Map Network Drive. In Windows Vista, go to Computer -> Map Network Drive. The 'Map Network Drive' dialog box opens. 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.
1. Go to My Network Places and choose 'Add a network place'. The 'Add Network Place Wizard' opens. 2. Click 'Next', ensure that 'Choose another network location' is selected and then click 'Next' again. 3. 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 then click 'Next'. When prompted for login credentials, specify your Confluence username and password. 4. Provide a meaningful name for your web folder and proceed with the remainder of the wizard. 5. Click 'Finish'.
To map a Confluence WebDAV client web folder in Windows Vista, This procedure is very similar to the one for Windows XP. However, the following procedure includes the slight interface differences that are specific to Windows Vista.
1. Open the 'Map Network Drive' dialog box (refer to first step of the procedure above for mapping a network drive) and choose 'Connect to a Web site that you can use to store your documents and pictures'. The 'Add Network Location' wizard opens. 2. Click 'Next', ensure that 'Choose a custom network location' is selected and then click 'Next' again. 3. 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 then click 'Next'. When prompted for login credentials, specify your Confluence username and password. 4. Provide a meaningful name for your network location/web folder and proceed with the remainder of the wizard. 5. Click 'Finish'.
81
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. If prompted for login credentials, specify your Confluence username and password. 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.
Known Issues
Please refer to the WebDAV plugin documentation for a description of the known issues and suggested workarounds.
RELATED TOPICS
Page: Attachment Storage Configuration (Confluence 4.1) Page: Configuring a WebDAV client for Confluence (Confluence 4.1) Page: Important Directories and Files (Confluence 4.1)
The maximum number of simultaneous quick navigation requests defines the maximum number of individuals who can use this feature simultaneously on the same Confluence server. 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.
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'General Configuration' in the left-hand panel. In the 'General Configuration' screen, click 'Edit'. To disable this feature, select 'Off' beside 'Quick Navigation'. To modify the maximum number of simultaneous quick navigation requests, enter the appropriate number in the field beside 'Max Simultaneous Requests'. Click 'Save'.
2. 3. 4. 5. 6.
The following screenshot demonstrates the user interface of the quick navigation aid. Screenshot: The quick navigation aid showing titles matching the query 'mark'
82
RELATED TOPICS
Searching Confluence
Enabling OpenSearch
With OpenSearch autodiscovery, you can add Confluence search to your Firefox or IE7 search box (see Searching Confluence from your Browser's Search Box). By default, OpenSearch autodiscovery is enabled. This feature can be enabled or disabled as described below. To enable or disable OpenSearch autodiscovery,
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'General Configuration' in the left-hand panel. In the 'General Configuration' screen, click 'Edit'. Select 'On' beside 'Open Search' to enable this feature, or 'Off' to disable it. Click 'Save'.
2. 3. 4. 5.
RELATED TOPICS
Searching Confluence
83
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'General Configuration' in the left-hand panel. 3. In the 'General Configuration' screen, click 'Edit'. 4. Select 'On' beside 'Did You Mean'. If you have no 'Did you mean' feature index or you have not yet created it, this option will not be available. To create this index, click 'build the did-you-mean index' and on the subsequent page, click 'Build' in the 'Did You Mean Index' section. Then return to the 'General Configuration' screen in Edit mode. 5. Click 'Save'.
The 'Did You Mean' feature supports only the English language. In addition, the 'Did You Mean' index requires the built-in UK-English locale ( en_UK). If your Confluence site uses a different language pack, such as English (US), the 'Did You Mean' feature will not work. You will see an error message like this: For Did You Mean both the indexing language and the global default language must be set to English. For more information about how the 'Did You Mean' feature works, please refer to the user guide. You can track the request to support other languages by watching issue CONF-14768.
RELATED TOPICS
Searching Confluence
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'General Configuration' in the left-hand panel. Click 'Edit' next to 'Site Configuration'. Select 'On' next to 'Remote API (XML-RPC & SOAP)'. Click 'Save' to retain your changes.
2. 3. 4. 5.
RELATED TOPICS
Page: Confluence XML-RPC and SOAP APIs Page: RPC Module Confluencer.NET
84
Threaded: Shows the comments in a hierarchy of responses. Each reply to a comment is indented to indicate the relationships between the comments. Flat: Displays all the comments in one single list and does not indicate the relationships between comments. By default, comments are displayed in threaded mode. The Confluence administrator can enable or disable the threaded view for the entire Confluence site. To enable or disable the threaded view: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select General Configuration in the left-hand panel. In the 'Feature Settings' section, click Edit. Check Threaded Comments to enable threaded mode. Clear the check box to disable threaded mode and display all comments in flat mode. Click Save.
2. 3. 4. 5.
Related Topics
Enabling Trackback
When Trackback is enabled, any time you link to an external webpage that supports Trackback Autodiscovery, Confluence will send a trackback ping to that page to inform it that it has been linked to. Confluence pages also support Trackback Autodiscovery and when Trackback is enabled, can receive trackback pings sent by other sites. To enable trackback,
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'General Configuration' in the left panel. 3. In the 'Feature Settings' screen, click 'Edit'. 4. Select "On' beside 'Trackback' and click 'Save'.
RELATED TOPICS
Page: Configuring Captcha for Failed Logins (Confluence 4.1) Page: Running Confluence Over SSL or HTTPS (Confluence 4.1) Page: Excluding external referrers (Confluence 4.1) Page: Configuring the Administrator Contact Page (Confluence 4.1) Page: Hiding the People Directory (Confluence 4.1) Page: User Email Visibility (Confluence 4.1) Page: Anonymous Access to Remote API (Confluence 4.1) Page: Enabling or Disabling Public Signup (Confluence 4.1) Page: Configuring Captcha for Spam Prevention (Confluence 4.1) Page: Hiding external referrers (Confluence 4.1) Page: Ignoring External Referrers (Confluence 4.1) Page: Managing External Referrers (Confluence 4.1) Page: Hiding External Links From Search Engines (Confluence 4.1)
85
Other Settings
Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats Configuring Shortcut Links Configuring Time and Date Formats
To configure the maximum 'index-able size of attachments': By default, large attachment is defined as greater than 1 MB. The threshold for attachments that won't get excerpts can be modified using the system property atlassian.indexing.contentbody.maxsize, which takes a size in bytes.
Example
To specify 250 kb you would use the following JVM parameter: -Datlassian.indexing.contentbody.maxsize=256000
Outcomes of Limiting Attachment Indexing Size
Limiting the size of attachment indexing has the following effects: Decreases the size of the index when large attachments are present. Decreases the memory used in indexing large attachments. Prevent excerpts of large attachments being displayed in search results. For more details, please refer to the following JIRA issue.
Related Topics
Page: Recognised System Properties Page: Configuring HTTP Timeout Settings Page: Configuring Attachment Size Page: Configuring Indexing Language Page: Configuring Character Encoding Page: Configuring Time and Date Formats Page: Configuring Number Formats
86
To change the character encoding: 1. Go to the 'Administration Console' and click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Formatting and International Settings' screen. For Confluence version earlier than 2.6.2, look for the 'Options and Settings' screen. 3. Beside 'Encoding', enter the new character encoding of your choice. 4. 'Save' your changes.
Related Links
Joel Spolsky: The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!)
Related Topics
Page: Recognised System Properties Page: Configuring HTTP Timeout Settings Page: Configuring Attachment Size Page: Configuring Indexing Language Page: Configuring Character Encoding Page: Configuring Time and Date Formats Page: Configuring Number Formats
Related Topics
87
Content Index Administration Rebuild the Content Indices from scratch Creating a Lowercase Page Title Index
Page: Recognised System Properties Page: Configuring HTTP Timeout Settings Page: Configuring Attachment Size Page: Configuring Indexing Language Page: Configuring Character Encoding Page: Configuring Time and Date Formats Page: Configuring Number Formats
Shortcut links are added and maintained by Confluence administrators from the Administration Console.
88
CONF-1000@JIRA
http://jira.atlassian.com/secure/QuickSearch.jspa?searchString=CONF-1000
CONF-1000
Atlassian Confluence@Google
http://www.google.com/search?q=Atlassian+Confluence
Atlassian Confluence@Google
Related Topics
Page: Recognised System Properties Page: Configuring HTTP Timeout Settings Page: Configuring Attachment Size Page: Configuring Indexing Language Page: Configuring Character Encoding Page: Configuring Time and Date Formats Page: Configuring Number Formats
89
This page describes how to set Java properties and options on startup for Confluence Stand-alone and EAR/WAR versions. See Fix Out of Memory Errors by Increasing Available Memory for specific instructions for OutOfMemory Errors.
On this page:
Linux
To Configure System Properties in Linux Installations, 1. From <confluence-install>/bin (Stand-alone) or <Tomcat-home>/bin (EAR-WAR installation), open setenv.sh. 2. Find the section JAVA_OPTS= 3. Refer to the list of parameters below. Add all parameters in a space-separated list, inside the quotations.
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
90
Setting Properties for Windows Services via Command Line 1. Identify the name of the service that Confluence is installed as in Windows ( Control Panel > Administrative Tools > Services ):
In the above example, the SERVICENAME is: JIRA030908110721. Find the Confluence equivalent. 2. Open the command window from Start >> Run >> type in 'cmd' >> Enter 3. cd to the bin directory of your Confluence instance, or the bin directory of your Tomcat installation if your are running Confluence EAR/WAR. 4. Run:
tomcat6w //ES//%SERVICENAME%
5. Click on the Java tab to see the list of current start-up options:
6. 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 below.
91
To Set Properties for Windows Services via the Windows Registry, 1. Go to {{Start >> Run, and run "regedit32.exe".
2. Find the Services entry: 32-bit: HKEY_LOCAL_MACHINE >> SOFTWARE >> Apache Software Foundation >> Procrun 2.0 >> Confluence 64-bit: HKEY_LOCAL_MACHINE >> SOFTWARE >> Wow6432Node >> Apache Software Foundation >> Procrun 2.0 >> Confluence
3. To change existing properties, especially increasing Xmx memory, double-click the appropriate value.
atlassian.forceSchemaUpdate
1.0
atlassian-config
By default, Confluence will only database schema update when it has been upgraded. This flag Confluence to perform the sche system startup.
92
confluence.home
1.0
If this system property is set, Co ignore the contents of the confluence-init.properti use this property as the setting f Confluence Home directory.
confluence.devmode
1.0
false
Confluence
Enables additional debugging o may be of use to Confluence de (additionally it changes spring b to use lazy initialization by defau startup time). Do not enable this production system.
confluence.disable.mailpolling
2.4
false
Confluence
If set to "true", will prevent Conf retrieving mail for archiving with Manually triggering "check for n the web UI will still work. This pr effect on outgoing mail
confluence.i18n.reloadbundles
1.0
true
Confluence
Setting this property will cause C reload its i18n resource bundles internationalised string is looked be useful when testing translatio make Confluence run insanely s
confluence.ignore.debug.logging
1.0
true
Confluence
Confluence will normally log a s message if it detects that DEBU logging is enabled (as DEBUG l generally causes a significant de system performance). Setting th suppress the error message.
confluence.jmx.disabled
3.0
false
Confluence
If set to "true", will disable Confl monitoring. This has the same e setting the "enabled" property to WEB-INF/classes/jmxConte Number of index queue flushes index is optimised.
confluence.optimize.index.modulo
2.2
20
Confluence
confluence.plugins.bundled.disable
2.9
false
Confluence
Starts confluence without bundle May be useful in a development to make Confluence start quicke bundled plugins are necessary f Confluence's core functionality, should not be set on a productio Disables mail fetching services POP Disables sending of mail
atlassian.mail.fetchdisabled
3.5
false
Confluence
atlassian.mail.senddisabled
3.5
false
atlassian.disable.caches
2.4
true
Setting this property will disable get and expires: headers on som resources. This will significantly the user experience, but is usefu devlopment if you are frequently static resources and don't want flush your browser cache.
confluence.html.encode.automatic
2.9
Confluence
Setting this property forces the a encoding on or off, overriding th dictated by settings. The default differs between Confluence vers
93
org.osgi.framework.bootdelegation
2.10
empty
atlassian-plugins
Comma-separated list of packag provide from application for OSG Typically required when profiling For example: "com.jprofiler.,com
confluence.diff.pool.size
3.1
20
Confluence
Maximum number of concurrent that number is exceeded, additio by RSS feeds to create diffs are logged. (The RSS requests succ just missing diffs).
confluence.diff.timeout
3.1
1000
Confluence
Number of milliseconds to wait f operation (comparing two page complete before aborting with a message.
atlassian.user.experimentalMapping
2.10
false
Confluence
Setting this property changes th between local users and local g reduce performance degradatio a local user to a local group with number of users. Please note, s property can slow down other us management functions. We reco you set it only if you are experie performance problems when ad users to large local groups. Plea CONF-12319, fixed in Confluen
confluence.import.use-experimental-importer
3.2
false
Confluence
Setting this property changes C use the Experimental XML Impo designed to be a more stable im but, at the time of the release of importer is largely untested and supported.
atlassian.webresource.disable.minification
3.3
false
atlassian-plugins
index.queue.thread.count
3.3
See "Effect"
Confluence
Sets the number of threads to b reindex job. The value has to be of 1 to 10 (inclusive), i.e. at leas but no more than 10 threads wil There is no default value, i.e.
If you don't set index.queue.threa number of threads to be calculated based on the objects that need to be the number of processo maximum of 10 threads If you set index.queue.threa then two threads will be reindex the content (reg number of objects to be the number of processo If you set index.queue.threa , then ten threads (the m allowed) will be used to content. index.queue.batch.size 3.3 1500 Confluence
Size of batches used by the inde Reducing this value will reduce the indexer puts on the system, takes longer. Increasing this val indexing to be completed faster, higher load on the system. Norm setting does not need tuning.
94
password.confirmation.disabled
3.4
false
Confluence
This property disables the passw confirmation functionality that C uses as an additional security m this property set, Confluence wi password confirmation for the fo actions: administrative actions, c email address and Captcha for f Disabling password confirmation you are using a custom authent
confluence.browser.language.enabled
3.5
true
Confluence
Setting this property to "false" d detection of browser language h effectively restoring Confluence that of earlier releases. Setting t "true" enables the detection of th headers sent by the browser. Co change the UI language based o headers. See documentation on can choose a language preferen
upm.pac.disable
false
When this property is set to true will not try to access the Atlassia Exchange. This is useful for app servers that do not have access Internet. See the UPM documen
confluence.reindex.documents.to.pop
3.5.9
20
Confluence
Indicates how many objects eac thread should process at a time re-index. Please note that this n not include attachments
confluence.reindex.attachments.to.pop
3.5.9
10
Confluence
Indicates how many attachment indexing thread should process during a full re-index.
confluence.upgrade.active.directory
3.5.11
false
Confluence
Forces Confluence to treat any directories it migrates as Active rather than relying on looking fo sAMAccountName in the userna This is necessary if you are upg before Confluence 3.5, and nee attribute other than sAMAccoun identify your users and are seein error code 4 - Sizelimit exceptions in your logs. For mor Unable to Log In with Confluenc Due to 'LDAP error code 4 - Siz Exceeded'
com.atlassian.logout.disable.session.invalidation
4.0
false
Confluence
Disables the session invalidation As of 4.0 the default behaviour i the JSession assigned to a clien log out. If this is set to true the s active (but the user logged out). valuable when using external au systems, but should generally n
RELATED TOPICS
Recognised System Properties Fix Out of Memory Errors by Increasing Available Memory
95
Property
Since
Module...
Effect
atlassian.forceSchemaUpdate
1.0
atlassian-config
By default, Confluence will only database schema update when it has been upgraded. This flag Confluence to perform the sche system startup.
confluence.home
1.0
If this system property is set, Co ignore the contents of the confluence-init.properti use this property as the setting f Confluence Home directory.
confluence.devmode
1.0
false
Confluence
Enables additional debugging o may be of use to Confluence de (additionally it changes spring b to use lazy initialization by defau startup time). Do not enable this production system.
confluence.disable.mailpolling
2.4
false
Confluence
If set to "true", will prevent Conf retrieving mail for archiving with Manually triggering "check for n the web UI will still work. This pr effect on outgoing mail
confluence.i18n.reloadbundles
1.0
true
Confluence
Setting this property will cause C reload its i18n resource bundles internationalised string is looked be useful when testing translatio make Confluence run insanely s
confluence.ignore.debug.logging
1.0
true
Confluence
Confluence will normally log a s message if it detects that DEBU logging is enabled (as DEBUG l generally causes a significant de system performance). Setting th suppress the error message.
confluence.jmx.disabled
3.0
false
Confluence
If set to "true", will disable Confl monitoring. This has the same e setting the "enabled" property to WEB-INF/classes/jmxConte Number of index queue flushes index is optimised.
confluence.optimize.index.modulo
2.2
20
Confluence
confluence.plugins.bundled.disable
2.9
false
Confluence
Starts confluence without bundle May be useful in a development to make Confluence start quicke bundled plugins are necessary f Confluence's core functionality, should not be set on a productio Disables mail fetching services POP Disables sending of mail
atlassian.mail.fetchdisabled
3.5
false
Confluence
atlassian.mail.senddisabled
3.5
false
96
atlassian.disable.caches
2.4
true
atlassian-plugins, atlassian-cache-servlet
Setting this property will disable get and expires: headers on som resources. This will significantly the user experience, but is usefu devlopment if you are frequently static resources and don't want flush your browser cache.
confluence.html.encode.automatic
2.9
Confluence
Setting this property forces the a encoding on or off, overriding th dictated by settings. The default differs between Confluence vers
org.osgi.framework.bootdelegation
2.10
empty
atlassian-plugins
Comma-separated list of packag provide from application for OSG Typically required when profiling For example: "com.jprofiler.,com
confluence.diff.pool.size
3.1
20
Confluence
Maximum number of concurrent that number is exceeded, additio by RSS feeds to create diffs are logged. (The RSS requests succ just missing diffs).
confluence.diff.timeout
3.1
1000
Confluence
Number of milliseconds to wait f operation (comparing two page complete before aborting with a message.
atlassian.user.experimentalMapping
2.10
false
Confluence
Setting this property changes th between local users and local g reduce performance degradatio a local user to a local group with number of users. Please note, s property can slow down other us management functions. We reco you set it only if you are experie performance problems when ad users to large local groups. Plea CONF-12319, fixed in Confluen
confluence.import.use-experimental-importer
3.2
false
Confluence
Setting this property changes C use the Experimental XML Impo designed to be a more stable im but, at the time of the release of importer is largely untested and supported.
atlassian.webresource.disable.minification
3.3
false
atlassian-plugins
97
index.queue.thread.count
3.3
See "Effect"
Confluence
Sets the number of threads to b reindex job. The value has to be of 1 to 10 (inclusive), i.e. at leas but no more than 10 threads wil There is no default value, i.e.
If you don't set index.queue.threa number of threads to be calculated based on the objects that need to be the number of processo maximum of 10 threads If you set index.queue.threa then two threads will be reindex the content (reg number of objects to be the number of processo If you set index.queue.threa , then ten threads (the m allowed) will be used to content. index.queue.batch.size 3.3 1500 Confluence
Size of batches used by the inde Reducing this value will reduce the indexer puts on the system, takes longer. Increasing this val indexing to be completed faster, higher load on the system. Norm setting does not need tuning.
password.confirmation.disabled
3.4
false
Confluence
This property disables the passw confirmation functionality that C uses as an additional security m this property set, Confluence wi password confirmation for the fo actions: administrative actions, c email address and Captcha for f Disabling password confirmation you are using a custom authent
confluence.browser.language.enabled
3.5
true
Confluence
Setting this property to "false" d detection of browser language h effectively restoring Confluence that of earlier releases. Setting t "true" enables the detection of th headers sent by the browser. Co change the UI language based o headers. See documentation on can choose a language preferen
upm.pac.disable
false
When this property is set to true will not try to access the Atlassia Exchange. This is useful for app servers that do not have access Internet. See the UPM documen
confluence.reindex.documents.to.pop
3.5.9
20
Confluence
Indicates how many objects eac thread should process at a time re-index. Please note that this n not include attachments
confluence.reindex.attachments.to.pop
3.5.9
10
Confluence
Indicates how many attachment indexing thread should process during a full re-index.
98
confluence.upgrade.active.directory
3.5.11
false
Confluence
Forces Confluence to treat any directories it migrates as Active rather than relying on looking fo sAMAccountName in the userna This is necessary if you are upg before Confluence 3.5, and nee attribute other than sAMAccoun identify your users and are seein error code 4 - Sizelimit exceptions in your logs. For mor Unable to Log In with Confluenc Due to 'LDAP error code 4 - Siz Exceeded'
com.atlassian.logout.disable.session.invalidation
4.0
false
Confluence
Disables the session invalidation As of 4.0 the default behaviour i the JSession assigned to a clien log out. If this is set to true the s active (but the user logged out). valuable when using external au systems, but should generally n
RELATED TOPICS
General Advice
Staged Rollout
Do not try to deploy Confluence immediately to your whole organisation. Instead, roll it out department by department, or project by project. How Confluence will scale given a particular software and hardware configuration depends very much on how Confluence is likely to be used in your organisation. Launching Confluence to everybody at once may seem like a neat idea, but it also means that any problems you might experience scaling the system up to your entire organisation will hit you all at once, annoy everyone and possibly hurt adoption. Rolling Confluence out gradually will give you the chance to tune it as you go, resulting in a much more painless experience. There will also be organisational advantages: you can identify those teams or projects who are most likely to be successful 'early adopters', and those teams can experiment with how best a wiki might suit your organisation, and pass on their 'best wiki practices' as usage of Confluence expands.
Plugin Governance
Confluence plugins can add tremendous value. Before adding one, visit the plugin's page and explore its issues (available from the issue management link). Try the plugin in a test environment and make sure to note any adverse effects after adding it to a production environment. Test plugins independently when upgrading.
Backup strategy
Disable the XML backup and use the Production Backup Strategy.
99
specific group or set of groups, thereby keeping the gradual rollout. Please refer to our detailed guide to Configuring User Directories and examine the User Management Limitations and Recommendations.
Best Practices
Troubleshooting possible memory leaks
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. Many of the issues reported there are exacerbated with a large installation.
Memory Usage
The Java virtual machine is configured with a "maximum heap size" that limits the amount of memory it will consume. If Confluence fills up this maximum heap size it will run out of memory, and start behaving unpredictably. You can keep track of Confluence's memory usage from the System Information screen of the administration console:
This example shows that, at the time of writing, confluence.atlassian.com is using 173MB of an allocated 313MB of heap. (The JVM was configured with a maximum heap size of 450MB, but this information is not available in the graph. The 313MB figure shows that the full 450MB of heap has not yet been needed)
Cache Sizes
The Performance Tuning page includes some useful rules of thumb for configuring the sizes of Confluence's internal caches.
RELATED TOPICS
Operating Large or Mission-Critical Confluence Installations Performance Tuning Confluence Clustering Overview Requesting Performance Support User Management Confluence Administrator's Guide Confluence Configuration Guide
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 Configuring Logging. 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.
100
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 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 behaviour 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
101
102
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.
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.
External Gadgets
The External Gadgets section allows you to register gadgets served from external web applications (such as JIRA 4.0+) or websites (such as iGoogle or Gmail) with your Confluence installation, so that they: Appear in the macro browser Can be added and used in Confluence pages or blog posts via a gadget macro
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click External Gadgets under 'Configuration' in the left panel. The 'External Gadgets' page is displayed. 3. In the 'Add a new Gadget' section, paste your gadget's URL into the Gadget Specification URL field. 4. Click Add. Your gadget will be shown in the list of registered gadgets below and it will also become available in the macro browser.
In addition to registering an external gadget for use in Confluence, you may also need to establish an OAuth or Trusted Application relationship between the application that serves the gadget (the service provider) and Confluence (the consumer). OAuth and Trusted Application relationships are usually only required for gadgets that access user-restricted data from the external web application. Refer to Configuring OAuth for further information. If an external web application provides anonymous access to all or some of its data and that is the only data you need to access, then establishing an OAuth or Trusted Applications relationship may be unnecessary.
Related Topics
The big list of Atlassian gadgets Adding JIRA Gadgets to a Confluence Page
Please be aware that Confluence clustered is not available for version 4.0 yet. It will be forthcoming in a minor release of Confluence following the release of version 4.0.
It is possible to run Confluence in a clustered environment instead of on a single server. This means that you can run multiple copies of Confluence in a cluster, so that clients (such as a browser) can connect to any copy and see the same information.
Consider your options carefully before deciding on a clustered installation While we have tried to make clustering Confluence as easy and administrator-friendly as possible, it is a major architectural change and requires extra planning for deployment and upgrades. Please consider the information on the Cluster Checklist and then consult Atlassian support before making your final decision.
This page gives an overview and links to further pages with information on installing, configuring and administering a Confluence cluster.
Technical Overview
Confluence on Virtualised Environments
Atlassian officially supports non-clustered installations of Confluence 3.0 and later on VMware. Although possible, we do not recommend (nor support) running versions of Confluence prior to 3.0 on VMware, since Confluence 3.0 resolved many performance issues that were present in earlier versions. Be aware that we also do not support clustered installations of Confluence on VMware. Please comment or vote on the feature request at CONF-19559.
Troubleshooting
105
Cluster troubleshooting
RELATED TOPICS
Operating Large or Mission-Critical Confluence Installations Performance Tuning Requesting Performance Support Confluence Administrator's Guide Confluence Configuration Guide
Overview of clustering documentation Refer to the overview of Confluence clustering in the Administrators' Guide.
Introduction
From version 2.3, Confluence has had the ability to configure and run multiple copies of itself in a cluster, so that clients can connect to any copy and see the same information. In effect, a Confluence cluster behaves as a single, powerful Confluence installation. While we have tried to make clustering Confluence as easy and administrator-friendly as possible, it is a major architectural change from earlier versions (or non-clustered installations) and consequently, requires extra planning for deployment and upgrades. This document will give a technical overview of clustering in Confluence, primarily for those users and developers who will be installing and configuring Confluence in a cluster. A separate overview is available for Confluence plugin developers.
Cluster topology
A simple description of the cluster topology for Confluence would be multiple applications, shared data source. A cluster of Confluence consists of: multiple homogeneous installations of Confluence (called nodes below) a Confluence home directory for each installation. a distributed Oracle Coherence cache (formerly known as Tangosol Coherence), which all nodes use via a multicast group - see networking summary below a single database, which all nodes connect to The user is responsible for configuring an appropriate HTTP load balancer in front of the clustered installations. Typically this means using mod_jk or another application server load-balancing technology. The load balancer must be configured to support session affinity. Communication between clustered nodes is minimised by using a distributed cache which propagates updates to all other nodes automatically. Where necessary, Coherence provides a locking mechanism for synchronising jobs and a RMI interface for more complex communication.
106
Copying the Confluence application and home directory helps ensure that the installations are homogeneous. An alternative to this method is to copy the Confluence web application, but not the Confluence home directory. In this case, the installation wizard will require your cluster name to connect to the other nodes, and it will automatically configure itself. You will need to rebuild the index manually after this installation, however. There is now full documentation for a Confluence Cluster Installation.
Upgrade process
Another consequence of the homogeneous requirement is that upgrades must be done by following a strict process. 1. 2. 3. 4. All cluster nodes are brought down Upgrade a single node to the latest Confluence version Start the single node so it can upgrade the database Upgrade subsequent nodes and start them one-by-one.
Single database
The Confluence database in a cluster is shared by all nodes. This means that the database must be able to scale to service all the Confluence nodes, which will probably mean implementing some kind of database cluster and JDBC-level load balancing. We can not offer support with scaling or tuning your database, you will need to talk to your DBA or database vendor. For obvious reasons, you must have an external database to run Massive - you can not cluster Confluence when using the embedded HSQL database. The most important requirement for the cluster database is that it have sufficient connections available to support the expected number of application nodes. For example, if each Confluence instance has a connection pool of 20 connections and you expect to run a cluster with four nodes, your database server must allow at least 80 connections to the Confluence database. In practice, you may require more than the minimum for debugging or administrative purposes. In a cluster, attachments must be stored in the database. Configuring a cluster in an existing installation will automatically migrate your attachments to the database. Non-clustered installations still have the option of using the Confluence home directory for storing attachments. While attachments are stored in the database, they are temporarily written to the cluster node's local filesystem, designated <confluence-home>/temp folder, when being streamed to users (so Confluence doesn't have to hold open database connections unnecessarily). For this reason, Confluence will still need enough temporary disk space to hold any attachments currently in transit.
Distributed cache
In a normal configuration, Confluence uses many caches to reduce the number of database queries required for common operations. Viewing a page might require dozens of permissions checks, and it would be very slow if Confluence queried the database for this information with every page view. However, caches must be carefully maintained so they are consistent with the application data. If the page permissions change, the old invalid data needs to be removed from the cache so it can be replaced with a fresh correct copy. To preserve consistent caches across a cluster, Confluence uses a distributed cache called Oracle Coherence, which manages replicating cache updates transparently across all nodes. The network requirements of the distributed cache are quite simple, but must be preserved if the cluster is to work properly. To discover other nodes in the cluster, Confluence broadcasts a join request on a multicast network address. Confluence must be able to
107
open a UDP port on this multicast address, or it will not 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. Because the Coherence network requirements are different to those required by the Confluence database connection, the situation can arise where Confluence can use the database but not talk to the other nodes in the cluster via Coherence. When Confluence detects this, it will shut itself down in a cluster panic. For more details on the network configuration of the distributed cache, see the networking summary
Home directory
Confluence's home directory has a much-reduced role in a cluster. Because the application data must be shared between all nodes for consistency, the only information stored in the Confluence home directory is either node-specific, or needed to start Confluence. This includes information related to: database connection license cluster connection The only application data stored in the Confluence home directory is the Lucene search index. Confluence synchronises this data itself by keeping track of indexing tasks in the database. This is also why we recommend copying the Confluence home directory from the first node when setting up subsequent nodes. If you did not copy the Confluence home directory, you would need to rebuild the search index from scratch on the subsequent nodes after installation.
Event handling
Broadcasting events to all nodes in a cluster is supported in Confluence, but not recommended. The cluster topology uses a shared data store so that application state does not need to be synchronised by events. The event broadcasting is done only for certain events, like installing a plugin. When a plugin is installed in one node, Confluence puts the plugin data in the database, and notifies the other nodes that they need to load the plugin into memory.
Indexing
Confluence maintains a copy of its Lucene search index on each node of the cluster. This index is used for many things beside full-text searches, including RSS feeds and lists of recently updated content. Indexing in a cluster works like this: 1. Node 1 gets a request to save some page update 2. After saving the page in the database, Node 1 adds a "page-updated" index entry to the queue, which is in the database 3. Periodically, each node picks up the "latest entries" from the queue, where what is latest is determined from a timestamp on a file in the Confluence home directory which indicates when the queue was last inspected. This process is called "flushing the index queue". 4. Each node independently updates its local Lucene index. The "page-updated" index entry is internally changed into a delete-document task and an add-document task to apply the changes to Lucene. 5. Each node updates the timestamp on its index-queue-timestamp file to reflect the most recent processing or "flushing" of the index queue. Because of step #3, if the timing of the nodes is not synchronised or changes sporadically (due to a virtualisation environment, typically), index changes will not be correctly synchronised in the cluster. This is the most common cause of index sync problems in clusters. If a node is disconnected from the cluster for a short amount of time (less than three hours), it will be able to bring its copy of the index up-to-date when it rejoins the cluster. If a node is down for a long amount of time and its lucene index has become stale as a result, you may want to avoid the expensive operation of rebuilding the index. To do that, you must copy a "live" version of the Lucene index from an active node. Simply replace the contents of the Confluence Home]/index directory with those from an active node before bringing the stale node back up.
Job synchronisation
For tasks such as sending the daily report emails, it is important that only one node in the cluster does this. Otherwise you would get multiple emails from Confluence every day. Confluence uses locks in the Coherence distributed cache to ensure only one node can be running certain jobs at a time. This ensures email notifications will only be sent once.
Activity tracking
Activity tracking does not work in a cluster, and will be disabled for clustered deployments. We're working on making the activity tracker clusterable in a future release. You can follow this issue. You can try some other options for tracking usage.
Cluster panic
In some situations, there can be a network issue or firewall that prevents the distributed cache from communicating but still allows Confluence to update the database. This is a dangerous situation because when the caches on the detached nodes become inconsistent, users on different nodes will see different information and updates can be lost.
108
Confluence can detect this problem by checking a database value against a cached value, and if they differ, all the clustered nodes will be shut down with a 'Cluster panic' message. This is considered a fatal error because the consequences can cause damage to your data. For those administrators that like to live on the edge, there is a system property to prevent cluster panic and allow data corruption. For more information, see Cluster safety mechanism. If a cluster panic does occur, you need to ensure proper network connectivity between the clustered nodes. Most likely multicast traffic is being blocked or not routed correctly. See the networking summary below.
Server Hardware Requirements Guide Overview of Confluence Clusters Developers' Guide to Clustering
Introduction
A mechanism was added in Confluence 2.3 and above to ensure database consistency when running multiple cluster nodes against the same database. This is called the cluster safety mechanism, and is designed to ensure that your wiki cannot become inconsistent because updates by one user are not visible to another. A failure of this mechanism is a fatal error in Confluence and is called cluster panic. Because the cluster safety mechanism helps prevents data inconsistency whenever any two copies of Confluence running against the same database, it is enabled in all instances of Confluence, not just clusters.
109
update the database safety number to a new value, which will cause all nodes accessing the database to fail. 4. If the numbers are the same or aren't set yet, update the safety numbers: set the safety number in the database to the new random number set the safety number in the cache to the new random number.
How to fix it
See 'Database is being updated by an instance which is not part of the current cluster' Error Message
Technical details
The cluster safety number in the database is stored in the CLUSTERSAFETY table. This table has just one row: the current safety number.
The recommended way of changing database connections is to shut down the whole cluster, install Confluence into new and empty directories and use the Setup Wizard to configure all new database connection settings.
However, if you wish to manually change your settings, you may proceed as described below. It is strongly recommended that you test all of the following in a staging or test instance of Confluence before performing these steps in your production environment.
Step 1: Prepare
Locate the confluence-cfg.xml file in the Confluence home directory. Make a backup copy of that file. Prepare the necessary changes to that file.
Cluster Troubleshooting
110
Please be aware that Confluence clustered is not available for version 4.0 yet. It will be forthcoming in a minor release of Confluence following the release of version 4.0.
Atlassian officially supports non-clustered installations of Confluence 3.0 and later on VMware. Although possible, we do not recommend (nor support) running versions of Confluence prior to 3.0 on VMware, since Confluence 3.0 resolved many performance issues that were present in earlier versions. Be aware that we also do not support clustered installations of Confluence on VMware. Please comment or vote on the feature request at CONF-19559.
This page covers troubleshooting for the Clustered Edition. If you're experiencing Cluster Panic messages in a Standard Edition, visit the Knowledge Base article 'Database is being updated by an instance which is not part of the current cluster' Error Message.
On this page: Symptoms Confluence cluster debugging tools Didn't find a solution? Related
Symptoms
Below is a list of potential problems with a Confluence cluster, and their likely solutions. The solutions are listed below. Problem Database is being updated by an instance which is not part of the current cluster errors on a stand-alone Likely solutions 'Database is being updated by an instance which is not part of the current cluster' Error Message Add multicast route, Check firewall
Database is being updated by an instance which is not part of the current cluster errors on a cluster Cannot assign requested address on startup, featuring an IPv6 address Error in log: The interface is not suitable for multicast communication Multicast being sent, but not received (detectable with Multicast Test)
Prefer IPv4
Check firewall, Check intermediate routers, Increase multicast TTL Contact support
111
There is an umbrella issue opened for all cluster debugging tools here It includes the tools listed below.
Multicast
Which multicast address? The multicast address and port used by Confluence can be found on the Cluster Administration page, or in confluence.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.
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 netstat -gn Information provided Lists multicast groups. Does not work on Mac OS X. Lists system routing table. Coherence tool for testing multicast traffic from one node to another. Captures network traffic on the given interface. Most useful on an interface that only receives cluster traffic.
112
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 the Multicast Test tool shows that 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:
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's a known issue with IPv6, especially on Linux.
The fix is to add -Djava.net.preferIPv4Stack=true to JAVA_OPTS. This tells the JVM to try binding an IPv4 address first, and resort to IPv6 only if that fails. Note: A more radical approach is to add NETWORKING_IPV6=no to /etc/sysconfig/network, yet probably should be left for a later consideration on a production machine.
<property name="confluence.cluster.interface">eth1</property>
<?xml version='1.0'?> <coherence> <cluster-config> <multicast-listener> <time-to-live system-property='tangosol.coherence.ttl'>1</time-to-live> </multicast-listener> </cluster-config> </coherence>
Alternatively, simply start Confluence with the system property: -Dtangosol.coherence.ttl=1. Again, 1 is the default value, and you should change it to something appropriate to your network topology.
113
Page: Cluster safety mechanism Page: How do I supress cluster warning message in confluence? Page: Technical Overview of Clustering in Confluence Page: Confluence Clustering Overview Page: Changing Datasources Manually in a Cluster Page: Viewing and Editing License Details Page: Cluster Troubleshooting Page: Confluence Cluster Installation Page: Apache and Tomcat load balancing Page: Cluster Administration page Page: Recommended network topology Page: Upgrading a Confluence Cluster
Open JIRA Features and Bug Reports
JIRA Issues (53 issues) Type Key CONF-14948 Summary Support failover NICs for cluster configuration... Generate new Multicast address from a "new" cluster name Database logging of clustersafety access Specify an arbitrary multicast port for a cluster Plugins which don't work in a cluster shouldn't look like an error Assignee Reporter Priority Status Open Resolution Created Updated Unresolved Mar 19, 2009 Mar 06, 2008 Feb 03, 2008 Jan 30, 2009 Oct 15, 2007 Jul 30, 2010 Mar 19, 2009 Sep 11, 2008 Feb 03, 2008 Jan 30, 2009 Oct 16, 2007 Jul 30, 2010 Tony Unassigned Atkins [Atlassian] Unassigned Ivan Benko [Atlassian]
CONF-10977
Open
Unresolved
CONF-10635
James Unassigned Fleming [Atlassian] James Unassigned Fleming [Atlassian] Unassigned Gary Weaver
Open
Unresolved
CONF-14338
Open
Unresolved
CONF-9712
Open
Unresolved
CONF-20501 Consider upgrading coherence Confluence should explicitly check for other confluence instances using the same home directory
Partha Unassigned Kamal [Atlassian] Don Willis [Atlassian] Ivan Benko [Atlassian] Matt Ryall [Atlassian]
Open
Unresolved
CONF-21670
Unassigned
Open
Unresolved
Jan 20, 2011 Mar 06, 2008 Jun 17, 2007 Jul 30, 2010 Mar 06,
Jan 25, 2011 Mar 06, 2008 Oct 29, 2007 Nov 08, 2010 Mar 06,
CONF-10979 List confluence cluster interface Determine index mismatch in cluster and warn on cluster info page A cluster panic should not bring down other nodes Cluster
Unassigned
Open
Unresolved
CONF-8716
Unassigned
Open
Unresolved
CONF-20500
Open
Unresolved
114
CONF-10980 debugging/troubleshooting tools CONF-11206 Confluence Clustered and JIRA trust delegation
Open Open
Check how many CONF-10981 nodes/processes running in a cluster and their identity Support unicast addressing in cluster when CONF-10953 well-known-addresses WKA are defined CONF-12689 Support Confluence cluster upgrades without an outage
Unassigned
Open
Unresolved
Unassigned
Open
Unresolved
Unassigned Igor Minar Carlos Alberto Unassigned Feijo Schedler [Atlassian] Unassigned Gary Weaver
Open
Unresolved
Remove the option to store CONF-23223 attachments on filesystem when using a cluster Confluence should be able to automatically recover from cluster panics In cluster, allow attachments to be stored on file system in network-shared directory
Open
Unresolved
CONF-9297
Open
Unresolved
Aug 27, 2007 Aug 29, 2007 May 06, 2010 Sep 04, 2009
Mar 25, 2009 Sep 22, 2011 Apr 08, 2011 May 12, 2010
CONF-9335
Jeremy Unassigned Largman [Atlassian] Tony Unassigned Atkins [Atlassian] Giles Gaskell [Atlassian] Jeremy Largman [Atlassian]
Open
Unresolved
Provide support for Confluence CONF-19559 clustered in a virtualized environment... CONF-16794 Document new cluster distributions
Open
Unresolved
Open
Unresolved
Coherence cache fails while retrieving profile picture CONF-12287 metadata (dashboard or view page shows UnexpectedRollbackException) Hibernates CONF-14120 UpdateTimestampsCache doesn't handle concurrent writes CONF-8959 Attachment migration does not happen when upgrading to a clustered license
Unassigned
Open
Unresolved
Unassigned
Open
Unresolved
Open
Unresolved
CONF-16419
Installing a font for PDF export in Charles a cluster will not carry to cluster Unassigned Miller nodes that are down or [Atlassian] unavailable. Lots of ObjectDeletedException's during cluster builds Matthew Unassigned Jensen [Atlassian] Anatoli Unassigned Kazatchkov [Atlassian] Unassigned Matt Ryall [Atlassian]
Open
Unresolved
CONF-9324
Open
Unresolved
Aug 28, 2007 Oct 01, 2009 May 05, 2009 Oct 24, 2007 Feb 29, 2008
May 12, 2010 May 12, 2010 May 12, 2010 Sep 04, 2011 Sep 03, 2008
Reindexing in cluster only runs CONF-17089 on one node if triggered from web UI CONF-15523 Run cluster performance build on two machines
Open
Unresolved
Open
Unresolved
CONF-9813
Gurleen Disable attachments migration to Unassigned Anand Filesystem in Cluster [Atlassian] Unassigned Ivan Benko [Atlassian]
Open
Unresolved
Node that can not join cluster CONF-10868 due to license restriction causes cluster panic Authenticator (subclass of DefaultAuthenticator) can be called twice at almost exactly same time by 2 or more clustered servers
Open
Unresolved
CONF-9040
Unassigned
Gary Weaver
Open
Unresolved
Intermittent Anatoli CONF-12614 ConcurrentModificationException Unassigned Kazatchkov in cluster [Atlassian] Retrieving the global settings in CONF-14657 a clustered environment causes Unassigned Chris Kiehl
Open
Unresolved
Unresolved
115
a lot of contention
[Atlassian]
Open
2009
2009
Viewing the members of a group Partha in a clustered environment works CONF-10325 Unassigned Kamal only on one node and not the [Atlassian] other. ConditionalPropertySet's cannot be cached breaking cluster installations that delegate user management to JIRA Dave Unassigned Loeng [Atlassian] Dave Unassigned Loeng [Atlassian]
Open
Unresolved
CONF-9594
Open
Unresolved
Open
Unresolved
CONF-12486
Open
Unresolved
Viewfile macro does not work in Confluence Clustered when Roy CONF-23033 Office Connector is configured to Unassigned Hartono use Cache in Memory for [Atlassian] temporary storage Layout customisations are not CONF-13421 propagated to other cluster nodes Unassigned Matt Ryall [Atlassian]
Open
Unresolved
Open
Unresolved
CONF-10323
Coherence Lock being held Paul when it appears no thread Unassigned Curren should have the lock. Causes [Atlassian] ConcurrentModificationException Cluster setup network interface selection shows loopback interface Coherence does not allow the disabling of all JDK shutdown hooks Unassigned Matt Ryall [Atlassian]
Open
Unresolved
CONF-9059
Open
Unresolved
Aug 01, 2007 Oct 17, 2007 Nov 27, 2008 May 09, 2011 Sep 25, 2009 Nov 10, 2009 Aug 26, 2007 Nov 12, 2008 Jul 27, 2007 Nov 23, 2006 Jul 27, 2011
Aug 01, 2007 Jan 29, 2008 Sep 04, 2011 May 10, 2011 Dec 08, 2009 May 12, 2010 Apr 16, 2011 Nov 13, 2008 Oct 08, 2007 Jan 19, 2009 Jul 28, 2011
CONF-9749
Open
Unresolved
After a site Import into a cluster, Agnes Ro CONF-13870 admin console displays Unassigned [Atlassian] attachment storage as filesystem Content Permission changes are CONF-22466 propagated between nodes one at a time, should be in bulk CONF-17040 Cannot build milestones outside Atlassian due to coherence Cluster build passed but didn't close down Confluence Plugin's I18n properties not loaded in other cluster nodes unless restarted Richard Unassigned Atkins [Atlassian] Jonathan Unassigned Gilbert [Atlassian] Brian Unassigned Nguyen [Atlassian] Unassigned Roberto Dominguez
Open
Unresolved
Open
Unresolved
Open
Unresolved
CONF-17577
Open
Unresolved
CONF-9281
Open
Unresolved
Changing custom html on one CONF-13698 node of a cluster is not imideatly reflected on the other node. CONF-9020 CONF-7368 Cluster nodes do not get notified of Layout changes Confluence Cluster setup dies horribly when DNS fails Migrating to a cluster with existing data does not add cluster attributes to the confluence.cfg.xml
Anatoli Unassigned Kazatchkov [Atlassian] Unassigned Unassigned Roberto Dominguez Don Willis [Atlassian]
Open
Unresolved
Open Open
Unresolved Unresolved
CONF-22979
Adam Unassigned Laskowski [Atlassian] Chris Kiehl [Atlassian] Don Willis [Atlassian]
Open
Unresolved
Locking on cache keys needs to CONF-14088 check if the lock was actually aquired CONF-9846 Tangosol configuration: the (optional) cluster-name element is in the wrong place Cannot override TTL configuration through tangosol coherence properties
Unassigned
Open
Unresolved
Unassigned
Open
Unresolved
CONF-8300
116
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.
Related
Cluster Safety Mechanism
Multicast Test
Please be aware that Confluence clustered is not available for version 4.0 yet. It will be forthcoming in a minor release of Confluence following the release of version 4.0.
This page describes the Multicast Test, a Coherence tool for testing multicast traffic from one node to another. You may find this useful when troubleshooting a clustered installation of Confluence. In order to run the Multicast test, you need to first download the attached Coherence zip file. The Multicast Test comes as a script called multicast-test, which you will find located in the bin folder in the above zip file. Instructions on how to run this script file can be found in the Coherence documentation. You may like to go straight to the subheading called ' Example' in the guide, where there is an example on how to use the multicast-test script.
RELATED TOPICS
People occasionally enquire about setting up High-Availability (HA) Confluence clusters. Confluence's clustering is designed to solve a different problem, that of scaling under high load. This page explains the difference. On this page: What is High Availability (HA)? What does Confluence's clustering do, then? So what kind of resilience can I build into a Confluence installation? What's the difference between load balancing and failover? What do you mean by 'session affinity'? RELATED TOPICS
117
disconnected from the network unexpectedly, and the rest of the cluster will continue operating cleanly as long as at least one node remains. It requires that nodes can be upgraded individually while the rest of the cluster operates, and that no disruption will result when a node rejoins the cluster. It typically also requires that nodes be installed in geographically separate locations.
It's vital to ensure that only one server is running at any one time, in this kind of setup. If a server starts while another is already running against the same database, the result will be a cluster panic that shuts down both servers.
A single database becomes the single point of failure in such a system. This can be alleviated by database clustering, or by replication from the 'active' database server to the standby server(s) if you wish to separate the failover systems while keeping database latency to a minimum. In the same vein, the home directory can be hosted on a shared network system SAN or NAS, preferably with its own replication/rapid recovery system though there's a known issue to consider. Alternatively, to avoid the use of networked file systems, a utility such as rsync can be used to periodically bring the spare servers' home directories up to date, so long as you keep the period sufficiently short probably between one and five minutes, depending on the rate of activity. This can be avoided altogether by keeping attachments in the database; it increases the demands on the bandwidth between the application and database servers, but guarantees that the system is in a consistent state at switchover. If the data is at all sensitive or confidential, it's advisable to run rsync over ssh, to minimise the opportunity for the data to be captured on its way across the network.
118
RELATED TOPICS
Atlassian recommends a network topology similar to the one shown below, to get the best results from a Confluence Clustered deployment. The number of Confluence nodes in the deployment is adjustable select the number which suits your own requirements. The most important aspect is that cluster, database and HTTP (client) traffic are all carried on separate subnets. It is possible, on a sufficiently fast network, to carry cluster and database traffic on the same subnet but we do strongly recommend that HTTP traffic be always confined to a separate subnet on production deployments. Confluence Clustered does not support clustered communication over WAN, VLAN or VPN. All Confluence Clustered nodes must be on the same local subnet, ideally networked via an ethernet hub or simple switch. The cluster communication network must also support multicast IP networking.
Use this example as a basis for your own network diagram When you are considering a Confluence Clustered deployment, you should prepare a network diagram like the one on this page. This will facilitate discussion with Atlassian Support and help with your own planning. Please refer to the cluster checklist for more guidance on planning your clustered deployment.
119
Overview
Any instance of Confluence which uses a clustered license has a Cluster Configuration page which includes information about the active cluster. To open the Cluster Administration page,
120
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'Cluster Configuration' in the left-hand menu, in the section called 'Clustering'.
Availability
To access this functionality, you must: Be a System Administrator (i.e. have global System Administrator permissions), and be using Confluence 2.3 or later, and be using a clustered Confluence license. Screenshot: Cluster Administration Page
This page shows your cluster configuration, and allows you to start a new Confluence cluster using data from this instance. Cluster Status indicates whether your cluster is currently running. Licensed nodes is the maximum number of instances of Confluence your license allows in a cluster. Active nodes lists the instances of Confluence currently participating in the cluster. Starting a new cluster will perform the following changes: enable a clustered cache migrate attachments from file system to the database
121
publish database connection information so other nodes can join the cluster. All access to Confluence will be locked while this takes place, and you will be forced to restart Confluence afterwards. Cluster name is a short name for identifying your cluster. Other Confluence instances can join the cluster using this name. To join an existing cluster, start a clean copy of Confluence on this node and select 'Join Cluster' during the setup wizard.
Related documents
Overview of Confluence Clusters Confluence Cluster Installation Cluster Troubleshooting
Cluster Checklist
Please be aware that Confluence clustered is not available for version 4.0 yet. It will be forthcoming in a minor release of Confluence following the release of version 4.0.
It is possible to run Confluence in a clustered environment instead of on a single server. This means that you can run multiple copies of Confluence in a cluster, so that clients (such as a browser) can connect to any copy and see the same information. Refer to the clustering overview for more information and a list of related pages about clustering Confluence.
Consider your options carefully before deciding on a clustered installation While we have tried to make clustering Confluence as easy and administrator-friendly as possible, it is a major architectural change and requires extra planning for deployment and upgrades. Please consider the information below and then consult Atlassian Sales before making your final decision.
On this page: Purpose of this Document Assumed Knowledge General Considerations Server Setup Database Setup Network Setup Staging Environment
Assumed Knowledge
In writing this document, we have assumed that our readers have an in-depth knowledge of the following technical areas: Database Networking Application servers Load balancers
122
Before starting a clustered deployment please read the information on this page carefully, as well as the linked documentation, to assess if you have the assumed knowledge.
General Considerations
What will Confluence Clustered do for you? The points in this section of the page will help you evaluate your reasons for considering a clustered deployment, and then decide whether Confluence Clustered is the right solution for your environment.
Confluence Clustered is designed to scale the number of simultaneously connected users at a much better performance than what a single node can achieve
Confluence Clustered will not improve performance in systems with few users.
Clustering Confluence means that user requests can be served by independent machines. The performance gains are substantial, and have improved a lot further since Confluence 3.0. Clustering is especially great in dealing with spikes to the load, e.g. during certain hours of business. Just note that if rendering a complicated page (e.g. containing many macros or rendering many graphs) takes five seconds on an otherwise idle server, it will not be faster in a clustered environment. Also, the first step when you encounter performance issues is to tune your existing system, make sure you are using the right hardware and have looked at your database.
Confluence Clustered is not designed specifically to provide a high availability solution. General availability is higher in a Confluence cluster than on a single installation, you can for example take one node down for minor maintenance tasks e.g. when adding a new CPU or adding RAM. But you still have to bring down all nodes at the same time for software upgrades. Also there are certain conditions, like loss of network connectivity between nodes ('split brain'), that will result in the cluster shutting itself down. Confluence Clustered offers higher reliability, but not high availability.
Confluence Clustered is not for disaster recovery nor for transparent failover.
If one node crashes, there is no transparent failover for the connected client. Also, our network requirements (see below) make Confluence unsuitable for deployment to different cities or even to different buildings.
Server Setup
The number of supported cluster nodes is limited to four.
Not supported. In theory, you can connect more than four nodes but that is not covered by Atlassian Support.
All cluster nodes must have the same version of OS, application server, etc.
Confluence requires a homogeneous environment. All Confluence cluster nodes must have the same version of the following: Operating system CPU Installed memory Java Application server Note that 'same version' means 'same to the last digit'. For example, Java v1.4.2_16 is not the same as v1.4.2_15 We strongly recommend user to have the same memory configuration (both the JVM and the physical memory) because a cluster uses a replicated cache. A replicated cache requires the same amount of memory on each node in the operating cluster. The memory allocations must be equal.
123
While the details are up to you, we strongly suggest that your servers have at least 4GB of physical RAM. A high number of concurrent users means that a lot of RAM will be consumed. You usually don't need to assign more than 4GB per JVM process, and most of the time even just 1GB or 2GB will be fine, you should just be prepared to fine tune the settings.
Not supported. We strongly discourage you to deploy a production environment of Confluence to virtual servers, and we will not be able to support you when problems arise. When running a Confluence cluster your goal is high capacity and performance, so you should not risk lower performance by virtualising it and sharing a computer with other processes. Many customers who are running Confluence on VMware, or similar virtualisation solutions, experience major performance problems that are extremely hard to pinpoint. Since the problems are not related to Confluence itself, we will not be able to help you.
No additional applications (other than core operating system services) should be running on the same servers as Confluence. Since your goal should be increased capacity and performance, you should not risk this by running any other process on the machine with a Confluence Clustered node. While it may be fine to run JIRA, Confluence and Bamboo on a dedicated Atlassian software server for small installations, it is strongly discouraged for clustering Confluence.
If you plan to migrate to a clustered solution, make sure you are migrating within the same version of Confluence. If you plan to upgrade to a higher version of Confluence, do this before the migration to the clustered version. For example, if you are currently running Confluence 2.9.2, and want to roll out the clustered version of Confluence 3.0, you must first upgrade to Confluence 3.0 and check that everything works fine (e.g. by running and monitoring your production system for a week). Then you are in a good position to migrate to the clustered version.
Database Setup
Run the database on its own physical server.
You are optimising for performance, so you don't want the database to slow down your application servers, or vice versa. In high load scenarios, the database may need to have better hardware than the application servers to be able to handle all requests. You should find out by performing loadtesting.
Attachments must be stored in a database and not the local file system
Storing attachments in the database is the only supported attachment storage configuration for clustering Confluence.
Make sure that you use a supported version of a database server to store Confluence's data.
Please check that your intended database is officially supported by Atlassian Confluence. The load on an average cluster solution is higher than on a single box installation, and it is therefore even more crucial to use the right database vendor and version.
Note that Confluence clustered stores file attachments in the database, and you need an experienced DBA who can monitor and manage the data growth.
Not having an experienced full-time DBA at hand at short notice when entering the realm of high load is dangerous. While small installations of Confluence basically work 'out of the box', anything that involves high load and a lot of database space requires continual monitoring, optimising and fine tuning of the Confluence database. When we ramp up the load on our loadtesting environment, we see that database usage goes up as well. Having powerful hardware in place helps, but if there are queries that become inefficient with you particular load
124
pattern, you need an expert to tune it. As an example, we have seen PostgresSQL switch its internal caching mechanism when a particular table reached a certain size, which resulted in a drop of performance by about 200ms per request. This happened from one second to the other. Being able to troubleshoot and then fix issues like these is important in any enterprise system, but it is even more in a high load scenario.
Network Setup
We recommend hardware load balancers or putting a software loadbalancer onto its on server.
If you use a software load balancer (which is fine except for really extreme installations), it must be deployed on a machine of its own. Running a software load balancer on a cluster node is not supported. If a node unexpectedly got overwhelmed by a spike in load, a load balancer on that node would turn unresponsive. As a result, your whole cluster would be inaccessible even though the other nodes would be available. So using a different server is common practice and common sense.
The Confluence cluster nodes should have a separate physical network (i.e. separate NICs) for inter-server communication. This is the best way of getting 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.
The switch connecting the Confluence cluster nodes must not be a 'smart switch'.
Not supported. Smart switches are not covered by Atlassian Support for Confluence Clustered. Do not use smart switches between cluster nodes. Many problems have been reported and attributed to smart switches. They have a tendency to interrupt broadcast or multicast traffic, thus reliably killing a cluster after a certain amount of time has passed. This makes troubleshooting especially complex and tedious.
If the switch connecting the Confluence cluster nodes is a Cisco switch then it might need additional configuration to support Confluence clustering. Please make sure you find out all the details about your switches before you start the deployment.
It is recommended that the database is on a different physical network from the Confluence server nodes.
Since you want to increase your capacity and performance for high loads, it is recommended to have your database on a different network. Please refer to the recommended topology diagram for more information.
Minimize the latency between the Confluence cluster nodes and the database.
Even though having the nodes and the database on the same physical network usually suffices, you should take the time to explicitly measure network latency, and make sure it is as close to zero as possible.
To facilitate discussion and to ease planning, you should prepare a network diagram like this example of recommended network topology. If you request support with Confluence Clustered, we may ask for your network diagram. We recommend that you create one similar to our example before you proceed with the installation.
You need network support staff available to troubleshoot cluster communication issues.
Setting up a cluster is not trivial. Even small problems in network design will be expanded in a clustered installation. (This is true of any kind of software.) It is absolutely vital that you have dedicated network staff available to track down problems when they arise. A cluster will usually be used by
125
thousands of users, and you don't want to keep them waiting because a network card breaks, or because someone made an undocumented change to the network and you don't have an expert around who can figure it out.
Staging Environment
You need a staging environment that is exactly the same as your production system.
You must be able to test drive any change to the cluster (installing upgrades, installing plugins) and to perform other tests (checking connectivity, debugging problems) on a staging cluster. The staging environment must be: On the same OS, database, and Java version as your production environment. Clustered. If you require support, we may for example ask you to turn off certain third-party plugins. If you can't do this in your production environment and you don't have a staging environment for troubleshooting, we may not be able to help you.
Getting a license for your staging environment Only a technical contact for your commercial/academic license is able to create a Developer license. Atlassian supplies 'developer' licenses which can be used by existing commercial license holders who wish to deploy non-production installations of our software to use in QA/staging environments. Developer licenses are free of charge to commercial license holders and, like our commercial offerings, they include 12 months of updates starting from the date of purchase of the commercial license. If you hold a commercial license, you can obtain a free developer license by following these steps: 1. Log in to your Atlassian account. 2. Under the "Licenses" heading, all of your licenses will be displayed. Click the plus sign next to a license to view its details. 3. Click the 'View Developer License' link in the bottom right corner of the license detail panel, below your commercial license key.
Related Topics Page: Cluster safety mechanism Page: How do I supress cluster warning message in confluence? Page: Technical Overview of Clustering in Confluence Page: Confluence Clustering Overview Page: Changing Datasources Manually in a Cluster Page: Viewing and Editing License Details Page: Cluster Troubleshooting Page: Confluence Cluster Installation Page: Apache and Tomcat load balancing Page: Cluster Administration page Page: Recommended network topology Page: Upgrading a Confluence Cluster
126
Confluence Cookies Configuring Secure Administrator Sessions Using Fail2Ban to limit login attempts Securing Confluence with Apache Using Apache to limit access to the Confluence administration interface Enabling or Disabling Public Signup Managing External Referrers Excluding external referrers Hiding external referrers Ignoring External Referrers Best Practices for Configuring Confluence Security Hiding the People Directory Configuring Captcha for Spam Prevention Hiding External Links From Search Engines Configuring Captcha for Failed Logins Configuring XSRF Protection User Email Visibility Anonymous Access to Remote API Running Confluence Over SSL or HTTPS Connecting to LDAP or JIRA or Other Services via SSL Configuring RSS Feeds
Confluence Cookies
Confluence uses Seraph, an open source framework, for HTTP cookie authentication.
Cookies
Confluence uses two cookies: The JSESSIONID cookie is created by the application server and used for session tracking purposes. The 'remember me' cookie, seraph.confluence, is generated by Confluence when the user selects the 'Remember me' checkbox on the login page. You can read about cookies on the Wikipedia page.
127
generates this cookie when the user selects the 'Remember me' checkbox on the login page.
Notes
The autocomplete that happens when a user logs in is a browser feature, not a Confluence feature. Confluence cannot enable or disable the autocompletion.
RELATED TOPICS
128
Confluence 4.0 Documentation 1. Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click 'Security Configuration' in the 'Security' section. The 'Edit Security Configuration' screen will be displayed. 3. Click the 'Edit' link. To disable secure administrator sessions (i.e. administrators will not be required to log into a secure session to access the administration console), uncheck the 'Enable' checkbox next to 'Secure administrator sessions'. To change the timeout for secure administrator sessions, update the value in textbox next to 'minutes before invalidation'. The default timeout for a secure administration session is 10 minutes. 4. Click the 'Save' button.
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 Recognised 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. 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.
129
Prerequisites
Requires Python 2.4 or higher to be installed Needs a specific file to follow, which means your Apache instance needs to log your Confluence access to a known logfile. You should adjust the configuration below appropriately.
How to set it up
This list is a skeletal version of the instructions There's an RPM available for RHEL on the download page, but you can also download the source and set it up manually Its configuration files go into /etc/fail2ban The generic, default configuration goes into .conf files (fail2ban.conf and jail.conf). Don't change these, as it makes upgrading difficult. Overrides to the generic configuration go into .local files corresponding to the .conf files. These only need to contain the specific settings you want overridden, which helps maintainability. Filters go into filter.d this is where you define regexps, each going into its own file Actions go into action.d you probably won't need to add one, but it's handy to know what's available "jails" are a configuration unit that specify one regexp to check, and one or more actions to trigger when the threshold is reached, plus the threshold settings (e.g. more than 3 matches in 60 seconds causes that address to be blocked for 600 seconds) Jails are defined in jail.conf and jail.local. Don't forget the enabled setting for each one it can be as bad to have the wrong ones enabled as to have the right ones disabled.
Running Fail2Ban
Use /etc/init.d/fail2ban {start|stop|status} for the obvious operations Use fail2ban-client -d to get it to dump its current configuration to STDOUT. Very useful for troubleshooting. Mind the CPU usage; it can soak up resources pretty quickly on a busy site, even with simple regexp It can log either to syslog or a file, whichever suits your needs better
Common Configuration
jail.local
# 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
[apache-shorewall] enabled = true filter = cac-login action = shorewall logpath = /var/log/httpd/confluence-access.log bantime = 600 maxretry = 3 findtime = 60 backend = polling
130
filter.d/confluence-login.conf
Further Information
Running Confluence behind Apache
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
In your Apache Virtual Host, add the following lines to restrict the administration actions to the Systems Administrator:
This configuration assumes you've installed Confluence under '/confluence'. If you have installed under '/' or elsewhere, adjust the paths accordingly.
131
<Location /confluence/admin> Include sysadmin_ips_only.conf </Location> <Location /confluence/plugins/servlet/oauth/consumers/list> Include sysadmin_ips_only.conf </Location> <Location /confluence/plugins/servlet/oauth/view-consumer-info> Include sysadmin_ips_only.conf </Location> <Location /confluence/plugins/servlet/oauth/service-providers/list> Include sysadmin_ips_only.conf </Location> <Location /confluence/plugins/servlet/oauth/service-providers/add> Include sysadmin_ips_only.conf </Location> <Location /confluence/plugins/servlet/oauth/consumers/add> Include sysadmin_ips_only.conf </Location> <Location /confluence/plugins/servlet/oauth/consumers/add-manually> Include sysadmin_ips_only.conf </Location> <Location /confluence/plugins/servlet/oauth/update-consumer-info> Include sysadmin_ips_only.conf </Location> <Location /confluence/pages/templates/listpagetemplates.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/pages/templates/createpagetemplate.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/spacepermissions.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/pages/listpermissionpages.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/removespace.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/importmbox.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/viewmailaccounts.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/addmailaccount.action?> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/importpages.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/flyingpdf/flyingpdf.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/exportspacehtml.action> Include sysadmin_ips_only.conf </Location> <Location /confluence/spaces/exportspacexml.action> Include sysadmin_ips_only.conf </Location>
132
To enable or disable public signup: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'Security Configuration' in the left-hand panel. This will display the 'Security Configuration' screen. Click 'Edit'. Tick the 'Public Signup' checkbox to enable Public Signup. Untick the checkbox to disable it. Click 'Save'.
2. 3. 4. 5.
Related Topics
Disabling the Built-In User Management User Management Configuring Confluence Security
133
Page: Configuring Captcha for Failed Logins (Confluence 4.1) Page: Running Confluence Over SSL or HTTPS (Confluence 4.1) Page: Excluding external referrers (Confluence 4.1) Page: Configuring the Administrator Contact Page (Confluence 4.1) Page: Hiding the People Directory (Confluence 4.1) Page: User Email Visibility (Confluence 4.1) Page: Anonymous Access to Remote API (Confluence 4.1) Page: Enabling or Disabling Public Signup (Confluence 4.1) Page: Configuring Captcha for Spam Prevention (Confluence 4.1) Page: Hiding external referrers (Confluence 4.1) Page: Ignoring External Referrers (Confluence 4.1) Page: Managing External Referrers (Confluence 4.1) Page: Hiding External Links From Search Engines (Confluence 4.1)
134
Page: Configuring Captcha for Failed Logins Page: Running Confluence Over SSL or HTTPS Page: Excluding external referrers Page: Configuring the Administrator Contact Page Page: Hiding the People Directory Page: User Email Visibility Page: Anonymous Access to Remote API
135
Page: Enabling or Disabling Public Signup Page: Configuring Captcha for Spam Prevention Page: Hiding external referrers Page: Ignoring External Referrers Page: Managing External Referrers Page: Hiding External Links From Search Engines
Related Topics
Page: Configuring Captcha for Failed Logins Page: Running Confluence Over SSL or HTTPS Page: Excluding external referrers Page: Configuring the Administrator Contact Page Page: Hiding the People Directory Page: User Email Visibility Page: Anonymous Access to Remote API Page: Enabling or Disabling Public Signup Page: Configuring Captcha for Spam Prevention Page: Hiding external referrers Page: Ignoring External Referrers Page: Managing External Referrers Page: Hiding External Links From Search Engines
136
Related Topics
Page: Configuring Captcha for Failed Logins Page: Running Confluence Over SSL or HTTPS Page: Excluding external referrers Page: Configuring the Administrator Contact Page Page: Hiding the People Directory Page: User Email Visibility Page: Anonymous Access to Remote API Page: Enabling or Disabling Public Signup Page: Configuring Captcha for Spam Prevention Page: Hiding external referrers Page: Ignoring External Referrers Page: Managing External Referrers Page: Hiding External Links From Search Engines
137
-Dconfluence.disable.peopledirectory.anonymous=true
-Dconfluence.disable.peopledirectory.all=true
138
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 Apache webserver in front of confluence and redirect requests to this URL. To remove the link on the dashboard: Procedure for Confluence 2.5.2 to 2.9.x. only This only applies to Confluence 2.5.2 to 2.9.x. Confluence 2.10.x or later only needs to configure system properties using the above. Edit the <confluence-install>/confluence/decorators/global.vmd: Comment out line 37:
<!-<img src="$req.contextPath/images/icons/people_directory_32.gif" align='absmiddle' height="32" width="32"> <b><a class="fontSizeDefault" href="$req.contextPath/peopledirectory.action"> $action.getText("people.directory.title")</a></b><span class="smalltext"> $action.getText("people.directory.description")</span><br> -->
Related Topics
Page: Configuring Captcha for Failed Logins Page: Running Confluence Over SSL or HTTPS Page: Excluding external referrers Page: Configuring the Administrator Contact Page Page: Hiding the People Directory Page: User Email Visibility Page: Anonymous Access to Remote API Page: Enabling or Disabling Public Signup Page: Configuring Captcha for Spam Prevention Page: Hiding external referrers Page: Ignoring External Referrers Page: Managing External Referrers Page: Hiding External Links From Search Engines
139
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 the technical term for a test that can distinguish a human being from an automated agent such as a web spider or robot. You can read more about Captcha on Wikipedia. When Captcha is switched on, users will need to recognise 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 above: Example of a Captcha test You can configure Confluence to enforce Captcha for certain types of users. You can exempt logged-in users (they will have completed a Captcha when they signed up) or members of particular groups. By default, Captcha for spam prevention is disabled. If you enable it, the default is that Captcha for spam prevention will apply to anonymous users only. Only anonymous users will have to perform the Captcha test when creating comments or editing pages. Captcha images will not be shown to logged-in users. To enable Captcha for spam prevention in Confluence: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'Spam Prevention' from the 'Configuration' menu on the left. Turn on Captcha by clicking the 'ON' link. 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 the '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. Click the 'Save' button.
2. 3. 4.
5.
Related Topics
Page: Configuring Captcha for Failed Logins Page: Running Confluence Over SSL or HTTPS Page: Excluding external referrers Page: Configuring the Administrator Contact Page Page: Hiding the People Directory Page: User Email Visibility Page: Anonymous Access to Remote API Page: Enabling or Disabling Public Signup Page: Configuring Captcha for Spam Prevention Page: Hiding external referrers Page: Ignoring External Referrers Page: Managing External Referrers Page: Hiding External Links From Search Engines
140
To hide external links from search engines: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click 'Security Configuration' in the left panel. This will display the 'Security Configuration' screen. Click 'Edit'. Check the 'Hide External Links From Search Engines' checkbox. Click the 'Save' button.
2. 3. 4. 5.
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.
Related Topics
Page: Configuring Captcha for Failed Logins Page: Running Confluence Over SSL or HTTPS Page: Excluding external referrers Page: Configuring the Administrator Contact Page Page: Hiding the People Directory Page: User Email Visibility Page: Anonymous Access to Remote API Page: Enabling or Disabling Public Signup Page: Configuring Captcha for Spam Prevention Page: Hiding external referrers Page: Ignoring External Referrers Page: Managing External Referrers Page: Hiding External Links From Search Engines
141
'Captcha' is the technical term for a test that can distinguish a human being from an automated agent such as a web spider or robot. You can read more about Captcha on Wikipedia. When Captcha is activated, users will need to recognise 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.
2. 3. 4.
5. 6.
Notes
Disabling all password confirmation requests, including Captcha on login. Confluence installations that use a custom
142
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 administrative actions, change of email address and Captcha for failed logins. See Recognised System Properties.
Related Topics
To configure XSRF protection: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click 'Security Configuration' in the 'Security' section. The 'Edit Security Configuration' screen will be displayed. Click the 'Edit' link. To disable XSRF protection, uncheck the 'Add Comments' checkbox in the 'XSRF Protection' section. Click the 'Save' button.
2. 3. 4. 5.
Confluence provides three options for email address privacy which can be configured by a Confluence administrator from the Administration Console: Public: email addresses are displayed publicly. Masked: email addresses are still displayed publicly, but masked in such a way to make it harder for spam-bots to harvest them. Only visible to site administrators: only Confluence administrators can see the email addresses. Note that, if you select this option, email addresses will not be available in the 'User Search' popup (e.g. when setting Page Restrictions).
To configure user email visibility: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'Security Configuration' in the left-hand panel. The 'Security Configuration' screen will be displayed. Click 'Edit'. The fields on the 'Security Configuration' screen will be editable. Select one of the options from the 'User email visibility' dropdown: 'public', 'masked', or 'only visible to site administrators'. Click the 'Save' button.
2. 3. 4. 5.
Page: Configuring Captcha for Failed Logins Page: Running Confluence Over SSL or HTTPS Page: Excluding external referrers Page: Configuring the Administrator Contact Page Page: Hiding the People Directory Page: User Email Visibility Page: Anonymous Access to Remote API Page: Enabling or Disabling Public Signup Page: Configuring Captcha for Spam Prevention Page: Hiding external referrers Page: Ignoring External Referrers Page: Managing External Referrers Page: Hiding External Links From Search Engines
2. 3. 4. 5.
Click 'Security Configuration' in the left panel. The 'Security Configuration' screen will be displayed. Click 'Edit'. The fields on the 'Security Configuration' screen will now be editable. Uncheck the 'Anonymous Access to API' checkbox. Click the 'Save' button.
Related Topics
Page: Configuring Captcha for Failed Logins Page: Running Confluence Over SSL or HTTPS Page: Excluding external referrers Page: Configuring the Administrator Contact Page Page: Hiding the People Directory Page: User Email Visibility Page: Anonymous Access to Remote API Page: Enabling or Disabling Public Signup Page: Configuring Captcha for Spam Prevention Page: Hiding external referrers Page: Ignoring External Referrers Page: Managing External Referrers Page: Hiding External Links From Search Engines
On this page: Step 1. Create or Request a New SSL Certificate Step 2. Modify the Server Configuration File in your Confluence Installation Step 3. Specify the Location of your Certificate Step 4. Change your Confluence Base URL to HTTPS Step 5. Add a Security Constraint to Cause Redirect of All URLs to HTTPS Notes Troubleshooting
145
2. When asked for a password: Specify the password you want to use for the certificate (private key). Note that the password text will not appear as you type it. Make a note of the password you choose, because you will need it in the next step when editing the configuration file. The default password is 'changeit'. 3. Follow the prompts to specify your name, organisation and location. This information is used to construct the X.500 Distinguished Name (DN) of the entity, such as: CN=Java Duke, OU=Java Software Division, O=Sun Microsystems Inc, C=US 4. Enter 'y' to confirm the details. 5. When asked for the password for 'tomcat' (the alias you entered in the keytool command above), press the 'Enter' key. This specifies that your keystore entry will have the same password as your private key. You MUST use the same password here as was used for the keystore password itself. This is a restriction of the Tomcat implementation. 6. You certificate is now ready. Go to step 2 below.
keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME>
3. Submit the generated file called certreq.csr to your chosen certificate authority. Refer to the documentation on the CA's website to find out how to do this. 4. The CA will send you a certificate. 5. Import the new certificate into your local keystore:
146
<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" SSLEnabled="true" URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>"/>
3. Replace the text <MY_CERTIFICATE_PASSWORD> with the password you specified for your certificate. 4. Make sure that the attribute-value pair SSLEnabled="true" is part of the Connector element, as shown above. If this attribute is not present, attempts to access Confluence will time out. 5. Save the server configuration file.
<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" SSLEnabled="true" URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>" keystoreFile="<MY_CERTIFICATE_LOCATION>"/>
3. Replace the text <MY_CERTIFICATE_LOCATION> with the path to your certificate, including the path and the name of the .keystore file. 4. Save the server configuration file.
147
<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. Protection for logins only or for individual spaces: As of Confluence 3.0, Atlassian does not support HTTPS for logins only or for specific pages. We support only site-wide HTTPS. To see the reasoning behind this decision, please see CONF-18120 and CONF-4116.
Troubleshooting
Check the Confluence knowledge base articles on troubleshooting SSL. If any of your users will access Confluence from Internet Explorer 7 on Vista, please note the following additional points when using Java's keytoolutility: Make sure that you specify the -keyalg RSA option, as shown in the example of the keytool command above. The default is the SHA1 algorithm, which results in an error 'Internet Explorer cannot display the webpage' on IE7 on Vista. You may also need to specify the -sigalg MD5withRSA option. Otherwise, SHA1 will be used even if you specify the -keyalg RSA option. See this Atlassian blogpost for more information. 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_INSTALLATION>/conf/server.xml and add the following line within the <Context ... />element:
Related Topics
SSL Configuration HOW-TO in the Apache Tomcat 6.0 documentation SSL Configuration HOW-TO in the Apache Tomcat 5.5 documentation keytool - Key and Certificate Management Tool in the Java SE documentation Connecting to LDAP or JIRA or Other Services via SSL Supported Platforms
148
keytool -import -alias serverCert -file RootCert.crt -keystore %JAVA_HOME%/jre/lib/security/cacerts (Windows) keytool -import -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 -import -alias ldapCert -file JIRAorLDAPServer.crt -keystore %JAVA_HOME%/jre/lib/security/cacerts (Windows) keytool -import -alias ldapCert -file JIRAorLDAPServer.crt -keystore $JAVA_HOME/jre/lib/security/cacerts (Linux/Unix/Mac)
3. Edit the file in your Confluence installation directory, { confluence-installation}\confluence\WEB-INF\classes\atlassian-user.xml. Change the value of securityProtocolfrom "plain" to "ssl":
<securityProtocol>ssl</securityProtocol>
Switch the LDAP connection to the SSL port, if it is different from the default LDAP port. If you are using the most common LDAPS port, set:
<port>636</port>
The keytool will ask you for a password. The default password is 'changeit' without the quotes. 4. 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)
5. Ensure that you have updated JAVA_OPTS to specify the path to the keystore, as specified in Connecting to SSL services, before restarting Tomcat/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 sun.security.provider.certpath.SunCertPathBuilderException SSL troubleshooting articles
Related Topics
149
Configure Web Proxy Support for Confluence Running Confluence Over SSL or HTTPS
To configure RSS feeds: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click Security Configuration in the left panel. The 'Edit Security Configuration' screen will be displayed. Click Edit. Edit the value for Maximum RSS Items. The default value is 200. Edit the value for RSS timeout. Click Save.
2. 3. 4. 5. 6.
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.
Related Topics
150
Customising the eMail Templates Customising the Login Page Themes Overview Applying a Theme to a Site Customising the Left Navigation Theme Modifying Look and Feel (for themes) Configuring the Theme Plugin Including Cascading Stylesheets in Themes Creating a Theme
RELATED TOPICS
Modifying Confluence Interface Text Site Configuration
Then press Enter. This will then cause each element of the user interface to display its special key name while Confluence is still in an interactive mode. This makes it easier to find the essential context for each key, which can then be searched on http://translations.atlassian.com where you can enter an appropriate translation for your custom language pack. The key names are displayed with a "lightning bolt" graphic between elements of the names. For example, the buttons will show up with elements shown like so:
151
For example, for the Browse button, the associated key system.space.menu can be found on http://translations.atlassian.com, allowing you to write a better translation for the term Browse, being able to see the full context of where the UI element belongs and what it means to the user. To turn off the translation view, add this code to the end of the Confluence URL:
RELATED TOPICS
Editing User Settings Recognised System Properties Configuring Indexing Language Installing a Language Pack
You can view and edit these decorators from within Confluence: they are available from the "Layouts" option on the site's Administration menu. Changes to the decorators will affect all spaces hosted on that Confluence installation. The decorator that is used to draw Confluence's administrative pages can not be edited from within Confluence. This means that if you make some editing mistake that renders the rest of the site unuseable, the administrative pages should still be available for you to fix the template.
152
<html> <head> <title>$title - Confluence</title> #standardHeader() </head> <body onload="placeFocus()"> <div id="Content"> <table border="0" cellpadding="0" cellspacing="0" width="100%"> <tr> <td width="60%" rowspan=2 class="logocell">#pagetitle("spacenametitle")</td> <td width="40%" align="right" valign="top">#globalnavbar("table")</td> </tr> #if ($setup.isSetupComplete()) <tr> <td align=right valign="bottom"> #usernavbar() #printableicon() #helpicon() </td> </tr> #end </table> #breadcrumbsAndSearch() <table border="0" cellpadding="5" cellspacing="0" width="100%"><tr><td> <table border="0" cellpadding="0" cellspacing="0" width="100%"><tr> <td valign="top" class="pagebody"> The "toolbar-style" page operations #if ($page.getProperty("page.operations")) <table align="right" class="toolbar"><tr><td> $page.getProperty("page.operations") </td></tr></table> #end #if ($page.getProperty("page.surtitle")) $page.getProperty("page.surtitle") #end #if (!$page.getProperty("page.no-page-header")) <div class="pageheader"> <span class="pagetitle">$title</span> </div> #end $body </td> #parse ("/decorators/includes/complete_footer.vmd")
## ## ## ## ## ##
When you insert this into the right section of the template and hit save, visitors to the site will see the logo at the top of each page. Note, the administrative pages will be unaffected: you will have to go to the dashboard or to a space to see the changes you have made.
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.
153
Here's how you can customise the look and feel of your site: Colour Scheme : Change the colour scheme of the user interface. Layouts : Edit how the controls are laid out in the site. This does not change the actual page layouts but the way the surrounding controls appear in the page. Themes : Use themes for advanced layout customisation.
RELATED TOPICS
Page: Customising Colour Schemes Page: Customising Look and Feel Overview Page: Global Templates Page: Upgrading Custom Layouts Page: Customising a Specific Page Page: Customising Layouts Page: Editing the Footer Page: Working With Decorator Macros Page: Adding a Site-Wide Banner
154
To change the site's colour scheme: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Colour Scheme' in the left-hand panel. This will bring up a new screen. See screenshot below. 3. Click 'Edit'. Enter standard HTML/CSS2 colour codes, or use the colour-picker to choose a new colour from the palette provided. Any changes you make will immediately be reflected across the Confluence installation. The colour scheme applies to the following UI elements: Top Bar - the bar across the top of the page that contains the breadcrumbs Tab Navigation Background - the background colour of the tab navigation menus Tab Navigation Text - the text of the tab navigation menus Breadcrumbs Text - the breadcrumbs text in the top bar of the page Space Name Text - the text of the current space name located above the page title Heading Text - all heading tags throughout the space. Links - all links throughout the space. Borders and Dividers - table borders and dividing lines. Tab Navigation Background Highlight - the background colour of the tab navigation menu when highlighted Tab Navigation Text Highlight - the text of the tab navigation menu when highlighted Top Bar Menu Selected Background - the background colour of the top bar drop down menu when selected Top Bar Menu Item - the text colour of the menu items in the top bar drop down menu Page Menu Selected Background - the background colour of the drop down page menu when selected Page Menu Item Text - the text of the menu items in the drop down page menu Menu Item Selected Background - the background colour of the menu item when selected (applies to both the top bar and page drop down menus) Menu Item Selected Text - the text colour of the menu item when selected (applies to both the top bar and page drop down menus) Please note that some UI elements are specific to the default theme and may not take effect for other themes.
155
If you mess things up, just click the 'Reset' button and then try again.
Related Topics
Page: Customising Colour Schemes Page: Customising Look and Feel Overview Page: Global Templates Page: Upgrading Custom Layouts Page: Customising a Specific Page Page: Customising Layouts Page: Editing the Footer Page: Working With Decorator Macros Page: Adding a Site-Wide Banner
Customising Layouts
Confluence's look and feel can be modified by editing the 'decorator' (layout) files. Modifying these files allows you to change the look and feel of: The Confluence site as a whole, which includes all spaces within the Confluence site. An individual space within the Confluence site.
156
This page tells you how to customise the layout files for your Confluence site as a whole. These customisations: Modify the default 'decorator' files of each space in your site Are reflected in every space unless the space's own equivalent layout files have been customised. You require System Administrator permissions to perform these customisations. You can also customise the layout files for a given space only. For more information, refer to Customising Layouts for a Space. Space layout file customisations override the equivalent site layout file customisations.
If you modify the look and feel of Confluence by following these instructions, you will need to update your customisations when upgrading Confluence. The more dramatic the customisations are, the harder it will be to reapply your changes when upgrading. Please take this into account before proceeding with your customisation. For more information on updating your customisations, please refer to Upgrading Custom Layouts.
Confluence is built on top of the open source SiteMesh library, a web-page layout system. Read more on the SiteMesh website. 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. You can learn more from the Velocity User Guide. Once you are familiar with Velocity, you can edit the decorator files to personalise the appearance of Confluence. The decorator files are grouped into: Site layouts : These are used to define the controls that surround each page in the site. For example, the header and the footer. Content layouts : These control the appearance of content such as pages and blog posts: they don't 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. If you are using Confluence to generate a static website, for example, you will need to modify these layouts.
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.
157
In Confluence 2.6 and later, some Velocity files are located inside the Confluence JAR file that can be found at confluence/WEB-INF/lib/confluence-x.x.x.jar. To override files inside this JAR (which you can open with any ZIP tool like WinZip or 7-Zip), put your customised file in the same directory structure under confluence/WEB-INF/classes/. For example, the file templates/macros/alphaindex.vm inside confluence.jar can be replace by putting your custom file in WEB-INF/classes/templates/macros/alphaindex.vm. You do not need to modify the file inside the JAR. See also Editing Files within JAR Archives.
RELATED TOPICS
Page: Customising Colour Schemes Page: Customising Look and Feel Overview Page: Global Templates Page: Upgrading Custom Layouts Page: Customising a Specific Page Page: Customising Layouts Page: Editing the Footer Page: Working With Decorator Macros Page: Adding a Site-Wide Banner Velocity Template Overview Basic Introduction to Velocity
158
Follow the instructions below to add the navigation sidebar to your Confluence space.
Step 1. Create the TreeNavigation Page
First, you will create a Confluence page containing the pagetree macro. This is just a normal Confluence page. The only slight oddity is that it should reside at the root of your space, instead of under the space's home page. Follow these instructions: 1. Go to the 'Space Pages' view for the current space. To do this: Go to a page in the space and choose Browse > Pages. You are now at the 'root' level of your space. The 'root' level contains pages that are added above the space's home page, not as children of the home page. 2. At the root level of the space, create a page named 'TreeNavigation'. 3. On the page, insert the following text:
{pagetree}
4. Now decide if you want to add extra functionality to your page tree. By default, using the code above, the page tree will use the home page of the space as its root. You can choose to: Specify a different root for your page tree. Add a search box at the top of the tree. Allow the viewers to expand and collapse the whole tree. Control other aspects of the display. For more information, read about the Pagetree macro.
Now you will change the page layout on your space, to include the above page on the left of every web page displayed. 1. Choose Browse > Space Admin. Space Admin is displayed only if you are a space administrator for that space or you are a Confluence system administrator. 2. Make sure the Confluence Default theme is selected from the 'Themes' menu. 3. Click 'Layout' under the 'Look and Feel' section. 'Layout' is only displayed if you are a system administrator on the Confluence site. 4. Click 'Create Custom' under the 'Page Layout' section. 5. In the layout, locate the 'VIEW' section, and find this code:
159
#if ($action.isPrintableVersion() == false) <style> .spacetree * ul{ padding-left:0px; margin-left: 0px; } .spacetree * li{ margin-left: 5px; padding-left:5px; } </style> <table cellspacing="2" cellpadding="5"> <tr> <td valign="top" align="left" width="22%" bgcolor="#F9F9F9" class="noprint"> <div class="tabletitle">Table of Contents</div> <div class="spacetree"> #includePage($helper.spaceKey "TreeNavigation") </div> </td> <td valign="top" align="left" width="78%" class="pagecontent"> <div class="wiki-content"> $body </div> </td> </tr> </table> #else <div class="wiki-content"> $body </div> #end
7. If you want to, you can change the table title in the above code from 'Table of Contents' to something else. For example, it might say 'Confluence Documentation'. 8. Save the updated layout.
160
The '*All Versions*' section in the navigation bar A number of people have asked how we created the 'All Versions' section at the top of our navigation side bar. Take a look at Adding an All Versions Section to your Navigation Bar.
RELATED TOPICS Configuring the Documentation Theme Customising Layouts Upgrading Custom Layouts Example Confluence Designs
This is how we added the 'All Versions' section to the sidebar: For each product (Confluence, Crowd, Bamboo, etc) there is a page in the Inclusions Library of the ALLDOC space. The page lists all the versions of that product's documentation, linking to the relevant spaces. For example, here is the page for Confluence and the page for Crowd. We put the 'all versions' page in ALLDOC because the page is used in a number of different spaces, via the {include} macro. For example, the 'all versions' page may be included: In every documentation space (each version) for the product concerned, such as DOC, CONF29, CONF28, CROWD, CROWD013, CROWD012, etc. In the Enterprise Hosting doc space. As a panel on the documentation home page, as shown in the 'All Versions' panel of the above screenshot, as well as in the left-hand navigation bar. Any other places where useful. In each documentation space, there is a page called 'TreeNavigationVersions' like this one or this one, which copies in the content of the above 'all versions' page. For each documentation space, the space's page layout now includes two pages instead of just one: The 'TreeNavigation' page, as already described on the page above. The new 'TreeNavigationVersions' page. Here's the relevant section of our page layout as it is currently for the Confluence documentation (DOC) space:
161
#if ($action.isPrintableVersion() == false) <style> .spacetree * ul{ padding-left:0px; margin-left: 0px; } .spacetree * li{ margin-left: 5px; padding-left:5px; } </style> <table cellspacing="2" cellpadding="5"> <tr> <td valign="top" align="left" width="30%" bgcolor="#eeecec" class="noprint"> <div class="tabletitle">All Versions</div> <div class="spacetree"> #includePage($helper.spaceKey "TreeNavigationVersions") </div> <div class="tabletitle">Confluence 2.10 Documentation</div> <div class="spacetree"> #includePage($helper.spaceKey "TreeNavigation") </div> </td> <td valign="top" align="left" width="70%" class="pagecontent"> <div class="wiki-content"> $body </div> </td> </tr> </table> #else <div class="wiki-content"> $body </div> #end
Another question we are asked is how we group the content of the included page under a collapsible control. We use the Expand macro. The details are on the Expand macro's documentation page.
Related Topics
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 customisations to the new default layouts.
162
This method is handy to use if you have: Many spaces with space layout customisations, or Do not have an independent record of your site or space layout customisations.
Before Confluence 2.3, custom layouts are stored in the velocity directory within your Confluence home directory tree. You can open these files in any text editor. In Confluence 2.3 and later, 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.
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 customisations: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'Layouts' under 'Look and Feel' in the left-hand navigation panel. The decorators are grouped under Site, Content and Export layouts. Ensure you have all your customisations available (preferably in a form which can be copied and pasted). Click 'Reset Default' next to the layout whose customisations need to be reapplied. Click 'Create Custom' next to the same layout and reapply your customisations (by copying and pasting them) into the appropriate locations within the new default layout. Click the 'Save' button. Repeat this procedure from step 4 for each layout whose customisations need to be reapplied.
2. 3. 4. 5. 6. 7.
If you have made space-specific layout customisations: 1. Visit any page in the relevant space. 2. Choose Browse > Space Admin. Space Admin is displayed only if you are a space administrator for that space or you are a Confluence system administrator. 3. Select 'Layout' under 'Look and Feel' in the left-hand navigation panel. The decorators are grouped under Site, Content and Export layouts. 4. Ensure you have all your customisations available (preferably in a form which can be copied and pasted). 5. Click 'Reset Default' next to the layout whose customisations need to be reapplied. 6. Click 'Create Custom' next to the same layout and reapply your customisations (by copying and pasting them) into the appropriate
163
Confluence 4.0 Documentation 6. locations within the new default layout. 7. Click the 'Save' button. 8. Repeat this procedure from step 5 for each layout whose customisations need to be reapplied.
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. For Confluence 2.6, the velocity.properties file is available in the confluence-2.6.0.jar file. 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. 2. 3. 4. 5. 6. 7. Stop Confluence. Make a backup copy of the jar file. Un-jar the file Locate and edit the appropriate file that you wish to modify. Re-jar the confluence-2.6.0.jar file. Relocate the jar file to the appropriate directory. Restart Confluence.
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.
Global Templates
A template is a predefined page that can be used as a prototype when creating new pages. Templates are useful for giving pages a common style or format. You can use regular Confluence markup to create the content of your template. You can also use special markup to define form fields that the author will fill in when creating the page. Global templates are defined by Confluence administrators and are available in every space across the Confluence site. To add a global template: 1. Go to the Global Templates option in the Confluence Administration Console, as follows: a. Choose Browse > Confluence Admin. b. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. c. Select Global Templates in the left-hand panel. d. Click Add New Global Template. 2. Click Add New Global Template. 3. Enter a name for your template in the Name box and an optional description in the Description box. 4. Using regular wiki markup and form field markup (if you are using forms), enter content in the text-entry box as you would in any other Confluence page. 5. Click Edit next to Labels if you want to use labels to categorise information. Add your labels. These labels will be included in all pages created using this template. 6. Preview and click Save. Screenshot: A template as used to create a page
Related Topics
164
Importing Templates
A template is a predefined page that can be used as a prototype when creating new pages. Templates are useful for giving pages a common style or format. You can use regular Confluence markup to create the content of your template. You can also use special markup to define form fields that the author will fill in when creating the page. Confluence ships with a number of templates, including the 'Charts', 'Document List' and 'Meeting Notes' templates. These templates are not available for use by default. However, if you have the appropriate permissions to access the Administration Console, you can import any of these templates to be used globally or within a specific space. In addition, you can download additional template bundles from the Atlassian Plugin Exchange and then make them available by importing them. On this page: Step 1. Check the Templates Installed on your Confluence Site Step 2. (Optional) Upload Additional Templates from the Atlassian Plugin Exchange Step 3. Import a Template to Make it Available to Users Notes
Quick guide to importing a template 1. 2. 3. 4. Go to the 'Confluence Administration Console' and click Import Templates. Select the templates that you want to import. Choose which space to import the templates to, or whether to import them as global templates. Click Import.
Step 2. (Optional) Upload Additional Templates from the Atlassian Plugin Exchange
Additional templates are available as plugins, known as template packages. Follow the steps below if you want to add template packagess to your site that were not shipped with your Confluence installation. Before installing a plugin into your Confluence site, please check the plugin's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on plugin support. To upload more templates: 1. Go to the Atlassian Plugin Exchange and download the template bundle that you need. 2. Log in to Confluence as a System Administrator or Confluence Administrator. 3. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 4. Select 'Plugins' in the left-hand panel. 5. The 'Plugins' screen will appear. Select the 'Install' tab. 6. Click 'Upload Plugin', browse to find the template bundle file that you downloaded and upload it to Confluence.
2. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 3. Select 'Import Templates' in the left-hand panel. The 'Import Templates' screen will appear, listing the template packages installed on your Confluence instance (for example, 'Default Templates Package') and the templates included in each package. 4. Select the templates to be imported by ticking the checkboxes next to the relevant template names. You can view a preview of the template by clicking the template name. 5. Select the import destination for the templates in the 'Import To' dropdown. If you want the templates to be available to only a specific space, select the name of the space, otherwise select 'Global Templates' to make the templates available to all spaces. 6. Click the 'Import' button to import the selected templates.
Notes
Known issue importing templates from multiple template bundles. There is a known issue preventing templates from being imported when multiple template bundles are available. Please read this KB article for further information. Building your own custom template bundles. These are built as plugins and deployed to your Confluence instance. You can then import the templates from your custom template bundle, as described on this page. Read Creating A Template Bundle for instructions. Please note, you will need some programming knowledge to develop a custom template bundle.
166
Duplicate template names. If a template with the same name already exists on import, a duplicate template of the same name will be created. You will need to check each template and rename manually. Removing the template. Removing the plugin that contains a template will not remove the template from your Confluence site if you have already imported it. You will need to remove it manually from the administration console or space.
RELATED TOPICS
Working with Templates Editing a template Removing a Template Browsing a space Working with Pages
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.
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
Common Modifications
Rename 'Dashboard' by searching for Dashboard. To change "Dashboard" to "My Portal", change dashboard.name=Dashboard to dashboard.name=My Portal
167
Common Modifications
Task Search For Dashboard Notes
Rename 'Dashboard'
The dashboard.name parameter has the name. To change 'Dashboard' to 'My Portal', change dashboard.name=Dashboard to dashboard.name=My Portal and update any other occurrences of the word 'Dashboard' in the instance The login.instructions parameter has the "Enter your account details below to login to Confluence" text
login.
#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.
Macro #breadcrumbs()
Usage Draws the "You are here" breadcrumbs list, like the one found above the page name in the default template. Includes a confluence page with the specified title. If you have 2 or more pages with the same title across multiple spaces, this macro will include the page belonging to the space you are currently viewing. Inserts a search box into the page, like the one to the far right of the breadcrumbs in the default template. Draws the global navigation bar, as found in the top right-hand corner of the default template. The navigation bar can be displayed in two modes: Displays the navigation bar in its default mode: drawn as a table of links with coloured backgrounds and mouse-over effects.
#includePage(pageTitle)
#searchbox()
#globalnavbar(type)
#globalnavbar("table")
168
#globalnavbar("text")
#usernavbar()
Draws the user-specific navigation-bar. This bar contains the links to the user's profile and history, or to the login and signup pages if the user is not logged in.
#helpicon()
Draws the
#printableicon()
On pages where a printable version is available, draws the printable version of the page. Otherwise, draws nothing
#pagetitle(class)
When you are viewing a page in a Confluence space, draws the name of the space that page is in. Otherwise, writes the word "CONFLUENCE".The "class" argument is the CSS class that the title should be drawn in. Unless you have customised your Confluence installation's CSS file, you should call this with "spacenametitle" as the class: #pagetitle("spacenametitle") Writes out the "Powered by Confluence" and Confluence version-number boilerplate found at the bottom of the default template. Draws the fading shadow-effect found at the bottom of the content area in the default template. Inserts a link to the dashboard page.
#poweredby()
#bottomshadow()
#dashboardlink()
RELATED TOPICS
Page: Adding, Editing and Removing User Macros Page: Writing User Macros Page: Enabling HTML macros Page: Include Page Macro Page: Enabling the html-include Macro
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.
169
RELATED CONTENT
Page: Customising Colour Schemes Page: Customising Look and Feel Overview Page: Global Templates Page: Upgrading Custom Layouts Page: Customising a Specific Page Page: Customising Layouts Page: Editing the Footer Page: Working With Decorator Macros Page: Adding a Site-Wide Banner
You can remove the existing entities panel by disabling the global-entities-panel plugin from the Dashboard macros plugin.
170
$helper.renderConfluenceMacro("{recently-updated-dashboard:dashboard|showProfilePic=true}")
To modify the bundled plugin macros used in the Confluence dashboard: 1. Modify the atlassian-bundled-plugins.zip file located at <Confluence install>/confluence/WEB-INF/classes/com/atlassian/confluence/setup. 2. Update the confluence-dashboard-macros-x.x.jar file, rezip it and then put it back to <Confluence install>/confluence/WEB-INF/classes/com/atlassian/confluence/setup. Refer to Editing Files within JAR Archives . 3. Delete the JAR from <confluence-home>/bundled-plugins. 4. Restart Confluence. To customise the space list, you can work with spacelist.vm.
Related Topics
Customising your Personal Dashboard Customising Look and Feel Overview
Only administrators with access to the server where Confluence is running can modify the Confluence email templates.
171
Velocity Template Overview Customising Layouts Customising Look and Feel Overview Modify Confluence Interface Text
Customisations to the Confluence login page will need to be reapplied when you upgrade Confluence. Consider this before making drastic changes to the layout, and be sure to keep a list of what you have changed for your upgrade process later.
Only administrators with access to the server where Confluence is running can modify the Confluence login page.
Related topics
Editing the Global Logo Velocity Template Overview Customising Layouts Customising Look and Feel Overview Modify Confluence Interface Text
Themes Overview
Themes are pre-defined style sets that can be applied to alter the appearance of your site. Themes allow you to personalise the 'look and feel' of Confluence. You can apply a theme to your entire Confluence site and to individual spaces. Choose a specific theme if you want to add new functionality or significantly alter the appearance of Confluence. Confluence comes with a selection of themes. In addition, a site administrator can install new themes as plugins via the Confluence Administration Console. Provided that the theme is installed into your Confluence site, any space administrator can apply a theme to a space. By default when you create a new space, the space will have the Confluence default theme. To look at the themes installed: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Themes' under 'Look and Feel' in the left-hand panel. 3. You will see a list of all installed themes.
Useful Plugins
Before installing a plugin into your Confluence site, please check the plugin's information page to see whether it is supported by Atlassian, by
172
another vendor, or not at all. See our guidelines on plugin support. Adaptavist's Theme Builder Plugin for Confluence allows you to customise your Confluence site by adding layouts, logo banners, menu-driven navigation, style sheets, footers and more.
Related Topics
Page: Applying a Theme to a Space Page: Configuring the Easy Reader Theme Page: Including Cascading Stylesheets in Themes Page: Creating a Theme Page: Applying a Theme to a Site Page: Configuring the Documentation Theme
1. Ensure that the theme you wish to apply has been installed as a plugin. 2. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 3. Select 'Themes' under 'Look and Feel' in the left-hand panel. 4. The screen will display all available themes. Click a radio button to select a theme. 5. Click 'Confirm'.
173
RELATED TOPICS
Page: Applying a Theme to a Space Page: Configuring the Easy Reader Theme Page: Including Cascading Stylesheets in Themes Page: Creating a Theme Page: Applying a Theme to a Site Page: Configuring the Documentation Theme
174
blogpost.vmd
blogpost (news)
mail.vmd space.vmd
'view', 'view-thread' and 'remove' CONTEXT: "space-pages". MODES: "list-alphabetically", "list-recently-updated", "list-content-tree", "create-page". CONTEXT: "space-mail". MODES: "view-mail-archive". CONTEXT: "space-blogposts". MODES: "view-blogposts", "create-blogpost". CONTEXT: "space-templates". MODES: "view-templates". CONTEXT: "space-operations". MODES: "view-space-operations". CONTEXT: "space-administration". MODES: "view-space-administration", "list-permission-pages". 'dashboard', 'view-profile', 'edit-profile', 'change-password-profile', 'edit-notifications-profile' main.vmd is used to control the header and footer of each page, not the page specific presentation logic space.vmd handles a wide range of options, this context is accessed by clicking on 'browse space' in the default theme of Confluence (tabbed theme)
global.vmd
global
main.vmd
For example, if you wanted to remove the 'Attachments' tab on the view page screen, you would make this layout change in the page.vmd file - where the 'view' mode is handled (as shown below).
175
#* Display page based on mode: currently 'view', 'edit', 'preview-edit', 'info' and 'attachments. See the individual page templates (viewpage.vm, editpage.vm, etc.) for the setting of the mode parameter. *# ## VIEW #if ($mode == "view") <make layout modifications here> #elseif ...
$helper.spaceKey
176
returns the name of the current space renders a call to a Confluence Macro for the velocity context looks up a key in a properties file matching
and returns the matching value ("A piece of text") $helper.action returns the XWork action which processed the request for the current page.
If you are on a page or space screen you also have access to the actual page and space object by using $helper.page and $helper.space respectively. If you want to deliver more into what other methods are available in this object, please see our API's for ThemeHelper.
Step Four: Configuring the central configuration file to reference the new decorators
How to do this is explained in Configuring the Theme Plugin
Working with colour schemes for themes Configuring the colour scheme
The easiest way to configure a colour scheme is to do it dynamically from the Administration Console (as you would normally when you want to change the site's colour scheme online), and then express it as an xml file. This method makes it possible for you to experiment with different colours and test them out before including the colour scheme in your theme. 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Colour scheme' in the left panel. 3. Use the colour picker to define the colours for the following UI elements: Top Bar - the bar across the top of the page that contains the breadcrumbs. Space Name Text - the text of the current space name located above the page title. Heading Text - all heading tags throughout the space. Links - all links throughout the space. Borders and Dividers - table borders and dividing lines. Menu Bar Background - background of top navigational buttons Menu Bar Text - text that appears on the menu bar Menu Bar Background Highlight - background colour of menu bar when highlighted. Menu Bar Text Highlight - menu bar text when highlighted More information on customising colour schemes
RELATED TOPICS
Page: Applying a Theme to a Space Page: Configuring the Easy Reader Theme Page: Including Cascading Stylesheets in Themes Page: Creating a Theme Page: Applying a Theme to a Site
177
<atlassian-plugin key="com.atlassian.confluence.themes.tabless" name="Plain Theme"> <plugin-info> <description>This theme demonstrates a plain look and feel for Confluence. It is useful as a building block for your own themes.</description> <version>1.0</version> <vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com/"/> </plugin-info> <theme key="tabless" name="Tabless Theme" class="com.atlassian.confluence.themes.BasicTheme"> <description>plain Confluence theme.</description> <layout key="com.atlassian.confluence.themes.tabless:main"/> <layout key="com.atlassian.confluence.themes.tabless:global"/> <layout key="com.atlassian.confluence.themes.tabless:space"/> <layout key="com.atlassian.confluence.themes.tabless:page"/> <layout key="com.atlassian.confluence.themes.tabless:blogpost"/> <layout key="com.atlassian.confluence.themes.tabless:mail"/> <colour-scheme key="com.atlassian.confluence.themes.tabless:earth-colours"/> </theme> <layout key="main" name="Main Decorator" class="com.atlassian.confluence.themes.VelocityDecorator" overrides="/decorators/main.vmd"> <resource type="velocity" name="decorator" location="com/atlassian/confluence/themes/tabless/main.vmd"/> </layout> <layout key="global" name="Global Decorator" class="com.atlassian.confluence.themes.VelocityDecorator" overrides="/decorators/global.vmd"> <resource type="velocity" name="decorator" location="com/atlassian/confluence/themes/tabless/global.vmd"/> </layout> <layout key="space" name="Space Decorator" class="com.atlassian.confluence.themes.VelocityDecorator" overrides="/decorators/space.vmd"> <resource type="velocity" name="decorator" location="com/atlassian/confluence/themes/tabless/space.vmd"/> </layout> <layout key="page" name="Page Decorator" class="com.atlassian.confluence.themes.VelocityDecorator" overrides="/decorators/page.vmd"> <resource type="velocity" name="decorator" location="com/atlassian/confluence/themes/tabless/page.vmd"/> </layout> <layout key="blogpost" name="Blogpost Decorator" class="com.atlassian.confluence.themes.VelocityDecorator" overrides="/decorators/blogpost.vmd"> <resource type="velocity" name="decorator"
178
location="com/atlassian/confluence/themes/tabless/blogpost.vmd"/> </layout> <layout key="mail" name="Mail Decorator" class="com.atlassian.confluence.themes.VelocityDecorator" overrides="/decorators/mail.vmd"> <resource type="velocity" name="decorator" location="com/atlassian/confluence/themes/tabless/mail.vmd"/> </layout>
<colour-scheme key="earth-colours" name="Brown and Red Earth Colours" class="com.atlassian.confluence.themes.BaseColourScheme"> <colour key="topbar" value="#440000"/> <colour key="spacename" value="#999999"/> <colour key="headingtext" value="#663300"/> <colour key="link" value="#663300"/> <colour key="border" value="#440000"/> <colour key="navbg" value="#663300"/> <colour key="navtext" value="#ffffff"/> <colour key="navselectedbg" value="#440000"/> <colour key="navselectedtext" value="#ffffff"/>
179
</colour-scheme> </atlassian-plugin>
<atlassian-plugin key="com.atlassian.confluence.themes.tabless" name="Plain Theme"> <plugin-info> <description>This theme demonstrates a plain look and feel for Confluence. It is useful as a building block for your own themes.</description> <version>1.0</version> <vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com/"/> </plugin-info>
plugin key : Specify a key that uniquely identifies the plugin, eg. com.example.themes.dinosaur name : Give the plugin a name. description : Provide a short description of the plugin. vendor : Replace the text with your information. Theme information
<theme key="dinosaurs" name="Dinosaur Theme" class="com.atlassian.confluence.themes.BasicTheme"> <description>A nice theme for the kids</description> <colour-scheme key="com.example.themes.dinosaur:earth-colours"/> <layout key="com.example.themes.dinosaur:main"/> <layout key="com.example.themes.dinosaur:mail-template"/> </theme>
theme key : Specify a key that uniquely identifies the theme. class : The class of a theme must implement com.atlassian.confluence.themes.Theme. The com.atlassian.confluence.themes.BasicTheme class provided with Confluence gathers together all the resources listed within the module definition into a theme. name : Give the theme a name. Make sure that you replace all instances of the theme name with this name. description : Provide a short description of your theme colour-scheme key : A theme can contain an optional colour-scheme element that defines which colour-scheme module this theme will use. If you are using a new colour scheme, enter its key. layout key : A theme can contain any number of layout elements that define which layouts should be applied in this theme. Refer to these modules by their complete module key as shown above. Referencing the decorators You will need to add a layout entity as shown below for each of the decorators you are using. See working with decorators
<layout key="page" name="Page Decorator" class="com.atlassian.confluence.themes.VelocityDecorator" overrides="/decorators/page.vmd"> <resource type="velocity" name="decorator" location="com/atlassian/confluence/themes/tabless/page.vmd"/> </layout>
class : The class which each decorator, or layout, is mapped to must implement com.atlassian.confluence.themes.VelocityDecorator.
180
overrides : The layout entry must provide an overrides attribute which defines which decorator within Confluence is being overrridden by the theme. Location : Specify the location of the new decorator file, so Confluence know where to look when overriding the default decorator. It is possible for a theme to use modules that aren't in the same plugin as the theme. Just keep in mind that your theme will be messed up if the plugin that the theme depends on is removed. Including the colour scheme Colour schemes can be pre-configured for your theme dynamically from the Administration Console. See configuring colour schemes To transport them within a theme however, they need to be expressed in the atlassian-plugin.xml file as shown above.
<colour-scheme key="earth-colours" name="Brown and Red Earth Colours" class="com.atlassian.confluence.themes.BaseColourScheme"> <colour key="topbar" value="#440000"/> <colour key="spacename" value="#999999"/> <colour key="headingtext" value="#663300"/> <colour key="link" value="#663300"/> <colour key="border" value="#440000"/> <colour key="navbg" value="#663300"/> <colour key="navtext" value="#ffffff"/> <colour key="navselectedbg" value="#440000"/> <colour key="navselectedtext" value="#ffffff"/> </colour-scheme>
colour-scheme key : Specify a key that uniquely identifies the colour scheme. name : Give a name to the colour scheme. class : The class of the colour scheme must implement com.atlassian.confluence.themes.ColourScheme. The com.atlassian.confluence.themes.BaseColourScheme class provided with Confluence sets the colours based on the module's configuration. colour key: For each UI element, you will need to add its name and value. See configuring colour scheme RELATED TOPICS Page: Applying a Theme to a Space Page: Configuring the Easy Reader Theme Page: Including Cascading Stylesheets in Themes Page: Creating a Theme Page: Applying a Theme to a Site Page: Configuring the Documentation Theme
To make a stylesheet available to a decorator, you will need to reference it as a resource from within the central configuration file atlassian-plugin.xml. Here is an example where a stylesheet is being used to define the 'leftnavigation' theme:
181
<layout key="main" name="Main Decorator" class="com.atlassian.confluence.themes.VelocityDecorator" overrides="/decorators/main.vmd"> <resource type="velocity" name="decorator" location="templates/leftnavigation/main.vmd"/> <resource type="stylesheet" name="leftnav.css" location="templates/leftnavigation/leftnav-css.vm"> </resource> </layout>
The resource parameter takes three arguments: Type: The type of resource-in this instance, 'stylesheet'. Name: The name of the stylesheet. Location: The location of the file represented in the jar archive you will use to bundle your theme.
Step Two: Using the stylesheet in the decorator
To reference the stylesheet in the decorator, you will need to use the #pluginStylesheet velocity macro. For example, here's how you reference the leftnav.css file defined in the layout entry above:
#pluginStylesheet("com.atlassian.confluence.themes.leftnavigation:main" "leftnav.css")
The macro takes two arguments: completePluginKey: The complete plugin key which is constructed from the pluginkey and the layout key like this: {pluginKey}:{ layoutKey} In the above example, com.atlassian.confluence.themes.leftnavigation is the key of the plugin, and main is the key of the layout. stylesheetName: the name of the stylesheet If you place your stylesheet after the #standardHeader macro in the decorator, the contents of your custom stylesheet will override those in Confluence's default stylesheet. If your stylesheet needs to reference the colour scheme, you need to use the space stylesheet macro instead:
You can then use colour scheme references in your stylesheet, similar to Confluence's stylesheets, and they will be replaced with the appropriate global or space-specific colour scheme:
RELATED TOPICS Page: Applying a Theme to a Space (Confluence 4.1) Page: Configuring the Easy Reader Theme (Confluence 4.1) Page: Including Cascading Stylesheets in Themes (Confluence 4.1) Page: Creating a Theme (Confluence 4.1) Page: Applying a Theme to a Site (Confluence 4.1) Page: Configuring the Documentation Theme (Confluence 4.1)
182
Creating a Theme
Unsure what a theme is? See the overview of themes. If you want to create your own theme, you will need to write a Confluence plugin. Please refer to the following pages: Get started with plugin development. Create a theme using the theme plugin module.
RELATED TOPICS
Page: Applying a Theme to a Space Page: Configuring the Easy Reader Theme Page: Including Cascading Stylesheets in Themes Page: Creating a Theme Page: Applying a Theme to a Site Page: Configuring the Documentation Theme
Importing Data
Importing Content from another Wiki Universal Wiki Converter Importing Content Into Confluence
You need to install and run the UWC separately from Confluence.
The UWC is a standalone application that communicates with Confluence remotely. You cannot install the UWC directly into Confluence. Instead, download the UWC separately and run it according to the instructions below.
The UWC supports many wiki dialects. In addition, the UWC is an extensible framework, which means that developers can continue writing new conversion modules for other wikis. To see the latest list of conversions available, please refer to the UWC documentation. Download the latest version of the UWC. For information on installation and usage, see the UWC Quick Start Guide. For information on developing your own converter module, see the UWC Developer Documentation. For information about a specific wiki, including a list of currently supported wikis, see the UWC documentation. To ask a question, see the UWC discussions on Atlassian Answers.
183
RELATED TOPICS
184
Viewing your Installed Plugins Plugin loading strategies in Confluence Removing Malfunctioning Plugins Enabling and Configuring Macros Configuring a URL Whitelist Configuring the User List Macro Enabling HTML macros Enabling the html-include Macro Troubleshooting the Gallery Macro Adding, Editing and Removing User Macros Writing User Macros Best Practices for Writing User Macros Examples of User Macros Hello World Example of User Macro NoPrint Example of a User Macro Guide to User Macro Templates Configuring the Office Connector
Plugin Safety Plugins are very powerful: they can change the behaviour of almost any part of the Confluence server. This makes it very important that you trust a plugin before you install it. Always be aware of where (and who) a plugin comes from.
The Universal Plugin Manager (UPM) provides you with a powerful and user-friendly interface to manage your plugins. The Universal Plugin Manager itself is a plugin, which contains a number of modules that are implementations of the Atlassian REST plugin module type. It allows you to perform common plugin tasks, such as: Enabling/disabling plugins and their plugin modules. Installing new plugins. Configuring advanced plugin options. Finding out-of-date plugins and updating them. Checking the compatibility of your installed plugins against newer versions of the application. The Universal Plugin Manager also interfaces with the Atlassian Plugin Exchange, so you can browse the wide range of plugins available for your application from within your application. You can install any of these plugins with a single click, or upload your own plugins using the Universal Plugin Manager as well. Read more about the Universal Plugin Manager in the topics linked below: Checking Plugin Compatibility for Confluence Upgrades Configuring a Plugin Disabling or Enabling a Plugin Installing a Plugin Uninstalling a Plugin Upgrading your Existing Plugins Viewing the Plugin Audit Log Viewing your Installed Plugins Having problems with the Universal Plugin Manager? Try the Universal Plugin Manager FAQ (note, this will redirect you to the Universal Plugin Manager documentation. Use the back button on your browser to return the Confluence documentation).
185
1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
1. Click the '<application name> Upgrade Check' tab, (e.g. 'Confluence Upgrade Check'). The '<application name> Upgrade Check' page will display (see screenshot below). 2. Select the version of your application that you wish to check the compatibility of your installed plugins against in the ' Check compatibility for' dropdown and click the 'Check' button. 3. The page will refresh displaying any of your installed plugins that are not compatible with the selected application version (see screenshot below). The compatibility checker will also check the compatibility of the latest available version of each plugin (if not already upgraded) with the selected application version. You can click on the name of any of the plugins to view more information about the plugin. The plugins will be grouped into sections under the following headings: Incompatible The installed versions of plugins in this section are currently not compatible with the selected application version. There are currently no plugin upgrades available that are compatible with the selected application version. Compatible, if upgraded The installed versions of plugins in this section are currently not compatible with the selected application version. However, the plugins will be compatible with the selected application version if they are upgraded. There are buttons to allow you to upgrade these plugins. Compatible if both Confluence and the plugin are upgraded The installed versions of plugins in this section are currently not compatible with the selected application version. There is a plugin compatible with the newer application version, but it is not compatible with the application version you are currently running. You must upgrade the application and then proceed with the plugin upgrade. There are buttons to allow you to disable these plugins before proceeding with the upgrade. Compatible The currently installed versions of plugins in this section are compatible with the selected application version. Unknown Plugins listed under this section may or may not be compatible with the selected application version. If a plugin is not registered with the Atlassian Plugin Exchange, the Universal Plugin Manager cannot check its compatibility with different application versions.
186
Configuring a Plugin
A number of Confluence plugins have advanced configuration options. If you have one of these plugins installed on your application instance, you can view and update these configuration options via the Universal Plugin Manager (UPM).
187
Disabling or Enabling a Plugin If you would like to disable or enable a plugin, please refer to Disabling or Enabling a Plugin.
To access the Universal Plugin Manager in Confluence, 1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
1. Click the 'Manage Existing' tab. 2. Locate the plugin that you want to configure in the list of installed plugins and click its title. The plugin details section will expand (see first screenshot below). 3. Click the 'Configure' link for that plugin. The link will be disabled if the plugin is disabled. If there is no 'Configure' link, then there are no advanced configuration options available for that plugin. 4. The advanced configuration options for the plugin will display (see second screenshot below). Update the configuration settings as desired and save your changes. Note: The advanced configuration screens are provided by each plugin. If you encounter any problems after you click the 'Configure' link, the plugin is responsible for the issue, not the Universal Plugin Manager.
188
Disabling a Plugin
To access the Universal Plugin Manager in Confluence, 1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
1. Click the 'Manage Existing' tab. The plugins installed on your application will be displayed. Enabled plugins will be listed with an icon. 2. Locate the plugin that you want to disable and click the title to expand its plugin details section. 3. Click the 'Disable' button. 4. Once a plugin has been disabled, you may need to restart your application for your change to take effect. If so, the plugin will display with 'Disabled, requires restart'. This will depend on the plugin and the application. The plugin will display with an 'Enable' link once your change is applied (i.e. immediately or after an application restart).
Enabling a Plugin
To access the Universal Plugin Manager in Confluence, 1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
1. Click the 'Manage Existing' tab. The plugins installed on your application will be displayed. Disabled plugins will be listed with an icon. 2. Locate the plugin that you want to enable and click the title to expand its plugin details section. 3. Click the 'Enable' button. 4. Once a plugin has been enabled, you may need to restart your application for your change to take effect. If so, the plugin will display with 'Enable, requires restart'. This will depend on the plugin and the application. The plugin will display with an 'Disable' link once your change is applied (i.e. immediately or after an application restart).
189
1. Click the 'Manage Existing' tab. The plugins installed on your application will be displayed. 2. Click the 'Enable Safe Mode' button. 3. Click the 'Continue' button in the confirmation window that displays. All user installed plugins will be disabled and your application will now be running in 'Safe Mode' (see screenshot below). 4. You can now make changes to your installed plugins, as desired (e.g. enable/disable specific plugins or plugin modules). 5. Exit safe mode by clicking one of the links in the Safe Mode banner: Click 'Exit Safe Mode and restore the previous configuration' to exit support mode and restore your plugin configuration prior to entering Safe Mode. Click 'Exit Safe Mode and keep the current configuration' to exit support mode and keep any changes made to your plugin configuration during Safe Mode.
Installing a Plugin
190
This page describes how to install a plugin into Confluence using the Universal Plugin Manager. Plugins can be used to customise and extend the functionality of your application. You can search for plugins in the Universal Plugin Manager that are sourced from the Atlassian Plugin Exchange or upload your own.
On this page: Adding a plugin from the Atlassian Plugin Exchange Uploading your own plugin Notes
To access the Universal Plugin Manager in Confluence, 1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
To find and add a plugin to Confluence from the Atlassian Plugin Exchange,
1. Click the 'Install' tab in the UPM. The Install Plugins page will display showing the featured plugins for your application (see screenshot below). 2. Search for your plugin as follows: Enter some keywords that describe your desired plugin, e.g. 'Charting', in the 'Search the Plugin Exchange' search box and press 'Enter' on your keyboard. Alternatively, just browse to the desired plugin in the list. choose 'Featured', 'Popular', 'Supported' (by Atlassian) or 'All available' from the 'Plugins to show' dropdown to show a different list of plugins. 3. When you have located the desired plugin, click the 'Install' button for the plugin to add it to your application. A confirmation message and the plugin details (see 'Viewing Plugin Details' in the Related Topics below) for the plugin will display, if it is installed successfully. Note: You may need to restart your application for your change to take effect. The Universal Plugin Manager will inform you if this is the case. Note: Not all plugins can be automatically installed. Some required manual installation. These plugins will have a 'Download' button instead of an install button. In these cases, you should read and follow that plugin's installation instructions.
191
To access the Universal Plugin Manager in Confluence, 1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
1. Click the 'Install' tab in the UPM. The find new plugin page will display showing the featured plugins for your application. 2. Click the 'Upload Plugin' link. The 'Upload Plugin' window will display. 3. Enter the location of your plugin in either the 'From my computer' or 'From this location' textbox. If the plugin you want to install is on your computer, use the 'Browse' dialogue to choose the plugin file. If you want to install a plugin from a remote location, enter the URL of the plugin jar file in to the 'From this location' field. 4. Click the 'Upload' button to upload and enable your plugin. A confirmation message for the plugin will display if it is installed successfully. Note: You may need to restart your application for your change to take effect. The Universal Plugin Manager will inform you if this is the case.
192
Notes
In Confluence, you can install and uninstall both version 1 and version 2 plugins using the Universal Plugin Manager. You will see an 'Install' or an 'Uninstall' button. Some entries that you find listed in the Universal Plugin Manager are not actually plugins. These entries will show a 'Download' button which allows you to download the application to your desktop and run it following its specific instructions.
Related Topics
Uninstalling a Plugin
If you wish to remove a plugin from Confluence altogether, you can uninstall it via the Universal Plugin Manager (UPM). If you only want to temporarily remove it, you may wish to disable your plugin instead. To access the Universal Plugin Manager in Confluence,
1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
1. Click the 'Manage Existing' tab. The plugins installed on your application will be displayed. 2. Click the name of the plugin that you wish to uninstall. The plugin details for the plugin will display. 3. Click the 'Uninstall' button. The information summary will display an 'Uninstalling' message and the plugin will be uninstalled from your application.
193
If you are considering upgrading Confluence, you can use the Universal Plugin Manager to check the compatibility of your plugins with your desired Confluence version. Read Checking Plugin Compatibility for Confluence Upgrades for further details.
Upgrading a Plugin
To access the Universal Plugin Manager in Confluence,
1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
1. Click the 'Upgrade' tab. The plugin upgrades page will display. If you have a version of a plugin installed that is not the latest version available, the latest compatible version of the plugin will be listed on this page. You can click the plugin name to expand the row and view more information about the plugin. You can filter your list by entering keywords in the 'Filter plugins' text box. 2. Click the 'Upgrade Now' button next to the relevant plugin to update it to the plugin version displayed.
1. Click the 'Browse' menu link on the top bar and select the 'Confluence Admin' option to open the 'Administration Console'. 2. Click the 'Plugins' link under the 'Administration' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your Confluence instance.
194
1. Click the 'Upgrade' tab. The plugin upgrades page will display. If you have a version of a plugin installed that is not the latest version available, the latest compatible version of the plugin will be listed on this page. You can click the plugin name to expand the row and view more information about the plugin. You can filter your list by entering keywords in the 'Filter plugins' text box. 2. Click the 'Upgrade all' button next to the relevant plugin, to update each to the plugin version displayed for each plugin. Note: Some plugins cannot be installed via the Universal Plugin Manager these plugins must be installed manually. These plugins will not be upgraded automatically.
1. Click the 'Audit Log' tab. The plugin audit log will be displayed. 2. The log will display the 25 most recent entries. You can use the arrows to view older entries. 3. Click the orange RSS icon, if you want to receive the audit log activity in an RSS feed.
195
1. 2. 3. 4.
Click the 'Audit Log' tab. The plugin audit log will be displayed. Click the link 'Configure purge policy'. Specify the number of days you wish to keep logs in the 'Purge audit log after' field. Click the 'Confirm' button.
196
1. Click the 'Manage Existing' tab. The plugins installed on your application will be displayed. The plugins will be grouped into 'User-installed Plugins' and 'System Plugins'. You can filter your list by entering keywords in the 'Filter visible plugins' text box. The list of 'System Plugins' will be hidden by default. Click the 'Show System Plugins' link, if you want to view them. Enabled plugins will be listed with an icon. Disabled plugins will be listed with an icon. Click the name of a plugin to view the plugin's details. Click 'Enable Safe Mode' to run your application in safe mode. Read 'Disabling or Enabling a Plugin' (see Related Topics below) for more information on Safe Mode.
What is the difference between a 'System Plugin' and a 'User Installed Plugin'? System plugins are those that shipped with the product when you downloaded it from Atlassian. These plugins are integral to the functioning of the system, and although you can disable some of them, you should not do so unless instructed by an Atlassian Support engineer. Note, not every system plugin can be disabled and you will not be able to uninstall any system plugins at all. User-installed plugins are those which have been installed in the product after it was set up: either by uploading a plugin jar file, or by placing it in the applications plugin directories. These plugins can be uninstalled.
197
Plugin key This field shows the unique key the identifies each plugin in the system. Developer This field lists the name of the plugin developer and a link to the developer's homepage, if provided by the plugin developer. Plugin version This field lists the version of the plugin currently installed. Manage plugin modules Click this link to display the modules below the plugin summary. This link will only display if the plugin has modules, e.g. the Confluence Advanced Macros plugin. If you want to enable or disable a plugin module, hover your mouse over the module and click the 'Enable'/'Disable' button that displays. Configure Click this link to display the configuration settings for the plugin in the Universal Plugin Manager. This link will be disabled if the plugin is disabled. Please note that not all plugins have settings that can be configured through the Universal Plugin Manager. Refer to 'Configuring a Plugin' (see Related Topics below) for more information. Disable Click this button to disable the plugin in your application. This button will only display if the plugin is enabled. Refer to 'Disabling or Enabling a Plugin' (see Related Topics below) for more information. Enable Click this button to enable the plugin in your application. This button will only display if the plugin is disabled. Uninstall Click this button to uninstall the plugin from your application. This button will only display if the plugin is a user-installed plugin. Refer to 'Uninstalling a Plugin' (see Related Topics below) for more information.
Related Topics
Description cannot be installed or upgraded without a Confluence restart Included with Confluence and cannot be uninstalled. The classes and plugin.xml are not bundled into plugin jars, but mixed in with Confluence source on the main classpath. Additionally, the plugin.xml definitions are not called "atlassian-plugin.xml" as they are everywhere else, but are named for the plugin e.g., "basic-macros.xml". We would like to separate some of them out and turn them into Bundled plugins. Confluence also places some plugin jars inside WEB-INF/lib. They are inserted during the build process by Maven. These plugins, likewise, cannot be uninstalled. In ancient times, this was the only way to install plugins, so users are also free to install plugins here. We try to discourage them from doing so, however. As of version 3.0, most of the JAR files in this directory are library dependencies, not plugins. the opposite of static, these can be installed/upgraded while Confluence is running
Example
Admin Sections
WEB-INF/lib
Dynamic
198
Bundled
Bundled plugins can be administered from the Plugins console from Administration >> Plugins. You can upload or disable them there.
Office Connector
Bundled plugins are included in a zip of jars called atlassian-bundled-plugins.zip which is on the main Confluence classpath, in a resources directory <confluence-install>/confluence/WEB-INF/classes/com/atlassian/confluence/setup. At Confluence startup, they are extracted and copied into the $CONFLUENCE_HOME/bundled-plugins directory, from whence they are loaded. To remove a bundled plugin (you shouldn't normally have to do this), remove the plugin from the atlassian-bundled-plugins.zip file and the bundled-plugins directory, otherwise Confluence will just put it back in place on the next startup. In versions later than 2.6, you'll have to recreate the .jar file (if the jar file is from the lib folder) or recreate the zip folder(if its in the classes folder). Bundled plugins can be upgraded or disabled. Uploaded Installed by the user via the plugin repository or the Plugin Manager page. These plugins are stored in the database and then copied to the $CONFLUENCE_HOME/plugins-cache folder on each Confluence node. could be anything
To summarise the relationships of categories in the table, all plugins are either Static or Dynamic. Static plugins can be further categorised into Core or WEB-INF/lib. Dynamic plugins are divided into Bundled and Uploaded.
Upgrading plugins
Core plugins cannot be upgraded. WEB-INF/lib plugins can be upgraded by replacing the JAR in WEB-INF/lib and restarting Confluence. Bundled plugins can be upgraded using the Plugin Manager or the Plugin Repository Client. A new plugin jar is uploaded and stored as an Uploaded plugin. Confluence compares the version number with the Bundled plugin and uses the newer. Uploaded plugins are upgradable using the Plugin Manager or the Plugin Repository Client. When a new plugin jar is uploaded, the previous version is discarded from the database and the $CONFLUENCE_HOME/plugin-cache.
RELATED TOPICS
199
Check the How to display classpath utility for tips on what's loading, and the Knowledge Base Article on plugin malfunctioning.
1. Connect to the Confluence database. 2. Run the following SQL statement in your database:
3. After you have found the plugindataid for the offending plugin, please run the following:
To disable in the database, Run the following query on your Confluence database:
Bundled plugins can be administered from the Plugins console from Administration >> Plugins. You can upload or disable them there.
Bundled plugins are included in a zip of jars called atlassian-bundled-plugins.zip which is on the main Confluence classpath, in a resources directory - <confluence-install>/confluence/WEB-INF/classes/com/atlassian/confluence/setup. At Confluence startup, they are extracted and copied into the $CONFLUENCE_HOME/bundled-plugins directory, from whence they are loaded. To remove a bundled plugin (you shouldn't normally have to do this), remove the plugin from the atlassian-bundled-plugins.zip file and the bundled-plugins directory, otherwise Confluence will just put it back in place on the next startup. In versions later than 2.6, you'll have
200
to recreate the .jar file (if the jar file is from the lib folder) or recreate the zip folder(if its in the classes folder). Bundled plugins can be upgraded or disabled. If you need to remove a bundled plugin, check to see if you have duplicates in the <confluence-home>/bundled-plugins or <confluence-home>/plugin-cache directory. Usually, the problem is that an old plugin is getting loaded along with the properly bundled one, but if you need to remove a bundled plugin, check Plugin loading strategies in Confluence.
RELATED TOPICS:
Configuring a URL Whitelist Configuring the User List Macro Enabling HTML macros Enabling the html-include Macro Troubleshooting the Gallery Macro
201
content may possibly be malicious or harmful to your Confluence instance. Confluence administrators can set up a list of trusted URLs, thus limiting the locations from which the RSS macro and the HTML-include macro can draw their content. The form below allows you to define specific URLs and/or URL patterns which are trusted, or to allow inclusion from all URLs without restriction. To configure the URL whitelist: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select Configure Whitelist in the left-hand panel. The 'Configure Whitelist' screen will appear, as shown in the screenshot below. 3. Select one of the options as follows: Allow all domains There will be no restrictions to the content which can be included onto your Confluence pages. Restrict to listed domains Confluence will allow content from trusted URLs only. When you select this option, a textbox will open allowing you to enter specific URLs and/or URL patterns. Enter one or more URLs, each on its own line. You can enter the full URL, or use the pattern matching rules described below. 4. Click Save. Screenshot: Configuring a URL whitelist for RSS or HTML-Include macros
Notes
Some things to be aware of: By default, the RSS and HTML-include macros are disabled in Confluence. A System Administrator can enable them on the 'Plugins' screen of the Confluence Administration Console. A user who has the 'Confluence Administrator' permission, but not necessarily the 'System Administrator' permission, can configure the URL whitelist (for the HTML-include and RSS macros).
202
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:
Related Topics
Enabling HTML macros RSS Feed Macro HTML Include Macro
2. 3. 4. 5.
List of online users can be misleading When the Display Online parameter is used, Confluence uses a context listener to generate the list of online users. A context listener is a J2EE term for something that listens for events in the application server. We listen for session open and close events, so a user is 'online' if they have a session on the application server. Some application servers don't correctly despatch close events for sessions in these cases, the list of online users may be misleading.
203
Related Topics
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Plugins' in the left-hand panel. This will display the installed plugins active for this Confluence installation. Click on 'Show System Plugins' to display bundled plugins. 3. Click' 'HTML macros', then click 'Enable Plugin' 4. Ensure that 'html (html)' module is enabled
RELATED TOPICS
Page: Adding, Editing and Removing User Macros Page: Writing User Macros Page: Enabling HTML macros Page: Include Page Macro Page: Enabling the html-include Macro
204
CAUTION: Including unknown HTML inside a web page is dangerous. Because HTML can contain active scripting components, 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.
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Plugins' in the left-hand panel. This will display the installed plugins active for this Confluence installation. 3. Click' 'HTML macros', then click 'Enable Plugin'.
{html-include:url=http://www.example.com}
RELATED TOPICS HTML Include Macro Page: Adding, Editing and Removing User Macros Page: Writing User Macros Page: Enabling HTML macros Page: Include Page Macro Page: Enabling the html-include Macro
205
The gallery will ignore any pictures specified. You can specify more than one picture, separated by commas. Please note, the filename and filetype for this parameter are case-sensitive, i.e. 'my picture.PNG' will not be recognised as 'my picture.png'. If you specifically include one or more pictures, the gallery will show only those pictures. You can specify more than one picture, separated by commas. Please note, the filename and filetype for this parameter are case-sensitive, i.e. 'my picture.PNG' will not be recognised as 'my picture.png'. Specify the title of the page which contains the images you want displayed. To specify a page in a different space, use the SPACEKEY:Page Title syntax.
If no page is specified, the gallery macro displays the images attached to the page on which the macro is used.
Specify an attribute to sort the images by. Sort order is ascending, unless you select the Reverse Sort parameter (see below). Options are: name file name. comment comment linked to the attached file. date date/time last modified. size size of the attached file.
Reverse Sort
Used in conjunction with the Sort Images By parameter above. Use Reverse Sort to reverse the sort order, from ascending to descending.
If the name of an attached file or page contains a comma, you can refer to it in the relevant parameters above by enclosing it in single or double quotes, for example "this,that.jpg", theother.png.
Troubleshooting
If you encounter the following error message: System does not support thumbnails: no JDK image support then ensure that you have following system property available for your JVM:
JAVA_OPTS=-Djava.awt.headless=true
206
To add a user macro: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click User Macros in the left-hand panel. Click Create a User Macro at the top of the list of macros. Enter the macro details as explained in the guide to writing user macros. Click Add.
2. 3. 4. 5.
To edit a user macro: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select User Macros in the left-hand panel. This will list the currently configured user macros. Click Edit next to the relevant macro. Update the macro details as explained in the guide to writing user macros. Click Save.
2. 3. 4. 5.
To remove a user macro: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select User Macros in the left-hand panel. This will list the currently configured user macros. 3. Click Remove next to the relevant macro.
Related Topics
Page: Writing Macros Page: Shared User Macros Page: Adding, Editing and Removing User Macros Page: Writing User Macros Page: Enabling HTML macros Page: Include Page Macro Page: Enabling the html-include Macro
207
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.
On this page: Creating a User Macro Examples and Best Practices Related Topics
Macro Name
Enter the text that people will see when looking for the macro in the Macro Browser.
Visibility
Set the visibility options to specify who can see this macro when they are searching using the Macro Browser or Autocomplete.
User macros must have parameters defined in order to appear in the Confluence 4.0 Macro Browser.
The options are as follows: Visibility Option Visible to all users Meaning
All users will see this macro when searching for a macro using the Macro Browser or Autocomplete.
208
Choose this option if you want the macro to be 'hidden' from most users when the users are looking for a macro to add to a page. Note that this does not completely hide the macro. Instead, it is useful if you want to avoid cluttering the Macro Browser and Autocomplete with unnecessary macros. Specifically, if you are: Editing a page and inserting a macro using the Macro Browser: Only system administrators will see this macro in the Macro Browser. For other users, the macro will not show up in the Macro Browser when the user searches for a macro to add to a page. Editing a page and inserting a macro using Autocomplete: Only system administrators will see this macro in Autocomplete. For other users, the macro will not show up in the Autocomplete list when the user searches for a macro to add to a page. Viewing the page: The macro output will be visible to all users who have permission to see the page. Editing a page that already contains the macro: Provided a user has permission to edit the page, the macro will be visible to all users when editing the page, and all users who have permission to edit the page will also be able to edit or remove the macro. Please note that all the macro information will also be discoverable, including the macro title, description, parameter names and other metadata. Do not include confidential data anywhere in the definition of a user macro, even if it is marked as visible only to system administrators.
Macro Title
Enter the text that should appear in the Macro Browser and in Autocomplete, to identify this macro when people are looking for it to insert onto a page.
Description
Enter the text that should appear in the Macro Browser describing this macro. Note that the Macro Browser's search will pick up matches in the description as well as in the title.
Categories
Select one or more categories for your macro. To select more than one category, hold down the 'Ctrl' key while selecting. These are the categories that appear in the Macro Browser, helping users to choose a macro from a logical set.
Icon URL
If you would like the Macro Browser to display an icon for your macro, enter the URL here. You can enter an absolute URL or a path relative to the Confluence base URL. For example: Absolute URL:
http://mysite.com/mypath/status.png
Relative URL:
/images/icons/macrobrowser/status.png
Documentation URL
Enter the URL pointing to the online help or other documentation for your macro.
The macro body is the content that is displayed on the wiki page. If the macro allows a body, users will be able to enter body content when configuring the macro in the Macro Browser.
How can I use the macro body?
If you specify that your macro has a body, you will be able to pass text to the macro when you invoke it from within a page. If your macro has a body, any body content that the user enters will be available to the macro in the $body variable. See the section about the template below. In addition, the options below allow you to tell Confluence to pre-process the body before it is placed in the macro output.
209
Meaning
If your macro has a body, and you make use of the body as $body in your template, Confluence will add escape characters to the HTML markup in the macro body. You could use this if you want to show the HTML markup in the rendered page. For example, if the body is:
<b>Hello World</b>
<b>Hello World</b>
<b>Hello World</b>
Unrendered Rendered
If your macro has a body, and you make use of the body as $body in your template, HTML in the body will be processed within the template before being output. Ensure that HTML is ultimately output by the template. If your macro has a body, and you make use of the body as $body in your template, Confluence will recognise HTML in the macro body. For example, if the body is:
<b>Hello World</b>
<b>Hello World</b>
Template
Enter XHTML code to specify what the macro will do. For example, to add a macro inside the macro you are writing, you would write:
Quick guide
Use XHTML in the macro template. You can use the Velocity templating language. Here is more information on the Velocity project. If your macro has a body, your template can refer to the macro body text by specifying '$body'. Each parameter variable you use must have a matching metadata definition. Use @param to define metadata for your macro
210
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. browser. See our detailed guide to writing a user macro template. Note that this will prevent your macro appearing in the macro
Related Topics
Developer documentation: User Macro Module Macro Module Confluence Plugin Guide Library of user-contributed user macros Shared User Macros
Be careful when installing user macros. Ideally use only macros from authors and sources that are well known to you.
## ## ## ## ## ## ## ##
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 Installed by: My Name
211
#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
Related Topics
Writing User Macros
Let's write a simple macro that creates a red box (using an existing Confluence style) around some text. This may be useful for writing about error conditions, for example. That is why we give this macro the name 'error'. To create the 'Error' user macro: 1. Go to the 'Confluence Administration Console' and click User Macros in the left-hand panel. 2. Click Create a User Macro at the top of the list of macros. 3. Enter the macro attributes as follows: Macro Name: error Visibility: Visible to all users in the Macro Browser Macro Title: Error Description: Displays a red box around some text Categories: Confluence Content Icon URL: You can leave this field empty. Documentation URL: You can leave this field empty. Macro Body Processing: Rendered Template:
<div class="error">$body</div>
4. 212
4. Click Add. To use the macro within a page, use the Macro Browser. Your page will display an error box, like this: This is bad
This example demonstrates how you can pass parameters into your macro. Let's say you want to write your own font colour macro:
The output will be: Some example text If your macro requires more than one parameter, you can use variables $param0 to $param9 to represent them. To specify multiple parameters, use:
{colour:red|blue|green}
Where red, blue and green are the 1st, 2nd and 3rd parameters respectively. 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. To specify named parameters, use:
{style:colour=red}
In your user macro you can then use $paramcolour which will have the value red in this case.
To create the 'Hello World' user macro: 1. Go to the 'Confluence Administration Console' and click User Macros in the left-hand panel. 2. Click Create a User Macro at the top of the list of macros. 3. Enter the macro attributes as follows: 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 empty. Documentation URL: You can leave this field empty. Macro Body Processing: Rendered Template:
213
Now you can add the macro to your Confluence page using the Macro Browser:
214
Related Topics
To create the 'NoPrint' user macro: 1. Go to the 'Confluence Administration Console' and click User Macros in the left-hand panel. 2. Click Create a User Macro at the top of the list of macros. 3. Enter the macro attributes as follows: Macro Name: noprint Visibility: Visible to all users in the Macro Browser Macro Title: NoPrint Description: Hides text from printed output. Categories: Confluence Content Icon URL: You can leave this field empty. Documentation URL: You can leave this field empty. Macro Body Processing: Rendered Template:
215
4. Click Add.
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.
Quick guide to user macro templates Use XHTML in the macro template. You can use the Velocity templating language. Here is more information on the Velocity project. If your macro has a body, your template can refer to the macro body text by specifying '$body'. Each parameter variable you use must have a matching metadata definition. Use @param to define metadata for your macro parameters. When using the information passed using parameters, refer to your parameters as $paramXXX where 'XXX' is the parameter name that you specifed in the @param metadata definition. Use @noparams if your macro does not accept parameters. the macro browser. Note that this will prevent your macro appearing in
On this page: Accessing your Macro's Body Using Parameters in your User Macro Objects Available to your Macro Controlling Parameter Appearance in the Editor Placeholder Related Topics
216
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
When adding a macro to a Confluence page, the Macro Browser will display an input field for each of your macro's parameters. The field type is determined by the parameter type you specify for each parameter.
Defining the Parameters
Briefly, a parameter definition in the template contains: @param The parameter name A number of attributes (optional) Format:
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 Name Description Required / Recommended / Optional Required
A unique name for the parameter. The parameter name is the first attribute in the list. The name attribute itself does not have a name. See the section on name below. The parameter title will appear in the Macro Browser. If you do not specify a title, Confluence will use the parameter name. The field type for the parameter. See the section on type below. The parameter description will appear in the Macro Browser. Specifies whether the user must enter information for this parameter. Defaults to 'false'. Specifies whether the parameter accepts multiple values. Defaults to 'false'. The default value for the parameter.
Recommended
217
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':
Parameter Type
The field type for the parameter. If you do not specify a type, the default is string. Parameter Type boolean enum Description Displays a checkbox to the user and passes the value 'true' or 'false' to the macro as a string. 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 internationalisation of the enum values.The value the user sees is the one passed to the macro as the parameter value, with the capitalisation given. In this case 'Grey', 'Red', etc. string A text field. This is the default type. Example with a required field:
confluence-content
Offers a control allowing the user to search for a page or blog post. Example:
username
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:
Note about dates: A user can enter a date in any format, you should validate the date format in your user macro.
218
int
Confluence accepts this type, but currently treats it in the same way as 'string'. Example with a default value:
percentage
Confluence accepts this type, but currently treats it in the same way as 'string'. Example:
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. That will let Confluence know that it need not display a parameter input field in the Macro Browser. 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, especially if the macro does not accept parameters. Example: Add the following line at the top of your template:
## @noparams
$config
The BootstrapManager object, useful for retrieving Confluence properties. The PageContext object, useful for (among other things) checking $renderContext.outputType The Space object that this content object (page, blog post, etc) is located in (if relevant). The current ContentEntity object that this macro is a included in (if available).
BootstrapManager PageContext
$renderContext
$space
Space
$content
ContentEntityObject
Macros can also access objects available in the default Velocity context, as described in the developer documentation.
219
The macro metadata for a plugin macro now has parameter options as shown in the following example:
<macro name="panel" documentation-url="help.panel.macro"> <category name="formatting"/> <parameters> <parameter name="title" type="string"> <option key="showNameInPlaceholder" value="false" /> <option key="showValueInPlaceholder" value="true" /> </parameter> <parameter name="borderStyle" type="string"/> <parameter name="borderColor" type="color"/> <snip
The option showNameInPlaceholder specifies that in the above example the 'title' parameters name should not be shown. The option showValueInPlaceholder specifies that the user entered value for this parameter should be shown. So, for the above example, the macro placeholder could show something like 'panel | my panel title'. If showNameInPlaceholder was true instead of false it would show something like 'panel | title = my panel title'. If a macro has neither option on any of it's parameters then the default behaviour is to show all parameters: full title and value. If one or more parameters has either option set then all parameters without the options set will default to false (i.e. will not be shown).
User Macro Metadata
The behaviour for a user macro is as described above, however the method of configuration is within the @param entry in the template. So, the example from above would look something like: ## @param title|type=string|option-showNameInPlaceholder=false|option-showValueInPlaceholder=true
Related Topics
Writing User Macros Examples of User Macros
On this page: Enabling and Disabling the Office Connector and its Modules Configuring the Office Connector Options Related Topics
220
Manage plugin modules You can also enable or disable one or more of the Office Connector modules, as described in the table below.
The following modules are available for the Office Connector plugin: Module OC Settings Manager Slide Cache Manager Html Cache Manager File Cache Cleanup Job File Cache Cleanup Office Connector administration link Link for previewing a search result Description Component to read and write persistent settings for the Office Connector.
Component to cache slide-based conversions when displaying PowerPoint and PDF documents.
Component to cache HTML-based conversions when displaying Word and Excel documents.
This module is a recurring task that cleans up the Office Connector file cache.
This module is the trigger for the File Cache Cleanup Job.
This module supplies the 'Office Connector Configuration' link in the left-hand panel of the Confluence Administration Console. The link gives access to the plugin configuration screen described below.
This modules supplies the 'View' link which appears next to attachments displayed in search results, where the attachment is an Office document.
221
Link for previewing an attachment viewfile viewdoc viewxls viewppt viewpdf editgrid Import Word UI on page tabs Import Word UI on drop down menu Edit in Office javascript resource Office Connector Servlet Office Authenticator Filter PPT slide web service DOC and XLS image cache web service Office Connector Actions
This modules supplies the 'View' link which appears next to attachments displayed on the 'Attachments' view of a page, where the attachment is an Office document.
This module supplies the {viewfile} macro. See View File Macro. This module supplies the Word document component of the {viewfile} macro. This module supplies the Excel document component of the {viewfile} macro. This module supplies the PowerPoint document component of the {viewfile} macro. This module supplies the PDF document component of the {viewfile} macro. This module is used to migrate editgrid users to the Office Connector. This module supplies a 'Doc Import' tab which appears in older versions of Confluence, next to the 'View', 'Edit', 'Attachments' and 'Info' tabs. Not relevant to Confluence 2.10 or later, except for custom themes. This modules supplies the 'Doc Import' link which appears in the Confluence 'Tools' dropdown menu.
This module contains the javascript resources for launching the desktop applications for editing Office documents.
This module allows Confluence users to edit their Confluence pages in Microsoft Word. It performs the conversion to and from Word. This module authenticates HTTP requests from Office applications.
This module allows Confluence users to view a PowerPoint presentation on a wiki page. It provides the slide images to the Flash control which displays the slides on the wiki page. This module is required if Confluence users want to view a Word document or an Excel spreadsheet on a wiki page. It allows images to be stored in a cache on the server, so that they can be retrieved when the browser renders the HTML page. This module must be enabled if the Office Connector is used.
222
The configuration options are described in the table below: Option Default Value Disabled Description
Warnings: Show a warning before allowing a user to perform an import Advanced Formatting Options: Use the footnote macro for Word footnotes Authentication: Allow authentication tokens in the URL path
If this option is enabled, the user will receive a warning when importing a Word document. The warning will tell the user w they are about to overwrite existing content.
Disabled
If this option is enabled, a Confluence page created from an imported Word document will use the {footnote} macro from Adaptavist to render any footnotes contained in the document. Note that you will need to install the Footnotes plugin onto Confluence site. For more information about this plugin and macro, please refer to the Footnotes plugin.
Disabled
If this option is enabled, the Office Connector will use authentication tokens in the URL.
223
The {viewfile} macro will cache data temporarily. This option allows you to set the location of the cache. Available settings
Confluence home directory The temporary file will be stored in your Confluence Home directory. A directory specified in the directories.properties file You can specify a location by editing the Office Connector's directories.propertiesfile: 1. Go to the bundled-plugins directory in your Confluence Home directory. 2. Copy the Office Connector JAR file to a temporary location: OfficeConnector-x.xx.jar, where 'x.x version number. 3. Unzip the JAR file and find the directories.properties file in the resourcesdirectory. The conten 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=
4. 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
5. Save the file, recreate the JAR and put it in the bundled-plugins directory in your Confluence Home directory, overwriting the original JAR. Cache in-memory The temporary file will be held in memory. We recommend this option if you are running in a clustered environment. Maximum file space for cache (MB) Number of Conversion Queues 500 This is the maximum size of the cache used by the {viewfile} macro. (See above.)
This is the maximum number of threads used to convert PowerPoint or PDF slide shows. You can use this setting to man Confluence performance, by limiting the number of threads so that the Office Connector does not consume too many reso Click Manage Queues to view attachments that are still pending conversion.
Related Topics
Office Connector Prerequisites Office Connector Limitations and Known Issues Working with the Office Connector Installing Plugins and Macros
224
We have assembled some requirements to help you make sure that your installation of Confluence can be mission critical. There are no surprises to be found here all of the requirements would apply to any other piece of software that is mission critical within your organisation.
225
Confluence at short notice. If problems arise and you need to contact Atlassian Support, these engineers will be our first point of contact. We may ask them to provide details of log files, application-server settings, monitoring systems, and so on.
Network Staff
If Confluence is mission critical for large numbers of users, it is vital that you have dedicated network staff available to track down problems when they arise. A mission-critical installation will usually be used by hundreds or even thousands of users, and you don't want to keep them waiting because a network card breaks, or because someone has made an undocumented change to the network and you don't have an expert around who can figure it out. Again, this only applies to mission-critical systems. If you use Confluence for less critical collaboration and knowledge sharing, and a broken network cable causing a day's downtime is no major catastrophe, then you will not need dedicated networking staff.
Database Staff
If Confluence is mission critical for a large number of users, you need an experienced database administrator (DBA) available to troubleshoot database performance issues and other potential problems. It is dangerous not to have an experienced full-time DBA at hand at short notice when running a mission critical application. While small installations of Confluence basically work 'out of the box', any system that involves high load or high-availability requirements needs continual monitoring, optimising and fine tuning of the Confluence database. Database monitoring is no trivial task it's not something that anyone can learn quickly.
Developers
You may have decided to customise Confluence by changing its source-code, or by writing your own plugins. If your server is mission-critical, you must nominate staff who will be responsible for that code, and they must be up for the task. Otherwise you might end up in a situation in which your server experiences downtimes because of custom code is broken, or does not work with a newer version of Confluence anymore, but you can't fix the problem because no one knows how the customized code works, and you can't uninstall it either because it has become critical for your Confluence usage pattern. Keep good track of changes, and have someone available to jump into action if there is a problem Don't let the summer intern write mission-critical plugins, unless you have more senior staff to maintain that code as long as it is in use.
Tools for Monitoring Confluence At Atlassian we use Hyperic. But the list of monitoring systems is long and we can't recommend a specific product over the other. If your organisation has a monitoring system already, make sure you hook up Confluence to it. If you don't have a monitoring system yet, you need to install one as soon as you feel Confluence is mission critical.
As an example of what our monitoring UI looks like, have a look at this screenshot:
226
The following screenshot shows one of our sensors looking at the HTTP response times of our documentation wiki over the last 8 days. You can clearly see an incident four days ago. Having the graph (and regularly looking at it) allowed us to pinpoint the problem. We analysed the access logs and found that webpage-profiling had been enabled but not disabled again, which caused performance problems.
227
This page would get too long if we described all our monitoring sensors - but just to give you an impression, this is what we monitor on the JVM level alone. JVM basics Current Loaded Classes Daemon Thread Count Heap Memory Committed Heap Memory Max Heap Memory Used Loaded Classes Loaded Classes per Minute Object Pending Finalization Count Peak Thread Count Thread Count Unloaded Classes Unloaded Classes per Minute JVM garbage collection Collection Count Collection Count per Minute Collection Time Collection Time per Minute JVM memory: (Metrics for Eden space, Old Gen, Survivor space, Perm Gen) Commited Memory Used Memory We get the same level of detail for our database, for the file system, for the CPU, for the network, and so on. Not all of this is needed all the time. But if your company depends on an application, then the more information you have at your fingertips the better. Fortunately these metrics can be extracted quite easily once you have a monitoring system in place.
Server brought back up after database restored from backup. Running 2.8-m9-r3. GC algorithm changed from concurrent to parallel collector. Max heap increased from 1.4 GB to 2.0 GB Hyperic agent started with connection to Resin.
228
Manual updates to menu.css, comments.js and comments.css in webapp Updated cache sizes for five caches, bounced server.
Temporary fix for @JIRA, @JIRA which was impacting performance Cache efficiency was low on these caches.
2008-05-13 03:00-03:20
2008-05-14 20:30
@JIRA
Getting a license for your staging environment Only a technical contact for your commercial/academic license is able to create a Developer license. Atlassian supplies 'developer' licenses which can be used by existing commercial license holders who wish to deploy non-production installations of our software to use in QA/staging environments. Developer licenses are free of charge to commercial license holders and, like our commercial offerings, they include 12 months of updates starting from the date of purchase of the commercial license. If you hold a commercial license, you can obtain a free developer license by following these steps: 1. Log in to your Atlassian account. 2. Under the "Licenses" heading, all of your licenses will be displayed. Click the plus sign next to a license to view its details. 3. Click the 'View Developer License' link in the bottom right corner of the license detail panel, below your commercial license key.
229
Make sure to have qualified staff around, so you can deal with security issues quickly. Once a security patch becomes available or a security incident happens, speed is essential. Please refer to our dedicated Configuring Confluence Security page for more technical details.
Load-Testing Environments
Many customers ask us, So, how many users and spaces can I put into Confluence, and what is the best hardware do to so? The answer is, 'It depends'. It depends a lot on your use case. Confluence is so successful because it can cover a huge range of use cases. If most of your users only access Confluence infrequently, it is no problem to have 70 000 to 100 000 users. But if each user is a power-user who uses the system the whole day, there's a substantial decrease in number Confluence can take without tuning. If your pages are short, simple, and don't contain a lot of macros, then the situation will be vastly different from a system that relies heavily on macros, background-tasks, or other features. If your system is large (for example serving more than 10 000 users or storing more than 1000 spaces) or mission-critical (which it could be with as few as 1000 users who use it all the time) you need one or more more load-testing environments. Even if your system is working nicely for 20 000 users right now, it might take just another 2000 users to push it over the edge. We recommend the following basic procedure: Set up an environment that closely resembles your production environment. Gather statistics from your production system. Regularly apply a similar kind of load (and slightly higher) to the load-testing environment. Analyse how well Confluence scales for your usage patterns. The Confluence development team has load-testing scripts available which you can use to simulate load. You can also contact Atlassian Support for more details.
Tuning
You may need to be able to tune your installation in the ways mentioned below.
230
Where ever possible run the most recent major release from your selected JVM manufacturer. The Sun JVM version 6 is much faster than 1.4, especially under high loads. Tune your garbage collection algorithms. Experiment with different algorithms and settings to get the response times you desire in your environment. Here are some specific guidelines for Sun JVM in the Sun documentation: Java 6 Java 5 Java 1.4
Related Topics
Performance Tuning Configuring a Large Confluence Installation Confluence Clustering Overview Requesting Performance Support Confluence Administrator's Guide Confluence Configuration Guide Server Hardware Requirements Guide Fix Out of Memory Errors by Increasing Available Memory
Performance Tuning
This document describes tuning your application for improved performance. It is not a guide for troubleshooting Confluence outages. Check Troubleshooting Confluence Hanging or Crashing for help if Confluence is crashing. NEW: Garbage Collector Performance Issues
Description
Like any server application, Confluence may require some tuning as it is put under heavier use. We do our best to make sure Confluence performs well under a wide variety of circumstances, but there's no single configuration that is best for everyone's environment and usage patterns. If you are having problems with the performance of Confluence and need our help resolving them, you should read Requesting Performance Support.
231
On this page: Description Use the latest version of your tools Avoid swapping due to not enough RAM Careful about those other systems using the same infrastructure Choice of Database Database Connection Pool Database in general Database indexes Database Statistics and Query Analysers Cache Tuning Antivirus Software Enabling HTTP Compression Virtual Operating Systems Performance Testing Access logs Built-in Profiler Adjust Application Server Memory Settings Use A Web Server Parallel GC Troubleshoot possible memory leaks Some 3rd-party plugins were not written to scale to large enterprises' needs
Choice of Database
The embedded database that is provided with Confluence is meant only to be used for evaluation, not for production Confluence sites. After the evaluation finishes, you will certainly need to switch to an external relational database management system. Beyond this, we do not recommend any particular RDBMS over another. 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 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
232
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 indexes
Especially if you have more than a few thousand active users, and all most obvious measures have been tried out but the database still seems to be under high load, you should consider engaging a database administrator (DBA) to tune the database specifically to the demands that your particular Confluence installation is placing on it. If you do not have a full-time DBA and can't even get one for temporary consulting, you may want to consult the database indexing advice that we have been gathering from customer reports and our own experience running and developing Confluence. The instructions on that page are for Oracle, but most of the indexes can be applied to (and will help with) any database. (These database indexes are now created automatically when Confluence is installed, but existing installations upgrading to a more recent version may still need to add them manually)
Cache Tuning
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.
Performance Testing
You should try out all configuration changes on a demo system. Ideally, you should run and customize loadtests that simulate user behaviour. Learn about how to test performance issues using the Performance Testing Scripts.
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.
233
Parallel GC
If you have multiple CPU's on your server, you can add -XX:+UseParallelOldGC to your JAVA_OPTS options. This will allow garbage collection of the Tenured Space to happen in parallel with the application and can boost performance and can reduce slow performance spikes. For more information, please refer to our detailed page on Garbage Collector Performance Issues, and Sun's summary of collectors.
Some 3rd-party plugins were not written to scale to large enterprises' needs
Confluence has been optimized to work under high load and with many pages. Some 3rd party plugins however have been written with small size companies in mind, and can't cope with large numbers of concurrent users, or large numbers of pages and permissions, or large numbers of spaces. It is impossible to tell which ones will fail under which conditions, but it will always help to turn off 3rd-party plugins that are not strictly mission-critical while investigating performance issues.
RELATED TOPICS
Garbage Collector Performance Issues Cache Performance Tuning Cache Performance Tuning for Specific Problems Performance Testing Scripts Working with Confluence Logs Operating Large or Mission-Critical Confluence Installations Confluence Clustering Overview Requesting Performance Support Confluence Administrator's Guide Confluence Configuration Guide
If you only need to modify Confluence's maximum cache sizes, you can do this through the Cache Statistics feature of the Administration Console.
The cache performance information for your Confluence installation is available under Administration > Cache Statistics. More information about the numbers displayed here is available on Cache Statistics.
234
On this page: Cache tuning example Finding the configuration file Cache Key Mappings Standard Editions of Confluence Clustered Editions of Confluence Important Caches Cache Tuning Follow-Up
The caches above are of size 1000 (meaning that it can contain up to 1000 objects), which is the default size for caches in the default cache scheme. Refer to Confluence Cache Schemes for more explanation. You can tell when a cache size needs to be increased because the cache has both: a high usage percentage (above 75%) a low effectiveness percentage. Check the 'effectiveness' versus the 'percent used'. A cache with a low percent used need not have its size lowered; it does not use more memory until the cache is filled. Based on this, the sizes of the "Attachments", "Database Queries", and "Users" caches should be increased to improve their effectiveness. As the stored information gets older or unused it will expire and be eliminated from the cache. Cache expiry may be based on time or on frequency of use. There is not much that you can do with a cache that has both a low percentage of usage and effectiveness. Over time, as the cache is populated with more objects and repeat requests for them are made, the cache's effectiveness will increase.
235
Oracle Coherence Licensing Change: Due to a license agreement change,Confluence is now available in two editions: Standard Edition Confluence with Ehcache's caching technology (available to customers with non-clustered Confluence licenses). If you are currently running a clustered installation of Confluence, please do not upgrade it with a standard edition of Confluence. Clustered Edition Confluence with Oracle's Coherence clustering and distributed caching technology (available to customers with Confluence clustered licenses only). For more information about these changes, please refer to the Coherence License Changes document. If you have a Confluence clustered license, are running a clustered installation of Confluence and wish to upgrade to Confluence version 2.6 or later, please ensure that you download only a clustered edition of Confluence and please refer to the Confluence 3.0.1 Upgrade Notes for additional upgrade information.
Using our example from the table above, if we were to modify parameters for the Users cache we would need to change the cache with the key com.atlassian.user.impl.hibernate.DefaultHibernateUser. Do not get confused with Users (External Mappings) and Users (External Groups) which are in themselves, two separate caches. "Users" is the friendly name for com.atlassian.user.impl.hibernate.DefaultHibernateUser.
To maintain your existing cache configuration file settings, you will need to transfer any cache customisations you have implemented in the Coherence cache configuration file (confluence-coherence-cache-config.xml) to the relevant entries in the Ehcache cache configuration file (ehcache.xml). Each cache has a cache-mapping element in the Coherence file (of which there is an equivalent cache element in the ehcache.xml file). Unfortunately, copying across your customisations is not quite a straightforward process because the Coherence file defines several 'caching schemes' to store the actual cache values, which in turn are referenced by the cache-mapping elements. In contrast, the ehcache.xml file does not support caching schemes and a cache's values are expressed explicitly in separate parameters of a cache element. To convert your Coherence cache configuration file customisations across to the equivalent Ehcache file: 1. Open both the confluence-coherence-cache-config.xml and ehcache.xml files in a text editor. These files are located in the <confluence-home>/config directory. If you implemented your customisations in a version of Confluence prior to 3.0, you will most likely find the confluence-coherence-cache-config.xml file in the <confluence-install>/confluence/WEB-INF/classes directory. 2. In the customised confluence-coherence-cache-config.xml file: a. Identify the caching schemes that were customised in this file and make a note of the values of all its child elements.
236
Confluence 4.0 Documentation 2. a. Typically, each caching scheme is located inside a local-scheme element and all of these are enclosed within the cache-schemes element, which appears towards the end of this file. b. Note each customised caching scheme by the content of its scheme-name element. c. For each cache-mapping element (which typically appears towards the top of this file), identify if it has a scheme-name element whose content matches one noted in the previous step and if so, make a note of its associated cache-name element. 3. In the ehcache.xml file: a. Identify each cache element whose 'name' parameter matches the cache-name elements noted in step '2c'. b. Using the mappings table below, apply the values noted in step '2a' to the appropriate parameters of the cache elements identified in the previous step ('3a'). Mappings table showing how elements of the Coherence cache configuration file map to parameters of the equivalent Ehcache file. Coherence Element high-units expiry-delay > 0s expiry-delay = 0s Ehcache Attribute
maxElementsInMemory timeToIdleSeconds - Use this attribute for expiry delays greater than 0s along with the eternal attribute set to 'false' eternal - For expiry delays of 0s, set this attribute to 'true'.
Then we will need to define a cache schema with name cache:com.atlassian.user.impl.hibernate.DefaultHibernateUser within <caching-schemes>...</caching-schemes> tags.
It's possible to define a local-scheme mapping for a cache key without defining certain parameters (e.g. <high-units> ). In such a cases, their parameters will be inherited from scheme-ref scheme, which is the default scheme in our case.
Important Caches
237
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.
com.atlassian.confluence.core.ContentEntityObject (known as Content Objects cache) 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. com.atlassian.confluence.core.ContentEntityObject.bodyContents (known as Content Body Mappings cache) 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. com.atlassian.confluence.security.PermissionCheckDispatcher.isPermitted() (known as User Authorized URLs cache) should be set to at least the number of concurrent users you expect to access Confluence at the same time com.atlassian.user.impl.hibernate.DefaultHibernateUser (known as Users cache) should be set to the number of users you have: select count (*) from users. Note that by default, this will also control the LDAP user's cache, including expiration. com.atlassian.confluence.security.SpacePermission (known as Permissions cache) 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.
You can monitor what's in the cache by using a JSP included in the Confluence distribution. Browse to <base-URL>/admin/cachecontents.jsp to monitor the cache contents.
RELATED TOPICS
Cache Performance Tuning for Specific Problems Confluence Cache Schemes Performance Testing Scripts Working with Confluence Logs Operating Large or Mission-Critical Confluence Installations Confluence Clustering Overview Requesting Performance Support Confluence Administrator's Guide Confluence Configuration Guide
If your installation of Confluence is suffering from this problem, it may be due to a insufficient SpacePermissions cache size. To address this problem, first determine the number of space permission objects in your Confluence instance. You can do this by running this query against your database:
238
Adjust the maxElementsInMemory or high-units property to the number of space permissions you have (in the example above, I've used 10000). Also, just as important, you need to adjust the timeToLiveSeconds or expiry-delay property to 0. Note: 10K of space permissions consumes approximately 8MB of memory. Please ensure there is enough memory allocated to your instance to cater for this.
How to set specific cache settings
1. Find the cache name from the cache name mappings: For Confluence 2.5.x and earlier, the cache name mappings are in file confluence/WEB-INF/classes/com/atlassian/confluence/admin/actions/cache-name-mappings.properties . For Confluence 2.6.0 and later, you will find the cache name mappings in the file com/atlassian/confluence/core/ConfluenceActionSupport.properties which is packed into the confluence-2.x.*.jar file. 2. Find the appropriate <cache-mapping> tag in confluence-coherence-cache-config.xml or confluence-coherence-cache-config-clustered.xml. If the tag doesn't exist, you can create it within the <caching-scheme-mapping>tag.
Attached to this page are corrected copies of confluence-coherence-cache-config.xml and confluence-coherence-cache-config-clustered.xml. These are updated from a bug CONF-11857.
3. The <scheme-name> will correspond to a <local-scheme>tag below. It refers to a scheme reference. Either change the high-units tag in the scheme reference, or add a high-units tag to override the scheme reference. For example, the following tag would change the Content Bodies cache from the default 1000 units to 2000 units:
<local-scheme> <scheme-name>cache:com.atlassian.confluence.core.ContentEntityObject.bodyContents</scheme-name><high-units>
4. After updating the appropriate file, you do not need to repack it into the jar to use it. You can simply place the file in your confluence/WEB-INF/classes/ directory. The file in this directory will override the settings in your jar file. If you want to back out the changes, you only need to remove the file from your confluence/WEB-INF/classes/ directory then the default values in the confluence-coherence-cache-config.xml located in your jar file will apply. You can find more information about configuring the Coherence cache in the Coherence cache documentation.
RELATED TOPICS
Cache Performance Tuning Performance Testing Scripts Confluence Cache Schemes Working with Confluence Logs Operating Large or Mission-Critical Confluence Installations Confluence Clustering Overview Requesting Performance Support Confluence Administrator's Guide Confluence Configuration Guide
239
If a cache has not been defined, then it will use the default cache size and expiry. As the start of your confluence/WEB-INF/classes/confluence-coherence-cache-config.xml file you will notice the following:
So basically all caches will default to using the default scheme, which is defined as below:
<!-- Default scheme --> <local-scheme> <scheme-name>default</scheme-name> <class-name>com.atlassian.confluence.cache.tangosol.ExpiryCountingLocalCache</class-name> <high-units>1000</high-units> <expiry-delay>3600</expiry-delay> </local-scheme>
I.e. with a size of 1000 Objects and an expiry of 3600 seconds. Other schemes use the above as their default and either override the size of the cache, or the length of the expiry.
Common Schemes
In addition to the default scheme, there are also common schemes used in Confluence caches:
<!-- Common schemes --> <local-scheme> <scheme-name>large</scheme-name> <scheme-ref>default</scheme-ref> <high-units>10000</high-units> </local-scheme> <local-scheme> <scheme-name>medium</scheme-name> <scheme-ref>default</scheme-ref> <high-units>5000</high-units> </local-scheme> <local-scheme> <scheme-name>small</scheme-name> <scheme-ref>default</scheme-ref> <high-units>100</high-units> </local-scheme> <local-scheme> <scheme-name>large-transient</scheme-name> <scheme-ref>default</scheme-ref> <high-units>10000</high-units> <expiry-delay>300s</expiry-delay> </local-scheme> <local-scheme> <scheme-name>user</scheme-name> <scheme-ref>default</scheme-ref> <high-units>5000</high-units> <expiry-delay>300s</expiry-delay> </local-scheme>
RELATED TOPICS
240
Cache Performance Tuning Confluence Cache Schemes Cache Performance Tuning for Specific Problems Requesting Performance Support Confluence Administrator's Guide Confluence Configuration Guide
Embedded Database
The embedded HSQL database that comes with Confluence essentially holds all your data in memory while the Confluence server is running. If you are running out of memory, you should consider migrating Confluence to some external RDBMS.
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 customise Confluence's cache to meet your needs, see cache tuning. To increase the amount of memory available to confluence, see Fix Out of Memory Errors by Increasing Available Memory.
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.
241
or in bin/setenv.sh, set:
If you modify bin/setenv.sh, you will need to restart Confluence for the changes to take effect. What can you do to minimise 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 minimise the impact that garbage collection has on the running application.
System Information
Confluence Server
Take a screenshot of Confluence's Administration Take a screenshot of Confluence's Administration System Information (or save the page as HTML) Cache Statistics (or save the page as HTML)
242
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.
243
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 audit Confluence - enabling user access logging, including redirecting the logs to a separate file You can run this file through a log file analyser such as AWStats, or manually look through for pages which are slow to load.
244
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.
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. If your site is non-responsive, please use our Live Support during business hours once you have created the ticket to escalate your problem.
Note All scripts are written in Ruby and assume the log file name contains the string 'confluence.atlassian.com-access.log'. Scripts need to be changed if another name is used. Modify the line: filenameRegexp = Regexp.new('confluence.atlassian.com-access.log')
On this page: Enabling Page-Request Profiling Profiling an Activity Example of a Profile Start Confluence with Profiling Enabled
245
To see just the slow performing macros, see Identifying Slow Performing Macros.
From Confluence 2.7, you can use the 'Logging and Profiling' option to enable or disable profiling. You need to have System Administrator permissions in order to perform this function. To enable page profiling,
1. Go to the 'Administration Console' and click 'Logging and Profiling' in the 'Administration' section of the left-hand panel. 2. The 'Logging and Profiling' screen appears. Click the 'Enable Profiling' button. If profiling is already enabled, the button will be labelled 'Disable Profiling' instead.
1. Go to the 'Administration Console' and click 'Logging and Profiling' in the 'Administration' section of the left-hand panel. 2. The 'Logging and Profiling' screen appears. Click the 'Disable Profiling' button. If profiling is already disabled, the button will be labelled 'Enable Profiling' instead.
246
Profiling an Activity
1. 247
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() [16ms] - AOP: SpacePermissionManager.hasPermission() [0ms] - AOP: SpacePermissionManager.hasPermission() [0ms] - AOP: SpacePermissionManager.hasPermission() [281ms] - XW Interceptor: After defaultStack: /pages/viewpage.action (ViewPageAction.execute()) [281ms] - XW Interceptor: After validatingStack: /pages/viewpage.action (ViewPageAction.execute()) ...
<filter> <filter-name>profiling</filter-name> <filter-class>com.atlassian.core.filters.ProfilingAndErrorFilter</filter-class> <init-param> <!-- specify the which HTTP parameter to use to turn the filter on or off --> <!-- if not specified - defaults to "profile.filter" --> <param-name>activate.param</param-name> <param-value>profile</param-value> </init-param> <init-param> <!-- specify the whether to start the filter automatically --> <!-- if not specified - defaults to "true" --> <param-name>autostart</param-name> <param-value>true</param-value> </init-param> </filter>
Remember to turn it back to false or your logs will grow very large.
RELATED TOPICS
248
sends to the user. This will speed up Confluence over slow or congested Internet links, and reduce the amount of bandwidth consumed by a Confluence server. Gzipping the HTTP Response is available in Confluence 1.4 and later. You should 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 having to compress each HTTP response may in fact slow Confluence down.
Known issues in Confluence 2.7 and earlier There are known issues with the GZip filter and memory consumption evident in versions 2.7 of Confluence and earlier ( CONF-9930). If you are running a large instance of Confluence 2.7 or earlier and frequently experiencing 'out of memory' errors, we recommend that you do not enable HTTP compression. These issues have been resolved in Confluence 2.8.
Introduction
Before making a new Confluence instance available to your users it is useful to get a feel for how it will perform under your anticipated load and where you may need to consider improving your configuration to remove bottlenecks. Likewise, before making changes to your Confluence instance it would again be useful to assess the impact of these changes before making them live in a production context. This kind of testing is not an exact science but the tools and process described here are intended to be a straightforward, configurable and extensible way of allowing you to begin this kind of load testing. It will rarely be the case that these scripts will perform representative testing for you 'out of the box'. But either through configuration or by extending the scripts it should be possible to build an appropriate load test.
249
Load testing scripts are not designed for a production environment The load testing scripts will update the data within the targeted Confluence instance and are not designed to be run against a production server. If you want to load test your production environment you will need to perform these tests on a backup of your data and restore your real data after the tests.
On this page: Load Testing Confluence Introduction Setup Quick, Just Tell Me How To Run It. Creating the Test Data Running the Test
Setup
You will need the following A Confluence server, set up and running with an admin user. The scripts assume a default username and password for this user: 'admin'/'admin'. Ensure the Confluence Remote API is enabled in the administration options. See Enabling the Remote API for details on how to configure this. Apache JMeter The load testing scripts and resources which are available in our public Maven repository Please choose the version that most closely matches your Confluence version and download the ZIP or Gzip file in that directory. If in doubt, download the ZIP file archive.
Users have reported problems when using the Windows built-in unzip utility. Please use a third party file archiving and extraction program (for example, 7-Zip) to extract these performance tests.
The test scripts have been updated to work with Confluence 3.4 in version 3.4. Using an older version of the tests will result in errors when running the test.
<jmeter location>/bin/jmeter -n -t jmeter-test-setup.jmx -Jspace.zip=<path to a demo space ZIP file> -Jadmin.user=<username> -Jadmin.pass=<password>
250
Where: <path to a space export.zip> is the absolute path to the space export zip you want to be used in your testing. For example, the path to demo-site.zip as found in your Confluence distribution or source: <confluence install>/confluence/WEB-INF/classes/com/atlassian/confluence/setup/demo-site.zip <username> and <password> are the username and password for an admin user that is able to create Confluence users and to import spaces. By default the setup process will create 250 users 50 each of the following formats: tstreader<n>, tstcommentor<n>, tsteditor<n>, tstcreator<n> and tstsearcher<n>. The password for each matches the username. A typical run of the setup script will only take a few seconds.
251
Control whether the test space will be created (or removed). The number of users to be created for making comments. The number of users to be created for adding pages. The number of users to be created for editing existing pages. The number of users to be created for viewing existing pages. The number of users to be created for performing searches. The number of users to be created for downloading site resources. The number of users to be created for downloading attachments.
Created the tree successfully Starting the test @ Mon Apr 14 17:35:08 EST 2008 (1208158508222) Tidying up ... @ Mon Apr 14 17:35:08 EST 2008 (1208158508928) ... end of run
The scripts location/results directory will contain the file jmeter-result-setuptest.jtl. There were failures or errors if there are any assertions in this file that have the value true for the failure or error element, e.g.
<assertionResult> <name>Manage Users</name> <failure>true</failure> <error>false</error> <failureMessage>Test failed: URL expected to contain /browseusers.action/</failureMessage> </assertionResult>
Where: <scripts location> is the absolute path to where you extracted the scripts e.g. /Users/YourName/Download/performanceTest. This is needed for the script to find its external resources.
Test Behaviour
The test has a number of parameters to tweak its behaviour but generally speaking it has the rough format of: 5 groups of users - readers, commentors, searchers, editors and creators. readers simply view a set of individual pages or browse space functionality. commentors add comments to a set of pages. searchers perform searches on a fixed set of keywords. editors make small additions to the end of a set of pages. creators add new pages to a particular space. Each individual user in each group will repeat for a fixed amount of time with a small pause between each request. Note that there is no execution of JavaScript by the client. Keep this in mind if you use this test to gauge Confluence performance in a
252
production environment. There is also very little use of permissions in these tests. All data involved is accessible to all of the test users.
Test Thread Parameters Parameter threads.reader pause.reader threads.searcher pause.searcher threads.creator pause.creator threads.editor pause.editor threads.commentor pause.commentor Default 15 2000 8 2000 3 2000 3 2000 4 2000 Explanation Number of readers. The approximate (within 500ms) millisecond pause between reader repeats. Number of searchers. The approximate (within 500ms) millisecond pause between searcher repeats. Number of page creators. The approximate (within 500ms) millisecond pause between creator repeats. Number of page editors. The approximate (within 500ms) millisecond pause between editor repeats. Number of page commentors. The approximate (within 500ms) millisecond pause between commentor repeats.
In version 3.0 of the tests, it's now possible to control the percentage executions of certain actions. These percentages are defined in the "Thread Details" configuration screen.
So with the default parameters, you are emulating a load on Confluence of 33 concurrent users who will each be hitting the server approximately every 2 seconds (16 users per second). 23 of these users are read only (searchers or readers) and 10 of them are read/write 11 read only users per second and 5 read/write users per second.
253
Created the tree successfully Starting the test @ Fri Apr 18 Display Summary Results During (0.22%) Display Summary Results During (0.00%) Display Summary Results During (0.06%) Display Summary Results During (0.00%) Display Summary Results During (0.04%) Display Summary Results During (0.00%) Display Summary Results During (0.03%) Display Summary Results During (0.00%) Display Summary Results During (0.02%) Display Summary Results During (0.00%) Display Summary Results During
00:07:39 EST 2008 (1208441259523) Run + 462 in 77.6s = 5.9/s Avg: 1564 Min: 18 Max: 33738 Err: 1 Run + 1338 in 189.9s = 7.0/s Avg: 3596 Min: 24 Max: 34545 Err: 0 Run = 1800 in 257.6s = 7.0/s Avg: 3074 Min: 18 Max: 34545 Err: 1 Run + 1046 in 200.9s = 5.2/s Avg: 4529 Min: 40 Max: 50461 Err: 0 Run = 2846 in 438.2s = 6.5/s Avg: 3609 Min: 18 Max: 50461 Err: 1 Run + 677 in 201.2s = 3.4/s Avg: 6638 Min: 46 Max: 27636 Err: 0 Run = 3523 in 618.1s = 5.7/s Avg: 4191 Min: 18 Max: 50461 Err: 1 Run + 561 in 197.5s = 2.8/s Avg: 8326 Min: 171 Max: 39494 Err: 0 Run = 4084 in 798.3s = 5.1/s Avg: 4759 Min: 18 Max: 50461 Err: 1 Run + 555 in 199.2s = 2.8/s Avg: 8247 Min: 160 Max: 45270 Err: 0 Run = 4639 in 978.0s = 4.7/s Avg: 5177 Min: 18 Max: 504
Please do not use the Concurrent Mark Sweep (CMS) Collector with Confluence, unless otherwise advised by Atlassian Support. It requires extensive manual tuning and testing, and is likely to result in degraded performance.
Summary
1. Set the Young space up to 30-40% of the overall heap: -XX:NewSize=<between 30% and 40% of your Xmx value, eg, 384m> 2. Use a parallel collector: -XX:+UseParallelOldGC (make sure this is Old GC) 3. limit the Tomcat connector's spare thread counts to minimize impact 4. effectively disable explicit garbage collection triggered from distributed remote clients -Dsun.rmi.dgc.client.gcInterval=900000 -Dsun.rmi.dgc.server.gcInterval=900000 5. Disable remote clients from triggering a full GC event -XX:+DisableExplicitGC 6. set the minimum and maximum Xmx and Xms values as the same (eg. -Xms1024m -Xmx1024m) to discourage address map swapping 7. Turn on GC logging (add the flags -verbose:gc -Xloggc:<full-path-to-log> -XX:+PrintGCTimeStamps -XX:+PrintGCDetails) and submit the logs in a support ticket 8. Use Java 1.6 9. Read below if heap > 2G See Configuring System Properties for how to add these properties to your environment.
Background
Performance problems in Confluence, and in rarer circumstances for JIRA, generally manifest themselves in either: frequent or infrequent periods of viciously sluggish responsiveness, which requires a manual restart, or, the application eventually and almost inexplicably recovers some event or action triggering a non-recoverable memory debt, which in turn envelops into an application-fatal death spiral (Eg. overhead GC collection limit reached, or Out-Of-Memory). generally consistent poor overall performance across all Confluence actions
254
There are a wealth of simple tips and tricks that can be applied to Confluence, that can have a significantly tangible benefit to the long-term stability, performance and responsiveness of the application. On this page: Summary Background Why Bad Things Happen Appreciate how Confluence and the JAVA JVM use memory Memory is contiguous Figure out which (default) collector implementation your vendor is using Use the Parallel Garbage Collector Restrict ability of Tomcat to 'cache' incoming requests Disable remote (distributed) garbage collection by Java clients Virtual Machines are Evil Use Java 1.6 Use -server flag If using 64bit JRE for larger heaps, use CompressedOops Use NUMA if on SPARC, Opteron or recent Intel (Nehalem or Tukwila onwards) Use 32bit JRE if Heap < 2GB JVM core dumps can be instigated by memory pressures Artificial Windows memory limit Instigate useful monitoring techniques Tuning the frequency of full collections Performance tuning works
Memory is contiguous
The Java memory model requires that memory be allocated in a contiguous block. This is because the heap has a number of side data structures which are indexed by a scaled offset (ie n*512 bytes) from the start of the heap. For example, updates to references on objects within the heap are tracked in these "side" data structures. Consider the differences between: 1. Xms (the allocated portion of memory) 2. Xmx (the reserved portion of memory) Allocated memory is fully backed, memory mapped physical allocation to the application. That application now owns that segment of memory. Reserved memory (the difference between Xms and Xmx) is memory which is reserved for use, but not physically mapped (or backed) by memory. This means that, for example, in the 4G address space of a 32bit system, the reserved memory segment can be used by other applications, but, because Java requires contiguous memory, if the reserved memory requested is occupied the OS must swap that memory out of the reserved space either to another non-used segment, or, more painfully, it must swap to disk. Permanent Generation memory is also contiguous. The net effect is even if the system has vast quantities of cumulative free memory, Confluence demands contiguous blocks, and consequently undesirable swapping may occur if segments of requested size do not exist. See Causes of OutOfMemoryErrors for more details. Please be sure to position Confluence within a server environment that can successfully complete competing requirements (operating
255
For larger instances with performance issues, it is recommended to tune Confluence such that there is a large Young space, at up to 50% the overall size of the heap.
-XX:NewSize=XXXm where XXX is the size in megabytes, is the command line parameter. -XmnXXXm can also be used interchangeably. Ie. -XX:NewSize=700m, -Xmn700m By setting a larger NewSize, the net effect is that the JRE will spend less time garbage collecting, clearing dead memory references, compacting and copying memory between spaces, and more time doing actual work.
<Connector port="8090" protocol="HTTP/1.1" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" useBodyEncodingForURI="true" enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true"/>
Here the Tomcat Connector is configured for 150 "maxThreads" with an "acceptCount" of 100. This means up to 150 threads will awaken to accept (but importantly not to complete) web requests during performance outages, and 100 will be cached in a queue for further processing when threads are available. That's 250 threads, many of which can be quite expensive in and of themselves. Java will attempt to juggle all these threads concurrently and become extremely inefficient at doing so, exasperating the garbage collection performance issue. Resolution: reduce the number of maxThreads and acceptCount to something slightly higher than normal 'busy-hour' demands.
256
257
# # # # # # # # #
An unexpected error has been detected by HotSpot Virtual Machine: SIGSEGV (0xb) at pc=0xfe9bb960, pid=20929, tid=17 Java VM: Java HotSpot(TM) Server VM (1.5.0_01-b08 mixed mode) Problematic frame: V [libjvm.so+0x1bb960]
---------------
T H R E A D
siginfo:si_signo=11, si_errno=0, si_code=1, si_addr=0x00000000 Registers: O0=0xf5999882 O4=0x00000000 G1=0xfe9bb80c G5=0xc24ff380 PC=0xfe9bb960
then you should upgrade the JVM. See SIGSEGV Segmentation Fault JVM Crash.
# # A fatal error has been detected by the Java Runtime Environment: # # java.lang.OutOfMemoryError: requested 8388608 bytes for GrET in C:\BUILD_AREA\jdk6_18\hotspot\src\share\vm\utilities\growableArray.cpp. Out of swap space? # # Internal Error (allocation.inline.hpp:39), pid=11572, tid=12284 # Error: GrET in C:\BUILD_AREA\jdk6_18\hotspot\src\share\vm\utilities\growableArray.cpp # # JRE version: 6.0_18-b07 # Java VM: Java HotSpot(TM) Server VM (16.0-b13 mixed mode windows-x86 ) # If you would like to submit a bug report, please visit: # http://bugreport.sun.com/bugreport/crash.jsp # --------------T H R E A D --------------GCTaskThread [stack: 0x00000000,0x00000000] [id=12284]
or,
258
# # # # # # # # # # # # #
A fatal error has been detected by the Java Runtime Environment: java.lang.OutOfMemoryError: requested 123384 bytes for Chunk::new. Out of swap space? Internal Error (allocation.cpp:215), pid=10076, tid=4584 Error: Chunk::new JRE version: 6.0_18-b07 Java VM: Java HotSpot(TM) Server VM (16.0-b13 mixed mode windows-x86 ) If you would like to submit a bug report, please visit: http://bugreport.sun.com/bugreport/crash.jsp
---------------
T H R E A D
---------------
Workarounds include: changing the server OS to something other than Windows. For example, Linux switching to the 64 bit Tomcat wrapper (this is not supported) reducing memory allocation to the Tomcat process. Try backing off 100MB at a time and observe the results.
Great tools available include: The excellent VisualVM, documentation. Thread Dump Analyzer - a great all-round thread debugging tool, particularly for identifying deadlocks. Samurai, an excellent alternative thread analysis tool, good for iterative dumps over a period of time. GC Viewer - getting a bit long in the tooth, but is a good mainstay for GC analysis. GChisto - A GC analysis tool written by members of the Sun Garbage Collection team. Documentation: Sun's White Paper on Garbage Collection in Java 6. Sun's state-of-the-art JavaOne 2009 session on garbage collection (registration required). IBM stack: Java 5 GC basics for WebSphere Application Server. An Excellent IBM document covering native memory, thread stacks, and how these influence memory constricted systems. Highly recommended for additional reading. The complete list of JRE 6 options I strongly recommend viewing George Barnett's Summit 2010 performance presentation, Pulling a Rabbit from a Hat.
Atlassian recommends at the very least to get VisualVM up and running (you willneed JMX), and to add Access and Garbage Collection logging.
259
Atlassian would classify frequency tuning on collections as an advanced topic for further experimentation, and is provided for informational purposes only. Unfortunately, it's impractical for Atlassian to support these kinds of changes in general.
Scheduled Jobs
The administration console allows you to schedule various administrative jobs in Confluence, so that they are executed at regular time intervals. The types of jobs which can be scheduled cover: Confluence site backups Storage optimisation jobs to clear Confluence's temporary files and caches Index optimisation jobs to ensure Confluence's search indexes are up to date Mail queue optimisation jobs to ensure Confluence's mail queue is maintained and notifications have been sent. You need to have System Administrator permissions in order to configure and execute jobs. On this page: Accessing Confluence's Scheduled Jobs Configuration Executing a Job Manually Configuring a Job's Schedule Disabling/Re-enabling a Job Viewing a Job's Execution History Types of Jobs Cron Expressions
260
261
Disabling/Re-enabling a Job
By default, all jobs in Confluence are enabled. 1. Access the 'Scheduled Jobs' configuration page (above). 2. Locate the job you wish to disable/re-enable. Refer to 'Types of Jobs' (below) for detailed descriptions about each job. If a job is enabled, click its 'Disable' link in the 'Actions' column to disable the job. If a job is disabled, click its 'Enable' link in the 'Actions' column to enable the job. Not all jobs in Confluence can be disabled.
262
Types of Jobs
Job Name Description Execution Behaviour Per cluster Default Schedule At 2am every day Every 30 seconds
For clustered Confluence installations, this job ensures that only one Confluence instance in the cluster writes to the database at a time. For standard (non-clustered) editions of Confluence, this job is useful for alerting customers who have accidentally connected a second Confluence instance to a Confluence database which is already in use. Triggers a periodical clean of the index queue to ensure that its size does NOT grow indefinitely. Cleans up temporary files generated in the 'temp' subdirectory of the Confluence home directory. This temp directory may be created by exports etc.
Per cluster
Clean Index Queue Clean Temporary Directory Clear Expired Mail Errors Clear Expired Remember Me Tokens
Per cluster
Per node
Clears notification errors in the mail error queue. A notification error is sent to the mail error queue whenever the notification fails to be sent due to an error.
Per cluster
Clears all expired 'Remember Me' tokens from the Confluence site. Remember Me tokens expire after two weeks.
Per cluster
263
Emails a daily summary report of all Confluence changes to all subscribers. 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 whilst keeping the job's frequency to 24 hours. Flushes changes to the 'Did You Mean' index, which keeps the 'Did You Mean' feature up to date. Confluence records each content update in the 'Did You Mean' index.
Per cluster
Per node
Every 2 hours from 12 am Every minute Every minute Every minute Every minute At 3am and 3pm every day
Flush Index Queue Flush Local Task Queue Flush Mail Queue Flush Task Queue Optimise Indexing
Flushes changes to Confluence's index so that Confluence's search results are up to date. Confluence records each content update in its search index. Flushes the local task queue. (These are internal Confluence tasks that are typically flushed at a high frequency.) Sends notifications that have been queued up in the mail queue.
Per node
Per node
Per cluster
Flushes the task queue. (These are internal Confluence tasks that are typically flushed at a high frequency.) Compacts the confluence indexes to maintain searching performance. This task is demanding on system resources and does not need to be performed too regularly. If you see Confluence performance deteriorate around 3pm, try scheduling this job for 3am only and check if search performance remains reasonable. Polls POP accounts on all spaces that have them configured.
Per node
Per node
Poll Mail
Per cluster
Every minute
Cron Expressions
A cron expression is a string of 6-7 'time interval' fields that defines the frequency with which a job is executed. Each of these fields can be expressed as either a numerical value or a special character and each field is separated by at least one space or tab character. The table below is shows the order of time interval fields in a cron expression and each field's permitted numerical values. You can specify a special character instead of a numerical value for any field in the cron expression to provide flexibility in defining a job's frequency. Common special characters include: '*' a 'wild card' that indicates 'all permitted values'. '?' indicates 'ignore this time interval' in the cron expression. That is, the cron expression will not be bound by the time interval (such as 'Month', 'Day of week' or 'Year') to which this character is specified. For more information about cron expressions, please refer to the Cron Trigger tutorial on the Quartz website. Order in cron expression 1 2 3 4 5 6 Time interval field Seconds Minutes Hours Day of month Month Day of week 0-59 0-59 0-23 1-31 1-12 or JAN-DEC 1-7 or SUN-SAT Yes Yes Yes Yes Yes Yes Permitted values* Required?
264
Year
1970-2099
No
RELATED TOPICS
Trigger Module Configuring Backups
Search
Page: Setup Confluence To Index External Sites Page: Setup External Search Tool To Index Confluence
Technical Reasons
Confluence indexes pages using a customised Lucene search engine that returns matching pages, mail and blog posts for which the searcher has view permission. It would require significant source code modifications to enable Confluence to process search results from external pages, as the indexing process has been customised to utilise internal Confluence metadata. Note that users can still index content from new attachment filetypes.
265
view content that will be indexed, you should create a Confluence user specifically for the search crawler to use. Grant this user view rights to all content you wish to index, but deny that user all delete and administration rights. This ensures that an aggressive crawler will not be able to perform actions that could modify the site. There is also a forum thread on Google Mini integration. External applications can also use the search function in the Confluence Remote API.
Related Information
Page: Setup Confluence To Index External Sites Page: Setup External Search Tool To Index Confluence Page: Setup External Search Tool To Index Confluence Page: Setup Confluence To Index External Sites Page: Setup External Search Tool To Index Confluence Page: Setup External Search Tool To Index Confluence Page: Setup Confluence To Index External Sites Page: Setup Confluence To Index External Sites Page: Setup Confluence To Index External Sites Page: Setup Confluence To Index External Sites Page: Setup External Search Tool To Index Confluence Page: Setup Confluence To Index External Sites Page: Setup External Search Tool To Index Confluence Page: Setup External Search Tool To Index Confluence Page: Setup External Search Tool To Index Confluence Page: Setup External Search Tool To Index Confluence Page: Setup External Search Tool To Index Confluence Page: Setup Confluence To Index External Sites Page: Setup External Search Tool To Index Confluence Page: Setup Confluence To Index External Sites Page: Integrate Confluence Search to Jira Search Page: Setup Confluence To Index External Sites Page: Setup Confluence To Index External Sites Page: Setup Confluence To Index External Sites Page: Setup External Search Tool To Index Confluence Page: Setup Confluence To Index External Sites Page: Setup External Search Tool To Index Confluence
266
Confluence uses Apache's log4j logging service. This allows a developer or administrator to control the logging behavior and the log output file by editing a configuration file, without touching the application binary. There are six known log4j logging levels. If you request help from Atlassian Support, we will almost always ask for the atlassian-confluence.log from the confluence-home/logs directory. You can access the logs from the Confluence Administration Console, via the support tool. If you cannot access the Confluence Administration Console, check the properties file at <confluence-installation>/confluence/WEB-INF/classes/confluence-init.properties, look for the confluence.home setting in that file, then find the logs in the Confluence home directory. On this page: Finding the Confluence Log Files Finding the Log Configuration File Changing the Destination of the Log Files Changing the Logging Levels Using Some Specific Confluence Logging Options Scanning Log Files for Known Problems Notes
267
See Configuring Logging for instructions on how to change the logging configuration of Confluence.
Notes
Finding the thread dumps. Thread dumps are logged to the application server log file.
RELATED TOPICS
Important Directories and Files Enabling Detailed SQL Logging Enabling user access logging Generating a Thread Dump Enabling Page Request Profiling Troubleshooting Problems and Requesting Technical Support
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. 2. Manually modifying the <Confluence-Install>\confluence\WEB-INF\classes\log4j.properties file.
268
User Management
Understanding User Management in Confluence Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Configuring the LDAP Connection Pool Configuring an SSL Connection to Active Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Reverting from Crowd or JIRA to Internal User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management Confluence User Management Searching For and Managing Users Adding a New User Adding a Group Adding or Removing Users in Groups Changing Usernames Editing User Details Global Groups Overview Global Permissions Overview Removing a Group Removing or Deactivating a User Setting up Anonymous Access Viewing members of a group Restoring Passwords To Recover Admin User Rights Resetting the Login Count for a User Disabling the Built-In User Management
269
On this page: Authentication Seraph XML-RPC and SOAP Authentication Password Authentication and User Management Confluence User Management Framework User Management via the Confluence Administration Console Information about Earlier User Management Frameworks
Authentication
Seraph
Almost all authentication in Confluence (and JIRA) 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 is correct) to Confluence's user management system. If you were looking 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.
270
Information about Earlier User Management Frameworks Atlassian-User Now Behind the Scenes
Atlassian-User is a user and group management framework developed by Atlassian. It provides user, group and profile management services to Confluence. In earlier versions of Confluence, you needed to configure your user directories by editing the atlassian-user.xml file directly. In Confluence 3.5 and later this is no longer necessary, nor is it possible. Please refer to the documentation for Confluence 3.4 or earlier, if you need details of this framework. Refer to the Confluence 3.5 Upgrade Notes for details of the automatic migration that will occur during the upgrade process.
OSUser Obsolete
OpenSymphony User was Confluence's core user management framework before Atlassian-User. Please refer to the documentation for Confluence 3.4 or earlier, if you need details of this framework.
RELATED TOPICS
HTTP authentication with Seraph User Management Understanding User Management in Confluence Configuring User Directories Confluence User Management Disabling the Built-In User Management
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. See Connecting to Crowd or JIRA for User Management. Atlassian JIRA 4.3 or later. See Connecting Confluence to JIRA for User Management.
271
Atlassian JIRA 4.2 or earlier, using the legacy database connection. See Connecting to JIRA 4.2 or Earlier 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 behaviour 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 an administrator user active in your internal directory for troubleshooting problems with your user directories.
Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management Adding a New User Adding a Group
272
Overview
The internal directory is enabled by default at installation. When you create the first administrator during the setup procedure, that administrator's username and other details are stored in the internal directory. If needed, you can configure one or more additional user directories. This is useful if you want to grant access to users and groups that are stored in a corporate directory or other directory server. On this page: Overview Diagram of Possible Configuration
Diagram above: Confluence using its internal directory for user management.
RELATED TOPICS
Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management How to Reenable the Internal Directory (Knowledge base article)
273
Overview
An LDAP directory is a collection of data about users and groups. LDAP (Lightweight Directory Access Protocol) is an Internet protocol that web applications can use to look up information about 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. On this page: Overview Connecting to an LDAP Directory in Confluence Server Settings Schema Settings Permission Settings Adding Users to Groups Automatically Advanced Settings User Schema Settings Group Schema Settings Membership Schema Settings Diagrams of Some Possible Configurations
2. 3.
4. 5. 6.
Server Settings
Setting Description
274
Name
Enter a meaningful name to help you identify the LDAP directory server. Examples: Example Company Staff Directory Example Company Corporate LDAP
Directory Type
Select the type of LDAP directory that you will connect to. If you are adding a new LDAP connection, the value you select here will determine the default values for many of the options on the rest of screen. Examples: Microsoft Active Directory OpenDS And more.
Hostname
The host name of your directory server. Examples: ad.example.com ldap.example.com opends.example.com
Port
The port on which your directory server is listening. Examples: 389 10389 636 (for example, for SSL)
Use SSL
Tick this check box if the connection to the directory server is an SSL (Secure Sockets Layer) connection. Note that you will need to configure an SSL certificate in order to use this setting. The distinguished name of the user that the application will use when connecting to the directory server. Examples: cn=administrator,cn=users,dc=ad,dc=example,dc=com cn=user,dc=domain,dc=name [email protected]
Username
Password
Schema Settings
Setting Base DN Description The root distinguished name (DN) to use when running queries against the directory server. Examples: o=example,c=com cn=users,dc=ad,dc=example,dc=com For Microsoft Active Directory, specify the base DN in the following format: dc=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. Additional User DN This value is used in addition to the base DN when searching and loading users. If no value is supplied, the subtree search will start from the base DN. Example: ou=Users Additional Group DN This value is used in addition to the base DN when searching and loading groups. If no value is supplied, the subtree search will start from the base DN. Example: ou=Groups
Permission Settings
Setting Read Only Description LDAP users, groups and memberships are retrieved from your directory server and can only be modified via your directory server. You cannot modify LDAP users, groups or memberships via the application administration screens.
275
LDAP users, groups and memberships are retrieved from your directory server and can only be modified via your directory server. You cannot modify LDAP users, groups or memberships via the application administration screens. However, you can add groups to the internal directory and add LDAP users to those groups.
LDAP users, groups and memberships are retrieved from your directory server. When you modify a user, group or membership via the application administration screens, the changes will be applied directly to your LDAP directory server. Please ensure that the LDAP user specified for the application has modification permissions on your LDAP directory server.
Advanced Settings
Setting Enable Nested Groups Description Enable or disable support for nested groups. Some directory servers allow you to define a group as a member of another group. Groups in such a structure are called 'nested groups'. 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 or disable the use of the LDAP control extension for simple paging of search results. If paging is enabled, the search will retrieve sets of data rather than all of the search results at once. Enter the desired page size that is, the maximum number of search results to be returned per page when paged results are enabled. The default is 1000 results. Choose whether to allow the directory server to redirect requests to other servers. This option uses the node referral (JNDI lookup java.naming.referral) configuration setting. It is generally needed for Active Directory servers configured without proper DNS, to prevent a 'javax.naming.PartialResultException: Unprocessed Continuation Reference(s)' error. If your directory server will always return a consistent string representation of a DN, you can enable naive DN matching. Using naive DN matching will result in a significant performance improvement, so we recommend enabling it where possible. This setting determines how your application will compare DNs to determine if they are equal. If this check box is ticked, 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 check box is not ticked, the application will parse the DN and then check the parsed version.
Follow Referrals
Naive DN Matching
276
Enable incremental synchronisation if you only want changes since the last synchronisation to be queried when synchronising a directory. Please be aware that when using this option, the user account configured for synchronisation must have read access to: The uSNChanged attribute of all users and groups in the directory that need to be synchronised. The objects and attributes in the Active Directory deleted objects container (see Microsoft's Knowledge Base Article No. 892806 for details). 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 JIRA.
Synchronisation Interval (minutes) Read Timeout (seconds) Search Timeout (seconds) Connection Timeout (seconds)
Synchronisation is the process by which the application updates its internal store of user data to agree with the data on the directory server. The application will send a request to your directory server every x minutes, where 'x' is the number specified here. The default value is 60 minutes. The time, in seconds, to wait for a response to be received. If there is no response within the specified time period, the read attempt will be aborted. A value of 0 (zero) means there is no limit. The default value is 120 seconds. The time, in seconds, to wait for a response from a search operation. A value of 0 (zero) means there is no limit. The default value is 60 seconds. This setting affects two actions. The default value is 0. The time to wait when getting a connection from the connection pool. A value of 0 (zero) means there is no limit, so wait indefinitely. The time, in seconds, to wait when opening new server connections. A value of 0 (zero) means that the TCP network timeout will be used, which may be several minutes.
277
The attribute field to use when loading the user's email address. Example: mail The attribute field to use when loading a user's password. Example: unicodePwd
278
Diagram above: Confluence connecting to an LDAP directory with permissions set to read only and local groups.
RELATED TOPICS
279
Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
Setting
Description
Default Value 1
The number of LDAP connections created when initially connecting to the pool.
The optimal pool size. LDAP will remove idle connections when the number of connections grows larger than this value. A value of 0 (zero) means that there is no preferred size, so the number of idle connections is unlimited. The maximum number of connections. When the number of connections reaches this value, LDAP will refuse further connections. As a result, requests made by an application to the LDAP directory server will be blocked. A value of 0 (zero) means that the number of connections is unlimited. The length of time, in seconds, that a connection may remain idle before being removed from the pool. When the application is finished with a pooled connection, the connection is marked as idle, waiting to be reused. A value of 0 (zero) means that the idle time is unlimited, so connections will never be timed out. Only these protocol types will be allowed to connect to the LDAP directory server. If you want to allow multiple protocols, enter the values separated by a space. Valid values are: plain ssl
10
30
Pool Protocol
Pool Authentication
Only these authentication types will be allowed to connect to the LDAP directory server. If you want to allow multiple authentication types, enter the values separated by a space. See RFC 2829 for details of LDAP authentication methods. Valid values are: none simple DIGEST-MD5
Notes:
280
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. RELATED TOPICS Connecting to an LDAP Directory Configuring User Directories
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 Internet Information Services (IIS) Windows Certificate Services Description This is required before you can install Windows Certificate Services. This installs a certification authority (CA) which is used to issue certificates. Step 1, below, explains this process. Required if you are using Windows 2000 Required if you are using Windows 2000. Provides the highest available encryption level (128-bit).
Windows 2000 Service Pack 2 Windows 2000 High Encryption Pack (128-bit)
281
4. On the Select Server Roles page, select the Active Directory Certificate Services check box. Click Next twice.
5. On the Select Role Services page, select the Certification Authority check box, and then click Next.
282
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.
283
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.
284
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.
285
11. After verifying the information on the Confirm Installation Selections page, click Install.
286
12. Review the information on the results screen to verify that the installation was successful.
287
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:
1. Navigate to the directory in which Java is installed. It's probably called something like 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:
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
You may now use the 'Secure SSL' option when connecting your application to your directory server.
UNIX
1. Navigate to the directory in which Java is installed. cd $JAVA_HOME will usually get you there. 2. Run the command below, where server-certificate.crt is the name of the file from your directory server:
3. keytool will prompt you for a password. The default keystore password is changeit. 4. When prompted Trust this certificate? [no]: enter yes to confirm the key import:
Password: Enter keystore password: changeit Owner: CN=ad01, C=US Issuer: CN=ad01, C=US Serial number: 15563d6677a4e9e4582d8a84be683f9 Valid from: Tue Aug 21 01:10:46 ACT 2007 until: Tue Aug 21 01:13:59 ACT 2012 Certificate fingerprints: MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE SHA1: 73:73:4E:A6:A0:D1:4E:F4:F3:CD:CE:BE:96:80:35:D2:B4:7C:79:C1 Trust this certificate? [no]: yes Certificate was added to keystore
You may now use the 'Secure SSL' option when connecting your application to your directory server.
Mac OS X
1. Navigate to the directory in which Java is installed. This is usually /Library/Java/Home. 2. Run the command below, where server-certificate.crt is the name of the file from your directory server:
288
3. keytool will prompt you for a password. The default keystore password is changeit. 4. When prompted Trust this certificate? [no]: enter yes to confirm the key import:
Password: Enter keystore password: changeit Owner: CN=ad01, C=US Issuer: CN=ad01, C=US Serial number: 15563d6677a4e9e4582d8a84be683f9 Valid from: Tue Aug 21 01:10:46 ACT 2007 until: Tue Aug 21 01:13:59 ACT 2012 Certificate fingerprints: MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE SHA1: 73:73:4E:A6:A0:D1:4E:F4:F3:CD:CE:BE:96:80:35:D2:B4:7C:79:C1 Trust this certificate? [no]: yes Certificate was added to keystore
You may now use the 'Secure SSL' option when connecting your application to your directory server. RELATED TOPICS Connecting to an LDAP Directory Configuring User Directories
Overview
An internal directory with LDAP authentication offers the features of an internal directory while allowing you to store and check users' passwords in LDAP only. Note that the 'internal directory with LDAP authentication' is separate from the default 'internal 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. On this page: Overview Connecting Confluence to an Internal Directory with LDAP Authentication Server Settings Copying Users on Login Schema Settings Advanced Settings User Schema Settings Group Schema Settings Membership Schema Settings Diagrams of Possible Configurations
4. Enter the values for the settings, as described below. 5. Save the directory settings. 6. If you want LDAP users to be used in place of existing internal users, move the 'Internal with LDAP Authentication' directory to the top of the list. You can define the directory order by clicking the blue up- and down-arrows next to each directory on the 'User Directories' screen. Here is a summary of how the directory order affects the processing: The order of the directories is the order in which they will be searched for users and groups. Changes to users and groups will be made only in the first directory where the application has permission to make changes. For details see Managing Multiple Directories. 7. Add your users and groups in Confluence. See Adding a New User and Adding a Group.
Server Settings
Setting Name Description A descriptive name that will help you to identify the directory. Examples: Internal directory with LDAP Authentication Corporate LDAP for Authentication Only Directory Type Select the type of LDAP directory that you will connect to. If you are adding a new LDAP connection, the value you select here will determine the default values for some of the options on the rest of screen. Examples: Microsoft Active Directory OpenDS And more. Hostname The host name of your directory server. Examples: ad.example.com ldap.example.com opends.example.com Port The port on which your directory server is listening. Examples: 389 10389 636 (for example, for SSL) Use SSL Select this check box if the connection to the directory server is an SSL (Secure Sockets Layer) connection. Note that you will need to configure an SSL certificate in order to use this setting. The distinguished name of the user that the application will use when connecting to the directory server. Examples: cn=administrator,cn=users,dc=ad,dc=example,dc=com cn=user,dc=domain,dc=name [email protected] Password The password of the user specified above.
Username
290
This field appears if you select the Copy User on Login check box. If you would like users to be automatically added to a group or groups, enter the group name(s) here. To specify more than one group, separate the group names with commas. Each time a user logs in, their group memberships will be checked. If the user does not belong to the specified group(s), their username will be added to the group(s). If a group does not yet exist, it will be added to the internal directory that is using LDAP for authentication. Please note that there is no validation of the group names. If you mis-type the group name, authorisation 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-users,jira-developers
This field appears if you select the Copy User on Login check box. If this check box is selected, group memberships specified on your LDAP server will be synchronised with Confluence each time the user logs in. If you select this check 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)
Schema Settings
Setting Base DN Description The root distinguished name (DN) to use when running queries against the directory server. Examples: o=example,c=com cn=users,dc=ad,dc=example,dc=com For Microsoft Active Directory, specify the base DN in the following format: dc=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 Name Attribute The attribute field to use when loading the username. Examples: cn sAMAccountName
Advanced Settings
Setting Use Paged Results Follow Referrals Description Enable or disable the use of the LDAP control extension for simple paging of search results. If paging is enabled, the search will retrieve sets of data rather than all of the search results at once. Enter the desired page size that is, the maximum number of search results to be returned per page when paged results are enabled. The default is 1000 results. Choose whether to allow the directory server to redirect requests to other servers. This option uses the node referral (JNDI lookup java.naming.referral) configuration setting. It is generally needed for Active Directory servers configured without proper DNS, to prevent a 'javax.naming.PartialResultException: Unprocessed Continuation Reference(s)' error.
291
The filter to use when searching user objects. Example: (&(objectCategory=Person)(sAMAccountName=*)) The RDN (relative distinguished name) to use when loading the username. The DN for each LDAP entry is composed of two parts: the RDN and the location within the LDAP directory where the record resides. The RDN is the portion of your DN that is not related to the directory tree structure. Example: cn
User First Name Attribute User Last Name Attribute User Display Name Attribute User Email Attribute
The attribute field to use when loading the user's first name. Example: givenName The attribute field to use when loading the user's last name. Example: sn The attribute field to use when loading the user's full name. Example: displayName
The attribute field to use when loading the user's email address. Example: mail
292
The attribute field to use when loading the user's groups. Example: memberOf
Use the User Membership Attribute, when finding the user's group membership
Select the check box if your directory server supports the group membership attribute on the user. (By default, this is the 'memberOf' attribute.) If this check box 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 retrieval. If this check box is not selected, your application will use the members attribute on the group ('member' by default) for the search.
293
Diagram above: Confluence connecting to an LDAP directory for authentication only, with each user synchronised with the internal directory when they log in to Confluence.
RELATED TOPICS
Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
294
management. The Crowd Administration Console provides a web interface for managing directories, users and their permissions. See the Crowd 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. 2. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click 'User Directories' in the left-hand panel. Add a directory and select type 'Atlassian Crowd'. Enter the settings as described below. Save the directory settings. Define the directory order by clicking the blue up- and down-arrows next to each directory on the 'User Directories' screen. Here is a summary of how the directory order affects the processing: The order of the directories is the order in which they will be searched for users and groups. Changes to users and groups will be made only in the first directory where the application has permission to make changes. For details see Managing Multiple Directories. If required, configure Confluence to use Crowd for single sign-on (SSO) too. See the Crowd documentation: Integrating Crowd with Atlassian Confluence.
3. 4. 5. 6.
7.
Crowd Permissions
Setting Read Only Description The users, groups and memberships in this directory are retrieved from Crowd and can only be modified via Crowd. You cannot modify Crowd users, groups or memberships via the application administration screens. The users, groups and memberships in this directory are retrieved from Crowd. When you modify a user, group or membership via the application administration screens, the changes will be applied directly to Crowd. Please ensure that the application has modification permissions for the relevant directories in Crowd. See the Crowd documentation: Specifying an Application's Directory Permissions.
Read/Write
295
Synchronisation is the process by which the application updates its internal store of user data to agree with the data on the directory server. The application will send a request to your directory server every x minutes, where 'x' is the number specified here. The default value is 60 minutes.
296
Application Password
The password used by your application when accessing the JIRA server that acts as user manager.
JIRA Permissions
Setting Read Only Description The users, groups and memberships in this directory are retrieved from the JIRA server that is acting as user manager. They can only be modified via that JIRA server. The users, groups and memberships in this directory are retrieved from the JIRA server that is acting as user manager. When you modify a user, group or membership, the changes will be applied directly to your application and to the JIRA server that is acting as user manager.
Read/Write
297
Diagram above: Confluence, JIRA and other applications connecting to Crowd for user management.
298
299
Diagram above: Confluence connecting to JIRA for user management, with JIRA in turn connecting to LDAP.
RELATED TOPICS
Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management
300
Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
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.
On this page: Option 1 Manually Recreate Users and Groups in Confluence Option 2 Transfer Crowd/JIRA Users and Groups to the Confluence Database
Creating backups is the only way to restore your data if something goes wrong. 1. 2. 3. 4. 5. From Confluence, create a full XML site backup including attachments. Stop Confluence. Make a backup copy of the Confluence home and installation directories. Repeat the above steps for your External Application. From your MySQL administration tool, create a database backup for the Crowd/JIRA and Confluence databases.
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.
301
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>.
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>.
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:
302
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:
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
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>;
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:
303
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:
Reset passwords 1. 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 Restoring 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. RELATED TOPICS Configuring User Directories
4. 5. 6. 7.
8.
304
Setting Name
Description A meaningful name that will help you to identify this JIRA server amongst your list of directory servers. Examples: JIRA Example Company JIRA
Datasource Location
The JNDI name of the JIRA datasource configured in your application server. Example: java:comp/env/jdbc/YourJiraDatasource In JIRA standalone distributions (using the default application server, Tomcat 6) you can construct the datasource location as follows: 1. Open your <jira_install>/conf/server.xml file in a text editor. 2. Look for the database setup section in that file. It looks something like this:
3. Copy the above lines (the 'Resource' section) and paste it to your Confluence's server.xml file (located at <confluence_install>/conf/server.xml), under the Context path. This will then expose the value of the name attribute as the JNDI resource locator. 4. Copy the JNDI name from the name parameter. In this example, the datasource location is: java:comp/env/jdbc/JiraDS
RELATED TOPICS
Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
Overview
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. On this page: Overview Configuring the Directory Order Effect of Directory Order Login Permissions Updating Users and groups
305
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.
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
The directory order is significant when granting the user permissions based on group membership. If the same username exists in more than one directory, the application will look for group membership only in the first directory where the username appears, based on the directory order. Example: You have connected two directories: The Customers directory and the Partners directory. The Customers directory is first in the directory order. A username jsmith exists in both the Customers directory and the Partners directory. The user jsmith is a member of group G1 in the Customers directory and group G2 in the Partners directory. The user jsmith will have permissions based on membership of G1 only, not G2.
Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
306
Login
When a user logs in, they will be allowed access to the application if they belong to an authorised group or any of its sub-groups.
Permissions
The user will be allowed access to a function if they belong to a group that has the necessary permissions, or if they belong to any of its sub-groups.
Examples
307
308
309
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 defined as 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:
RELATED TOPICS
Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
310
On this page: Affected Directory Types How it Works Finding the Time Taken to Synchronise Manually Synchronising the Cache Configuring the Synchronisation Interval
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 synchronisation 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 synchronisation task has copied that user's details into the cache. A periodic synchronisation task will run to update the database with any changes made to the external directory. The default synchronisation interval, or polling interval, is one hour (60 minutes). You can change the synchronisation interval on the directory configuration screen. You can manually synchronise 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.
311
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 synchronise more frequently, then your data will be more up to date. The downside of synchronising 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.
RELATED TOPICS
Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
312
Diagram above: Confluence using its internal directory for user management.
313
Diagram above: Confluence connecting to an LDAP directory with permissions set to read only and local groups.
314
Diagram above: Confluence connecting to an LDAP directory for authentication only, with each user synchronised with the internal directory when they log in to Confluence.
315
316
Diagram above: Confluence connecting to JIRA for user management, with JIRA in turn connecting to LDAP.
317
Diagram above: Confluence, JIRA and other applications connecting to Crowd for user management.
RELATED TOPICS
Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
318
On this page: General Recommendations Recommendations for Connecting to LDAP Optimal Number of Users and Groups in your LDAP Directory Redundant LDAP is Not Supported Specific Notes for Connecting to Active Directory Recommendations for Connecting to JIRA for User Management Single Sign-On Across Multiple Applications is Not Supported Custom Application Connectors are Not Supported Custom Directories are Not Supported Optimal Number of Users and Applications Recommendations
General Recommendations
Duplicate usernames across directories are not supported. If you are connecting to more than one user directory, please ensure that the usernames are unique to one directory. For example, if you have a user jsmith in both 'Directory1' and 'Directory2', that is an unsupported configuration. Be careful when deleting users in remote directories. If you are connecting to an LDAP directory, a Crowd directory or a JIRA directory, please take care when deleting users from the remote directory. If you delete a user that is associated with data in Confluence, this will cause problems in Confluence.
We performed internal testing of synchronisation with an AD server on our local network consisting of 10 000 users, 1000 groups and 200 000 memberships. We found that the initial synchronisation took about 5 minutes. Subsequent synchronisations 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 synchronisation 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 synchronisations are much faster for AD than for other LDAP servers.
319
Network topology. The further away your LDAP server is from your application server, the more latent LDAP queries will be. Database performance. As the synchronisation process caches data in the database, the performance of your database will affect the performance of the synchronisation. JVM heap size. If your heap size is too small for your userbase, you may experience heavy garbage collection during the synchronisation process which could in turn slow down the synchronisation.
Recommendations
Your environment Recommendation
320
If all the following are true: You have fewer than 500 users. You want to share user and group management across just a few applications, such as one JIRA server and one Confluence server, or two JIRA servers. You do not need single sign-on (SSO) between JIRA 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 JIRA. You do not have Bamboo. Or, if you do have Bamboo, you are happy not to integrate its user management with JIRA at the moment. You are happy to wait until at least July 2011, perhaps longer. If one or more of the following are true: You have more than 500 users. 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. You have Bamboo and you want to integrate its user management with JIRA immediately. If you are considering creating a custom directory connector to define your own storage for users and groups
Your environment meets the optimal requirements for using JIRA for user management.
We recommend that you install Atlassian Crowd for user management and SSO.
Please see if one of the following solutions will work for you: 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 developing a custom directory connector for Crowd.
RELATED TOPICS
Connecting to an LDAP Directory Connecting to Crowd or JIRA for User Management Configuring User Directories
321
2. 3. 4. 5.
Please refer to our knowedge base articles for troubleshooting user management and login issues. If the above resources do not help, continue below.
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 seraph-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:
322
Remove the '#' signs at the beginning of the lines, so that it looks like this:
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 or exploded WAR directory, then zip the full /logs subdirectory into a single file for us to examine.The logs subdirectory is located in your Confluence Home directory.
RELATED TOPICS
Troubleshooting Problems and Requesting Technical Support Configuring User Directories Configuring the Internal Directory Connecting to an LDAP Directory Connecting to an Internal Directory with LDAP Authentication Connecting to Crowd or JIRA for User Management Connecting to JIRA 4.2 or Earlier for User Management Managing Multiple Directories Managing Nested Groups Synchronising Data from External Directories Diagrams of Possible Configurations for User Management User Management Limitations and Recommendations Requesting Support for External User Management
Searching For and Managing Users Adding a New User Adding a Group Adding or Removing Users in Groups Changing Usernames Editing User Details Global Groups Overview Global Permissions Overview Removing a Group Removing or Deactivating a User Setting up Anonymous Access Viewing members of a group Restoring Passwords To Recover Admin User Rights Resetting the Login Count for a User
323
324
325
To search via the advanced user search: 1. Open the 'Manage Users' screen as described above. 2. If the 'Advanced' link is showing, click it. (If you see the 'Simple' link and no 'Advanced' link, then you're fine. The advanced search is already active.) 3. The advanced user search screen will appear, as shown below. 4. Complete one or more of the following fields: User Name Enter all or part of the person's username i.e. their login id, e.g. 'joe', or 'bloggs'. Full Name Enter all or part of the person's name, e.g. 'joe bloggs', or 'bloggs', or 'joe'. E-Mail Enter all or part of the person's email address, e.g. 'acme' 5. Click the 'Search' button. 6. Confluence will display a list of matching users. Click the link on a username to see and edit the details for that user.
Notes
Multiple user directories: You may define multiple user directories in Confluence, so that Confluence looks in more than one place for its users and groups. For example, you may use the default Confluence internal directory and also connect to an LDAP directory server. In such cases, 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. Crowd and the user search: If you are using Atlassian's Crowd for user management, you will need Crowd 1.5.1 or later to use the 'Simple' option in the user search. If your version of Crowd does not support the simple user search, you will see only the 'Advanced' search form.
RELATED TOPICS
Page: Removing a Group Page: Adding a New User Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Viewing members of a group Page: Removing or Deactivating a User Page: Adding a Group Page: Permissions Overview Page: Changing Usernames Page: Enabling or Disabling Public Signup Page: Global Groups Overview
326
Page: Disabling the Built-In User Management Page: Setting up Anonymous Access Page: Searching For and Managing Users
To add a new user to Confluence from the Administration Console: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'Manage Users' in the left-hand panel. Click the link 'Add User' at the top of the page. Enter the user's details: username, password, name and email address. Click 'Create'.
2. 3. 4. 5.
Notes
Multiple user directories: You may define multiple user directories in Confluence, so that Confluence looks in more than one place for its users and groups. For example, you may use the default Confluence internal directory and also connect to an LDAP directory server. In such cases, 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.
RELATED TOPICS
Page: Removing a Group Page: Adding a New User Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Viewing members of a group Page: Removing or Deactivating a User Page: Adding a Group Page: Permissions Overview Page: Changing Usernames Page: Enabling or Disabling Public Signup Page: Global Groups Overview Page: Disabling the Built-In User Management Page: Setting up Anonymous Access Page: Searching For and Managing Users
327
Adding a Group
A group is a collection of users. Administrators create groups so that the administrator can assign permissions to a number of people at once. For example, it is quicker to give group 'X' access to Confluence, rather than giving every team member access individually.
To add a new group: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click Manage Groups in the left-hand panel. 3. Click Add Group. 4. Enter a name for your group and click Save. You are now ready to start adding users to the group.
Notes
Multiple user directories: You may define multiple user directories in Confluence, so that Confluence looks in more than one place for its users and groups. For example, you may use the default Confluence internal directory and also connect to an LDAP directory server. In such cases, 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.
Related Topics
Page: Removing a Group Page: Adding or Removing Users in Groups Page: Viewing members of a group Page: Global Groups Overview Page: Searching For and Managing Users
328
This is the recommended method, available in Confluence 2.10 and later. It allows you to manage the group membership for a number of users at the same time. To add members to a group: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'Manage Groups' in the left-hand panel. The 'Manage Groups' screen appears, showing a list of groups. Select the group to which you want to add users. The 'Group Members' screen appears, showing the users who belong to the selected group. (See screenshot below.) Click the ' Add Members' link. The 'Add Members' screen appears, as shown below. Type in the usernames of the people you want to add to the group. You can
2. 3. 4. 5.
also search for and select users by clicking the icon, as described in Searching for Users. 6. When you have added the required username(s), click the 'Add' button to add the member(s) to the group. To remove members from a group: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Manage Groups' in the left-hand panel. 3. The 'Manage Groups' screen appears, showing a list of groups. Select the group from which you want to remove the user. 4. The 'Group Members' screen appears, showing the users who belong to the selected group. (See screenshot below.) Click the 'Remove user from group' icon next to the user whose group membership you want to remove.
329
Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Select 'Manage Users' in the left-hand panel. The 'Manage Users' screen appears, as shown below. You can now choose to 'Show all users' or you can search for a specific user by entering all or part of the person's username, full name or email address. (For more details about the user search, see Searching For and Managing Users.) Click the link on the username you want to edit. 2. Now you should be able to see the user's current details, with links allowing you to edit the user's details and groups. See the screenshot showing a user's details below. 3. Click 'Edit Groups'. This will display two lists of groups, as shown in the screenshot below. Update the user's group membership as follows: 'Not a member of groups' This box shows all groups to which the user does not belong. To add the user to a group, select a group and click 'Join'. Hold the Ctrl key down and click to select more than one group. 'Member of groups' This box shows all groups to which the user belongs. Select a group and click 'Leave' to remove the user from the group.
Notes
Multiple user directories: You may define multiple user directories in Confluence, so that Confluence looks in more than one place for its users and groups. For example, you may use the default Confluence internal directory and also connect to an LDAP
330
directory server. In such cases, 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.
RELATED TOPICS
Page: Removing a Group Page: Adding a New User Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Viewing members of a group Page: Removing or Deactivating a User Page: Adding a Group Page: Permissions Overview Page: Changing Usernames Page: Enabling or Disabling Public Signup Page: Global Groups Overview Page: Disabling the Built-In User Management Page: Setting up Anonymous Access Page: Searching For and Managing Users
Changing Usernames
A username is the name used to log into Confluence, eg. jsmith.
Currently, there is no straightforward method for changing a username and its associated content, to that of another user. The only practicable method currently available is to execute direct SQL queries on your database. There is a feature request to facilitate this process via a web interface and you can vote for it to improve its chances of being implemented. Be aware, however, that no matter what method you use to change usernames in Confluence, there is no support provided for this process. The instructions below provide suggested guidelines on how to change a username via SQL queries, although this may vary depending on your database.
Usernames can only be changed through direct update to the Confluence database. 1. 2. 3. 4. If you have a database administrator, request that they approve the database-related steps described below If you are using JIRA user management, Revert from JIRA To Internal User Management Backup Confluence If you are using MySQL, make sure you are not running in safe updates mode:
331
set sql_safe_updates=0;
5. Create a usermigrationtable:
6. Usernames that will be changed must be placed in the usermigrationtable with their current and planned usernames:
7. Run the following SQL commands: a. If you have command line access to your database, download the scripts for PostgreSQL or MySQL then run them against your database: PostgreSQL
MySQL
b. Otherwise, run the following: i. If your DB administration tool does not support multiple SQL queries, these must be entered individually: PostgreSQL
update attachments set creator = newusername from usermigration u where creator = u.oldusername; update attachments set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update content set creator = newusername from usermigration u where creator = u.oldusername; update content set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update content set username = newusername from usermigration u where username = u.oldusername; update content_label set owner = newusername from usermigration u where owner = u.oldusername; update content_perm set creator = newusername from usermigration u where creator = u.oldusername;
332
update content_perm set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update content_perm set username = newusername from usermigration u where username = u.oldusername; update contentlock set creator = newusername from usermigration u where creator = u.oldusername; update contentlock set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update cwd_user set lower_user_name = lower(newusername) from usermigration u where lower_user_name = lower(u.oldusername); update cwd_user set user_name = newusername from usermigration u where user_name = u.oldusername; update extrnlnks set creator = newusername from usermigration u where creator = u.oldusername; update extrnlnks set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update follow_connections set followee = newusername from usermigration u where followee = u.oldusername; update follow_connections set follower = newusername from usermigration u where follower = u.oldusername; update label set owner = newusername from usermigration u where owner = u.oldusername; update links set creator = newusername from usermigration u where creator = u.oldusername; update links set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update notifications set creator = newusername from usermigration u where creator = u.oldusername; update notifications set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update notifications set username = newusername from usermigration u where username = u.oldusername; update pagetemplates set creator = newusername from usermigration u where creator = u.oldusername; update pagetemplates set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update remembermetoken set username = newusername from usermigration u
333
where username = u.oldusername; update spacegroups set creator = newusername from usermigration u where creator = u.oldusername; update spacegroups set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update spacepermissions set creator = newusername from usermigration u where creator = u.oldusername; update spacepermissions set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update spacepermissions set permusername = newusername from usermigration u where permusername = u.oldusername; update spaces set creator = newusername from usermigration u where creator = u.oldusername; update spaces set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update trackbacklinks set creator = newusername from usermigration u where creator = u.oldusername;
334
update trackbacklinks set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername;
MySQL
update ATTACHMENTS a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update ATTACHMENTS a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update CONTENT a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update CONTENT a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update CONTENT a, usermigration u set a.username = u.newusername where a.username = u.oldusername; update CONTENTLOCK a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update CONTENTLOCK a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update CONTENT_LABEL a, usermigration u set a.owner = u.newusername where a.owner = u.oldusername; update CONTENT_PERM a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update CONTENT_PERM a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update CONTENT_PERM a, usermigration u set a.username = u.newusername where a.username = u.oldusername; update CWD_USER a, usermigration u set a.lower_user_name = LOWER(u.newusername) where a.lower_user_name = LOWER(u.oldusername); update CWD_USER a, usermigration u set a.user_name = u.newusername where a.user_name = u.oldusername; update EXTRNLNKS a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update EXTRNLNKS a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update FOLLOW_CONNECTIONS a, usermigration u set a.followee = u.newusername where a.followee = u.oldusername;
335
update FOLLOW_CONNECTIONS a, usermigration u set a.follower = u.newusername where a.follower = u.oldusername; update LABEL a, usermigration u set a.owner = u.newusername where a.owner = u.oldusername; update LINKS a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update LINKS a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update NOTIFICATIONS a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update NOTIFICATIONS a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update NOTIFICATIONS a, usermigration u set a.username = u.newusername where a.username = u.oldusername; update PAGETEMPLATES a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update PAGETEMPLATES a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update REMEMBERMETOKEN a, usermigration u set a.username = u.newusername where a.username = u.oldusername; update SPACEGROUPS a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update SPACEGROUPS a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update SPACEPERMISSIONS a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update SPACEPERMISSIONS a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update SPACEPERMISSIONS a, usermigration u set a.permusername = u.newusername where a.permusername = u.oldusername; update SPACES a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername; update SPACES a, usermigration u set a.lastmodifier = u.newusername where a.lastmodifier = u.oldusername; update TRACKBACKLINKS a, usermigration u set a.creator = u.newusername where a.creator = u.oldusername;
336
ii. Reassign user preferences in the OS_PROPERTYENTRY table. Usernames in the OS_PROPERTYENTRY table need to be prefixed with 'CWD_'. PostgreSQL
update os_propertyentry set entity_name = 'CWD_' || newusername from usermigration u where entity_name = 'CWD_' || u.oldusername;
MySQL
update OS_PROPERTYENTRY a, usermigration u set a.entity_name = concat('CWD_', u.newusername) where a.entity_name = concat('CWD_', u.oldusername);
iii. Reassign personal spaces and settings associated with the old username to the new username. The tilda (~) is required as it is prepended to the space key of all personal spaces: PostgreSQL
update spaces set spacekey = '~' || newusername from usermigration u where spacekey = '~' || u.oldusername; update bandana set bandanacontext = '~' || newusername from usermigration u where bandanacontext = '~' || u.oldusername;
MySQL
update SPACES a, usermigration u set a.spacekey = concat('~', u.newusername) where a.spacekey = concat('~', u.oldusername); update BANDANA a, usermigration u set a.bandanacontext = concat('~', u.newusername) where a.bandanacontext = concat('~', u.oldusername);
8. Each username is associated with a full name. For example, username 'jsmith' may have a full name of 'John M Smith'. If this fullname needs to be changed, modify the first_name, lower_first_name, last_name and lower_last_name in the cwd_user table. Ensure the lower_ columns are merely copies of their normal counterparts but with all letters in lower case. Then modify the display_name and lower_display_name columns so that they are the first_name and last_name columns or the lower_first_name and lower_last_name columns put together but separated by a space.
337
Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Viewing members of a group Page: Removing or Deactivating a User Page: Adding a Group Page: Permissions Overview Page: Changing Usernames Page: Enabling or Disabling Public Signup Page: Global Groups Overview Page: Disabling the Built-In User Management Page: Setting up Anonymous Access Page: Searching For and Managing Users
338
Notes
Multiple user directories: You may define multiple user directories in Confluence, so that Confluence looks in more than one place for its users and groups. For example, you may use the default Confluence internal directory and also connect to an LDAP directory server. In such cases, 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.
RELATED TOPICS
Page: Adding a New User Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Removing or Deactivating a User Page: Configuring Captcha for Spam Prevention Page: Setting up Anonymous Access Page: Searching For and Managing Users
2. confluence-users: This is the default group for all new users. Permissions you assign to this group will be assigned to all newly signed-up users of Confluence.
Confluence Administrator permission and confluence-administrators group are not related Going by the names, you would think the 'confluence-administrators' group and the 'Confluence Administrator' permission are related but they are not. To resolve confusion, we want to make explicit that granting a user or group 'Confluence Administrator' permission is not the same as granting them membership to the 'confluence-administrators' group. Granting the 'Confluence Administrator' permission enables access to only a subset of the administrative functions. Granting membership to the 'confluence-administrators' group, on the other hand, gives complete access.
Confluence Administrator permission and confluence-administrators group are not related Going by the names, you would think the 'confluence-administrators' group and the 'Confluence Administrator' permission are related but they are not. To resolve confusion, we want to make explicit that granting a user or group 'Confluence Administrator' permission is not the same as granting them membership to the 'confluence-administrators' group. Granting the 'Confluence Administrator' permission enables access to only a subset of the administrative functions. Granting membership to the 'confluence-administrators' group, on the other hand, gives complete access.
Other user groups : A Confluence administrator can also group users together into user groups for more convenient administration. Once created, groups become available at the space and page levels to allow for flexible access control. A user in one of these groups will automatically be granted all permissions granted to the group. Anonymous users : Confluence treats all users who do not log in when they access Confluence as being 'anonymous'. You can grant anonymous 'Use Confluence' permission via the Global Permissions screen. This will allow non-registered users to access pages and spaces in Confluence. A space administrator can then further control anonymous access per space via the space permissions.
Related Topics
Page: Removing a Group Page: Adding a New User Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Viewing members of a group Page: Removing or Deactivating a User Page: Adding a Group Page: Permissions Overview Page: Changing Usernames Showing first 10 of 15 results
340
On this page: Overview of the Global Permissions Comparing the System Administrator with the Confluence Administrator Permission Comparing the Administrator Permissions with the confluence-administrators Group Updating Global Permissions Related Topics
This is the most basic permission that allows users to access the site. Users with this permission count towards the number of users allowed by your license. See the information on removing/deactivating users.
This allows the user to upload files to be stored in their user profile. This feature was made obsolete by the introduction of personal spaces in Confluence 2.2. Hence, this permission is no longer relevant. Attachments can be accessed from a user profile view (for example, an image within the 'About Me' field of a profile view) by attaching these files to a page within that user's personal space and referencing them using appropriate wiki markup code. This allows the user to update their user status message, which can be seen on the user's profile, pages in their personal space and on various activity streams accessible to other Confluence users. This permission allows the user to create a personal space.
This permission allows users to create new spaces within your Confluence site. When a space is created, the creator automatically has the 'Admin' permission for that space and can perform space-wide administrative functions. This permission allows users to access the 'Administration Console' that controls site-wide administrative functions. Users with this permission can perform most, but not all, of the Confluence administrative functions. See the comparison of 'System Administrator' and 'Confluence Administrator' below. This permission allows users to access the 'Administration Console' that controls site-wide administrative functions. Users with this permission can perform all the Confluence administrative functions, including the ones which the 'Confluence Administrator' permission does not allow. See the comparison of 'System Administrator' and 'Confluence Administrator' below. Refer also to the note about the 'confluence-administrators' group below.
System Administrator
The first system administrator is defined during installation During the initial configuration of Confluence, the Setup Wizard asks for the username of the System Administrator. This user will have the 'System Administrator' permission and will be a member of the 'confluence-administrators' group.
341
The following functions are excluded from the 'Confluence Administrator' permission: Administration Screen General Configuration Excluded Function The following functionality is disallowed: Server Base URL Remote API plugin Public Signup Connection Timeouts Security Configuration The following functionality is disallowed: External user management Append wildcards to user and group searches Public Signup Anti XSS Mode Enable Custom Stylesheets for Spaces Show system information on the 500 page Maximum RSS Items XSRF Protection Plugins The following functionality is disallowed: Upgrade Install Confluence Upgrade Check Daily Backup Admin Mail Servers User Macros Attachment Storage Layouts Custom HTML Backup & Restore Logging and Profiling Cluster Configuration Scheduled Jobs Application Links This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely. This function is disallowed entirely.
342
Confluence Administrator permission and confluence-administrators group are not related Going by the names, you would think the 'confluence-administrators' group and the 'Confluence Administrator' permission are related but they are not. To resolve confusion, we want to make explicit that granting a user or group 'Confluence Administrator' permission is not the same as granting them membership to the 'confluence-administrators' group. Granting the 'Confluence Administrator' permission enables access to only a subset of the administrative functions. Granting membership to the 'confluence-administrators' group, on the other hand, gives complete access.
To add permissions for a specific user: (Consider adding the user to a group and then assigning the permissions to the group, as described above, instead of assigning permissions to the specific user.) 1. 2. 3. 4. 5. First add the user to Confluence, if you have not already done so. Click Edit Permissions. The 'Edit Global Permissions' screen appears, as shown below. Enter the username in the Grant browse permission to box in the 'Individual Users' section. You can search for the username. Click Add. The username will appear in the list and you can now edit its permissions.
To add or edit the permissions for a user or group: 1. Select, or clear, the check box under the relevant permission in the row for the relevant user/group. A selected check box indicates that the permission is granted. 2. To allow anonymous access to your Confluence site, select the 'Use Confluence' and 'View User Profile' options in the 'Anonymous Access' section. For more information about these permissions, refer to Setting up Anonymous Access. 3. Click Save All to save your changes. Screenshot: Editing global permissions
343
About some error messages you may see In Confluence 2.7.2 and later, Confluence will let you know if there is a problem with some permissions. In rare situations, you may see the following error messages below a permission: 'User/Group not found' This message may appear if your LDAP repository is unavailable, or if the user/group has been deleted after the permission was created. 'Case incorrect. Correct case is: xxxxxx' This message may appear if the upper/lower case in the permission does not match the case of the username or group name. If you see a number of occurrences of this message, you should consider running the routine supplied to fix the problem.
Related Topics
Page: Removing a Group Page: Adding a New User Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Viewing members of a group Page: Removing or Deactivating a User Page: Adding a Group Page: Permissions Overview Page: Changing Usernames Page: Enabling or Disabling Public Signup Page: Global Groups Overview Page: Disabling the Built-In User Management
344
Page: Setting up Anonymous Access Page: Searching For and Managing Users
Removing a Group
To remove a group: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Manage Groups' in the left panel. A list of all existing groups is displayed along with links to remove them. 3. Click 'Remove' beside the group you want to remove. You will need to confirm your action before the group is deleted.
Notes
Multiple user directories: You may define multiple user directories in Confluence, so that Confluence looks in more than one place for its users and groups. For example, you may use the default Confluence internal directory and also connect to an LDAP directory server. In such cases, 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.
RELATED TOPICS
Page: Recognised System Properties Page: Configuring HTTP Timeout Settings Page: Configuring Attachment Size Page: Configuring Indexing Language Page: Configuring Character Encoding Page: Configuring Time and Date Formats Page: Configuring Number Formats
1. Go to the user's Profile and click the 'Administer User' link. 2. Click 'Remove'.
To deactivate a user: 1. Go to the user's Profile and click the 'Administer User' link. 2. Click 'Disable'.
Notes
The 'Administer User' link is only visible if you are logged in as an administrator. You can also remove or disable users using the Administration Console. You can edit the groups that a user belongs to if you don't wish to prevent their access to Confluence completely. Multiple user directories: You may define multiple user directories in Confluence, so that Confluence looks in more than one place for its users and groups. For example, you may use the default Confluence internal directory and also connect to an LDAP directory server. In such cases, 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. Number of users and your license. The Confluence 'License Details' screen tells you how many users your Confluence instance is licensed to support, and how many are currently registered. See Viewing and Editing License Details. The number of registered users includes only users who have the 'Can Use' global permission. Deactivated users, as described above, are not included.
Related Topics
Page: Removing a Group Page: Adding a New User Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Viewing members of a group Page: Removing or Deactivating a User Page: Adding a Group Page: Permissions Overview Page: Changing Usernames
346
Page: Enabling or Disabling Public Signup Page: Global Groups Overview Page: Disabling the Built-In User Management Page: Setting up Anonymous Access Page: Searching For and Managing Users
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click 'Global Permissions' in the left-hand panel. Click 'Edit Permissions'. In the 'Anonymous Access' section, select the 'can use' check box to enable anonymous access to the content on your site. If you selected the 'can use' check box in the previous step and want to allow anonymous access to user profile views, select the check box in the 'View User Profiles' section. Note: You cannot grant the 'View User Profiles' permission independently of the 'Use Confluence' permission. Click 'Save All'. You can now grant further permissions from the space administration screens to control the viewing and editing privileges of anonymous users. See Space Permissions Overview
2. 3. 4. 5.
6. 7.
Page: Adding a New User Page: Editing User Details Page: Adding or Removing Users in Groups Page: Global Permissions Overview Page: Removing or Deactivating a User Page: Configuring Captcha for Spam Prevention Page: Setting up Anonymous Access Page: Searching For and Managing Users
347
To view the members of a group: 1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Click Manage Groups in the left-hand panel. This will list all the existing groups on the site. 3. Click a group name to display all the users in the group.
Notes
Multiple user directories: You may define multiple user directories in Confluence, so that Confluence looks in more than one place for its users and groups. For example, you may use the default Confluence internal directory and also connect to an LDAP directory server. In such cases, 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.
Related Topics
Page: Removing a Group Page: Adding or Removing Users in Groups Page: Viewing members of a group Page: Global Groups Overview Page: Searching For and Managing Users
Confluence now uses the CWD_USER table in the database to store and refer to its users. When you imported your backup on upgrade from Confluence 3.4.9 or earlier, the upgrade process copied the users from the OS_USER table (for upgrades from versions older than 2.7) or the USERS table (for versions 2.7 to 3.4) into the CWD_USER table. The new user management framework also introduced user directories. Making modifications to users in the database will only fully work for users in Confluence's Internal Directory. The instructions below include extra steps for instances in which the user management has been delegated to external sources (via LDAP, Crowd or JIRA). Please refer to the older documentation if you are still using OSUser or AtlassianUser.
348
On this page: Before you Start Step 0. Get access to the database Step 1. Identify Administrator Step 2. Replace Administrator Password Step 3. Put the Internal Directory in First Position Step 4. Clean Up Notes
select u.id, u.user_name from cwd_user u join cwd_membership m on u.id=m.child_user_id join cwd_group g on m.parent_id=g.id join cwd_directory d on d.id=g.directory_id where g.group_name = 'confluence-administrators' and d.directory_name='Confluence Internal Directory';
If there are multiple results, choose one ID/username combination to use for the following steps. If there are no results, skip down to 'If No Local Users Exist' in Step 2.
x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB+XURPWx1ONxp3Y3pB37A==
To change the password to admin for a given username: 1. Shut down Confluence. 2. Connect to your database. 3. Run the following SQL:
To change the password to admin for a given username: 1. Shut down Confluence. 2. Open <confluence-home>/database/confluencedb.script, or confluencedb.log if the .script file looks empty. 3. Search for:
349
4. Keep searching until you find the appropriate user, then replace their password with the hash value above. 5. Save the file. 6. Restart Confluence.
If No Local Users Exist
There may be no administrators in your Internal Directory. If this is the case, you need to add one: 1. Add a new admin user by running:
insert into cwd_user(id, user_name, lower_user_name, active, created_date, updated_date, first_name, lower_first_name, last_name, lower_last_name, display_name, lower_display_name, email_address, lower_email_address, directory_id, credential) values (1212121, 'admin', 'admin', 'T', '2009-11-26 17:42:08', '2009-11-26 17:42:08', 'A. D.', 'a. d.', 'Ministrator', 'ministrator', 'A. D. Ministrator', 'a. d. ministrator', '[email protected]', '[email protected]', (select id from cwd_directory where directory_name='Confluence Internal Directory'), 'x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB+XURPWx1ONxp3Y3pB37A==');
insert into cwd_group(id, group_name, lower_group_name, active, local, created_date, updated_date, description, group_type, directory_id) values ( '888888','confluence-administrators','confluence-administrators','T','F','2011-03-21 12:20:29','2011-03-21 12:20:29',NULL,'GROUP',(select id from cwd_directory where directory_name='Confluence Internal Directory')); insert into cwd_group(id, group_name, lower_group_name, active, local, created_date, updated_date, description, group_type, directory_id) values ( '999999','confluence-users','confluence-users','T','F','2011-03-21 12:20:29','2011-03-21 12:20:29',NULL,'GROUP',(select id from cwd_directory where directory_name='Confluence Internal Directory'));
insert into cwd_membership (id, parent_id, child_user_id) values (888888, (select id from cwd_group where group_name='confluence-users' and directory_id=(select id from cwd_directory where directory_name='Confluence Internal Directory')), 1212121); insert into cwd_membership (id, parent_id, child_user_id) values (999999, (select id from cwd_group where group_name='confluence-administrators' and directory_id=(select id from cwd_directory where directory_name='Confluence Internal Directory')), 1212121);
2. Take note of the ID with list_index 0, and the list_index and ID of the Confluence Internal Directory. 3. Switch the order of the directories:
350
update cwd_app_dir_mapping set list_index = 0 where directory_id = <Internal Directory id>; update cwd_app_dir_mapping set list_index = <Noted Internal Directory list_index> where directory_id = <Directory id that had list_index 0>;
4. Check to see if the directory is active (the 'active' column should be set to 'T'):
select id, directory_name, active from cwd_directory where id = <Internal Directory id>;
Step 4. Clean Up
To tidy up: 1. 2. 3. 4. 5. Start Confluence. Log in with your modified/created username and use password admin Change your password. Do not leave your password as admin, or your instance will not be secure. If you created a new user in Stage 2, create a new admin via the UI and delete the admin you created in Stage 2. If you followed Stage Three, go to Confluence Administration > User Directories and rearrange your directories so they are correctly configured again.
Notes
Learn more about the password hash algorithm Confluence is using.
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Manage Users' in the left-hand panel. The 'Manage Users' screen appears, as shown below. 3. Search for the desired user and click the user in the search results. The 'View User' screen will be displayed. 4. Click the 'Reset Failed Login Count' for the user. The 'Current Failed Login Count' will be reset to 0.
351
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. Click 'Security Configuration' in the left-hand panel. The 'Edit Security Configuration' screen will appear. Click 'Edit'. Tick the 'External user management' check box. Click 'Save'.
2. 3. 4. 5.
Notes
Please refer to the following bugs and improvement requests: CONF-16709 When the External User Management check box is ticked, the group and user management screens are still functional. CONF-21158 Enabling both public signup and external user management renders a blank screen during signup. CONF-9830 This is a request to rename this feature to better reflect its functionality.
RELATED TOPICS
Getting Started
The Application Links quick start guide provides instructions on how to set up the most common application link configuration.
Administrator's Guide
The administrator's guide is for administrators who want to configure application links for their applications. The guide contains information on adding a new application link, configuring the authentication for an application link, setting up project links and more.
352
Developer Resources
These resources are for developers who want to develop with the Application Links plugin. Take a look at the Development Hub.
Related Topics
Configuring Application Links Configuring OAuth Confluence and JIRA
Notes
In the above screenshot, the column titled 'Incoming Authentication' is visible in Confluence 3.5.1 and later. The column does not appear in Confluence 3.5.
Related Topics
Adding an Application Link Configuring Authentication for an Application Link Editing an Application Link Making an Application Link the Primary Link Relocating an Application Link Upgrading an Application Link Deleting an Application Link Configuring Project Links across Applications
353
Step 1
Step 2
Step 3
Screenshots above: Adding an application link to an application that supports Application Links (click to view full-sized images)
Adding an Application Link to an Application That Does Not Support Application Links
Before you begin: Make sure that the base URL is set correctly in Confluence. See Configuring the Server Base URL for instructions. Make sure that the base URL is set correctly in the application which you intend to link to. See the appropriate instructions: JIRA instructions | FishEye/Crucible instructions | Bamboo instructions). This is required for synchronisation to work correctly. To link to an application that does not support Application Links: 1. Log in as a system administrator and go to the administration page. Click 'Application Links' in the administration menu. The 'Configure Application Links' page will appear, showing the application links that have been set up. 2. Click 'Add Application Link'. Step 1 of the 'Link to another server' dialogue will be displayed. 3. Enter the server URL of the application that you want to link to, in the 'Server URL' field. Click the 'Next' button. Step 2 of the 'Link to another server' dialogue will be displayed. 4. 354
4. Fill out the fields, as follows: 'Application Name' Enter the name by which this remote application will be referred to, in your application. 'Application Type' Select the type of application that you are linking to: Bamboo, FishEye/Crucible, JIRA, Confluence, Subversion. 'Application URL' This will be set to the server URL you entered in the previous step and will not be editable. 5. Click the 'Create' button to create the application link. The 'Configure Application Links' page will be displayed, listing all of the application links that have currently been set up for your application including the one you just added. 6. Configure the desired authentication type (Trusted Applications, OAuth, basic HTTP, none) for your new application link. See Configuring Authentication for an Application Link. 7. In your application that does not support Application Links, configure the same type of authentication that you configured for your application link's outgoing authentication (in the previous step). For example, if you configured outgoing Trusted Applications authentication in your Application-Links-enabled application, you also need log into your non-Application-Links application and manually configure Trusted Applications (see the relevant administrator's documentation for the application).
Step 1
Step 2
Screenshots above: Adding an application link to an application that supports Application Links (click to view full-sized images)
Notes
Related Topics
Making an Application Link the Primary Link Configuring Authentication for an Application Link Configuring Project Links across Applications
355
Do the two applications you are linking share the same user base or not? Do you have administrative access to the application you are linking to? Common scenarios include: If the two applications you are linking trust each other and share the same user base, configure two-way authentication using Trusted Applications for both incoming and outgoing authentication. For example, you may link your internal Confluence server to an internal JIRA server. If the two applications you are linking trust each other but do not share the same user base, configure two-way authentication using OAuth for both incoming and outgoing authentication. For example, you may link your internal Confluence server to an external (customer-facing) JIRA server. If you do not have administrative rights to the application that you are linking to (e.g. linking to a public FishEye server), configure a one-way outgoing link authenticated using basic HTTP authentication or do not configure any authentication for the link. For example, you may link your external Confluence server to a partner organisation's Confluence server. An unauthenticated link will still allow the local application to render hyperlinks to the remote application or query anonymously-accessible APIs. The flowchart below provides a guide to what authentication you should configure for your application link. Read the following topics for information on how to configure authentication for an application link: Configuring Basic HTTP Authentication for an Application Link Configuring OAuth Authentication for an Application Link Configuring Trusted Applications Authentication for an Application Link Incoming and Outgoing Authentication
356
that you use SSL for your applications while configuring OAuth authentication. Do not link to an application using OAuth authentication, unless you trust all code in the application to behave itself at all times. OAuth consumers are a potential security risk to the applications that they are linked to.
You cannot configure which authentication type is the primary authentication type. The primary authentication type is determined automatically by Application Links and depends on a weight defined by each authentication type method. However, every feature that uses Application Links can also choose to use a specific authentication type and might not use the default primary authentication type.
357
authentication for an application link. Basic HTTP authentication allows Confluence to provide user credentials to a remote application and vice versa. Once authenticated, one application can access specified functions on the other application on behalf of that user. For example, if you supply the credentials of a Confluence administrator on your Confluence server to a remote application, the remote application will be able to access all functions on your Confluence server that the Confluence administrator can access. This method of authentication relies on the connection between Confluence and the remote application being secure. We recommend that you use Trusted Applications authentication or OAuth authentication for your application link instead, if possible. On this page: Before You Begin Configuring Basic HTTP Authentication for Outgoing Authentication Configuring Basic HTTP Authentication for Incoming Authentication Notes
Notes
Related Topics Configuring OAuth Authentication for an Application Link Configuring Trusted Applications Authentication for an Application Link
358
The instructions on this page describe how to configure OAuth for outgoing authentication and/or incoming authentication for an application link. OAuth is a protocol that allows a web application to share data/resources with any other OAuth-compliant external application. These external applications could be another web application (such as a JIRA installation or an iGoogle home page), a desktop application or a mobile device application, provided that they are accessible from within your network or available on the Internet. For example, you could set up an application link between Confluence and an iGoogle page using OAuth authentication. This would allow you to view data from your Confluence server in a Confluence gadget on the iGoogle page (see Configuring Confluence Gadgets for Use in Other Applications). A typical scenario is setting up an application link between two applications which trust each other, do not share the same set of users but both applications have the Application Links plugin installed. In this case, you would configure OAuth for both outgoing authentication and incoming authentication. See Configuring Authentication for an Application Link for other configurations.
Key OAuth Terminology Service provider An application that shares ('provides') its resources. Consumer An application that accesses ('consumes') a service provider's resources. User An individual who has an account with the Service Provider. For more information about OAuth, see Configuring OAuth as well as the OAuth specification.
On this page: Before You Begin Configuring OAuth for Outgoing Authentication Configuring OAuth for Incoming Authentication
359
Configuring incoming OAuth authentication will allow the remote application that you are linking to, to access data in Confluence. To configure OAuth authentication for an incoming application link: 1. Log in as a system administrator and go to the administration page. Click 'Application Links' in the administration menu. The 'Configure Application Links' page will appear, showing the application links that have been set up. 2. Click the 'Configure' link next to the application link that you want to configure OAuth for. 3. Click the 'Incoming Authentication' tab. The incoming authentication page will be displayed. 4. Click the 'OAuth' tab. 5. Click the 'Enable' button to enable OAuth authentication for the incoming link. The remote application will be automatically set up to be the 'consumer' and your local application as a 'service provider'. Related Topics Configuring Basic HTTP Authentication for an Application Link Configuring Trusted Applications Authentication for an Application Link Configuring Confluence Gadgets for Use in Other Applications
5. Configure the settings for the Trusted Applications authentication: 'IP Patterns' Enter the IP addresses (IPv4 only) from which the remote application will accept requests (this effectively is the IP address your local server). You can specify wildcard matches by using an asterisk (*), e.g. ' 192.111.*.*' (note, you cannot use netmasks to specify network ranges). If you are entering multiple IP addresses, separate them with commas or spaces. Please note, if you are setting up Trusted Applications between two applications that both have the Application Links plugin installed, you can leave this field blank (or explicitly use *.*.*.*). However, if your remote application does not have the Application Links plugin installed and you are configuring the IP Patterns in the remote application (not the Application Links plugin), you must not leave this field blank nor use *.*.*.*. Failure to configure IP address restrictions in this scenario is a security vulnerability, allowing an unknown site to log into your site under a user's login ID. Consider the following scenarios, if you want to limit access by using this field: If your local application is using a proxy server, you need to add the proxy server's IP address to this field. If your local application is a clustered instance of Confluence, you need to configure the remote server to accept requests from each cluster node. If you do not set up each node appropriately, your Confluence users may not be able to view any information from the remote server. You can set this up by either specifying each individual IP address for each node of the cluster (e.g. 172.16.0.10, 172.16.0.11, 172.16.0.12), or specifying the IP address for the clustered Confluence instance using wildcards (e.g. 172.16.0.*). 'URL Patterns' Enter the URLs in the remote application that your local application will be allowed to access. Each URL corresponds to a particular application function. Enter one URL per line, as follows: If your remote application is JIRA, enter the following URL Patterns: /plugins/servlet/streams, /sr/jira.issueviews:searchrequest, /secure/RunPortlet, /rest, /rpc/soap If your remote application is Confluence, enter the following URL Patterns: /plugins/servlet/streams, /plugins/servlet/applinks/whoami 'Certificate Timeout (ms)' Enter the certificate timeout. The default is 10 seconds. The certificate timeout is used to prevent replay attacks. For example, if a Trusted Applications request is intercepted and (maliciously) re-sent, the application will be able to check when the request was first sent. If the second request is sent more than 10 seconds (or whatever the certificate timeout is set to) after the initial request, it will be rejected. Please note, you should not have to change the default value of this field for most application links. Note that the certificate timeout relies on the clocks on both servers being synchronised. 6. Click the 'Apply' button to save your changes.
Notes
Related Topics
361
Configuring Basic HTTP Authentication for an Application Link Configuring OAuth Authentication for an Application Link
362
Notes
Related Topics
Configuring Authentication for an Application Link Making an Application Link the Primary Link Relocating an Application Link
363
Confluence 4.0 Documentation 2. 'Primary' column next to the application link. The 'Primary' column and 'Make Primary' link will only display if you have set up application links to more than one of the same application type, e.g. you have linked your application to two JIRA servers.
Notes
Please read Making a Project Link the Primary Link for information on how primary project links also influence the information shared between servers.
Related Topics
To relocate an application link: 1. Log in as a system administrator and go to the administration page. Click 'Application Links' in the administration menu. The 'Configure Application Links' page will appear, showing the application links that have been set up. 2. If the remote application for an application link cannot be reached by your application, the 'List Application Links' page will display a warning message (see 'Relocate Link - Warning Message' screenshot below). 3. If your remote application has been moved to a different address (rather than just being offline temporarily), click the 'Relocate' link in the warning message (see 'Relocate Link - Updating URL' screenshot below). 4. Enter the new URL for the remote application of your application link and click 'Relocate'. 5. You will need to confirm the relocation, if the new URL cannot be contacted. Otherwise, the application link will be updated.
364
Your Confluence instance has been upgraded from a version that does not include Application Links to a version that does. For example, you may have configured Trusted Applications or OAuth in a Confluence 3.4 instance (does not include Application Links) and then upgraded to Confluence 3.5 (includes Application Links). Your remote application has been upgraded to a version that includes Application Links. For example, you had set up an application link in a Confluence 3.5 instance (includes Application Links) to JIRA 4.2 instance (does not include Application Links), and then upgrade to JIRA 4.3 (includes Application Links). On this page: Upgrading an Application Link (Local App Upgraded to Include Application Links) Upgrading an Application Link (Remote App Upgraded to Include Application Links) Notes
Step 1
Step 2
Step 3
365
If you upgrade your remote application to a version that does include Application Links, the application link will continue to work. However, upgrading your link may simplify link configuration and make additional authentication protocols available (as mentioned above). To upgrade an application link when your remote application has been upgraded to include Application Links: 1. After you have upgraded your remote application to a version that includes Application Links, go to the administration console of your local application. A warning will be displayed, requesting that you upgrade the link to full Application Links mode. 2. Click 'Upgrade' in the warning message to start the upgrade wizard. Note the following: You will be prompted to make your application link a reciprocal link. You will need to provide administrator credentials for your remote application, if you choose to do so. If you make your application link a reciprocal link, you will also be able to make reciprocal links for your project links. For example, you may be able to link your JIRA project to a FishEye repository and also make a link from your FishEye repository back to the JIRA project.
366
Notes
Related Topics
367
To delete an application link: 1. Log in as a system administrator and go to the administration page. Click 'Application Links' in the administration menu. The 'Configure Application Links' page will appear, showing the application links that have been set up. 2. Click the 'Delete' link next to the application link that you want to delete. A confirmation screen will be displayed. 3. Click the 'Confirm' button to delete the application link.
RELATED TOPICS
368
information relating to your project or team. Using project links (also called entity links) you can associate one or more projects, spaces and repositories across the linked applications. To connect all the information relating to the project or team that you are managing, you can link one or more of the following: JIRA projects. Confluence spaces. FishEye repositories. FishEye projects. A FishEye 'project' is the Crucible project if you have installed FishEye and Crucible, otherwise it is the paths associated via the 'FishEye Project Content' function in FishEye. Crucible projects. Bamboo projects.
To link a Confluence space to a project in another application: 1. Choose Browse > Space Admin. Space Admin is displayed only if you are a space administrator for that space or you are a Confluence system administrator. 2. Click 'Application Links' in the left-hand panel. 3. Choose the Confluence space that you want to link from. 4. The instructions for adding a project link will vary depending on whether the target application has the Application Links functionality installed: If the target application has Application Links: a. Click 'Add Link'. A dropdown menu will appear listing the applications you have already linked to. b. In the dropdown menu, click the application that contains the project you want to link to. For example, if you want to link to a specific JIRA project, click the JIRA site that contains that project. If you want to link to a Confluence space, click the Confluence site that contains that space. c. Click one of the options on the 'Authorization required' screen: 'Authorize' Click this option if you want to grant your project authorised access to the target project. The target application will open in a new window, so that you can log in and authorise access. 'Skip your access is anonymous' Click this option if you only want to allow anonymous access to the target project. d. In the 'Name or Key' field, enter the name/key of the project in the remote application that you want to link to. For example, if you want to link to a JIRA project, enter the project key. If you want to link to a Confluence space, enter the space key. e. Click the 'Create' button to create the project link. If the target application does not have Application Links: a. Click 'Add Link'. A dropdown menu will display listing the applications you have already linked to. b. In the dropdown menu, click the application that contains the project you want to link to. For example, if you want to link to a specific JIRA project, click the JIRA site that contains that project. If you want to link to a Confluence space, click the Confluence site that contains that space. c. In the 'Key' field, enter the name/key of the project in the remote application that you want to link to. For example, if you want to link to a JIRA project, enter the project key. If you want to link to a Confluence space, enter the space key. d. (optional) Enter the alias for the project in the 'Alias' field. This is the display name for the project in your administration console. e. Click the 'Create' button to create the project link.
Step 1
Step 2
Step 3
369
Screenshots above: Linking to a JIRA project (where the target JIRA server supports Application Links) RELATED TOPICS Making a Project Link the Primary Link Deleting a Project Link
To make a project link the primary link: 1. Choose Browse > Space Admin. Space Admin is displayed only if you are a space administrator for that space or you are a Confluence system administrator. 2. Click 'Application Links' in the left-hand panel. 3. Click the 'Make Primary' link in the 'Action' column for the project link that you want to make the primary link. A symbol will display in the 'Primary' column next to the link. Note: The 'Primary' column and 'Make Primary' link will appear only if you have set up multiple project links to the same application, for example you have linked a Confluence space to a number of JIRA projects.
Screenshot above: Viewing the project links for a Confluence space RELATED TOPICS Adding Project Links between Applications Deleting a Project Link
To delete a project link: 1. Choose Browse > Space Admin. Space Admin is displayed only if you are a space administrator for that space or you are a Confluence system administrator. 2. Click 'Application Links' in the left-hand panel. 3. Click the 'Delete' link next to the link that you want to delete. 4. A confirmation screen will appear. Click the 'Confirm' button to delete the link.
370
Screenshot above: Confirming the deletion of a project link Related Topics Adding Project Links between Applications Making a Project Link the Primary Link
Configuring OAuth
OAuth is a protocol that allows one application to share a defined set of its private resources and data (through gadgets, for example) with another application. These applications could be a Confluence or JIRA site, or a website such as iGoogle. All applications involved must be OAuth-compliant. In Confluence, use Application Links to set up an OAuth relationship with another application. On this page: Configuring OAuth Authentication About OAuth Notes
About OAuth
Using OAuth, you can access data within a Confluence installation externally via a Confluence gadget published on a JIRA site's dashboard, another Confluence site's page, or a website like iGoogle. While some data in Confluence may be accessible anonymously on the external application, other data may be restricted to a specific user account within the Confluence installation. OAuth provides the facility to access this restricted data. The key security advantage of OAuth is that Confluence's user-restricted resources can be shared without Confluence having to hand out user authentication details. Instead, access to these private resources is handled via an access token. Access tokens define what Confluence resources can be accessed by another application and the duration of this access. Access tokens are dissociated from a user's authentication details, since authentication to gain access to these resources is handled separately. In OAuth terminology, an application that shares its resources is known as a service provider and an application that accesses a service provider's resources is known as a consumer.
Notes
371
OAuth relationships provide the ability to access restricted data on the service provider when an individual's usernames on the service provider and consumer applications are different. This is different to Trusted Application relationships, also provided via [Application Links|Administering Application Links, where the usernames must be the same in both applications. Not all external gadgets used in Confluence require the establishment of an OAuth relationship. If the gadget does not need to access restricted resources on the service provider, then there should be no need to establish an OAuth relationship. For more information about OAuth, please refer to the OAuth protocol workflow section of our Gadgets and Dashboards documentation.
Related Topics
Connecting to Crowd or JIRA for User Management JIRA Issues Macro JIRA Portlet Macro
372
Apache Web Server is recommended and reliable. It is also a third-party product, and therefore not developed nor supported by Atlassian. See How to Get Legendary Support from Atlassian for details.
JIRA: http://jira.atlassian.com/secure/QuickSearch.jspa?searchString=
373
Use the above option to create links using Confluence's shortcut notation. Link directly to JIRA issues like this: CONF-1000 Use JIRA's quick-search functionality to create links to particular groups of issues. The following link will display a list of all open issues in the Confluence project of type 'Improvement': CONF open improvements
You can embed a Confluence activity stream or a Confluence page in JIRA's dashboard. Likewise, JIRA gadgets can be rendered on a Confluence page. See Adding a Confluence Gadget to a JIRA Dashboard and Gadget Macro for information on how to set up gadgets.
Using the JIRA Issues macro
For versions earlier than Confluence 3.1 and JIRA 4.0, use the {jiraissues} and {jiraportlet} macros to embed JIRA reports and portlets into your Confluence site Any JIRA search result can be embedded in a Confluence page using the JIRA Issues macro with your choice of included fields and field ordering, and any JIRA dashboard portlet can be embedded in a Confluence page using the JIRA Portlet macro.
Useful Plugins
Before installing a plugin into your Confluence site, please check the plugin's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on plugin support. The JIRA Linker plugin provides a custom field that helps you find an URL, particularly a Confluence page, so you can add a page link into a JIRA issue.
374
Potential security risk Do not configure a trusted application unless you trust all code in that application to behave itself at all times. Trusted communication uses public/private key cryptography to establish the identity of the trusted server, so you must also be sure that the trusted application will maintain the security of its private key. Read the details of the security risks below.
On this page: Prerequisites Why do we need Trusted Communication? Overview Configuring JIRA to Trust Confluence Using Trusted Applications Configuring the Macro Plugin in Confluence Adding the Macro to a Confluence Page Viewing the Confluence Page Security Risks Troubleshooting Technical Overview of the Trusted Applications Authentication (TAA) Protocol
Prerequisites
JIRA 3.12.0 or later. Confluence 2.7.0 or later. In order to authenticate successfully against JIRA, the Confluence user must also be registered as a JIRA user with the same username.
Common user base recommended It is highly recommended that your JIRA and Confluence instances share a common user base, rather than two separate user bases with duplicated usernames. You will receive an error if Confluence passes JIRA a username which JIRA cannot recognise. Also, with separate user bases you run the risk that the same username may be used by two different people. The trusted application does not supply the user's password, so the trusting application will assume the username belongs to the user registered in the trusting application's own user base.
Overview
Here is a summary of the integration points in a trusted communications relationship. Each of the following points is described in more detail in the sections below. A JIRA System Administrator configures JIRA to trust Confluence. A Confluence System Administrator configures the macro plugin to use (or not use) trusted communication. A Confluence user adds one of the macros to a Confluence page. A Confluence user or anonymous user views the Confluence page.
375
Trust only has to be established once between the two applications. Once trust has been established, it is entirely transparent to the Confluence users. Application links are used to enable trust relationships between two applications. Linking two applications allows you to share information and access one application's functions from within the other. You can configure an application link to use Trusted Applications as the authentication mechanism. For instructions, see Configuring Trusted Applications Authentication for an Application Link.
1. Go to the Confluence 'Administration Console': Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed. Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'. 2. Select 'Plugins' in the left-hand panel. 3. The 'Plugin Manager' screen appears, showing a list of installed plugins. Scroll down and click the 'JIRA Macros' link. 4. The 'JIRA Macros' panel appears in the top middle of the screen, as shown below. Click 'Enable' or 'Disable' next to the following options: 'JIRA application trust support' With this option enabled, Confluence will attempt trusted communication with JIRA whenever a user views a page containing the JIRA Issues or Portlet macro, provided criteria are met as described below. With this option disabled, Confluence will never attempt trusted communication with JIRA for these macros. Disable the above option if you do not intend to configure trusted communication between JIRA and Confluence. 'JIRA application trust warnings' With this option enabled, Confluence will display all error and warning messages that may arise from a problem during trusted communication (assuming that trusted communication is enabled). With this option disabled, Confluence will suppress certain warnings. See troubleshooting below. Disable the above option if you have a large number of existing JIRA macros already on your Confluence instance, pointing at a diverse range of JIRA servers. Some of those JIRA servers may have a trusted communication link established (requiring the functionality to be enabled) while other JIRA servers may have no trusted communication link. In this case, you may want to turn off the warning messages so they do not appear on your Confluence pages where the JIRA macros point to non-trusting JIRA servers.
376
Remove the username and password from your macro markup code Prior to Confluence 2.7, you needed to include a username and password in the macro markup code if you wanted to display JIRA issues which had restricted viewing. Once your administrator has set up trusted communication between Confluence and JIRA, you no longer need to include a username and password in the markup code for your JIRA macros.
The following options are available for determining the issues which will be retrieved from JIRA and displayed on the Confluence page: What you want to do Macro parameter URL parameter Comments
377
Display the JIRA issues which the logged-in user is authorised to see. And if the user is not logged in, display only issues which allow unrestricted viewing.
Do not specify any authentication parameters. In this case, the behaviour depends on the way your administrator has set up trusted communication between JIRA and Confluence. Here is a summary of the behaviour. If trusted communication is enabled, the authorisation will work seamlessly. When a logged-in user views your page, they will see only the JIRA issues they are allowed to see. And if they are not logged in, they will see only the issues which allow unrestricted viewing. If trusted communication is disabled, the Confluence page will show only the JIRA issues which allow unrestricted viewing. anonymous Regardless of who the user is (logged in or not), the Confluence page will show only anonymously-visible issues. Confluence will not attempt to set up a trusted communication link with JIRA in this case. &os_username=MYNAME&os_password=MYPASSWORD Not recommended. Prior to Confluence 2.7, this was the only way of displaying issues with restricted viewing. For Confluence 2.7 and later, this method will still work. Confluence will not attempt to set up a trusted communication link with JIRA in this case.
Ensure that Confluence will display only the JIRA issues which allow unrestricted viewing.
Refer to the section below for details of what happens when a user views a Confluence page containing a JIRA macro.
Security Risks
Please take the following considerations into account when setting up trusted communication:
378
When you configure JIRA to trust an application, you are allowing the application to access JIRA in the name of a particular user. The trusted application passes JIRA the user's login name, but no other authentication information. JIRA does not request the user's password. By doing this, you are bypassing JIRA's authentication mechanism. Do not configure a trusted application unless you trust all code in that application to behave itself at all times. Trusted communication uses public/private key cryptography to establish the identity of the trusted server. The trusted application needs to maintain the security of its private key. Confluence stores its private key in the database. So you must be sure that the Confluence database is secure, and also any full backups of the database. Ensure that you specify an IP address for your Confluence site when configuring trusted applications in JIRA. Do not use the wild card *.*.*.* as the IP address. Failure to configure IP address restrictions is a security vulnerability, allowing an unknown site to log into your JIRA site under a user's login ID. Be aware of the risks associated with using separate user bases, as explained above. We strongly recommend a common user base between the trusted and trusting applications. When configuring an application to trust another application, you should use a trusted network or SSL to protect the sensitive information passed between the applications during the configuration procedure. This will help to prevent man-in-the-middle attacks.
Troubleshooting
Below are the warning messages which may appear on your Confluence page, above the output of the JIRA Issues or JIRA Portlet macro. Warning Message Cause Solution
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
The JIRA server does not recognise your user name. Issues have been retrieved anonymously.
The logged-in Confluence user is not registered in the JIRA user base.
Add the username to your JIRA user base. It is highly recommended that your JIRA and Confluence instances share a common user base. One of the following solutions: Configure JIRA to trust Confluence. Disable trusted communications for the JIRA macros in Confluence. Use the anonymous parameter in all your JIRA Issues and JIRA Portlet macros.
The JIRA server does not trust this Confluence instance for user authentication. Issues have been retrieved anonymously. You can set the macro to always use an anonymous request by setting the 'anonymous' parameter to 'true'.
Your JIRA instance has not been configured to trust your Confluence instance.
379
The JIRA server does not support trust requests. Issues have been retrieved anonymously. You can set the macro to always use an anonymous request by setting the 'anonymous' parameter to 'true'.
Your JIRA instance is not able to handle trusted communications (i.e. the JIRA version is earlier than 3.12.0).
One of the following solutions: Download the latest version of JIRA and then configure JIRA to trust Confluence. Disable trusted communications for the JIRA macros in Confluence. Use the anonymous parameter in all your JIRA Issues and JIRA Portlet macros.
Failed to login trusted application: confluence:14159892 due to: com.atlassian.security.auth.trustedapps.CertificateTooOldException: OLD_CERT; Certificate too old.
There is a date/time difference between the JIRA server and Confluence server.
Consult Troubleshooting the JIRA Issues Macro and Trusted Applications for further troubleshooting.
JIRA Issues Macro JIRA Portlet Macro Connecting to LDAP or JIRA or Other Services via SSL Single Sign-on Integration with JIRA and Confluence Troubleshooting the JIRA Issues Macro and Trusted Applications
380