Space Details

Key: Name: Description: Creator (Creation Date): Last Modifier (Mod. Date): DOC Confluence 2.6
Complete documentation for latest version of Confluence wiki

mike@atlassian.com (Dec 18, 2003) smaddox (Sep 27, 2007)

Available Pages
• Outdated Pages Archive (outdated) Keyboard Shortcuts • Adding LDAP Integration To Confluence 2.0.x • • • • • • • • • • • Administrators Guide draft Confluence Administration Guides Confluence Backups begin failing on MySQL Confluence Configuration Tips Confluence Plugin Development Kit Converting Macro Libraries to Confluence Plugins Customising Confluence Decorator Macros Documentation Home Frequently Asked Questions Confluence System Files and Data Storage • How-To Guides • Gallery Macro Themes • • • • •

Restoring Passwords To Recover Admin User Rights Troubleshooting HTTPS or SSL-related problems

What browsers are supported? I cannot see the Rich Text Editor in my browser Guide to Confluence Macros (outdated) Attachments Macro • (outdated) Blog Posts Macro • • (outdated) Children Display Macro (outdated) Child Page 1 • (outdated) Grandchild Page • (outdated) Child Page 2 • (outdated) Code Block Macro

• • • • • • • •

(outdated) Create Space Button Macro (outdated) Dynamic Tasklist Macro (outdated) Global Reports Macro (outdated) IM Presence Macro (outdated) Include Page Macro (outdated) JIRA Issues Macro JIRA 3.7 Link Format Change • (outdated) JIRA Portlet Macro
Page 1

Document generated by Confluence on Oct 10, 2007 11:54

• • • • • • • • • • • •

(outdated) JUnit Report Macro (outdated) Layout Macros (outdated) Noformat Macro (outdated) Recently Updated Content Macro (outdated) RSS Feed Macro (outdated) Search Macro (outdated) Space Details Macro (outdated) Spacegraph Macro (outdated) Spaces List Macro (outdated) Userlister Macro

(outdated) Welcome Message Macro • How to delegate user management in Confluence 1.0 to JIRA Import, Export and Backups Change the time of day the Daily Backup runs • • • Restore system from backup Troubleshooting failed XML backups

• • • • • • • •

Troubleshooting XML backups that fail on restore • Macro Plugins v1.3 MySQL index and PostgreSQL Contraint Trigger problem Oracle and Confluence 1.3 RSS Shortcut Links Special LDAP Integration Note for users upgrading to Confluence version 2.1.x or higher Structured Content with Templates The Confluence Manual Customizing Site Title • Installing the standalone version • • • • • • Installing the WAR version Integrating With JIRA Page Families Page History Requirements

• • • • •

Macro Management - obsolete • __ConfluenceHosted TreeNavigation

Security and Permissions • Use, Write, and Install Macros - obsolete Custom Java Macros - obsolete •

Administration Guide Attachments Directory _ConfluenceHostedNA1 .bookmarks

Document generated by Confluence on Oct 10, 2007 11:54

Page 2

Confluence Documentation Home Administrators Guide • Administration • Cache Statistics • Changing time of Daily Backup • • • • • •

Confluence Data Directory Configuration Confluence home directory contents Content Index Administration Important Directories and Files Manually Backing Up The Site Configuring Daily Backups • User Submitted Backup & Restore Scripts • Migrate Or Clone Confluence Between Servers Moving Confluence Between Servers Rebuilding the Ancestor Table Restoring a Site Restoring a Space Changing the version of a space backup • Restoring Data from other Backups Restoring Data from the Administration Console Retrieve file attachments from a backup Troubleshooting failed XML site backups Viewing and Editing License Details Viewing System Information

• • • • • • • • • • • • •

Where Is My ConfluenceHome Directory? • Cluster Administration page Cluster Troubleshooting • Configuring Confluence Optional Settings • Attachment Storage Configuration • • • • • • • • Enabling CamelCase Linking Enabling Remote APIs Enabling Rich Text Editing Option Enabling Threaded Comments Enabling Trackback Making Rich Text Editing default

WebDAV Configuration • Other Settings Configuring Attachment Size • • • • •

Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Jira Issues Icon mappings

Document generated by Confluence on Oct 10, 2007 11:54

Page 3

• • • • •

Configuring Number Formats Configuring Shortcut Links Configuring Time and Date Formats Number of Ancestors to Show in Breadcrumbs

Thumbnail Settings • Site Configuration Configuring the Server Base URL • Configuring the Site Homepage • • • • • Editing the Global Logo Editing the Site Title

Customising Default Space Content

Editing the Site Welcome Message

View Space Goes to Browse Space • Configuring Encoding Troubleshooting Character Encodings • "€" Euro character • MySQL 3.x Character Encoding Problems • Configuring Mail Configuring a Server for Outgoing Mail • Enabling the 'Mail Page' plugin •

The Mail Queue • Confluence and JIRA Add Confluence EAR-WAR to JIRA Standalone • Integrating JIRA and Confluence •

Override properties in JIRA to Confluence Bridge • Confluence Security Confluence Community Security Advisory 2006-01-19 • • • • • • • • Confluence Security Advisory 2005-02-09 Confluence Security Advisory 2005-12-05 Confluence Security Advisory 2006-01-20 Confluence Security Advisory 2006-06-14 Confluence Security Advisory 2007-07-26 Confluence Security Advisory 2007-08-08 Java Policy Security with Confluence

NoFollow Support • Design and Layout Custom Decorator Templates • Customising Look and Feel Overview • Customising Colour Schemes • • • • Customising Layouts Upgrading Custom Layouts • Global Templates

Working With Decorator Macros

Document generated by Confluence on Oct 10, 2007 11:54

Page 4

Themes Configuration Applying a Theme To A Site • Creating a Theme • Adding a theme icon • Customising the Left Navigation Theme • • • • Deploying the theme as a plugin Including Cascading Stylesheets in Themes Modifying Look and Feel (for themes) Configuring the theme plugin •

• •

Themes Overview • Importing Data Snip Snap Import • Macros Editing and Removing macros • Enable The Flowchart Macro • •

Troubleshooting the Gallery Macro • Performance Tuning Configuring a Large Confluence Installation • Confluence Performance Enhancement • Creating Memory Leaks with Spring • Filtering Regular Expression Application • • • • How Adaptavist Runs Confluence Memory usage and requirements java.util.zip.ZipFile.open causes OutOfMemoryError for large zip • files Requesting Performance Support

Enabling HTML macros Enabling the html-include Macro •

• • • •

Troubleshooting Slow Performance Using Page Request Profiling • Profiling using the YourKit Plugin Recognised System Properties Scheduled Jobs Search Setup Confluence To Index External Sites •

Setup External Search Tool To Index Confluence • Security Adding SSL for Secure Logins and Page Security • • • • • • Anonymous Access to Remote API Enabling or Disabling Public Signup Hiding External Links From Search Engines Hiding the People Directory Managing External Referrers Excluding external referrers • Hiding external referrers •
Page 5

Document generated by Confluence on Oct 10, 2007 11:54

• • •

User Email Visibility • Spam Prevention (Captcha) Troubleshooting slow search performance and "Too many open files" problem User Management Confluence User Management • Adding a Group • Adding a New User • • • • • • • • • • • • • Adding or Removing a User from a Group Changing Usernames Editing User Details Global Groups Overview Global Permissions Overview Migrating to new User Management Removing a Group Removing a User Setting up Anonymous Access

Viewing members of a group • How to Improve User Search Performance Integrating with Crowd JIRA User Management Delegate user management to use JIRA logins • Revert from JIRA to internal user management • JIRA User Management FAQ • LDAP User Management Activating External User Management • •

Add LDAP Integration Automatically Adding LDAP users to the confluence-users • Group Customising atlassian-user.xml • Add LDAP Integration For User Authentication Only atlassian-user.xml reference Changes in osuser.xml from 1.0.3a to 1.1.x Configuring multiple LDAP repositories Confluence Caching OSUser Provider Importing LDAP Users LDAP FAQ Connect to LDAP via SSL •

• • • • • • • •

• • •

Troubleshooting the "Not Permitted" Screen Integration Cannot login with Confluence admin account • Migrating users from Confluence to JIRA Requesting External User Management Support Understanding User Management in Confluence

under

LDAP

Document generated by Confluence on Oct 10, 2007 11:54

Page 6

User Management Frequently Asked Questions • Configuration Guide Adding SSL on Confluence 2.1.5a and earlier • Application Server Configuration • Known Issues for Apache Tomcat • Configuring a MySQL Datasource in Apache Tomcat • Configuring Tomcat's URI encoding • • • • • • • NotSerializableException on shutdown

Max size of HTTP POST request and Confluence page size

Running Tomcat on a Different Port • Known Issues for JBoss Known Issues for Jetty Known Issues for Resin 2.x Known Issues for Resin 3.x Confluence and SOAP on Resin • Updating web.xml for Resin 3 • Known Issues for WebLogic Known Issues for Websphere List Of Supported Application Servers

• • • • • •

Known Issues for SAP Application Server

Websphere 6 Install Walkthrough • Application Server URL encoding Confluence Installation Guide Confluence Cluster Installation • Apache and Tomcat load balancing • Confluence Cluster Installation with Existing Data • Upgrading a Confluence Cluster • Confluence Unix and X11 Dependencies • • • • • Error creating bean with name 'scheduler' Get A Confluence Licence Installing Confluence Standalone Change listen port for Confluence Standalone • Set JAVA_HOME variable in Windows • Installing the Confluence EAR-WAR edition License will not validate Server Hardware Requirements Guide Example Size & Hardware Specifications From Customer Survey

• • • •

Using the IBM 64bit J9 JDK • Confluence Release Cycle Development Releases • Development Release Warnings • Release Notes 1.3-DR1 • • Release Notes 1.3-DR2

Document generated by Confluence on Oct 10, 2007 11:54

Page 7

• • • • • • • • • • • • • • • • •

Release Notes 1.3-DR3 Release Notes 1.3-DR4 Release Notes 1.3-final Release Notes 1.4-DR1 Release Notes 1.4-DR2 Release Notes 1.4-DR3 1.4 Interface - Where Did Everything Go? • Release Notes 1.4-DR4 Release Notes 1.4-DR6 Issues Resolved for 1.4-DR6 • Release Notes 1.4-DR7 Release Notes 1.4-RC2 Release Notes 1.5-DR2 table test • Release Notes 2.0-RC1 Release Notes 2.0-RC2 Release Notes 2.3-DR1 Release Notes 2.3-DR2

Release Notes 2.6-dr1 Including Cascading Stylesheets in Themes for Confluence 2.6 • Release Notes Confluence 2.6 Release Notes • Confluence 2.6 Upgrade Guide • Issues resolved in Confluence 2.6 • • Release Notes 1.0 Demonstration Site •

• • • • • • • • • •

Issues Resolved for 1.0 • Release Notes 1.0.1 Issues Resolved for 1.0.1 • Release Notes 1.0.3 Issues Resolved for 1.0.3 • Release Notes 1.0a2 Release Notes 1.0a3 Release Notes 1.0b1 Release Notes 1.0b2 Feature List • Release Notes 1.0b3 Issues Resolved for 1.0b3 •

Release Notes 1.0b4 Issues Resolved for 1.0b4 • Release Notes 1.0rc1 Issues Resolved for 1.0rc1 • Release Notes 1.0rc2 Issues Resolved for 1.0rc2 •
Page 8

Document generated by Confluence on Oct 10, 2007 11:54

• • • • • •

Release Notes 1.0rc5 Issues Resolved for • Release Notes 1.0rc6 Issues Resolved for • Release Notes 1.1 Issues Resolved for • Release Notes 1.1.1 Issues Resolved for • Release Notes 1.1.2

1.0rc5 1.0rc6 1.1 1.1.1

Release Notes 1.2 Issues Resolved for 1.2 • Permissions Changes in 1.2 • Release Notes 1.2.1 Issues Resolved for 1.2.1 • Release Notes 1.2.2 Issues Resolved for 1.2.2 • Release Notes 1.2.3 Issues Resolved for 1.2.3 • Release Notes 1.3 Confluence Presentation • • Issues Resolved for 1.3 What's New in 1.3 • Release Notes 1.3.1 Issues Resolved for • Release Notes 1.3.2 Issues Resolved for • Release Notes 1.3.4 Issues Resolved for • Release Notes 1.3.5 Issues Resolved for • Release Notes 1.3.6

• • • •

• • • • • • • • •

1.3.1 1.3.2 1.3.4 1.3.5

Release Notes 1.4 Issues Resolved for 1.4 •

Release Notes 1.4.1 Issues Resolved for 1.4.1 • Release Notes 1.4.2 Issues Resolved for 1.4.2 •

Release Notes 1.4.3 Confluence SOAP Provider Migration • Issues Resolved for 1.4.3 • Release Notes 1.4.4 Issues Resolved for 1.4.4 • Release Notes 2.0 Issues Resolved for 2.0 • Release Notes 2.0.1

• • •

Document generated by Confluence on Oct 10, 2007 11:54

Page 9

• • • • • • • • • • • • • • • •

Issues resolved for 2.0.1 • Release Notes 2.0.2 Issues resolved for 2.0.2 • Release Notes 2.0.3 Issues resolved for 2.0.3 • Release Notes 2.1 Issues Resolved for 2.1 • Release Notes 2.1.1 Issues resolved for 2.1.1 • Release Notes 2.1.2 Issues resolved for 2.1.2 • Release Notes 2.1.3 Issues resolved for 2.1.3 • Release Notes 2.1.4 Issues resolved for 2.1.4 • Release Notes 2.1.5 Issues resolved for 2.1.5 • Release Notes 2.2 Issues Resolved for 2.2 • Release Notes 2.2.1 Issues resolved for 2.2.1 • Release Notes 2.2.10 Release Notes 2.2.2 Issues resolved for 2.2.2 •

Release Notes 2.2.3 Issues resolved for 2.2.3 • Release Notes 2.2.4 Issues Resolved for 2.2.4 • Release Notes 2.2.5 Release Notes 2.2.6a 2.2.5 Security Patch • Issues Resolved for 2.2.6a • Release Notes 2.2.7 Issues Resolved for 2.2.7 • Release Notes 2.2.8 Issues Resolved for 2.2.8 •

• • • •

Release Notes 2.2.9 Issues Resolved for 2.2.9 • Release Notes 2.3 FileAppender log4j.properties • Issues Resolved for 2.3 • Release Notes 2.3.1 Release Notes 2.3.2 Release Notes 2.3.3 Release Notes 2.4

• • • •

Document generated by Confluence on Oct 10, 2007 11:54

Page 10

• • • • • • • • • • • • • •

Changes to the Page Permission API in Confluence 2.4 • Release Notes 2.4.1 Release Notes 2.4.2 Issues Resolved for 2.4.2 • Release Notes 2.4.3 Release Notes 2.4.4 Release Notes 2.4.5 Release Notes 2.5 Issues Resolved for 2.5 • Release Notes 2.5.1 Release Notes 2.5.2 Release Notes 2.5.3 Release Notes 2.5.4 Release Notes 2.5.5 Upgrade Guide 2.5.5 • Release Notes 2.5.6 Upgrade Guide 2.5.6 • Release Notes 2.5.7 Upgrade Guide 2.5.7 • Release Notes 2.5.8 Upgrade Guide 2.5.8 • Release Notes_1.0.1

• Confluence Setup Guide Custom Installation • External Database • •

Load Content for the site

• •

• Content Anonymizer for Data Backups

Restoring from Backup During Setup • Standalone Setup Wizard

Database Configuration Database Setup Guides • Database Setup For Any External Database • Database Setup For mySQL • •

• •

• Improving Database Performance

Database Setup for Oracle Database Setup for Oracle (Pre Confluence 2.2) • Database Setup for SQL Server

Known Issues For Supported Databases Configuring Database Character Encoding • Known Issues for DB2 • Interpreting DB2 error codes • Known Issues for MySQL • • • Known Issues For Oracle Known Issues for PostgreSQL
Page 11

Document generated by Confluence on Oct 10, 2007 11:54

• • • • •

Known Issues For SQL Server

Known Issues for Sybase Database • List Of Supported Databases Migrate to a Different Database Database JDBC drivers •

Troubleshooting External Database Connections Troubleshooting the Embedded Database (hSQL DB) Connecting to HSQLDB using DBVisualizer • Database Tables Reference •

• • • • • • • • •

Upgrading From HSQL 1.7.1 to 1.8 • Guide to using Apache Tomcat's Virtual Hosts How to dump Active Directory data to a file

Known Issues with Enterprise or Webhosting environments List Of Supported Operating Systems Managing Application Server Memory Settings Modify Confluence Interface Text Paddle Pull down RSS Feeds or use the Repository plugin through a web proxy Running Confluence behind Apache Using Apache with mod_jk • Using Apache with mod_proxy •

• • • •

Using Apache with virtual hosts and mod_proxy • Setting up Confluence with IIS Setting Up Public Access Setup a mail session in standalone version Start Confluence automatically on system startup Start Confluence automatically on Linux & Unix • • •

Start Confluence automatically on OS X using launchd

• • • • •

Start Confluence automatically on Windows as a Service Start Confluence automatically on Windows as a Service (Pre 2.2) • Supported Platforms FAQ Troubleshooting SQL Exceptions Upgrading Confluence How to run a SQL script on your database • Weblogic - Troubleshooting Webserver Configuration Apache and Apache Connector Tips • Configure Web Proxy Support for Confluence •

Confluence Development Hub Confluence Developer FAQ • Encrypting error messages in Sybase • How do I associate my own properties with a ContentEntityObject? • • How do I autowire a component?

Document generated by Confluence on Oct 10, 2007 11:54

Page 12

• • • • • • • • • • • • • • • • • • • • • • • • • •

How do I change the default polling time for email in Confluence? How do I configure Confluence to use GMail as the mail server How do I convert wiki text to HTML? How do I find information about lost attachments? How do I find the logged in user? How do I get a reference to a component? How do I get hold of the HttpServletRequest? How do I get the base URL and ContextPath of a Confluence installation? How do I get the information about Confluence such as version number, build number, build date? How do I get the location of the confluence.home directory? How do I load a resource from a plugin? How do I make my attachments open in a new window or a tab? How do I prevent my rendered wiki text from being surrounded by paragraph tags? How do I tell if a user has permission to...? How does RENDERMODE work? HTTP Response Code Definitions I am trying to compile a plugin, but get an error about the target release I have checked out the source, and use IntelliJ IDEA. Where do I go from here? What class should my macro extend? What class should my XWork action plugin extend? What is Bandana? One form of Confluence Persistence What is the best way to load a class or resource from a plugin? What's the easiest way to render a velocity template from Java code? how do I retrieve the current

Within a Confluence macro, ContentEntityObject? Confluence Developer Forum Confluence Internals Bandana caching • • • • • • • • • • •

Character encodings in Confluence Clustering in Confluence Cluster safety mechanism • Confluence Internals History Confluence rendering pipeline Date formatting with time zones HTML to Markup Conversion for the Rich Text Editor HTTP authentication with Seraph Persistence in Confluence Spring IoC in Confluence Velocity Template Overview

Document generated by Confluence on Oct 10, 2007 11:54

Page 13

Confluence Objects Accessible From Velocity • Confluence Plugin Guide Installing and Configuring Plugins manually • Installing and Configuring Plugins using the Plugin Repository • • • • Installing plugins overview Single Sign-on Writing Confluence Plugins Accessing Confluence Components From Plugin Modules • • Confluence Plugin Module Types Code Formatting Plugins • Component Plugins • • • • • Decorator Plugins Editor Plugins Event Listener Plugins Writing an Event Listener Plugin Module • EventListener Example • Extractor Plugins Attachment Content Extractor Plugins • Job Plugins

Basic Introduction to Velocity

Downloadable Plugin Resources

• • •

Language Pack Plugins Creating A New Confluence Translation • Translating ConfluenceActionSupport Content • • Translations for the Rich Text Editor Updating A Confluence Translation • Lifecycle Plugins Macro Plugins Documenting Macros • User Macros • Writing Macros • RPC Plugins Servlet Plugins Spring Component Plugins StateAware Theme Plugins Creating a Theme Plugin • Packaging and installing a Theme Plugin •

• •

• • • • •

• • • •

Updating a theme for editable comments • Trigger Plugins User Macro Plugins Velocity Context Plugins Web UI Plugins

Document generated by Confluence on Oct 10, 2007 11:54

Page 14

• Customise Confluence Page Exports Customise Adobe PDF Exports • Customise MS Word Exports •

• Plugin Self-Configuration

Workflow Plugins Workflow Plugin Prototype • Approval Workflow • XWork-WebWork Plugins

Getting Started Build and Deploy Confluence and Confluence Plugins • Building and Deploying Confluence in IDEA • Compiling and Running Confluence • Creating an IDEA project with a Confluence distribution • • • Setup Confluence Source Code For Development • Building and Deploying Plugins in IDEA Adding a plugin project to IDEA • • • • Setting up a new Confluence plugin Working on an existing Confluence plugin • Developing with Eclipse Development Tips Allocate more memory to IDEA • • • Disable Velocity Caching Enabling Developer Mode • Initial development environment setup Atlassian Maven repositories • Example settings.xml • Packaging and releasing a plugin Plugin Project Files build.properties • • •

Creating an IDEA project with a Confluence source release Maven1

• •

project.properties

project.xml • Userinfo Plugin Tutorial UPT 1 - Getting Started • •

UPT 2 - Getting the Data UPT 2.1 - The UserInfo Bean • UPT 2.2 - The XWork Action Class • • UPT 2.3 - The Velocity Template UPT 2.4 - Defining the XWork Plugin Module • UPT 3 - Integrating with the Confluence UI UPT 3.1 - Linking Using Web UI Plugins • UPT 3.2 - Using Inline Decorators •

UPT4 - Display the info in a macro • Remote API Specification

Document generated by Confluence on Oct 10, 2007 11:54

Page 15

Remote API Specification 2.4 • Confluence Main FAQ Copy Or Rename A Space • GZipping a HTTP Response within Confluence • • • • How do I change the space key? How do I disable indexing of attachments How Do I? Add many files to a page at once • Add Spell Checking To Confluence • • • • • • • • • • • • • • • • • • • • •

Backup FAQ Alternative Backup Strategy for Large Confluence Sites • Change default font size in Confluence Create a page by passing parameters to a template Disable public account signups Enable public anonymous access Enable user access logging How much disk space does Confluence need? I can not find the "Rich Text" editor. Is the editor part of Confluence 1.4.3? Migrate Confluence from one database to another Redirect users to a page on login Restrict Attachments Based On File Type Setup email notifications of page updates Share users and groups between Confluence and JIRA Upgrade My Trial To A Commercial Version

Where does Confluence store all its data? • How to resolve the "Unprocessed Continuation Reference" error Installation Troubleshooting FAQ Internationalising Confluence Bundled Plugins JIRA Issues Macro FAQ Mail Archiving FAQ New User FAQ Can I use CamelCaseLinks like they do on WardsWiki? • Can Users Edit Individual Sections Within a Page? •

• • •

How does Confluence differ from a wiki? • Redirect users straight to space home page after successful login Running Confluence Behind a Caching Proxy Server Troubleshooting FAQ Cannot install Confluence due to 'NullPointerException in • DefaultPluginManager' error Cannot install Confluence due to missing demo-site.zip • Cannot register Confluence due to 'License you entered was not valid' • error

Document generated by Confluence on Oct 10, 2007 11:54

Page 16

• • • • • • • • • • • • • • • • • • •

Cannot send email due to 'javax.mail.NoSuchProviderException' SMTP error Confluence content or attachments are randomly lost Confluence stops responding after some time Confluence will not start - CommandBridge ClassNotFoundException Confluence won't start with "Error creating Home directory" Custom HTML broken in Look and Feel after saving invalid HTML Dynamic tasklist macro edits fail with ConversionException after JDK upgrade Edit page fails with 'DataIntegrityViolationException... Violation of PRIMARY KEY constraint' Fix '404' errors in Space tree view Fix 'Error using thumbnails - No image support in Java runtime' Fix 'java.lang.UnsupportedClassVersionError... Unsupported major.minor version 49.0' Fix 'Out of Memory' errors by increasing available memory Fix 'Page Not Found' errors for pages with spaces in the title Fix 'Too many open files' error on Linux by increasing filehandles Fix JavaScript browser errors PDF export fails on Linux with UnsatisfiedLinkError Resolve Missing Attachments in Confluence RSS Feed FAQ RSS Readers Compatibility • Search is not finding my data AND the indexing process does not appear to be completing View page containing Chart macro throws 'NoClassDefFoundError'

• Confluence User Guide Archiving Mail Overview • Adding a Mail Account • • • • • • • • • • Deleting Mail Fetching Mail Importing Mail Linking to Mail

Managing Mail Accounts Restoring Mail

Viewing Mail • Confluence Glossary Confluence Icons Confluence Notation Guide Overview Confluence Emoticons • Form Field Markup for Templates • • • • Working with Headings Working with Lists Working with Tables

Document generated by Confluence on Oct 10, 2007 11:54

Page 17

• •

Working with Text Breaks

Working with Text Effects • Customising Look and Feel Applying A Theme To A Space • Change Confluence Browser Icon • • • • • Changing a Space's Logo Customising Homepage Editing a Space's Colour Scheme Modify Confluence User Interface Text

• • •

Modifying Confluence Layouts Using Custom Decorators • Dashboard Customising the Dashboard • Displaying an Image Image File Formats • Exporting a Space Confluence to HTML • Confluence to PDF • Create PDF in another language • • Confluence to XML Exporting to a Word document • Importing Content Into Confluence Importing Pages from Disk • Keyboard Shortcuts Rich Text Editor Overview Enabling Rich Text Editing • Rich Text-Creating a new link • • • • • • • • Rich Text-Inserting an image Rich Text-Inserting Symbols Rich Text-Linking to a Page Rich Text-Linking to an Attachment Rich Text-Linking to an Image Rich Text-Working with Tables Rich Text-Inserting emoticons

• • •

Rich Text-Working with Text Effects • Searching Confluence Confluence Search Fields • Confluence Search Syntax • • Searching the People Directory Text Tokenization and Filtering • Security Overview Page Restrictions • Setting a Page's Restrictions • The User Search Window •

Document generated by Confluence on Oct 10, 2007 11:54

Page 18

• • •

Viewing a Page's Restrictions • Site Administrators and their permissions Space Administrators and their permissions Space Permissions Overview Assigning Space Permissions • • Revoking Space Permissions Viewing Space Permissions • Users and Groups

• • • • •

Viewing Restricted Pages • Site Backup and Restore Space Attachments Directory Space Backup and Restore Tracking Updates Overview Managing Watches • • •

Subscribing to Daily Email Reports Subscribing to RSS Feeds within Confluence Using pre-specified RSS feeds • Using the RSS Feed Builder • Watching a Page Watching a Space Working with RSS Feeds Adding a username and password to Confluence RSS feeds •

• • • •

User Profile Overview Changing Password • Editing User Preferences • • • • • • Editing User Profile Email Address Privacy

Linking to Personal Spaces and User Profiles Updating Email Address Uploading a Profile Picture

Viewing User Profile • What's New in Confluence 2.0 What's New-Favourites • What's new-Labels • •

What's New-Rich Text Editor

What's new-RSS Feed Builder • Working with Attachments Overview Attaching Files to a Page • Attachment Versions • • • • • Downloading Attachments Editing Attachment Details Embedding Multimedia Content

Displaying List of Attachments in a Page

Document generated by Confluence on Oct 10, 2007 11:54

Page 19

• • • •

Embedding PowerPoint Presentations in a Page Finding an Attachment Linking to Attachments

Viewing Attachment Details • Working with Bookmarks Adding a bookmark • Adding a Bookmark Icon to your Browser • Adding a Bookmark Link to your Browser's Favorites • Dragging a Bookmark Link to your Browser • • • • Editing or Commenting on a Bookmark Removing a Bookmark Subscribing to a Bookmarks RSS Feed

Viewing Bookmarks • Working with Favourites Overview Adding Favourites • Removing Favourites • Viewing Favourites • Working with Labels Overview Adding a Global Label • Adding a Personal Label • • • • • Adding a Space Label Adding a Team Label Categorising Wiki Content Using Labels Label Macros Content by Label Macro • Navmap Macro • • • • • • • •

Recently Used Labels Macro

Related Labels Macro • Removing a label from a page Removing a space label Removing a team label Viewing Global Labels Viewing labelled pages Viewing personal labels

Viewing Popular Labels • Working with Links Overview CamelCase linking • CamelCasePage • Changing the Title of a link • Sample Release Notes • • • • Linking an Image Linking to Confluence Pages from Outside Confluence Linking to Pages in Another Space
Page 20

Document generated by Confluence on Oct 10, 2007 11:54

• • • • •

Linking to Pages Within the Same Space Linking to Web Pages Trackback Using a link to create a new mail message

Working with Anchors • Working with Macros Blog Posts Macro • Bookmarks Macro • •

Children Display Macro Child Page 1 • Grandchild • Child Page 2 • Code Block Macro Color Text Macro Column Macro Create Space Button Macro Dynamic Tasklist Macro Excerpt Include Macro Excerpt Macro Favourite Pages Macro Flowchart Macro Gallery Macro Global Reports Macro HTML Macro IM Presence Macro Include Page Macro Sample Include Page • Info Macro JIRA Issues Macro JIRA Portlet Macro JUnit Report Macro Noformat Macro Note Macro Panel Macro Recently Updated Content Macro RSS Feed Macro Search Macro Section Macro Space Details Macro Spacegraph Macro Spaces List Macro Thumbnail Macro
Page 21

• • • • • • • • • • • • • • • • • • • • • • • • • • • • •

Document generated by Confluence on Oct 10, 2007 11:54

• • • •

Thumbnail and Gallery Example • Tip Macro Userlister Macro Warning Macro

Welcome Message macro • Working with News Overview Adding News • Deleting News • • • Editing News Linking to News

Viewing News • Working with Page Families Breadcrumbs • Changing Parent of a Page • • • • • • Creating a Child Page Viewing a Page's Family Viewing a Page's Location within a Space Viewing Children of a Page Viewing Hierarchy of Pages within a Space

What is a Page Family? • Working with Pages Overview Commenting on a Page • Adding a Comment • • • • Deleting Comments Editing a Comment Linking to Comments Sample Page • child page • Viewing Comments

• • • • • • • • • • • • •

• Concurrent Editing and Merging Changes Copying a Page Creating a New Page Choose a Page • Deleting a page Deleting an Attachment Display an older version of a page E-mailing a Page Editing an Existing Page Linking pages Making Rich Text or Wiki Markup Editing Default Page Layout in Edit Mode (Rich Text) Page Layout in Edit Mode (Wiki Markup) Page Layout in View Mode
Page 22

Document generated by Confluence on Oct 10, 2007 11:54

• • • • •

Purging Deleted Pages Recording Change Comments Renaming a Page Restoring a Deleted Page Viewing Page Information Viewing History of a Page • Comparing Two Different Versions of a Page • Restoring an Older Version of a Page • Viewing Recent changes • Working with Drafts Overview Working with Drafts Faq • Writing Confluence pages

• Working with Spaces Overview Administering Spaces • •

Browsing a space Editing Space Details • Managing Orphaned Pages • • • • • Tree View of Pages

Managing Undefined Pages Viewing Pages Alphabetically Viewing Recently Updated Content

• • • •

Viewing Space Details • Converting a Global Space to a Personal Space Deleting a Space Guidelines For Partitioning Content Into Spaces & Pages Moving Content from one Space to Another Moving a family of pages from one space to another • • Moving a Page from one Space to Another Moving an Attachment • Setting up a New Global Space Setting up your Personal Space Viewing all Spaces

• • • •

Viewing Space Activity • Working with Templates Overview Adding a Template • • • Editing a template

Creating a Page using a Template

Removing a Template • Troubleshooting & Technical Support Enabling detailed Hibernate logging • • • General Support Enquiries Logging A Thread Dump

Document generated by Confluence on Oct 10, 2007 11:54

Page 23

Outdated Pages Archive
This page last changed on Feb 03, 2006 by vidya.

A list of pages outdated pages in the doc space. • • • • • • • • • • • • (outdated) Keyboard Shortcuts Adding LDAP Integration To Confluence 2.0.x Administrators Guide draft Confluence Administration Guides Confluence Backups begin failing on MySQL Confluence Configuration Tips Confluence Plugin Development Kit Converting Macro Libraries to Confluence Plugins Customising Confluence Decorator Macros Documentation Home Frequently Asked Questions ° Confluence System Files and Data Storage ° How-To Guides - Gallery Macro Themes ° Restoring Passwords To Recover Admin User Rights ° Troubleshooting HTTPS or SSL-related problems ° What browsers are supported? I cannot see the Rich Text Editor in my browser Guide to Confluence Macros ° (outdated) Attachments Macro ° (outdated) Blog Posts Macro ° (outdated) Children Display Macro - (outdated) Child Page 1 - (outdated) Grandchild Page - (outdated) Child Page 2 ° (outdated) Code Block Macro ° (outdated) Create Space Button Macro ° (outdated) Dynamic Tasklist Macro ° (outdated) Global Reports Macro ° (outdated) IM Presence Macro ° (outdated) Include Page Macro ° (outdated) JIRA Issues Macro - JIRA 3.7 Link Format Change ° (outdated) JIRA Portlet Macro ° (outdated) JUnit Report Macro ° (outdated) Layout Macros ° (outdated) Noformat Macro ° (outdated) Recently Updated Content Macro ° (outdated) RSS Feed Macro ° (outdated) Search Macro ° (outdated) Space Details Macro ° (outdated) Spacegraph Macro ° (outdated) Spaces List Macro ° (outdated) Userlister Macro ° (outdated) Welcome Message Macro How to delegate user management in Confluence 1.0 to JIRA Import, Export and Backups ° Change the time of day the Daily Backup runs ° Restore system from backup ° Troubleshooting failed XML backups ° Troubleshooting XML backups that fail on restore Macro Plugins v1.3 MySQL index and PostgreSQL Contraint Trigger problem Oracle and Confluence 1.3 RSS Shortcut Links Special LDAP Integration Note for users upgrading to Confluence version 2.1.x or higher Structured Content with Templates The Confluence Manual

• •

• • • • • • • •

Document generated by Confluence on Oct 10, 2007 11:54

Page 24

Customizing Site Title Installing the standalone version ° Installing the WAR version ° Integrating With JIRA ° Page Families ° Page History ° Requirements ° Security and Permissions • Use, Write, and Install Macros - obsolete ° Custom Java Macros - obsolete ° Macro Management - obsolete
° °

Document generated by Confluence on Oct 10, 2007 11:54

Page 25

(outdated) Keyboard Shortcuts
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Confluence provides the following keyboard shortcuts. Not all are compatible with Internet Explorer:

Screen All Login

Keystroke Alt-S Alt-U Alt-P Alt-R

Action Search field Username field Password field Check 'Remember Me' View Page Tab Edit Tab Attachments Tab Information Tab Add Page

Firefox

Internet Explorer

Page View

Alt-V Alt-E Alt-A Alt-I

Add Page

Alt-A

Document generated by Confluence on Oct 10, 2007 11:54

Page 26

Adding LDAP Integration To Confluence 2.0.x
This page last changed on May 10, 2006 by david.soul@atlassian.com.

Old Documentation Notice A new improved LDAP integration was introduced in Confluence 2.1. This document describes the 'old style' OSUser LDAP integration. You MUST use this document if you are delegating user management to Jira. Otherwise, if you are new to Confluence and have not set up LDAP integration before, we recommend using the new LDAP integration.

Introduction
Many organizations have an LDAP directory acting as a centralized database of system users. Confluence is able to authenticate users against their LDAP password. This kind of LDAP integration is limited to checking passwords against the LDAP repository. For advanced LDAP group management, you can use the new LDAP integration in Confluence 2.1 and later. Before starting this guide, please ensure you have gone through the normal Confluence installation process, including setting up the administrative user. Once this is done, you can apply the changes below to enable LDAP integration. If you're starting with a brand new Confluence installation, a summary of process looks like this: 1. Log in as the Confluence administrator, and for each LDAP user who should be able to log in to Confluence: • Add a new user in Confluence with the same username as in LDAP. The user's password in Confluence can be set to anything, because the password will be checked against LDAP. • Configure groups for the user as appropriate. 2. Edit the OSUser configuration file to add LDAP authentication. 3. Restart Confluence. 4. You can now log out, and log back in as any user, using the LDAP password. If you have an existing users and groups in Confluence, all you need to do it edit the OSUser configuration file and restart Confluence.

Instructions
In Confluence, user management is handled by OSUser, a pluggable user management framework. OSUser is configured through the WEB-INF/classes/osuser.xml file. Default osuser.xml providers
<provider class="bucket.user.providers.CachingCredentialsProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingAccessProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingProfileProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property></ provider>

CredentialsProviders are responsible for checking usernames and passwords, which is what we are interested in here. The default CachingCredentialsProvider looks in the Confluence database. We are going to add a ConfluenceLDAPCredentialsProvider, so that LDAP users can also be authenticated: With LDAP authentication added

Document generated by Confluence on Oct 10, 2007 11:54

Page 27

<provider class="com.atlassian.confluence.user.ConfluenceLDAPCredentialsProvider"><property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property><property name="java.naming.provider.url">ldap://localhost:389</property><property name="searchBase">dc=atlassian,dc=com</property><property name="uidSearchName">cn</property> <!-<property name="java.naming.security.principal">cn=Manager,dc=atlassian,dc=com</property><property name="java.naming.security.credentials">secret</property><property name="exclusive-access">true</ property> --> </provider><provider class="bucket.user.providers.CachingCredentialsProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingAccessProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingProfileProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property></ provider>

You will need to update the following properties to suit your LDAP server: • url (currently set to ldap://localhost:389) • searchBase (currently set to dc=atlassian,dc=com) • uidSearchName (currently set to cn) If your LDAP server is not configured to allow anonymous lookups, you need to: 1. remove comment tags 2. enter the username; including searchBase (currently set to cn=Manager,dc=atlassian,dc=com) 3. enter password (currently set to secret)

How it works
It is useful to have a general idea of how this setup works. This section outlines some consequences of the current implementation, and provides some help for people experiencing LDAP connection problems. Only password-checking for LDAP users done in Confluence The main point to realise is that user profiles are still managed in Confluence (the CachingProfileProvider in osuser.xml). Only the password lookup is done against LDAP, and only if the Confluence username coincides with a LDAP username. Technically, this behaviour is due to Credentials (password) checking being a separate operation to userprofile lookups. The profile can be loaded from the Confluence database, but the password looked up from LDAP. Furthermore, multiple credentials providers can be specified (here, LDAP and OSUser), and if one fails, the other will be used. This allows non-LDAP users to log in with their Confluence password. Not all LDAP users have Confluence access Another effect of this implementation is that LDAP users do not automatically have access to Confluence. A Confluence account must be created for each user wishing to use Confluence. This is because each Confluence user has a set of groups (for example, 'confluence-users') stored in their profile. Without an associated group, that user can do nothing; not even browse Confluence (they lack the 'use' permission). Thus, for an LDAP user to be able to use Confluence, a Confluence admin must create an account for them, and assign them to a group (typically 'confluence-user'). The password in this Confluence account will be ignored, as the LDAP password will override it.

Document generated by Confluence on Oct 10, 2007 11:54

Page 28

Administrators Guide draft
This page last changed on Jul 30, 2007 by david.soul@atlassian.com.

Administration Topics Find below a collection of links on Administration topics for Confluence.

How to...
• • • • • • • • • • • • • • • • • • • Frequently Asked Questions Restore system from backup Start Confluence automatically on Windows as a Service (Pre 2.2) Tune Confluence's Performance [Categorize Pages in Confluence] Redirect users straight to space home page after successful login Import Data from JSPWiki Import Data from other Wikis Adding LDAP Integration To Confluence 2.0.x Setup a mail session in standalone version Known Issues with Enterprise or Webhosting environments Database Setup for Oracle (Pre Confluence 2.2) Configure Web Proxy Support for Confluence Database Setup For Any External Database Pull down RSS Feeds or use the Repository plugin through a web proxy Change the time of day the Daily Backup runs Confluence Configuration Tips GZipping a HTTP Response within Confluence Create Shortcut Links

Confluence Security
• Java Policy Security with Confluence • Confluence Security Advisory 2005-12-05 • Confluence Security Advisory 2005-02-09

DON'T PANIC!
• • • • Get Help For Confluence Troubleshooting External Database Connections Confluence Configuration Tips Troubleshooting failed XML backups

Integrate Confluence and JIRA
• • • • Integrating JIRA and Confluence Add Confluence EAR-WAR to JIRA Standalone Delegate user management to use JIRA logins Override properties in JIRA to Confluence Bridge

Other
• • • • • Release Notes Development Releases Confluence Security Advisory 2005-02-09 Confluence Presentation Confluence SOAP Provider Migration

Document generated by Confluence on Oct 10, 2007 11:54

Page 29

Confluence Administration Guides
This page last changed on Mar 29, 2006 by mryall.

Old documentation This page is kept only for archiving purposes. Please see the current Administrators Guide.

Document generated by Confluence on Oct 10, 2007 11:54

Page 30

Confluence Backups begin failing on MySQL
This page last changed on Jan 14, 2005 by david.soul@atlassian.com.

This can begin to occur when your Confluence site has grown to a certain size that the database connections times out, during the backup operation: Stacktrace: java.sql.SQLException: Communication link failure: java.io.EOFException, underlying cause: null •
°

BEGIN NESTED EXCEPTION **

java.io.EOFException STACKTRACE: java.io.EOFException at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1394) Increase the wait_timeout variable in the Mysql configuration file.

Document generated by Confluence on Oct 10, 2007 11:54

Page 31

Confluence Configuration Tips
This page last changed on Jun 22, 2007 by smaddox.

This page represents a collection of tips accrued from answering support questions and developing with various configurations. If you need further configuration help or wish to contribute your own configuration tip please contact confluence-support . Application Servers For application server errors: Known Issues for Apache Tomcat Known Issues for JBoss Known Issues for Jetty Known Issues for Resin 2.x Known Issues for Resin 3.x Known Issues for SAP Application Server Known Issues for WebLogic Known Issues for Websphere Databases For database errors: Known Issues for DB2 Known Issues for MySQL Known Issues For Oracle Known Issues for PostgreSQL Known Issues For SQL Server Troubleshooting External Database Connections Troubleshooting the Embedded Database (hSQL DB) Web servers • Apache and Apache Connector Tips Licensing • License will not validate. Miscellaneous problems. • Confluence won't install - I keep seeing org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'scheduler' defined in class path resource [schedulingSubsystemContext.xml]

Document generated by Confluence on Oct 10, 2007 11:54

Page 32

Confluence Plugin Development Kit
This page last changed on Mar 29, 2007 by jnolen.

Name Plugin Version Product Version Author(s) Home Page Download Location Download Source

Confluence Plugin Development Kit 2.2.9 2.2.9 Atlassian Confluence Plugin Development Kit current versionall versions http://svn.atlassian.com/svn/public/atlassian/ confluence/confluence-development-kit/trunk/

The maven repository at ibiblio has moved to a new URL, so developers will have to update their maven configurations in order to build Confluence or its plugins. For more information, see the Atlassian Developer Blog: Maven 1 Repository Changes. Description/Features A full development kit for Confluence plugins bundled with Confluence API and dependencies. For more information, documentation and plugin tutorials, see our Confluence Development Hub. Included in this of the development kit are: • Skeleton project templates for creating your own plugins • Full API documentation of Confluence 2.2.9 • All Confuence 2.2.9 dependencies For more details on plugins, see the plugin guide. Requirements 1. Sun Java JDK 1.4+ Confluence doesn't currently support Java 6. 2. Apache Maven 1.0 : http://maven.apache.org/maven-1.x/start/download.html 3. Atlassian-IDEA Maven Plugin 4. A running instance of Confluence: either built from source or a standalone installation. Maven is not strictly required to build your Confluence plugins, however, all of the example plugins have been developed with Maven as well as the template project. We highly recommend that you use Maven to build your plugins. Idea is the Java Ide developped by JetBrains. This is totally optional for Confluence plugin development. You can use your own Ide or no Ide at all. Instructions 1. 2. 3. 4. 5. 6. 7. Copy the templates directory and rename it for your plugin Edit the project.xml for your plugin name in your new directory, run 'maven atlassian-idea' to generate IDEA project files. Launch your new project in IDEA by opening the $MY_PLUGIN_NAME.ipr file. Edit 'src/etc/atlassian-plugin.xml' for your project, as described in the documentation. Develop something cool! When you're ready to deploy, run 'maven jar' to build your plugin jar in the target directory

Document generated by Confluence on Oct 10, 2007 11:54

Page 33

8. Deploy it to your Confluence instance. Version History

Version 1.4 2.0 2.1.1 2.1.4 2.2.9

Comments initial version upgraded for new version of Confluence upgraded for new version of Confluence upgraded for new version of Confluence upgraded for new version of Confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 34

Converting Macro Libraries to Confluence Plugins
This page last changed on Oct 04, 2005 by jnolen.

Version Warning This document concerns upgrading Macro libraries written for Confluence 1.1 or 1.2 to a macro plugin compatible with Confluence 1.3 or later. If you are not upgrading a Macro Library, you don't need these instructions.

XML based conversion of Macros to Plugins
From Confluence 1.3 and onwards Macros become 'Plugins.' When upgrading, the only conversion which must take place is XML based. The example below uses the tasklist macro, which is bundled in Confluence 1.3 and used frequently in earlier versions. From Confluence 1.3 and onwards the XML descriptor is called atlassian-plugin.xml used in Confluence 1.3
<atlassian-plugin name='Task List Macros' key='confluence.extra.tasklist'><plugininfo><description>Macros to generate simple task lists</description><vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/><version>1.3</version></plugininfo><macro name='tasklist' class='com.atlassian.confluence.extra.tasklist.TaskListMacro' key='tasklist'><description>Creates a very simple task list, with user checkable tasks</ description></macro></atlassian-plugin>

In Confluence 1.2 and earlier the XML descriptor is called macro-library.xml and looks like:
<macro-libraries> <macro-library name="Task List Macros" key="confluence.extra.tasklist" description="An example macro library which generates task lists."> <macro name="tasklist" class="com.atlassian.confluence.extra.tasklist.TaskListMacro" description="Creates a very simple task list, with user checkable tasks."/> </macro-library></macro-libraries>

Document generated by Confluence on Oct 10, 2007 11:54

Page 35

Customising Confluence
This page last changed on Mar 29, 2006 by mryall.

Old documentation This page is kept only for archiving purposes. Please see the current documentation at Customising Look and Feel Overview.

Document generated by Confluence on Oct 10, 2007 11:54

Page 36

Decorator Macros
This page last changed on Apr 23, 2007 by david.soul@atlassian.com.

Old documentation This page is kept for only for archiving purposes. Please see Working With Decorator Macros.

Document generated by Confluence on Oct 10, 2007 11:54

Page 37

Documentation Home
This page last changed on Feb 02, 2006 by vidya.

This is the old documentation home for Confluence. For current information, please visit the new Confluence Documentation Home

Document generated by Confluence on Oct 10, 2007 11:54

Page 38

Frequently Asked Questions
This page last changed on Jun 22, 2007 by rosie@atlassian.com.

Old documentation This is the old list of frequently asked questions, left here temporarily. Please refer to the latest FAQ for up-to-date information. The best way you can help make this FAQ more useful is by asking questions: either in any of the places above, or by leaving your questions in the comments below. • Bugs and requests for new features can be submitted to JIRA. • Ideas for new features can be talked about in the discussion space • If you have a support query, please submit this on our new support system at http:// support.atlassian.com

General
° °

Troubleshooting
°

°

°

°

°

° °

How does Confluence differ from a wiki? Can I use CamelCaseLinks like they do on WardsWiki? How do I display an attached image in a page? How do I set Confluence to redirect users to a space homepage immediately after login? How do I migrate Confluence from one database to another? How do I change the port used by Confluence Standalone? Where does Confluence store all its data? I can not find the "Rich Text" editor. Is the editor part of Confluence 1.4.3?

°

°

°

°

°

Users and Permissions
° °

°

°

°

°

°

How do I configure Confluence for public/ anonymous access? Can I restrict access to individual pages within a space? How do I prevent just anyone from being able to sign up for new accounts? How do I share users and groups between Confluence and JIRA? I have lost my administrator password, what do I do? Does the license check include deactivated users?

°

°

°

°

°

°

°

°

I am using MySQL, and after a while Confluence stops working with database errors. When Confluence tries to send mail, I get a "javax.mail.NoSuchProviderException: smtp" error. I am using MS SQL Server and I get a "ResultSet can not re-read row data for column 2" error. I am trying to use thumbnails, and I get the message: "This Confluence installation can not generate thumbnails: no image support in Java runtime" I am using Fedora Linux, and PDF exports fail with an UnsatisfiedLinkError I am getting Out of Memory errors, how can I allocate more memory to tomcat? Search is not finding my data AND the indexing process does not appear to be completing I am trying to install Confluence but the demo-site.zip is missing? I am trying to compile a plugin, but get an error about the "target release" I am getting "404" errors in the Space tree view I am getting an error message about NoClassDefFoundError when using the Chart macro Confluence says "the license you entered was not valid" when I try and register I am getting JavaScript errors when using Confluence The {rss}, {jiraissues} or {html-include} macros fail when retrieving data from SSL (https) servers Troubleshooting failed XML site backups

General
How does Confluence differ from a wiki?

Document generated by Confluence on Oct 10, 2007 11:54

Page 39

Essentially, Confluence is a wiki. Our aim was to build an application that was built to the requirements of an enterprise knowledge management system, without losing the essential, powerful simplicity of the wiki in the process. From the wiki, we took the following lessons: • • • • • It should be easy for anyone to create and edit pages It should be easy for anyone to link pages together It should be easy to see what has changed recently The site should be searchable Users should have the tools to organise and group pages without having any particular structure imposed upon them

On top of that, we added professional features, such as the partitioning of content into separately managed spaces, user- and group-based access control, automated refactoring, PDF exporting, searchable attachments, a comprehensive remote API, easy installation and a professional and easy-touse presentation; all wrapped up in Atlassian's "Legendary Service". Can I use CamelCaseLinks like they do on WardsWiki? Yes. However, CamelCaseLinks are turned off by default. The site administrator can enable them from the Administration Console. How do I display an attached image in a page? Simple. Attach the image to the page. You can then include the image in the page by putting just the attachment filename in your image tag, like so: !attachmentFilename.jpg! For example, the following code produces the subsequent image:
\!fish.gif\!

Go to the User Guide for more information on Working with images. RELATED TOPICS: Working with images Confluence User Guide Can I set Confluence to redirect users to a space homepage immediately after login? Yes. This is configured by a site administrator from the Administration Console. Please vist the doc page on how to do this. RELATED TOPICS: Confluence Administration Guides Customising Space Homepage How do I migrate Confluence from one database to another? First perform an XML backup of your Confluence site. You can do this from the Administration > Backup and Restore page. Once you've made the backup file, you can set up a new Confluence instance from scratch against your new database and restore the backup that you just created. Detailed instructions can be found here. RELATED TOPICS: Configuration Guide Confluence Administration Guides Where does Confluence store all its data?

Document generated by Confluence on Oct 10, 2007 11:54

Page 40

Attachments, extensions and configuration files are stored in the Confluence Home Directorythat was configured when Confluence was first installed. All remaining data resides in the configured database. For more detailed answer to this question, see Confluence System Files and Data Storage. I can not find the "Rich Text" editor. Does Confluence 1.4.3. contain the Editor? The Rich Text Editor (aka WYSIWYG editor) is available in Confluence 2.O and upwards. A site administrator will need to enable Rich text editing from the Administration Console before you can use this option. If you wish to upgrade your Confluence installation, instructions can be found here. RELATED TOPICS: Rich Text Editor Overview Enabling Rich Text Editing

Users and Permissions
How do I configure Confluence for public/anonymous access? There are two different permissions that need to be set to allow anonymous access to a Confluence site. First, the 'Anonymous' user needs the global "Use Confluence" permission, secondly you need to give 'Anonymous' permissions in each space you want to make public. Full instructions can be found here. RELATED TOPICS Security Overview Users and Groups Can I restrict access to individual pages within a space? Yes, Confluence has a fine grained security structure that allows you to restrict access at the site, space and page levels. More information can be found in the Confluence User Guide. RELATED TOPICS: [Page Level Permissioning] Space Permissions Overview How do I prevent just anyone from being able to sign up for new accounts? Public signup can be enabled or disabled from the 'General Configuration' section of the Administration Console. How do I share users and groups between Confluence and[*JIRA|http://www.atlassian.com/software/ jira]**?* This topic has been covered in length here I have lost my administrator password, what do I do? You will have to change the pasword manually in the database. A detailed description of the process can be found under Restoring Passwords To Recover Admin User Rights. Does the license check include deactivated users? No. The license check only includes users who have 'use Confluence' permission. As of Confluence 2.1.x, you can no longer deactivate users, but users who cannot use Confluence are still not counted in the license check. RELATED TOPICS: Removing a User Viewing and Editing License Details

Document generated by Confluence on Oct 10, 2007 11:54

Page 41

Troubleshooting
I am using MySQL, and after a while Confluence stops working with database errors. MySQL's JDBC drivers have an annoying default behaviour where if a connection is idle for a certain amount of time (by default, eight hours), it is closed. Since Confluence uses a connection pool, this means that pooled connections die if they are not used within a certain time period. The solution is to append ?autoReconnect=true to the end of your database's JDBC URL. • If you are using JNDI data-sources, you will do this in your application server's configuration files. • If you have configured Confluence to access the database directly, you will need to manually edit the hibernate.connection.url property in the confluence.cfg.xml file in your confluence.home directory. After you have changed the URL in this file, restart Confluence.

Note In Confluence versions 1.0RC5 and before, there was a bug that manifested when you used Confluence to connect directly to a MySQL database instead of going through a datasource configured in the application-server under which Confluence runs. Unfortunately the symptoms of the bug were identical to the much more common problem above, so it took us a little longer to find the problem than we should have. So long as you specify autoReconnect=true, Confluence 1.0RC6 and later should remain connected to your MySQL database indefinitely.

When Confluence tries to send mail, I get a "javax.mail.NoSuchProviderException: smtp" error. The technical explanation is that you have two different versions of Sun's Javamail libraries in your application classpath. When Confluence tries to send an email, Java gets confused as to which version of the library it should be using, and falls over. If (and only if) you are encountering this error, try removing the Javamail-1.3.jar and activation-1.0.1.jar files from the confluence/WEB-INF/lib directory of your Confluence installation, and restarting the server. The problem should go away. You can find more information on this forum thread I am using MS SQL Server and I get a "ResultSet can not re-read row data for column 2" error. See the Known Issues For SQL Server I am trying to use thumbnails, and I get the message: "This Confluence installation can not generate thumbnails: no image support in Java runtime" On some Java installations (i.e. Unix without X11), you need to pass an additional parameter to Java when you are starting up to tell it how to use its image-manipulation libraries. To get thumbnail support working in this configuration, you need to start java with the argument 'Djava.awt.headless=true'. If you are using tomcat (or the Confluence standalone edition), try setting the environment variable JAVA_OPTS before starting the server. Assuming you're using the bourne or bash shell: export JAVA_OPTS=-Djava.awt.headless=true On Fedora Linux, you will also need to install the xorg-x11-deprecated-libs package. (See: https:// bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130239) For other application servers, techniques may vary. If you need help with a particular server, mail us at confluence-support@atlassian.com

Document generated by Confluence on Oct 10, 2007 11:54

Page 42

I am using Fedora Linux, and PDF exports fail with an UnsatisfiedLinkError You need to install the xorg-x11-deprecated-libs package. (See: https://bugzilla.redhat.com/bugzilla/ show_bug.cgi?id=130239) I am getting Out of Memory errors, how can I allocate more memory to tomcat? Since the default memory setting usually is around 64 or 128MB, you might have to adjust the settings to run a bigger Confluence instance with sufficent memory. In order to allocate more memory to tomcat, you will have to change the following settings: On Linux Edit the file $TOMCAT_HOME/bin/startup.sh and insert the following line, subsituting for the desired value, eg. Bash Shell: export CATALINA_OPTS=-Xms(min heap)m -Xmx(max heap)m; On Windows Edit the file $TOMCAT_HOME\bin\startup.bat and insert or alter the following line, subsituting for the desired values: set CATALINA_OPTS=-Xms(min heap)m -Xmx(max heap)m For example if you want to allocate a minimum heap size of 256MB and a max heap size of 512MB you will have to write the following on Windows: set CATALINA_OPTS=-Xms256m -Xmx512m If you are running tomcat 5.5 via tomcat.exe, you can update the heap size by running tomcatw.exe and setting the required values via the Java tab. On OS X If you are using the 'serveradmin start appserver' to start and stop tomcat, then you will need to update / usr/share/servermgrd/bundles/servermgr_appserver.bundle/Contents/Resources/run.sh Search is not finding my data AND the indexing process does not appear to be completing. Whats happening? If you are not seeing pages returned by the search that you expect to be returned, it's most likely that the indexing is not running correctly (either not running or failing). You can check the status of the index processing via the "Administration Console | Administration | Content Indexing" link. Why could indexing be failing? The indexing process is multi-threaded and therefore has a tendency to consume a lot of resources when running an initial index or reindexing the entire site. So, what can do wrong? • Some systems do not like the multi-threaded index process. You can set the index process to us only a single thread by setting bucket.indexing.threads.fixed=1 • The index process may also block if there are insufficient available database connections. Increasing the number of connections from 15 to 30 will help in this situation. For more detailed information, see the Content Index Administration page. I am trying to install Confluence but the demo-site.zip is missing? There are some cases where the unzip utility used to unzip the Confluence download will recursively unzip all contained zip files. The demo-site.zip should be located in the WEB-INF\classes\com\atlassian \confluence\setup directory. If it has been extracted, you will see an entities.xml file in this directory instead. I am trying to compile a plugin, but get an error about the "target release" When compiling plugins and using version 1.5 of the JDK, the following error may appear:
[javac] javac: target release 1.3 conflicts with default source release 1.5

Document generated by Confluence on Oct 10, 2007 11:54

Page 43

This is due to the fact that the default target for the plugins is version 1.3 of the JDK, which 1.5 cannot compile for. To fix this, open the src/etc/plugins/build.xml file and change the "1.3" in the following line to "1.5":
<javac destdir="${library}/classes" target="1.3" debug="${debug}" deprecation="false" optimize="false" failonerror="true">

I am getting "404" errors in the Space tree view If you are browsing a space and looking at the "tree view", 404 errors may appear (or it will display "Loading...") if the base url of your Confluence instance is not set. You can fix this by going to Administration -> General Configuration, and making sure that the "Base URL" setting is set to the correct address/domain name and path. I am getting an error message about NoClassDefFoundError when using the Chart macro The following error may appear when viewing certain pages where the Chart Macro is used:
Caused by: java.lang.NoClassDefFoundError at org.jfree.chart.ChartFactory.createAreaChart(ChartFactory.java:874) at com.atlassian.confluence.extra.chart.ChartMacro.getChart(ChartMacro.java:217) at com.atlassian.confluence.extra.chart.ChartMacro.execute(ChartMacro.java:102)

This is indicative of an out-of-date version of the Chart macro. Make sure you have the latest version and have removed any old versions or dependencies. If you are using Confluence 1.4, it may be a symptom of not having the jfreechart and jcommon JARs in your installation, which are required. Confluence says "the license you entered was not valid" when I try and register If this happens, please check your logs. The following message may appear:
2006-03-19 16:32:05,969 ERROR [atlassian.license.decoder.LicenseDecoder] String) Exception looking up public key: null java.security.spec.InvalidKeySpecException at gnu.java.security.provider.DSAKeyFactory.engineGeneratePublic(java.security.spec.KeySpec) (/usr/ lib/libgcj.so.6.0.0) at java.security.KeyFactory.generatePublic(java.security.spec.KeySpec) (/usr/lib/libgcj.so.6.0.0) at com.atlassian.license.decoder.LicenseDecoder.getPublicKey(java.lang.String) (Unknown Source) at com.atlassian.license.decoder.LicenseDecoder.getLicense(com.atlassian.license.LicensePair, java.lang.String) (Unknown Source) at com.atlassian.license.LicenseManager.setLicense(java.lang.String, java.lang.String) (Unknown Source) at com.atlassian.confluence.setup.actions.SetupLicenseAction.validateLicense() (Unknown Source) at com.atlassian.confluence.setup.actions.SetupLicenseAction.validate() (Unknown Source)

If you see this, you are most likely using GCJ/Kaffe, which sometimes has problems running Confluence. Please try using the Sun JDK. I am getting JavaScript errors when using Confluence If your web browser is complaining about JavaScript errors or functions not being defined, then it is possible that you are not retrieving the latest versions of pages from your Confluence instance. To fix this, you need to clear your browser cache. Follow the instructions for your particular browser: • Internet Explorer • Firefox - Open the Preferences -> Privacy -> Click on the "Clear Cache" button • Safari - Go to the Safari menu -> Clear Cache If you are still having problems, please create a support request.

Document generated by Confluence on Oct 10, 2007 11:54

Page 44

Confluence System Files and Data Storage
This page last changed on Sep 10, 2005 by cmiller.

A commonly asked question is "Where does Confluence store its data?" This page describes the files that Confluence requires to run, and where runtime data is stored. Confluence Filesystem Usage Confluence's use of the filesystem for many of its configuration and runtime files may make it unsuitable for certain modes of deployment, such as restricted or clustered environments. Atlassian are aware of this restriction, and working on overcoming it in a future Confluence release.

The Application Directory
This is the directory into which the downloaded Confluence application has been unpacked. Confluence does not modify or store any data in this directory, but the following files are important to know about if you are backing up or upgrading your Confluence instance: 1. confluence/WEB-INF/classes/confluence-init.properties - this file is modified by the administrator installing Confluence, and tells Confluence where to find the Confluence Home Directory. 2. {{confluence/WEB-INF/classes/osuser.xml - administrators may modify this file to connect Confluence to some external user management such as an LDAP server or JIRA instance 3. confluence/WEB-INF/lib/ - administrators may choose to deploy plugin or extension JAR files into this directory, especially if they are plugins that can not be automatically loaded through the web interface.

java.io.tmpdir
The standard "temp" directory as configured in the Java runtime. Typically this is /tmp on Unix systems, or C:\Temp on Windows. Some Confluence components will write temporary files or lockfiles to this directory, but very little disk space will be used. To change the location of this directory, you should start the Java Virtual Machine in which confluence is running with the argument -Djava.io.tmpdir=/path/to/ your/own/temp/directory.

The Confluence Home Directory
The location of this directory is configured by the Confluence administrator during installation (see confluence-init.properties above). Confluence writes its configuration files, uploaded plugin and attachments into this directory, as well as many temporary files and runtime data. Administrators should expect the Confluence Home Directory to grow quite large in a busy site. The Confluence Home Directory has the following files and subdirectories: • confluence.cfg.xml - Confluence's core configuration, including the configuration for connecting to its database • default-formatting.properties - a small amount of auxiliary configuration data concerning default number and date formats • attachments/ - all file attachments in the Confluence site are stored beneath this directory. This is the only place Confluence keeps attachment files. • backups/ - if Confluence is configured to produce daily backups, they are kept in this directory. Administrators should occasionally delete old or unwanted backups from this directory, or it will grow too large. • config/ - miscellaneous global and per-space configuration files are kept in this directory. • database/ - if Confluence is being run from the embedded HSQL database, the database files will be kept in this directory. • index/ - the full-text search index is kept in this directory. Removing or modifying files in this directory may cause search to no longer function. Rebuilding the search index from Confluence's global administration screen will completely regenerate the contents of this directory. • plugins/ - dynamically uploaded plugins are stored in this directory. Administrators can install new plugins by copying them into this directory and triggering a scan from the plugin management page. • temp/ - Confluence stores temporary files in this directory, especially during backups and exports. A daily job within Confluence deletes files that are no longer needed.

Document generated by Confluence on Oct 10, 2007 11:54

Page 45

• thumbnails/ - stores temporary files for image thumbnails. The contents of this directory can be safely deleted, as Confluence will regenerate thumbnails as required. • velocity/ - storage for customised page layouts, globally and per-space.

The 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 being 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 Restore system from backup).

Document generated by Confluence on Oct 10, 2007 11:54

Page 46

How-To Guides
This page last changed on Mar 16, 2007 by david.soul@atlassian.com.

These documents are a useful collection of "How do I do x?" guides:

Basic Confluence Operations
• • • • How How How How do do do do I I I I upgrade to a new version of Confluence? write Confluence pages in HTML? delete unwanted "incoming links" from pages? define structured content templates for pages?

Confluence and JIRA
• How can I best use Confluence and JIRA together? • How do I make Confluence use my existing JIRA user database? • How do I add a Confluence server to my existing JIRA standalone installation?

Hacks and Unsupported Modifications
• How do I change the look of the {gallery} macro?

Document generated by Confluence on Oct 10, 2007 11:54

Page 47

Gallery Macro Themes
This page last changed on May 24, 2007 by rosie@atlassian.com.

This page describes an unfinished feature of Confluence, for technical users who wish to play with it. The features and modifications described in this page are not officially supported. The GalleryMacro that is used to draw image galleries in a Confluence page has an undocumented "theme" parameter that allows you to specify a different Velocity template from which to draw the gallery. This allows enterprising Confluence administrators to come up with their own photo-album themes.

You will need:
• A basic knowledge of Velocity markup • Access to put files in Confluence's installation directory • Access to restart the server, since getting Java to reload resources it has pulled from the classpath is really hacky.

Instructions:
The Velocity template used to draw image galleries is in WEB-INF/classes/templates/macros/gallerydefault.vm, and as it stands it's 22 lines long and very basic. However, you can change this with the undocumented "theme" parameter in the gallery macro. {gallery:theme=fish} will attempt to draw the gallery with /templates/macros/gallery-fish.vm from anywhere in the application's CLASSPATH. So all you need to do is write the velocity file, dump it in the right directory and restart the server. If the gallery macro turns out to be something people really use, we'll probably make gallery themes a supported feature with a user interface, a way to drop in theme packs, and so on. For now it's a backdoor hack. Objects Passed to the Template:

$galleryTitle $thumbnails

is the gallery titled specified for the macro. It may be null. the container for all the pictures in the gallery (Defined as an inner class in GalleryMacro.java, if you've got the source and want a look) total number of thumbnails in the gallery a list of all thumbnails in the gallery a list of lists: each representing one row in the gallery (each list will be of length $thumbnails.columns, see the note below) the height, in pixels, of the tallest thumbnail in the gallery the width, in pixels, of the widest thumbnail in the gallery the number of columns that the gallery should be drawn with

$thumbnails.size $thumbnails.thumbnails $thumbnails.rows

$thumbnails.maxHeight $thumbnails.maxWidth $thumbnails.columns

Document generated by Confluence on Oct 10, 2007 11:54

Page 48

NOTE: The last row of the thumbnail gallery may contain empty cells. In this case, because Velocity is really broken with regards to its handling of nulls, the final list in $thumbnails.rows may be padded to its full width with the string "BLANK". Be sure to check for this. The ThumbnailInfo objects themselves that you get out of $thumbnails (Defined in ThumbnailInfo.java if you've got the source and want a look):

$thumbnail.originalWidth $thumbnail.originalHeight $thumbnail.thumbnailWidth $thumbnail.thumbnailHeight $thumbnail.thumbnailUrlPath

width in pixels of the full-sized image height in pixels of the full-sized image width in pixels of the thumbnail height in pixels of the thumbnail the path to download the thumbnail image, relative to the application's context path ($req.contextPath) returns the HTML to draw the thumbnail image as a popup link for the full-sized image attachment. imageParameters is a string that can contain HTML attributes for the image tag so for example you could call $thumbnail.getPopupLink("border='1' align='right'"). If you don't want any parameters, just pass in null or the empty string. the path to download the full-sized image, relative to the application's context path. the image's attachment comment

$thumbnail.getPopupLink(imageParameters)

$thumbnail.attachment.downloadPath $thumbnail.attachment.comment

Document generated by Confluence on Oct 10, 2007 11:54

Page 49

Restoring Passwords To Recover Admin User Rights
This page last changed on Oct 31, 2006 by david.soul@atlassian.com.

Use this document if you are unable to login as administrator, to manually replace administrator passwords or give users administration rights. Follow the instructions for either the Embedded Database or External Database. If you have not configured a database, use the Embedded instructions.

Embedded Database Instructions
Stage One - Identify Administrator
This guide assumes that the first user added was an administrator. If this is not the case, search for the admin username and find their user id number, then modify their password has instead. 1. Shutdown Confluence 2. In your Confluence home directory, open \database\confluencedb.script file in a text editor 3. Search for the text:
INSERT INTO OS_USER VALUES(1

To find the administrator login entry:
INSERT INTO OS_USER VALUES(1,'USERNAME','PASSWORD_HASH')

Where the 1 is the user id number, and USERNAME and PASSWORD_HASH are actual values. 4. This step makes admin the administrator's password. Confluence does not store passwords in plain text in the database, but uses hashes computed from the original password. The hash for the characters admin is below:
x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB+XURPWx1ONxp3Y3pB37A==

Paste the admin password hash between the '' characters of their existing PASSWORD_HASH. The new administrator login entry should look like:
INSERT INTO OS_USER VALUES(1,'USERNAME','x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB +XURPWx1ONxp3Y3pB37A==')

Where USERNAME is the administrator username. 5. Save the file 6. Start up Confluence 7. Login with the administrator username and password admin

External Database Instructions
Stage One - Identify Administrator
To find out which usernames have admin privileges, connect to your database using a database admin tool such as DBVisualiser. Please download a database admin tool now if you do not have one installed already. Once installed, connect to your database and retrieve the list of administrator usernames with:
select username from os_user u, os_group g, os_user_group ug where u.id = ug.user_id and g.id = ug.group_id and g.groupname = 'confluence-administrators'

Stage Two - Replace Administrator Password
Confluence does not store passwords in plain text in the database, but uses hashes computed from the original password. You instead cut and a paste a hash, rather than the plain password, over the existing password. Below is the hash for the password admin

Document generated by Confluence on Oct 10, 2007 11:54

Page 50

x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB+XURPWx1ONxp3Y3pB37A==

To change the password to admin for a given username: 1. Shutdown Confluence 2. Connect to your database. If you are using internal user management, run this SQL:
update os_user set passwd = 'x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB+XURPWx1ONxp3Y3pB37A==' where username='<USERNAME>';

If you are using LDAP integration for user managment (not only authentication) then your admin user will be in a different table. The SQL to run is:
update users set password = 'x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB+XURPWx1ONxp3Y3pB37A==' where name='<USERNAME>';

3. Start Confluence 4. Login with your modified username and use password admin

Document generated by Confluence on Oct 10, 2007 11:54

Page 51

Troubleshooting HTTPS or SSL-related problems
This page last changed on Oct 19, 2006 by david.soul@atlassian.com.

The {rss}, {jiraissues} or {html-include} macros fail when retrieving data from SSL (https) servers
Confluence is deployed on Linux, and pages containing these macros fail to load, or load very slowly If Confluence is deployed on Linux, and you experience time-outs or slow page loads when accessing pages that cuase SSL-protected resources to be loaded, it could be because Linux is not generating secure random numbers fast enough, and Java is blocking waiting for more to be generated. If this is the problem, apply the following fix:

1. Edit $JAVA_HOME/jre/lib/security/java.security and change the property: securerandom.source=file:/dev/random to: securerandom.source=file:/dev/urandom 2. Restart Confluence. More information is available here: CONF-2848. (You could also install dedicated cryptographic hardware into your server that guarantees fast secure random number generation, but that might be overkill Confluence does not accept the authority of the server's signing certificate If Confluence is displaying or logging errors related to not being able to verify the certificate of an SSL/ https server, then it may be that the SSL server certificates are not signed by an authority recognised by Confluence's Java environment. In this event you will need to add the signing authority of the server's SSL certificate to Java's store of trusted signers. You can find further instructions here: 1. Retrieving the Certification Path of an SSL Server 2. Adding a Certificate to a Key Store )

Document generated by Confluence on Oct 10, 2007 11:54

Page 52

What browsers are supported? I cannot see the Rich Text Editor in my browser
This page last changed on Sep 25, 2006 by ivan@atlassian.com.

Internet Explorer 5 or later, and Firefox are fully supported. Other browsers such as Safari, Opera and Konqueror are supported too. However, the Rich Text Editor is not available in these browser due to the issue outlined below. The rich text editor doesn't work with certain browser/OS combinations

Document generated by Confluence on Oct 10, 2007 11:54

Page 53

Guide to Confluence Macros
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see Working with Macros for a current list of Confluence macros.

Macros allow you to perform programmatic functions within a page, and can be used for generating more complex content structures. Generally speaking, a macro is simply a command wrapped inside curly braces {...}. To learn how to write your own macro, or use macros written by other people, read the Confluence Plugin Guide. Macros currently available in Confluence include: • • • • • • • • • • • • • • • • • • • • • • (outdated) Attachments Macro — Show a list of attachments belonging to the current page. (outdated) Blog Posts Macro — Lists the most recent blog entries in the space. (outdated) Children Display Macro — Displays the children and descendants of the current page. (outdated) Code Block Macro — Allows you to display code in your document with the appropriate syntax highlighting. (outdated) Create Space Button Macro — Renders a create space button linked to the create space page. (outdated) Dynamic Tasklist Macro — Displays a dynamic task list which can be modified in View mode. (outdated) Global Reports Macro — Renders a list of links to global reports within a table (outdated) IM Presence Macro — Show a graphic indication of when someone is online (outdated) Include Page Macro — Inserts the contents of the specified page into the current one. (outdated) JIRA Issues Macro — Display a list of JIRA issues in a page. (outdated) JIRA Portlet Macro — Display a JIRA dashboard portlet in Confluence (outdated) JUnit Report Macro — Display a summary of JUnit test results (outdated) Layout Macros — Allows display content in multiple columns. (outdated) Noformat Macro — Displays a block of text in monospace font (outdated) Recently Updated Content Macro — Include a list of which Confluence content has changed recently (outdated) RSS Feed Macro — Displays the contents of an RSS feed. (outdated) Search Macro — Search Confluence, and include the results in the page (outdated) Space Details Macro — Include the summary of a Confluence space in the page (outdated) Spacegraph Macro — Displays a chart of the pages in a space and their connections. (outdated) Spaces List Macro — Displays a list of all spaces visible to the user (outdated) Userlister Macro — Display a list of Confluence users, from an optional group (outdated) Welcome Message Macro — Include the Confluence site welcome message.

Document generated by Confluence on Oct 10, 2007 11:54

Page 54

(outdated) Attachments Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Attachments Macro

Usage:

{attachments:patterns=pattern, ...|old=true/ false|sortBy=name/size/date|upload=true/false} the patterns, old and sortBy arguments are alll optional Show a list of attachments belonging to the current page. Optionally filter attachments by name, optionally include old attachments, optionally allow uploads of new attachments.
{attachments:patterns=.*jpg,.*gif|old=true| sortBy=date}

Description:

Example: Input:

patterns An optional comma separated list of regular expressions, any of which must match a complete file name for it to included in the output of the macro. Note that the patterns are regular expressions, so to match a file suffix of 'jpg', use .*jpg, not *.jpg. old An optional true/false value which determines whether to show old versions of attachments. False by default. A list of attachments belonging to the current page. Yes

Output: Bundled with Confluence?:

Here's a detailed tutorial on regular expressions, but often you just need to know that '.' matches any character and '' matches zero or more occurences of the preceding character. So '.' in a regular expression matches anything (including nothing). The regular expression pattern 'a.jpg' will match 'a123.jpg', 'axxxxxxxxjpg' or 'ajpg'. The regular expression '.*handout.' would match 'Biology handout number one.doc', 'Chemistry handout2.txt' or 'handout'. Issue There is a current issue open against this bug that prevent the "old" parameter to work on Confluence 2.3.3 onwards. Please see CONF-8297 for more details. This bug is fixed in Confluence 2.4.6

Document generated by Confluence on Oct 10, 2007 11:54

Page 55

(outdated) Blog Posts Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Blog Posts Macro

Usage: Description: Example:

{blog-posts:1}

Lists the most recent blog entries in the space. Tuesday, June 26, 2007 Sample News To demonstrate linking to a news item. Posted at 26 Jun @ 11:25 AM by Jameson | Rosie

3 comments

Arguments: Output: Bundled with Confluence?:

1: The number of posts to display content: A listing of blog posts the number of which determined by input yes

Document generated by Confluence on Oct 10, 2007 11:54

Page 56

(outdated) Children Display Macro
This page last changed on May 29, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Displays the children and descendants of the current page. Usage: {children} OR {children:page=a_page_title} OR {children:all=true} OR {children:depth=a_depth} OR {children:depth=_a_depth_|style=heading_style} OR {children:_sort=<mode>|reverse=<true or false>} parameter page depth style Required no no no Default the current page none none Description Specify which page to display children for Specify the depth of descendents to display One of "h1", "h2" .... "h6" - displays children in a contents view Display the child pages' excerpts (if they exist) The 'sort' attribute is an optional attribute that allows you to configure how the children are sorted. Specify 'creation' to sort by content creation date, 'title' to sort alphabetically on title and 'modified' to sort of last modification date. Use the reverse attribute to optionally reverse the sorting.

excerpt sort

no no

false title

reverse

no

false

If the page parameter is '/', then the macro will list all the current space's "top level" pages - those without parents. If the page parameter is a space key followed by a colon (e.g {children:page=DOC:}), then the top level pages of that space will be listed. Example 1: {children:all=true} gives:

Document generated by Confluence on Oct 10, 2007 11:54

Page 57

• (outdated) Child Page 1 ° (outdated) Grandchild Page • (outdated) Child Page 2 Example 2: A depth of 1 will only display the first generation descendents of the current page. That is it will only display the direct children of the current page. {children:depth=1} gives: • (outdated) Child Page 1 • (outdated) Child Page 2 Example 3: A style of "h3" will display the page's direct children as level 3 headings, with their children as lists below the headings. Very useful for quickly generating a contents page {children:all=true|style=h3} gives

(outdated) Child Page 1
• (outdated) Grandchild Page

(outdated) Child Page 2

Document generated by Confluence on Oct 10, 2007 11:54

Page 58

(outdated) Child Page 1
This page last changed on May 29, 2007 by rosie@atlassian.com.

Document generated by Confluence on Oct 10, 2007 11:54

Page 59

(outdated) Grandchild Page
This page last changed on May 29, 2007 by rosie@atlassian.com.

This is the grandchild page!

Document generated by Confluence on Oct 10, 2007 11:54

Page 60

(outdated) Child Page 2
This page last changed on May 29, 2007 by rosie@atlassian.com.

Document generated by Confluence on Oct 10, 2007 11:54

Page 61

(outdated) Code Block Macro
This page last changed on May 29, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Allows you to display code in your document with the appropriate syntax highlighting. Usage: {code:language} ... code ... {code} OR {code} ... java code ... {code} Parameter language Required no Default Java Description Specify the programming language. Currently supported: Java, XML and SQL.

Example 1: Java {code} public String getFoo() { return foo; } {code} gives:
publicString getFoo() { return foo; }

Example 2: XML {code:XML} <test> <another tag="attribute"/> </test> {code} gives:
<test><another tag="attribute"/></test>

Document generated by Confluence on Oct 10, 2007 11:54

Page 62

(outdated) Create Space Button Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Create Space Button

Usage: Description: Example: Input:

{create-space-button: size=large | width=32 | height=32} Renders a create space button linked to the create space page. {create-space-button} size=small (size of 'small' uses a smaller graphic, whereas size of 'large' uses a larger one) \ height=x (pixel height in pixels) \ width=y (width in pixels) a create space icon linked to the create space page Yes 1.4 DR2

Output: Bundled with Confluence?: Since:

Document generated by Confluence on Oct 10, 2007 11:54

Page 63

(outdated) Dynamic Tasklist Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Usage: Description: Example: Input: Output: Bundled with Confluence?:

{dynamictasklist:tasklist name} Displays a dynamic task list which can be modified in View mode.
{dynamictasklist:Shopping}

optional task list name, defaults to no visible name. A task list on the page. Yes

Install Instructions
Users must upgrade to JDK 1.5 before installing the plugin. This plugin must be installed using ant, it cannot be uploaded. If you are having problems, ensure that you have installed it using the command ant -Dlibrary=dynamictasklist install and that there is no dynamictasklist.jar or plugins-dynamictasklist.jar file in your <confluence home>/plugins directory, and only a plugins-dynamictasklist.jar, not a dynamictasklist.jar in your WEB-INF/lib directory.

JDK Upgrade Problem
If you are using JDK 1.4 or earlier, tasklist content created while must be manually transferred into a new list when you upgrade your JDK. New users can avoid this by upgrading to JDK 1.5 before installing the plugin. Example Tasklist Screenshot: Here is a screenshot of what the dynamic tasklist looks like:

Live Example Below is a live example of the dynamic task list in operation. Play with it! Add new tasks, complete or uncomplete tasks, grab the handles on the right hand side to reorder your tasks. Tasks: To Do • test (del)

Document generated by Confluence on Oct 10, 2007 11:54

Page 64

• •

test2 (del)

test3 (del) Add Task:

Document generated by Confluence on Oct 10, 2007 11:54

Page 65

(outdated) Global Reports Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Global Reports Macro

Usage: Description:

{global-reports: width=x} Renders a list of links to global reports within a table of width x (defaults to 99%).

Example: Input: Output: Bundled with Confluence?: Since

{global-reports} (arguments are optional) width=x A table of links leading to global reports Yes 1.4 DR2

Document generated by Confluence on Oct 10, 2007 11:54

Page 66

(outdated) IM Presence Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

The IM presence macros allow you to show a graphic indication when someone is online. The supported systems are 1. Yahoo! 2. AIM 3. ICQ Yahoo! Presence Macro

Usage: Description: Example: Input: Output:

{yahoo:yahooID} Show a graphic indication of when someone is online
{yahoo:myYahooId}

yahooID: is required and should be a valid Yahoo! account ID. An image indicating the online status of the specified user. eg: or

Bundled with Confluence?: Since: AIM Presence Macro

Yes 1.4

Usage: Description: Example: Input: Output:

{aim:screenname} Show a graphic indication of when someone is online
{aim:myScreenName}

screenname: is required and should be a valid AIM screen name. An image indicating the online status of the specified user. eg: or

Bundled with Confluence?: Since:

Yes 1.4

Document generated by Confluence on Oct 10, 2007 11:54

Page 67

ICQ Presence Macro

Usage: Description: Example: Input: Output:

{icq:icqnumber} Show a graphic indication of when someone is online
{icq:12345678}

icqnumber: is required and should be a valid ICQ UIN. An image indicating the online status of the specified user. eg: or

Bundled with Confluence?: Since:

Yes 1.4

Document generated by Confluence on Oct 10, 2007 11:54

Page 68

(outdated) Include Page Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Summary
Inserts the contents of the specified page into the current one.

Usage
{include:Some page} {include:spaceKey=KEY|pageTitle=Another page}

Parameters

Parameter (default) pageTitle spaceKey

Required yes, if no pageTitle parameter yes, if no default parameter no

Default none none current space

Description Name of a page in the current space to include Name of a page to include Key for space which has the page

Notes
Users without permission to view the included page will see an error that the page could not be found. A page cannot include itself or a page that includes itself. An error message will be displayed if this occurs.

Document generated by Confluence on Oct 10, 2007 11:54

Page 69

(outdated) JIRA Issues Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

You can embed a JIRA issue into your Confluence page. This page covers parameters available when calling the macro.

Usage: Description: Input: Output: Bundled with Confluence?:

{jiraissues:url=jira_rss_url|columns=columns} Display a list of JIRA issues in a page. See parameters table below. Nice looking list of issues in a Confluence page

Setup Notes
1. HTTPS The JIRA issues macro can access a JIRA instance running under SSL as long as the Confluence server is set to accept the JIRA SSL certificate. 2. JIRA 3.7 Link Format Change As a result of RSS feed improvements, the (outdated) JIRA Issues Macro differs between JIRA 3.6 and 3.7. This is not an issue for users running the latest versions of Confluence and JIRA. However, users using Confluence versions older than 2.2.10 to access JIRA 3.7 must upgrade Confluence or patch the JIRA issues macro to handle the 3.7 format.

Confluence 2.2.10, 2.3 Older than 2.2.10

JIRA Any version 3.7

OK

Action Required None Stop Confluence, open your Confluence install directory and remove the file \WEBINF\lib\jira3.jar. Download the JIRA 3.7 version and rename it to jira3.jar None

Older than 2.2.10

Older than 3.7

Using The JIRA Issues Macro
See the User Guide entry.

Document generated by Confluence on Oct 10, 2007 11:54

Page 70

JIRA Issue Parameters
The following parameters can be embedded in the macro call.

Parameter url

Required yes

Default none

Description The URL of the XML view of your selected issues in Jira Issue Navigator. a semi-colon delimited list of jira column names. Valid columns are key, summary, type, created, updated, due, assignee, reporter, priority, status and resolution true will output the number of issues in JIRA, linking the count to the JIRA instance 'off' will refresh the jiraissues cache, forcing a reload on the page before the display the header link to the issue navigator will use this base url (used when Confluence connects to Jira with a different URL to normal users)

columns

no

none

count

no

false

cache

no

on

baseurl

no

tempMax

no

20

limits the number of results you get back. This is the case even when count is set to true.

Example
This macro call requests a filter results from the Atlassian public JIRA instance:
{jiraissues:url=http://jira.atlassian.com/secure/IssueNavigator.jspa? view=rss&pid=10470&fixfor=10650&sorter/field=issuekey&sorter/order=DESC&tempMax=25&reset=true| columns=type;key;summary}

The filter results are embedded in the page as:

Atlassian JIRA(3 issues) T CONF-497 CONF-496 Key Summary Search includes old versions of pages Problem with rename

Document generated by Confluence on Oct 10, 2007 11:54

Page 71

CONF-495

Problem with incoming links

Troubleshooting
For problems relating to the JIRA Issues Macro, click on your query below for the solution. Issues Appear Out Of Date Using cache with this macro it can be that you have stale data in you table. You can force a refresh of the table by clicking the Refresh button in the top-right hand corner of the table. Cannot Access Issues When JIRA Uses HTTPS Check out Troubleshooting HTTPS or SSL-related Problems. 'Error Rendering Macro' or No Issues Are Displayed or Not All Issues Are Displayed You must append a JIRA username and password to your JIRA issues filter URL. That JIRA user must also have permission to view the all issues returned by the filter, otherwise they will be omitted. Please append the os_username and os_password as described below so that jiraissues:url=http://host.com/secure/IssueNavigator.jspa?... becomes jiraissues:url=http://host.com/secure/ IssueNavigator.jspa?...&os_username=MYUSERNAME&os_password=MYPASSWORD where MYUSERNAME and MYPASSWORD are a JIRA login. 'Error rendering macro: java.io.IOException: Could not download' You may need to configure Confluence to acknowledge your proxy server before it is able to download the feed. 'Error rendering macro: java.io.IOException: Error on line -1: Premature end of file' Did you select an existing JIRA filter? If you did, your issues filter URL will end with .../12345/ SearchRequest-12345.xml where 12345 is any number. You should retry using a new and unsaved filter. Issue icons are not displayed Check that you are using the correct macro version for JIRA.

Document generated by Confluence on Oct 10, 2007 11:54

Page 72

JIRA 3.7 Link Format Change
This page last changed on May 29, 2007 by rosie@atlassian.com.

As a result of RSS feed improvements, the (outdated) JIRA Issues Macro differs between JIRA 3.6 and 3.7. This is not an issue for users running the latest versions of Confluence and JIRA. However, users using Confluence versions older than 2.2.10 to access JIRA 3.7 must upgrade Confluence or patch the JIRA issues macro to handle the 3.7 format.

Confluence 2.2.10, 2.3 Older than 2.2.10

JIRA Any version 3.7

OK

Action Required None Stop Confluence, open your Confluence install directory and remove the file \WEBINF\lib\jira3.jar. Download the JIRA 3.7 version and rename it to jira3.jar None

Older than 2.2.10

Older than 3.7

Document generated by Confluence on Oct 10, 2007 11:54

Page 73

(outdated) JIRA Portlet Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Jira Portlet Macro

Usage: Description: Input:

jiraportlet:url= Display a JIRA dashboard portlet in Confluence url=

http://jira.atlassian.com/secure/ RunPortlet.jspa? portletKey=com.atlassian.jira.plugin.system.portlets:project description=Stats:%20Confluence %20(Versions)&projectid=10470& statistictype=fixfor&template=/portlets/ dashboard/projectstats.jsp

Output: Bundled with Confluence?:

Nice looking portlet in a Confluence page yes

Example
Statistics: Confluence (Fix For Versions (non-archived)) 2.5.x 2.6.1 2.6.x 2.7 Unscheduled 91 7 34 31 3052 1% 1% 95% 3%

How to find the URL for a JIRA Portlet
Confluence needs a URL in order to retrieve JIRA portlets. If your JIRA instance requires you to log in, you must add &os_username=username&os_password=password to the end of the URL (substituting a valid JIRA username and password) so that Confluence can log in to retrieve the portlet. This is a temporary measure until we get Confluence and JIRA cross-authentication working more effectively. 1. Add the portlet you wish to include in Confluence to your JIRA dashboard (Once you have copied the portlet's URL into Confluence, you will be able to remove from your JIRA dashboard) 2. Configure your dashboard

Document generated by Confluence on Oct 10, 2007 11:54

Page 74

3. Locate the portlet's direct link in the top-left corner

4. Right-click on the link to copy it to your clipboard, and paste it into the {jiraportlet} macro

(Note, the command for copying a link to the clipboard may differ in your browser)

Document generated by Confluence on Oct 10, 2007 11:54

Page 75

(outdated) JUnit Report Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Display a summary of JUnit test results from a directory accessible from the Confluence server. When generating reports, set ant formatter to "xml". Usage: {junitreport:directory=[file:///directory/]} OR {junitreport:url=http://*host*/*path*\}

parameter directory

Required no

Default none

Description URI of a directory containing your test result files. URI of a particular test result XML file. Detail for report. Can be 'all', 'fixture', 'summary' or 'failuresonly'. Show the content of failures, as well as their message.

url reportdetail

no no

none 'fixture'

debug

no

false

Document generated by Confluence on Oct 10, 2007 11:54

Page 76

(outdated) Layout Macros
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Layout Macros

Usage: Description: Example:

{section} {column:width=30%}content{column} {column:width=70%}content{column} {section} Allows display content in multiple columns.
{section} {column:width=30%}Some stuff goes here{column} {column:width=70%}Some more stuff goes here{column} {section}

Input: Output: Bundled with Confluence?:

Any wiki content within columns A column display of that content. Yes

Layout macros allow you to define a {section} of the page that is divided into multiple {column}'s. You must always define {column}s inside a {section}, or the macro will not work. Optional parameters for the {section} macro: • border - use {section:border=true} to draw the columns with borders around them. The default is no border. Option parameters for the {column} macro: • width - use the width parameter to determine how wide each column should be. By default, the columns are automatically resized to fit their contents. Example:
{section} {column:width=30%} This is some _Wiki Markup_ {column} {column:width=70%} This is some more wiki *markup* {column} {section}

Produces: This is some Wiki Markup And the same with{section:border=true} This is some Wiki Markup This is some more wiki markup This is some more wiki markup

Document generated by Confluence on Oct 10, 2007 11:54

Page 77

(outdated) Noformat Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Displays a block of text in monospace font . Usage: {noformat} ... text ... {noformat} Example: {noformat} Hello World! Hello Mike! {noformat} gives:
Hello World! Hello Mike!

Document generated by Confluence on Oct 10, 2007 11:54

Page 78

(outdated) Recently Updated Content Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Recently Updated Content Macro

Usage: Description:

{recently-updated: spaces=foo1,foo2 | width=50% } Include a list of which Confluence content has changed recently Content will be listed from the current space or for each space defined in a comma separated list (space = x, y). The list will be rendered in a table with width matching the width argument (width=z) or defaulting to 99%

Example: Input: Output: Bundled with Confluence?: Since

{recently-updated} (arguments are optional) spaces= x, y | width=z a table of width z, listing recently updated content for spaces x and y yes 1.4 DR2

Document generated by Confluence on Oct 10, 2007 11:54

Page 79

(outdated) RSS Feed Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Displays the contents of an RSS feed. RSS is an Internet standard for syndicating news, and is used by many news sites and weblogs. Please note that updates are only retrieved after at least an hour has elapsed since the last update. Usage: {rss:url=my_rss_url}

Parameter my_rss_url max showTitlesOnly

Required yes no no

Default none none false

Description the url to the RSS feed Maximum entries to be displayed Show only the title of the enrty

Example: {rss:url=http://feeds.feedburner.com/AtlassianDeveloperBlog} gives:

Atlassian Developer Blog ￿￿￿ JIRA!! Let's go fighting! Our Japanese partner reported a bug introduced in JIRA 3.11 in the Japanese version of JIRA to do with the date picker popup not functioning correctly. The bug was caused by some javascript missing, which is something we'd fixed quite... Atlassian Agile Process part 2 XP Practices Automated Testing, The Planning Game, Pair Programming and Stand Up Meetings at Atlassian's Sydney development group. The Remote Import Plugin If you have multiple instances of Confluence running within your company, there was no easy way to move a space or a group of users from one instance to another. Until now. Plugging Memory Leaks in Confluence Recently the Confluence team became aware that our public facing instance, http:// confluence.atlassian.com was slowly leaking memory. This blog entry is the story of how we found and fixed the leaks. What makes us think there's a leak? The initial reason... Atlassian Agile Process part 1 Atlassian adopts a range of development process elements with a strong focus on Agile methods. In practice each product team defines their own process while also attempting to learn from other teams. In JIRA and Confluence, the two largest teams... More GreenHopper: video demo I should have included this in my post yesterday about GreenHopper, but they have a great demo reel on their website. Click the image to watch:... Developer blog re-design Today we've completed an exciting new redesign of this blog. With a cleaner layout, this should make it a bit easier to read on the web, and provide a better fit for code samples and screenshots. We hope you like... New JIRA Plugin: GreenHopper, for Agile Teams One of the recurring religious debates in the agile community is paper cards vs. issue-tracking. One of our very own developers, Charles Miller, is a big fan of using paper cards for planning, although he is quick to note that...

Document generated by Confluence on Oct 10, 2007 11:54

Page 80

Releases, releases, releases ... Since coming on board last month, the Cenqua team has been flat out like a lizard drinking. We've updated FishEye and Crucible, revamped the FishEye plugin for Jira, and finally let Clover 2 beta loose on the world. Atlassian "Fedex Day" VI Here at Atlassian we have just finished up our sixth edition of "Fedex Day". What is it? For those who don't know, "Fedex Day" is Atlassian's irregular answer to Google 20% time: time set aside for developers to work... JIRA, Agile, Scrum, and Pragmatic Marketing Christina Noren, VP Product Management at Splunk, recently wrote a blog post on Automating and opening up product planning. Their product development process was already going fast, but now they're going to kick into turbo as they move to a... JIRA and VSS: we need your help If you've been watching the JIRA Plugin Library like a hawk, this post will come as no surprise to you. But in case you haven't, I have an exciting announcement. We've just released a beta version of the JIRAVSS plugin... FedEx VI Winner - JIRA Caller ID The Problem Many people have come to know and love JIRA as an issue tracker for software development projects. What many people don't realise is that JIRA, with its customisable workflows, is useful for any team that needs to track... Caching - Confluence Style Special thanks to our guest blogger, Dan Hardiker from Adaptavist. Confluence in its naked, default form is nice, fast and responsive from the user's perspective – but load it up with a few too many plugins and a nice looking... JIRA Labels Plugin 2.0 We recently completed a major overhaul of the JIRA Labels Plugin with a primary focus on stability and performance. New Atlassian Developer, Rich Wallace (p.s. we're hiring java developers in San Francisco!) spent several days cleaning things up, and the...

Document generated by Confluence on Oct 10, 2007 11:54

Page 81

(outdated) Search Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Search Confluence, and include the results in the page . The search macro behaves identically to Confluence's built-in site search. Usage: {search:my_query} OR {search:my_query|maxLimit=maxLimit}

Parameter query maxLimit

Required yes no

Default none none

Description search query (what you enter in the search box) sets the maximum number of search results to return sets the kind of content to search Limit the search to the contents of a particular space

type spaceKey

no no

all except mail none

Available types:

type parameter all page blogpost mail attachment comment userinfo spacedesc

Will search: all content, including mail only pages only news only mail only attachments only comments only user profiles only space descriptions

Supplying no type will result in the search returning results from all content except mail. Example: {search:confluence|maxLimit=5} gives:

Document generated by Confluence on Oct 10, 2007 11:54

Page 82

Found 13572 search result(s) for confluence (Display limit: 5) Confluence 2.0(Space Description) User Guide for Confluence version 2 Jun 18, 2007 Labels: confluence, Confluence Community(Space Description) space is for discussing ideas, new features and suggestions for Confluence. null Sep 27, 2005 Labels: confluence Offline Confluence Editor(Atlassian Developer Network) Offline Confluence Editor Offline Confluence Editor High Provide an offline client that would allow a user to add/edit pages/news/comments when disconnected. \\ Name Offline Confluence Editor Author(s) Priority High Description Provide ... Mar 23, 2007 Labels: confluence CSP-11777 - Running two Confluence clusters on one machine(Atlassian KnowledgeBase) CSP11777 Running two Confluence clusters on one machine Error Message 20070918 14:20:50,750 ERROR Logger@17450849 3.2/365 (RC3) Coherence log 20070918 14:20:50.749 Tangosol Coherence AE 3.2/365 (RC3) <Error ... Sep 24, 2007 Labels: confluence CSP-12084 - Crowd and Confluence compatibility library issues(Atlassian KnowledgeBase) CSP12084 Crowd and Confluence compatibility library issues Error Message @4000000047019e2e07813de4 20071001 20:25:56,110 INFO main com.atlassian.confluence.lifecycle contextInitialized Starting Confluence 2.6.0 (build #913) @4000000047019e3307ea0234 20:26:01.132 Loading Spring root WebApplicationContext ... Oct 02, 2007 Labels: confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 83

(outdated) Space Details Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Space Details Macro

Usage: Description:

{space-details: width=x} Include the summary of a Confluence space in the page . Renders space details within a table with width specified by width argument or defaulting to 99%.

Example: Input: Output: Bundled with Confluence?: Since You may also be interested in Spaces List Macro

{space-details} (width argument is optional) width = x a table holding the current's space's details Yes 1.4 DR2

Document generated by Confluence on Oct 10, 2007 11:54

Page 84

(outdated) Spacegraph Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Spacegraph Macro

Usage: Description: Example: Input: Output: Bundled with Confluence?:

{spacegraph:space key} Displays a chart of the pages in a space and their connections.
{spacegraph:ds}

optional space key, defaults to space of current page. A chart of the space. Yes

This macro requires that GraphViz is installed. You should perform the default installation for your operating system. See the Enable The Flowchart Macro for Graphviz configuration information. For details on composing diagrams, see the GraphViz Documentation. This macro is shipped with Confluence as source, to use it you need to build the 'graphviz' plugin. To do this, you need to install ant and run the command:
ant -Dlibrary=graphviz install

from the plugins directory.

Document generated by Confluence on Oct 10, 2007 11:54

Page 85

(outdated) Spaces List Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

spaces-list Macro

Usage: Description:

{spaces-list:width=<width_variable>} Displays a list of all spaces visible to the user , with linked icons leading to various space content functionality, within a table. The width parameter expresses the specifies the table on the page.

Example: Input: Output: Bundled with Confluence?: Since: You may also be interested in Space Details Macro

{spaces-list:width=40%}

width a list of spaces yes 1.4 DR2

Document generated by Confluence on Oct 10, 2007 11:54

Page 86

(outdated) Userlister Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

Userlister Macro
The Userlister macro has been updated for the Confluence 1.4 release to provide a greater range of flexibility. For convenience, the 1.3 Userlister usage documentation is provided below.

Usage: Description: Example: Input:

{userlister:groups=group,...|online=true/false} Display a list of Confluence users, from an optional set of groups
{userlister:groups=confluence-users| online=true}

groups: is an optional comma separated list of group names online: is an optional true/false value to filter the users based upon there online status Displays a table of user names and emails Yes 1.4

Output: Bundled with Confluence?: Since: Examples: • • • • •

{userlister} List all users {userlister:groups=confluence-users} List all users in group confluence-users {userlister:groups=project1,project2} List all users in group project1 or project2 {userlister:online=true} List all users currently online (may not be 100% accurate) {userlister:groups=confluence-users|online=true} List all currently online users in group confluence-users

1.3 Userlister Macro usage documentation

Usage: Description: Example: Input: Output: Bundled with Confluence?: Since:

{userlister:group-name} Display a list of Confluence users, from an optional group
{userlister:confluence-users}

a group-name is optional and will restrict the user list to members of that group Displays a table of user names and emails Yes 1.3

Document generated by Confluence on Oct 10, 2007 11:54

Page 87

(outdated) Welcome Message Macro
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

This page is outdated. Please see new page.

welcome-message Macro

Usage: Description:

{welcome-message} Include the Confluence site welcome message. The site welcome message may be configured in the Adminstation -> General Configuration section.

Example: Input: Output: Bundled with Confluence?: Since:

{welcome-message}

The site welcome message Yes 1.4 DR2

Document generated by Confluence on Oct 10, 2007 11:54

Page 88

How to delegate user management in Confluence 1.0 to JIRA
This page last changed on Sep 14, 2006 by david.soul@atlassian.com.

This version of the document applies to Confluence 1.0 and earlier. Users of Confluence 1.0.1 and later should refer to this document instead. This article will help you set up Confluence to re-use your existing JIRA user base. The examples assume you are running Confluence under Tomcat 4.1.x and your JIRA database is running under Postgres, but the same concepts (but not the verbatim examples) can be applied to other application-servers or databases.

Please note that this feature will not work if you are using JIRA with the embedded HSQL database. That is, this will not work if you are running JIRA standalone against the default database out of the box. However, it does not matter which database you are using for Confluence.

Step 1 - Run through standard setup process
• Install Confluence as per normal. • Ensure you do not add any spaces or content once the setup is complete.

Note: the admin user account will no longer be valid once you switch over to using your JIRA user base. Therefore you should avoid adding any content with this account.

Step 2 - Set up datasource to JIRA user base
• Open up server.xml located in the conf folder. If you have already set up JIRA to run against Tomcat, then all you have to do is cut and paste the datasource information you entered for JIRA into Confluence's <context>. • Locate your confluence context statement which should look similar to the following:
<Context path="/confluence" docBase="[OMMITTED]" debug="0" reloadable="true"><Logger className="org.apache.catalina.logger.FileLogger" prefix="atlassian-confluence." suffix=".log" timestamp="true"/></Context>

and insert the following block of code after the <Logger className . . . timestamp="true'/> statement.
<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/ ><ResourceParams name="jdbc/JiraDS"><parameter><name>username</name><value>postgres</ value></parameter><parameter><name>password</name><value>postgres</value></ parameter><parameter><name>driverClassName</name><value>org.postgresql.Driver</ value></parameter><parameter><name>url</name><value>jdbc:postgresql://your.domain.com/ jira_database_name</value></parameter></ResourceParams>

You will need to change the sample values given above to suit your installation.

Step 3 - Install JDBC driver in Tomcat
• Download a postgres JDBC driver from here • Copy the jar file into the /common/lib folder

Document generated by Confluence on Oct 10, 2007 11:54

Page 89

Step 4 - Modify osuser.xml
• Find this file in the /confluence/WEB-INF/classes folder and open in a text editor • Comment out the following block of code:
<provider class="com.atlassian.confluence.user.providers.ConfluenceCredentialsProvider"><property name="configuration.provider.class"> com.atlassian.confluence.user.ConfluenceHibernateConfigProvider </property></provider><provider class="com.atlassian.confluence.user.providers.ConfluenceAccessProvider"><property name="configuration.provider.class"> com.atlassian.confluence.user.ConfluenceHibernateConfigProvider </property></provider><provider class="com.atlassian.confluence.user.providers.ConfluenceProfileProvider"><property name="configuration.provider.class"> com.atlassian.confluence.user.ConfluenceHibernateConfigProvider </property></provider>

• Uncomment this block:
<provider class="com.atlassian.confluence.user.providers.jira.JiraJdbcCredentialsProvider"> <property name="datasource">java:comp/env/jdbc/JiraDS</property> </provider> <provider class="com.atlassian.confluence.user.providers.jira.JiraJdbcAccessProvider"> <property name="datasource">java:comp/env/jdbc/JiraDS</property> </provider> <provider class="com.atlassian.confluence.user.providers.jira.JiraJdbcProfileProvider"> <property name="datasource">java:comp/env/jdbc/JiraDS</property> <property name="configuration.provider.class"> com.atlassian.confluence.user.ConfluenceHibernateConfigProvider </property> </provider>

• Replace the datasource property with the datasource you set up in step 2.

Step 5 - Create Confluence Groups in JIRA
• Add confluence-users and confluence-administrators groups in JIRA • Add yourself to both these groups. To give your existing JIRA users access to Confluence, you have two options. 1. Manually edit the groups of these users inside JIRA and give them membership to one or both of these confluence groups OR 2. Restart Confluence. Log in using your JIRA account, and go to Administration and then Global Permissions. Now add USE permission to your desired JIRA groups.

In order to use Confluence, users must be a member of the confluence-users group (or have confluence USE permission).

Step 6 - Activating External User Management
Finally, since user management is now conducted in JIRA and outside of Confluence, you will need to switch external user management on. Activating external user management will remove user and group management options from Confluence. Your users will also no longer be able to edit their full name or email address inside Confluence (if they want to, they would have to do so in JIRA). To do this: • Log into Confluence using your JIRA account • Goto Administration and then General Configuration • Click the edit button to edit the defaults

Document generated by Confluence on Oct 10, 2007 11:54

Page 90

• Switch External User Management ON

Document generated by Confluence on Oct 10, 2007 11:54

Page 91

Import, Export and Backups
This page last changed on Nov 17, 2005 by vidya.

• Change the time of day the Daily Backup runs • Restore system from backup — This document outlines setting up a Confluence instance from a Confluence backup file. • Troubleshooting failed XML backups • Troubleshooting XML backups that fail on restore Wiki Importer We have developed a small java application that will help you extract the content from other wiki products and arrange it in a Confluence-friendly, importable format. Currently, it supports TWiki and JSPWiki but the framework was developed so that it is possible to add support for other formats.

Document generated by Confluence on Oct 10, 2007 11:54

Page 92

Change the time of day the Daily Backup runs
This page last changed on Dec 29, 2005 by tom@atlassian.com.

By default, Confluence runs its daily backup at 2AM. You may wish to change this to another time if you have user activity at 2AM. Confluence uses Quartz for scheduling periodic jobs. The Quartz configuration is in the file confluence/ WEB-INF/classes/schedulingSubsystemContext.xml. To change the time that the backup job runs, find the section of the file:
<bean id="backupTrigger" class="org.springframework.scheduling.quartz.CronTriggerBean"><property name="jobDetail"><ref bean="backupJob"/></property><property name="cronExpression"><value>0 0 2 * * ?</value></property></bean>

The string '0 0 2 * * ?' sets up a Cron Trigger which states that the job will run at the zeroth second of the zeroth minute of the 2nd hour, every day of every month, every day of the week. To change the time to, say, twenty past ten PM, change the string to '0 10 22 * * ?'. If you wanted to back up only weekly, you could use '0 0 0 ? * SUN' to backup at midnight every Sunday. For complete details on the format of the cron string, please see http://www.opensymphony.com/quartz/ api/org/quartz/CronTrigger.html.

Document generated by Confluence on Oct 10, 2007 11:54

Page 93

Restore system from backup
This page last changed on Jul 21, 2005 by jnolen.

This document outlines setting up a Confluence instance from a Confluence backup file. Restoring from daily backups On a daily basis, Confluence back ups your data and configuration information into a zipped XML file. You can find these daily backups in the backups folder inside your Confluence home directory. You can restore this backup file from two places: Restoring it from the Confluence setup wizard Backup files are typically restored into a new instance of Confluence. When going through the setup wizard, remember to select Custom install. Now setup your database details for your choice of database. Once that is done, you will be asked if you want to set up a: • empty instance • an instance with a demonstration space • restore from backup Select the last option. Under where it says Upload a zipped backup to Confluence, browse for the relevant daily backup file. If you have: • a very large daily backup file (say greater than 100MB) OR • a daily backup file that is already on the server and doesn't require uploading You can copy the backup file into the restore directory inside your confluence home folder and then refresh the page. You should now see your backup file appear in the box underneath the heading Restore a backup from the filesystem. Select and submit to commence the restore process. Restoring it from the Confluence Administration Page The first place is from the Administration > Backup & Restore page. Under where it says Upload a zipped backup to Confluence, browse for the relevant daily backup file. If you have: • a very large daily backup file (say greater than 100MB) OR • a daily backup file that is already on the server and doesn't require uploading You can copy the backup file into the restore directory inside your confluence home folder and then refresh the page. You should now see your backup file appear in the box underneath the heading Restore a backup from the filesystem. Select and submit to commence the restore process. Restoring from database backups and a backup of your confluence home directory If your daily backup zips cannot be restored for whatever reason, but you have both a database backup and backups of your confluence home diretory, then it is still possible to restore from these. If you are running against the embedded database, the database is located inside the database folder of your confluence home directory. Pointing the confluence-init.properties file in a new Confluence install to one of your backup home directories should get you up and running. If you're using an external database, you need to first build up a working database from one of your database backups (if you haven't got one running already). If this database happens to have a different name, or is on a different server, you can modify the jdbc url in the confluence.cfg.xml file inside the confluence home directory (Beside the hibernate.connection.url property). Now set the confluence.home property in the confluence-init.properties file in your Confluence webapp to this home directory and you should be up and running.

Document generated by Confluence on Oct 10, 2007 11:54

Page 94

Troubleshooting failed XML backups
This page last changed on Nov 17, 2006 by david.soul@atlassian.com.

Out Of Date Please refer to Troubleshooting failed XML site backups instead. If creating an XML backup of Confluence fails with a stack trace error similar to this, your database has become slightly corrupted. This is likely to have occurred while using the embedded database. If you are using the embedded database, be aware that it is bundled for evaluation purposes and does not offer full transactional integrity in the event of sudden power loss, which is why an external database is recommended for production use. To correct the corruption, increase the level of logging to identify the cause and manually correct any invalid entries in the database. To do this: 1. Shutdown Confluence. 2. Open the confluence/WEB-INF/classes/log4j.properties and add this to the bottom and save:
log4j.logger.com.atlassian.confluence.importexport.impl.XMLDatabinder=DEBUG, confluencelog log4j.additivity.com.atlassian.confluence.importexport.impl.XMLDatabinder=false

3. Restart Confluence and begin a backup. 4. When the backup fails, the error will be logged to the log files. Open the most recent log and review the stack track of the error for information identifying the object causing the failure. Here's an example error you can use to identify the database object:
2005-08-24 00:00:33,743 DEBUG [confluence.importexport.impl.XMLDatabinder] Writing object: com.atlassian.confluence.core.ContentPermission with ID: 5 to XML. 2005-08-24 00:00:33,743 DEBUG [confluence.importexport.impl.XMLDatabinder] Writing property: type 2005-08-24 00:00:33,743 DEBUG [confluence.importexport.impl.XMLDatabinder] Writing property: group 2005-08-24 00:00:33,743 DEBUG [confluence.importexport.impl.XMLDatabinder] Writing property: expiry 2005-08-24 00:00:33,743 DEBUG [confluence.importexport.impl.XMLDatabinder] Writing property: content [ERROR] LazyInitializer - Exception initializing proxy <net.sf.hibernate.ObjectNotFoundException: No row with the given identifier exists: 2535, of class: com.atlassian.confluence.core.ContentEntityObject>net.sf.hibernate.ObjectNotFoundException: No row with the given identifier exists: 2535, of class: com.atlassian.confluence.core.ContentEntityObject at net.sf.hibernate.ObjectNotFoundException.throwIfNull(ObjectNotFoundException.java:24) at net.sf.hibernate.impl.SessionImpl.immediateLoad(SessionImpl.java:1946) at net.sf.hibernate.proxy.LazyInitializer.initialize(LazyInitializer.java:53) at net.sf.hibernate.proxy.LazyInitializer.initializeWrapExceptions(LazyInitializer.java:60) at net.sf.hibernate.proxy.LazyInitializer.getImplementation(LazyInitializer.java:164) at net.sf.hibernate.proxy.CGLIBLazyInitializer.intercept(CGLIBLazyInitializer.java:108) at com.atlassian.confluence.core.ContentEntityObject$$EnhancerByCGLIB$ $cc2f5557.hashCode(<generated>) at java.util.HashMap.hash(HashMap.java:261) at java.util.HashMap.containsKey(HashMap.java:339) at com.atlassian.confluence.importexport.impl.XMLDatabinder.toGenericXML(XMLDatabinder.java:155)

This excerpt from a log file shows that there was an error trying to confer the ContentPermission object with id 5 into XML. The database object is a row in the CONTENTLOCK table with id = 5 and reset CONTENT column property so that it no longer points to the id 2535 (the id of an entry that no longer exists). If you are wondering which table a certain object is stored in, here's a rough guideline: Pages, blogposts, comments are stored in the CONTENT table, attachments in the ATTACHMENTS table. 5. 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. 6. Once the database has been updated, restart Confluence and reattempt the backup.

Document generated by Confluence on Oct 10, 2007 11:54

Page 95

7. To help prevent this issue from reoccurring - If you are using the embedded database, you should migrate to an external database. 8. To help prevent this issue from reoccuring - If you are using an older version of Confluence than the latest), you should consider upgrading at this point.

Document generated by Confluence on Oct 10, 2007 11:54

Page 96

Troubleshooting XML backups that fail on restore
This page last changed on Apr 05, 2007 by david.soul@atlassian.com.

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

Resolve Errors When Attempting To Restore An XML Backup
The errors may be caused by a slightly corrupt database. You will need to find the XML backup file entry that is violating the DB rules, modify the entry and recreate the XML backup: 1. On the instance being restored, follow the instructions to disable batched updates (for simpler debugging), log SQL queries and log SQL queries with parameters at http:// confluence.atlassian.com/display/DOC/Enabling+detailed+Hibernate+logging 2. Once all three changes have been made, restart Confluence 3. Attempt another restore 4. Once the restore fails, check your log files to find out what object could not be converted into XML format. For Confluence Standalone users, check your Confluence install directory under the /logs/ and check both atlassian-confluence.log and catalina.out file. The correct file will contain SQL debug output. 5. Scroll to the bottom of the file and identify the last error relating to a violation of the database constraint. For example:
2006-07-13 09:32:33,372 ERROR [confluence.importexport.impl.ReverseDatabinder] endElement net.sf.hibernate.exception.ConstraintViolationException: could not insert: [com.atlassian.confluence.pages.Attachment#38] net.sf.hibernate.exception.ConstraintViolationException: could not insert: [com.atlassian.confluence.pages.Attachment#38] ... Caused by: java.sql.SQLException: ORA-01400: cannot insert NULL into ("CONFUSER"."ATTACHMENTS"."TITLE") at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.java:112) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:288)

This example indicates a row in your attachment table with ID = 38 that has a null title. 6. Go to the server that the backup was created on. You must have a copy of the database from which the backup was created. If you do not have this, use a DBA tool to restore a manual backup of the database. 7. Open a DBA tool and connect to the original database instance and scan the table names in the schema. You will have to modify a row in one of these tables 8. To work out which table, open catalina.out, check the first line of the exception. To work out what table an object maps to in the database, here's a rough guide: • Pages, blogposts, comments --> CONTENT table • attachments --> ATTACHMENTS table 9. To correct the example error, go to the attachment table and find that attachment object with id 38. This will have a a null title. Give a title using the other attachments titles as a guide. You may have a different error and should modify the database accordingly. 10. Once the entry has been corrected, create the XML backup again 11. Import the backup into the new version 12. If the import succeeds, revert the changes made in http://confluence.atlassian.com/display/DOC/ Enabling+detailed+Hibernate+logging to re-enable disable batched updates and turn off log SQL queries and log SQL queries with parameters 13. Restart Confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 97

To Help Prevent This Issue From Reoccuring
1. If you are using the embedded database, be aware that it is bundled for evaluation purposes and does not offer full transactional integrity in the event of sudden power loss, which is why an external database is recommended for production use. You should migrate to an external database. 2. If you are using an older version of Confluence than the latest, you should consider upgrading at this point.
RELATED TOPICS

Administrators Guide

Document generated by Confluence on Oct 10, 2007 11:54

Page 98

Macro Plugins v1.3
This page last changed on Jan 18, 2007 by jnolen.

This documentation concerns Confluence version 1.3. For current documentation, see Macro Plugins Macros are Confluence code that can be invoked from inside a page by putting the name of the macro in curly brackets. Users of Confluence will be familiar with macros like {color} or {children} or {rss}. Thanks to the plugin system, it is easy to write and install new macros into a Confluence server. For Simple Macros If you want to create a macro that just inserts some boiler-plate text or performs simple formatting, you may only need a User Macro. User macros can be written entirely from within the Confluence web interface, and require no special installation or programming knowledge.

Adding a macro plugin
Macros are a kind of Confluence plugin module. • For more information about plugins in general, read Confluence Plugin Guide. • To learn how to install and configure plugins (including macros), read Installing and Configuring Plugins manually. • For an introduction to writing your own plugins, read Writing Confluence Plugins

The Macro Plugin Module
Each macro is a plugin module of type "macro", packaged with whatever Java classes and other resources (i.e. Velocity templates) that the macro requires in order to run. Generally, similar macros are packaged together into a single plugin, for ease of management. Here is an example atlassian-plugin.xml file
<atlassian-plugin name='Task List Macros' key='confluence.extra.tasklist'><plugininfo><description>Macros to generate simple task lists</description><vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/><version>1.3</version></plugin-info> <macro name='tasklist' class='com.atlassian.confluence.extra.tasklist.TaskListMacro' key='tasklist'> <description>Creates a very simple task list, with user checkable tasks</description></macro><!-more macros... --></atlassian-plugin>

The name of the macro defines how it will be referenced from the page. So if you define your macro as having name="tasklist", the macro will be called from the page as {tasklist}.

The Macro Plugin Module Implementing Class
The class attribute of the macro defines what Java class will be used to process that macro. This is the class you need to write in order for the macro to function. Your class should extend com.atlassian.renderer.macro.BaseMacro.

Example Java macros
The Confluence installation contains a custommacros directory with a "Confluence Macro Builder" Ant script and some sample macro projects. The best way to learn how to write your own macros is to start by looking at this example code.

Task List Example Library
As an example, tasklist is one of the example macros, which builds a simple task list within a Confluence page and allows users to complete and uncomplete the various tasks simply. It also serves as a good example of how easy it is to build add functionality to Confluence.

Document generated by Confluence on Oct 10, 2007 11:54

Page 99

Example Here's a screenshot of the tasklist macro in action, showing a simple shopping list that's half completed:

This was generated by notation like the following, with tasks completed or uncompleted by clicking on the relevant or :

{tasklist:Shopping List} Buy apples Buy bananas Purchase shopping bag Collect laundry Deposit money {tasklist}

As of 1.3, the tasklist macro is packaged with Confluence as a plugin, and should be available when you install the application. Building the tasklist library To build tasklist, go to the custommacros directory within the expanded distribution, and run:
ant -Dlibrary=tasklist build

Your macro library is now located at custommacros/tasklist/dist/macros-tasklist.jar Installing the tasklist library To install the library straight into the web application, run:
ant -Dlibrary=tasklist install

and then restart your Confluence instance. Similarly you can uninstall the library like so:
ant -Dlibrary=tasklist uninstall

Note: Confluence must first be shutdown before you can uninstall macros.

Document generated by Confluence on Oct 10, 2007 11:54

Page 100

MySQL index and PostgreSQL Contraint Trigger problem
This page last changed on Jun 18, 2004 by david.soul@atlassian.com.

Pre-1.1 Confluence would add an extra copy of an index/constraint on a confluence database table every time the server was restarted. This has caused some users to run into memory problems such as CONF-1204 when the maximum limit of indexes per table has been reached. To check if this problem exists in your installation, first open up a console window to your database. For MySQL users, run:

> show index from CONTENT; You can verify this problem exists if you notice multiple indexes referencing the same column name like the following: BLOGSPACEID is duplicated by BLOGSPACEID_2 and both reference the BLOGSPACEID column +---------+------------+---------------+--------------+-------------+ | Table | Non_unique | Key_name | Seq_in_index | Column_name | +---------+------------+---------------+--------------+-------------+ | CONTENT | 0 | PRIMARY | 1 | CONTENTID | | CONTENT | 1 | BLOGSPACEID | 1 | BLOGSPACEID | | CONTENT | 1 | PAGEID | 1 | PAGEID | | CONTENT | 1 | PARENTID | 1 | PARENTID | | CONTENT | 1 | PREVVER | 1 | PREVVER | | CONTENT | 1 | SPACEID | 1 | SPACEID | | CONTENT | 1 | DESCSPACEID | 1 | DESCSPACEID | | CONTENT | 1 | BLOGSPACEID_2 | 1 | BLOGSPACEID | | CONTENT | 1 | PAGEID_2 | 1 | PAGEID | | CONTENT | 1 | PARENTID_2 | 1 | PARENTID | | CONTENT | 1 | PREVVER_2 | 1 | PREVVER | | CONTENT | 1 | SPACEID_2 | 1 | SPACEID | | CONTENT | 1 | DESCSPACEID_2 | 1 | DESCSPACEID | +---------+------------+---------------+--------------+-------------+

For PostgreSQL users, run:
> \d content; You can verify this problem exists if you get lots of RI_ConstraintTriggers being displayed like the following: Example: Triggers: RI_ConstraintTrigger_214459, RI_ConstraintTrigger_214460, RI_ConstraintTrigger_214465, RI_ConstraintTrigger_214466, RI_ConstraintTrigger_214468, RI_ConstraintTrigger_214469, RI_ConstraintTrigger_214482, RI_ConstraintTrigger_214483, RI_ConstraintTrigger_214484,

If you observe this in your database, you can fix the problem by performing the following: 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. backup your existing confluence home directory and database upgrade to confluence 1.1 login to Confluence goto Administration > Backup & Restore perform a backup by clicking the "Backup" button when the backup completes, download it (use the click "here" link) now go back to the Administration > Backup & Restore page restore the backup you have just made If you are using MySQL continue with the next 3 steps. Else skip to the end. shutdown confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 101

11. open up the confluence.cfg.xml file in your confluence home directory 12. locate the line
<property name="hibernate.dialect">net.sf.hibernate.dialect.MySQLDialect</property>

and change it to:
<property name="hibernate.dialect">bucket.dialect.MySQLDialect</property>

13. now start up Confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 102

Oracle and Confluence 1.3
This page last changed on Dec 13, 2005 by david.soul@atlassian.com.

Old Documentation This documentation refers to Confluence 1.3. Users of Confluence 1.4 or later should ignore this documentation.

You are evaluating Confluence
We suggest that first-time evaluators of Confluence use the default installation, which installs an embedded database within Confluence itself. This allows you to see what Confluence can do for you as quickly as possible, without the unnecessary complexity of installing an external database. Once you have determined that Confluence's features are for you, then it's time to set up against whichever database you plan to deploy against in production.

You Are Installing Confluence with Oracle for the First Time
A fresh installation of Confluence will work quite happily against an Oracle 8 or 9i database provided you keep the following in mind: • Regardless of what version of the Oracle database you are using, you must use the Oracle 10g JDBC drivers. • You must use the thin drivers. • You must connect to Oracle through a datasource configured in your application server. Confluence will not connect directly to an Oracle database. • You must set the following connection parameter in your datasource configuration: SetBigStringTryClob=true Consult the documentation for your application server on how to configure a datasource, and set datasource properties. If you have any problems, ask on the Confluence forum, or http:// support.atlassian.com SetBigStringTryClob is a connection parameter, not a datasource parameter. Your application server may handle these two things differently. An example of how to configure a connection parameter in Tomcat is provided below.

Setting SetBigStringTryClob=true in a Tomcat Datasource
If you are using Tomcat (or the Confluence standalone, which is packaged with Tomcat) you will need to add the following to your datasource definition in order for it to recognise the new connection parameter:
<parameter><name>connectionProperties</name><value>SetBigStringTryClob=true</value></parameter>

You Are Upgrading an Existing Confluence Instance
The same restrictions noted in the new installation apply to you also. Note that previous versions of Confluence only required the Oracle 9i JDBC drivers, so you will need to upgrade to the 10g JDBC drivers for Confluence 1.3.

Why No Oracle 10g Installation Option?
It may seem strange that we require the Oracle 10g drivers, but do not offer Oracle 10g as an option in the setup screens. This is simply because we have not yet tested Confluence against Oracle 10g. This will also be resolved by the time we release Confluence 1.3.2

Document generated by Confluence on Oct 10, 2007 11:54

Page 103

RSS
This page last changed on May 29, 2007 by rosie@atlassian.com.

RSS is a file format used for syndication on the web. When a site publishes new content regularly, the site can represent those changes in an RSS file. RSS isn't designed to be read in a regular web browser, but specialised RSS newsreader programs can check RSS files every so often, and tell you what's new on a site. For a technical description of the RSS format, you can read Mark Pilgrim's "What is RSS?" article on XML.com.

Using RSS with Confluence
There are two ways that Confluence uses RSS. Firstly, it can display RSS feeds from other sites, allowing you to follow the news from those sites inside Confluence. Secondly, Confluence publishes RSS feeds of recently updated content, allowing you to be notified of those changes through your own RSS reader. Reading RSS From Other Sites If another site publishes an RSS feed, you can include its contents in a Confluence page by including the (outdated) RSS Feed Macro in the page, giving it the URL of the feed you want to follow. Confluence will check the feed for updates at most every hour. Subscribing to Confluence Updates via RSS Confluence also produces RSS that you can subscribe to (using an RSS Newsreader) in order to receive notifications of new or updated content on the Confleunce site. Authentication To have your news aggregator log into Confluence, you can append ? os_username=yourusername&os_password=yourpassword to the URL of the feed you are trying to retrieve. Note, however, that this means someone with access to your aggregator configuration can read your password.

RSS Newsreaders
The following are some popular RSS newsreader programs for various operating systems. You can find a more comprehensive list on Google's open directory Windows • • • • • SharpReader NewsGator Syndirella FeedDemon NewzCrawler

Mac OS X • NetNewsWire • NewsFire • Shrook Multi-Platform • NewsMonster (Runs in the Mozilla web browser) • Radio Userland (Windows and MacOS) • AmphetaDesk (Windows, Unix, Mac OS X)

Document generated by Confluence on Oct 10, 2007 11:54

Page 104

Shortcut Links
This page last changed on Apr 01, 2005 by vidya.

What Are Shortcut Links?
Shortcut links are defined by the Confluence administrator. They are a quick way to create links to resources that are frequently referenced from Confluence. Administrators can maintain shortcuts from the "Shortcut Links" link in the administrative console. For example, here are the shortcuts currently defined on http://confluence.atlassian.com:

For the examples I give below to work, these shortcuts must be configured on your Confluence server. If they aren't, ask your server administrator to add them.

How To Use Shortcut Links
Easy. You just specify in the link what should go on the end of the shortcut URL, followed by an at-sign and the name of the shortcut. Shortcut names are case-insensitive. So, for example:

Shortcut JIRA issue

Example [CONF-1000@JIRA]

Resulting URL

Demonstration

http:// CONF-1000 jira.atlassian.com/ secure/ QuickSearch.jspa? searchString=CONF-1000 http:// jira.atlassian.com/ secure/ QuickSearch.jspa? searchString=CONF +open+bugs http:// www.google.com/ search?q=Atlassian +Confluence CONF open bugs

JIRA search

[CONF open bugs@JIRA]

Google Search

[Atlassian Confluence@Google]

Atlassian Confluence@Google

Shortcut links can have titles just like any other link:

Shortcut Internet Movie Database Google Cache

Example [Fight Club| tt0137523@IMDB]

Resulting URL http://us.imdb.com/ Title?tt0137523

Demonstration Fight Club

[Cached Homepage| http:// Cached Homepage www.atlassian.com@cache] www.google.com/ search? q=cache:www.atlassian.com

Document generated by Confluence on Oct 10, 2007 11:54

Page 105

Limitations
Currently, you can only have shortcuts append things to the end of URLs. We're planning on removing this limitation in future versions of Confluence.

Document generated by Confluence on Oct 10, 2007 11:54

Page 106

Special LDAP Integration Note for users upgrading to Confluence version 2.1.x or higher
This page last changed on May 10, 2006 by david.soul@atlassian.com.

Confluence 2.1 carries a new User system - Atlassian User. It is compatible with most existing osuser.xml configurations, but if you are running with the OSUser LDAP integration, you will need to change one line of osuser.xml to get it to work with Confluence 2.1. Please see the original instructions for setting up an osuser.xml which can integrate with LDAP. You must ensure that the only CredentialsProvider in your osuser.xml is the ConfluenceLDAPCredentialsProvider (see below).

The one line change to osuser.xml
The LDAPCredentialsProvider class changes from
<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider">

to
<provider class="com.atlassian.confluence.user.ConfluenceLDAPCredentialsProvider">

Thus, the final configuration for the credentials provider is:
<provider class="com.atlassian.confluence.user.ConfluenceLDAPCredentialsProvider"><property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property><property name="java.naming.provider.url">ldap://localhost:389</property><property name="searchBase">dc=atlassian,dc=com</property><property name="uidSearchName">cn</property> <!-<property name="java.naming.security.principal">cn=Manager,dc=atlassian,dc=com</property><property name="java.naming.security.credentials">secret</property><property name="exclusive-access">true</ property> --> </provider>

Document generated by Confluence on Oct 10, 2007 11:54

Page 107

Structured Content with Templates
This page last changed on Mar 29, 2005 by vidya.

About Templates
Templates are a Confluence feature that allow you to create pages from previously defined forms. Templates are useful for giving your Confluence pages a 'house style', especially for types of pages that are commonly created. For example, a software development project might have templates for use-cases, or a systems administration space might make a template defining what information is being kept about each server. Templates are written in Confluence's regular wiki markup, using special markup to define form fields that need to be filled in.

Using Templates
When you create a page, you may see a link asking you to select a template page:

If you do not see this link, then there are currently no templates defined - an administrator will have to create one before you can use it. Following this link will present you with a list of the templates that are available in the current space.

Once you have selected a template, you will be asked to fill it in: enter the appropriate values into the form and press the "Insert Variables" button:

Document generated by Confluence on Oct 10, 2007 11:54

Page 108

Once you've inserted the variables into the template, you'll have one last chance to edit the page as a whole to clean up anything messy (or add more information) before saving it.

Creating Templates
There are two kinds of templates. Global Templates are defined by the site administrators from the global administration pages, and are available in every space. Space Templates are defined by space administrators in the space administration screens, and are only available in the space in which they are defined. Either way, templates are just regular wiki pages with special markup to tell Confluence where to insert form fields. There are three kinds of form fields supported: text input, text areas and drop-down menus. Every input field must have a unique name, which is just a word that will . Text input fields are special. If you have more than one text input field in the same template with the same name, then Confluence will make sure that they all end up with the same value: this is useful if you need the same information in more than one place in the page! Template input markup

@VAR@ @VAR|textarea(5x10)@

Creates a text input field for a variable called VAR Creates a 5 x 10 text-area for a variable called VAR Creates a drop-down box containing the values "one", "two", "three" and "four"

@VAR|list(one,two,three,four)@

Important There must be no spaces between the @-signs in the markup. This means you can't have items in your drop-down lists that contain spaces: Good
@VAR|textarea(10x80)@ @VAR|list(red,blue,green,orange)@

Bad
@VAR|textarea(10 x 80)@ @VAR|list(red, blue, green, orange)@ @VAR|list(red,blue,light green,orange)@

Template Limitations
Templates can only be used to create a page. Once a page is created, the template is gone and all further editing is performed as if the template had never been used. In the future, templates will be expanded to do more interesting things - such as remaining part of the page, having more complex (and even dynamic) fields, being able to search Confluence based on the value of particular fields, and so on.

Document generated by Confluence on Oct 10, 2007 11:54

Page 109

The Confluence Manual
This page last changed on Feb 02, 2006 by vidya.

This page is outdated. The new documentation is here. \

Document generated by Confluence on Oct 10, 2007 11:54

Page 110

Customizing Site Title
This page last changed on May 23, 2005 by tom@atlassian.com.

Customizable Site Titles are a new feature in the release of Confluence 1.4.

Customizing Site Title
The site title within Confluence appears at the top of each of browser window (within the HTML META TITLE element) and within the login and logout pages.

Top of each browser window

Site title used on login page

A common need for this is to represent that name of your organisation wherever you would normally see 'Confluence'. Configuring the Site Title. Only Confluence administrators can edit the value of the site title. Navigate to the Administration region and follow the 'General Configuration' Link. Simply edit the field to represent the value you wish to use for the site title:

Before:

After:

Afterwards your nominated site title will be used universally.

Top of each browser window

Site title used on login page

Also see: [Customizing Confluence's Logo]

Document generated by Confluence on Oct 10, 2007 11:54

Page 111

Installing the standalone version
This page last changed on Sep 19, 2006 by david.soul@atlassian.com.

This document is now out of date Please refer to Installing Confluence Standalone for updated instructions. Installing the standalone version is easy: 1. Download and install the Java Development Kit (JDK) from http://java.sun.com/j2se/1.4.2/ download.html. You want the J2SE SDK version without the Sun Java System Application Server. 2. Set the JAVA_HOME variable to where you installed Java. If you are running windows, steps on how to do this can be found here 3. Unzip the standalone version into a directory. It does not matter where you put it, but you need to remember where it is. This directory is called the 'confluence install directory' in the rest of the instructions. 4. Ensure that you do not have the CATALINA_HOME environment variable specified or pointing to a previously installed instance of Tomcat. The confluence standalone instance runs within a bundled tomcat instance, and having CATALINA_HOME specified in the environment will confuse the tomcat startup scripts. 5. Edit the confluence-init.properties file in the confluence\WEB-INF\classes directory which you can find under the confluence install directory, and set the confluence.home property to a directory of your choice. The line that you need to change in the confluence-init.properties file looks like #confluence.home=/tmp/confluence. You need to change it to confluence.home=<your confluence home location>. For example you might choose c:/confluencedata as your confluence.home directory, so you'd change that line to confluence.home=c:/confluencedata. Don't forget to remove the leading '#' character. This directory is where Confluence will store it's configuration information, indexes and attachments, so the user running the server must have write access to this directory. 6. Run bin/startup.sh (*nix) or bin\startup.bat (Windows). Check that there are no errors on the console. See Troubleshooting & Technical Support if you see any errors 7. Point your browser at http://localhost:8080/. You should see the Confluence Setup Wizard! If you are installing on Mac OS X this document contains more detail: Confluence Installation OS X.pdf

Document generated by Confluence on Oct 10, 2007 11:54

Page 112

Installing the WAR version
This page last changed on Feb 17, 2006 by mryall.

Old documentation This documentation is for old versions prior to Confluence 2.0. For the latest documentation see the Confluence Installation Guide.

You will need
1. A Java Application Server, as described in the Requirements 2. To know how to install and configure your application server. If you do not, we suggest you download Confluence Standalone instead. 3. (Optional) A database, as described in the Requirements Installing the WAR version is a piece of cake: 1. Unzip the Confluence WAR zip that you have downloaded 2. Find the confluence folder in this unpacked distribution and copy this over to the webapps directory of your application server (assuming you are using tomcat and resin). 3. Edit the confluence-init.properties file in the webapps\confluence\WEB-INF\classes directory and set the confluence.home property to a directory of your choice. This directory is where Confluence will store it's configuration information, indexes and attachments. 4. Restart your webserver if necessary. 5. Point your browser at www.mydomain.com/confluence where mydomain is your website domain. You should see the Confluence Setup Wizard! Unix without X11 On some Java installations (i.e. Unix without X11), you need to pass an additional parameter to Java when you are starting up to tell it how to use its image-manipulation libraries. To get thumbnail support working in this configuration, you need to start java with the argument 'Djava.awt.headless=true'. If you are using tomcat (or the Confluence standalone edition), try setting the environment variable JAVA_OPTS before starting the server. Assuming you're using the bourne or bash shell: export JAVA_OPTS=-Djava.awt.headless=true

Alternatives to confluence-init.properties
This is an advanced note for experienced Java application server administrators. If you do not know how to set system properties or edit web.xml in your application server, we recommend you stick with editing confluence-init.properties as described above. If you wish to deploy the WAR directly into an application server (or several application servers), you may want to skip the step of exploding the WAR file. Confluence needs one piece of information in order to get running: the location of the confluence.home directory in which it should save its configuration files and other data. It obtains this information by looking at the following three places (in order): 1. System properties (i.e. start the application with -Dconfluence.home=/path/to/your/confluence/ home) 2. confluence-init.properties (i.e. follow the procedure above) 3. Servlet context (i.e. customise the web.xml deployment descriptor to include a <context-param> called confluence.home) The first not-null value Confluence finds will be used as the confluence home. So, if your application server supports the easy editing of system properties or servlet context parameters when deploying an application, you may want to use one of these methods instead of editing confluence-init.properties

Document generated by Confluence on Oct 10, 2007 11:54

Page 113

Integrating With JIRA
This page last changed on Mar 16, 2007 by david.soul@atlassian.com.

1. 2. 3. 4.

Add Confluence EAR-WAR to JIRA Standalone Delegate user management to use JIRA logins Integrating JIRA and Confluence Override properties in JIRA to Confluence Bridge

Document generated by Confluence on Oct 10, 2007 11:54

Page 114

Page Families
This page last changed on Jan 19, 2004 by cmiller.

Page Families When you create or edit a page, you have the option of setting its parent page. This allows you to create hierarchies of parent-child relationships between pages. It is a simple but effective way of grouping related pages together, and making navigation of your site simpler by providing links forward and backwards through the page hierarchy. To create a child page, you can choose the Cannot resolve external resource into attachment. Add Child Page option from the Page Operations menu. Alternatively, you can just type a parent page name into the "Parent Page" field in any page creation or editing form. When you view a page that has a parent, the "Location" breadcrumbs at the top of the page will list the parent, for ease of navigating back up the page hierarchy. Also, when you view the Cannot resolve external resource into attachment. Page Information for any page, the "Hierarchy" section at the bottom of the information page will show all of the page's ancestors and descendents. Child pages are listed in the collapsible "children" area at the bottom of the parent page. To insert an automatically generated list of child pages into a parent page, you can edit the page to include the children macro (described in the macros section of the notation guide). A page can only have one parent. Confluence will only allow you to create page families that are a simple tree: you may not set a page to have a parent that is already one of its own child-pages.

Document generated by Confluence on Oct 10, 2007 11:54

Page 115

Page History
This page last changed on May 23, 2005 by tom@atlassian.com.

Each time a page is edited, Confluence keeps the previous version. You can see all of these old versions, and you can see the differences between two versions, which makes it easy to see what has changed. Previous versions of a page are accessed from the page's [Info Tab].

The History List
Clicking the 'View page history' link takes you to a view which shows all the previous versions of the page. Each version is numbered. The oldest version is number 1.

On this page you can: • Replace the content of the page with that of an old version by clicking the restore link . • Compare two versions by selecting their check boxes and clicking the compare selected version button.

• View an old version by clicking on the numbered link in the version column.

Comparing Versions
To compare two versions you select two versions as described above, or use one of the shortcuts on the [Info Tab] to compare two recent consecutive versions. The comparison view shows: • Information about the two versions: their authors, and creation times.

• The number of changes between the two versions, and a link to the first of them.

• The changes. Lines inserted are shown in green, and lines removed in red.

Document generated by Confluence on Oct 10, 2007 11:54

Page 116

Unchanged lines have a white background. Each change has links to go to the previous and next changes.

Document generated by Confluence on Oct 10, 2007 11:54

Page 117

Requirements
This page last changed on Mar 29, 2006 by cmiller.

This page is outdated. The new documentation exists here.

Document generated by Confluence on Oct 10, 2007 11:54

Page 118

Security and Permissions
This page last changed on Sep 21, 2007 by smaddox.

This page is out of date and is left here for reference purposes only. Please read the Security Overview and Global Permissions Overview for up-to-date information.

Users and Groups
Users are individuals who sign on to Confluence. Most of the time a user represents a human being, but you could also register accounts for programmatic agents accessing the site. For example, a robot sitting in a chat-room and relaying the logs to a Confluence page via the SOAP API might have its own user account. New users can be created by a site administrator through the "Manage Users" option in the Administration pages, or they can sign themselves up for an account using the signup form. If you do not want users signing up for their own accounts, you can disable the signup form in the "General Configuration" section of the Administration pages: change "Allow Public Signup" to "OFF" Users can be grouped together into groups for more convenient administration. You can create new groups in the "Manage Groups" section of the Administration pages, and assign users to groups through the "Manage Users" section. Once you have assigned a user to a group, anything the group is permitted to do, the user is also permitted to do.

The "Anonymous" user
The "Anonymous" user isn't really a user, although it shows up on the permission management pages. "Anonymous" represents not only all the users in the system, but also anyone who has not logged in at all. (We call these people "Anonymous users", since they haven't identified themselves) For more information about setting up anonymous access in Confluence, see Setting up Anonymous Access.

Two Special Groups: confluence-administrators and confluence-users
confluence-administrators is the super-user group. Any user in this group automatically has permission to do anything in the site, regardless of the setting of any other privileges. Users in the confluence-administrators group are also listed as being availble to help on the "Contact Administrators" page that is linked throughout the site. confluence-users is the default group. All new users are added to this group, so whatever permissions you assign to this group will be the default access for newly signed-up users.

Deleting and Deactivating Users
Confluence will only allow you to delete a user entirely if the user is not responsible for any content within the site. If a user has edited a page or blog post, or left a comment, Confluence will need to keep the user around in the system to maintain its knowledge of who wrote what. You can, however, deactivate a user so they can no longer log in to Confluence. Deleting and deactivating users can be done in the "Manage Users" section of the Administration pages.

Permissions
What a user is allowed to do in Confluence is determined by the permissions they have assigned to them. Managing the users of a Confluence installation consists of giving the right users the right permissions.

A Digression: Security Policy and Confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 119

Traditionally, security is determined by the Principle of Least Privilege: you give each person the minimum amount of permissions that allow them to do their job. Unless someone can demonstrate a specific need to see or change some data, they are not given the authority to do so. For Confluence this is entirely the wrong approach. Confluence is a tool for communication and collaboration. You get the most value out of Confluence the more people you have participating in its discussions and editing its pages. Because Confluence keeps histories of all changes, it is very easy to see who has changed what, and reverse any edits that should not have been made. In short, you should design the security of a Confluence installation in accordance with the principle of Most Privilege. Give people the ability to do anything that you can't think of a good reason to restrict them from doing. There are three levels of permissions in Confluence: Global Permissions, Space Permissions and Page Restrictions.

Global Permissions
Global Permissions are granted in the "Global Permissions" section of the Administration screens. In order to assign these permissions, a user must already have the global "Administrate Confluence" permission. Confluence will do its best to make sure you never end up in a situation where the site no longer has any more administrators. • Use Confluence: The most basic permission. Without this, a user is not able to access the site at all, regardless of what other permissions they may have. In the case of a limited-user license, the number of licensed users is calculated as the number of users who have this permission. (If the "Anyone" user has this permission, then the number of licensed users will always be equal to the number of registered users) • Create Space: Users with this permission can create new spaces within a Confluence site. When a space is created, the creator automatically has the "Administer Space" permission for that space. • Administer Confluence: Users with this permission have access to the site administration pages, can change the site configuration, perform backups and imports, and create and modify user details. Note that this isn't quite the same as the super-user privilege of being in the confluenceadministrators group, but since any Administrator has the power to add themselves to that group, the distinction is only a technical one.

Space Permissions
Every space has its own, independant set of permissions. Space Permissions are granted in the "Permissions" section of each Space Information page. In order to assign these permissions, a user must have the "Administrate Space" permission for that space. If you misconfigure a space so that nobody has access to administer it any more, you will need to have someone in the confluence-administrators group fix the permissions for you. • View: user can view this space's content. • Pages: user can view the space's details, and its page and blog-posts. ° Create - user may create and edit pages in this space. ° Export - user may export pages in this space. ° Restrict - user may apply page level permissions. ° Remove - user may remove pages in this space. • Blog Posts: ° Create - user may post blogs in this space. ° Delete - user may remove blogs in this space. • Comments: ° Create - user may make comments in this space. ° Delete - user may remove comments from this space. • Attachments: ° Create - user may add attachments in this space. ° Delete - user may remove attachm\ents from this space.

Document generated by Confluence on Oct 10, 2007 11:54

Page 120

• Space: ° Export - user may export content from this space. ° Administer - user has administrative permissions over this space. • Mail: User may delete individual mail items.

Page Restrictions
The Page Restrictions, introduced in Confluence 1.4, allow to restrict view and edit actions on pages. For complete details, see Page Restrictions. To understand how Space Permissions and Page Restrictions affect each other, please see Security Overview.

Document generated by Confluence on Oct 10, 2007 11:54

Page 121

Use, Write, and Install Macros - obsolete
This page last changed on Oct 04, 2005 by jnolen.

Macros allow you to perform programmatic functions within a page, and can be used for generating more complex content structures. Generally speaking, a macro is simply a command wrapped inside curly braces {...}. Macro libraries are collections of macros which may work together or provide common functionality. They also allow groups of macros to be enabled or disabled together. (Added in Confluence 1.1). Confluence comes bundled with a host of useful macros, but users can also create their own macros to do specific things. Between Confluence 1.2 and 1.3, macros were made a part of the Confluence plugin architecture, with each macro being a plugin module. As such, the configuration files needed to configure a macro for Confluence have changed. Follow this link for information on converting between 1.2 macro libraries and 1.3 plugins Created a new macro or looking for macros? Share your macros and find new plugins in the Confluence extensions space.

More Information
• Guide to Confluence Macros - a list and usage examples of the macros that come bundled with Confluence • User Macros - how to create simple formatting macros inside Confluence in real time. • Macro Plugins - how to extend Confluence with more complex macros written in Java • Documenting Macros - You haven't finished writing your macro until you've documented it! • User Contributed Macros - Macros written by other Confluence users Old Information The following pages describe how to write macros for Confluence 1.1 and 1.2. This information is not relevant to users of Confluence 1.3. • Macro Management - obsolete - enabling and disabling individual macros and entire libraries. • Custom Java Macros - obsolete - creating more complicated custom macros using Java, including a worked example.

Document generated by Confluence on Oct 10, 2007 11:54

Page 122

Custom Java Macros - obsolete
This page last changed on Oct 04, 2005 by jnolen.

Old Documentation This documentation is for Confluence 1.1 and Confluence 1.2. If you are using Confluence 1.3 or later, macros are now written as Confluence Plugins, and you should read the Macro Plugins documentation instead. Java-based macros give you the most power to create your own Confluence macros that can produce complex HTML, retrieve data from Confluence, manipulate pages and interact with other systems and resources.

If you want to create more simple formatting macros in Confluence, you may only need a User macro.

Adding a Java macro
To add a Java macro library, drop the macro library JAR (called by convention macros-name.jar - ie macros-tasklist.jar) into the WEB-INF/lib directory within your Confluence web application and restart Confluence.

Structure of a Java macro library
A Confluence macro library is a JAR file containing classes and resources (ie Velocity templates) used by the macros in the library, as well as a macro library descriptor file macro-library.xml. This descriptor defines and documents the macro library, like the example below:
<macro-libraries> <macro-library name="Task List Macros" key="confluence.extra.tasklist" description="An example macro library which generates task lists."> <macro name="tasklist" class="com.atlassian.confluence.extra.tasklist.TaskListMacro" description="Creates a very simple task list, with user checkable tasks."/> <!-- more macros --></macro-library><!-- more macro libraries --></macro-libraries>

A descriptor can contain multiple library definitions, each with multiple macros.

Building Java macros
The Confluence installation contains a custommacros directory with a "Confluence Macro Builder" Ant script and some sample macro projects.

Task List Example Library
As an example, tasklist is one of the example macros, which builds a simple task list within a Confluence page and allows users to complete and uncomplete the various tasks simply. It also serves as a good example of how easy it is to build add functionality to Confluence. Example Here's a screenshot of the tasklist macro in action, showing a simple shopping list that's half completed: !tasklist-screenshot.gif|align=center!

Document generated by Confluence on Oct 10, 2007 11:54

Page 123

This was generated by notation like the following, with tasks completed or uncompleted by clicking on the relevant or :

{tasklist:Shopping List} Buy apples Buy bananas Purchase shopping bag Collect laundry Deposit money {tasklist}

You can download a prebuilt tasklist library or build it yourself as below. Building the tasklist library To build tasklist, go to the custommacros directory within the expanded distribution, and run:
ant -Dlibrary=tasklist build

Your macro library is now located at custommacros/tasklist/dist/macros-tasklist.jar Installing the tasklist library To install the library straight into the web application, run:
ant -Dlibrary=tasklist install

and then restart your Confluence instance. Similarly you can uninstall the library like so:
ant -Dlibrary=tasklist uninstall

Note: Confluence must first be shutdown before you can uninstall macros.

Document generated by Confluence on Oct 10, 2007 11:54

Page 124

Macro Management - obsolete
This page last changed on Jan 18, 2007 by rosie@atlassian.com.

Old Documentation This documentation refers to Confluence 1.1 and 1.2. As of Confluence 1.3, macros have been incorporated into the plugin system. For information on how to manage plugins, read Installing and Configuring Plugins manually. Since Confluence 1.1, users can enable and disable macro libraries and individual macros through the web interface. To manage macros, go to Administration then Manage Macros.

You must be a Confluence administrator to manage macros. Here is an example of the Manage Macros screen:

From this screen you can see: • Libraries - There are 4 macro libraries installed (Basic, Compatibility, Advanced and HTML macros). There is also the special User Macros library, see DOC:User Macros for more detail on how to create your own user macros. • Disabled libraries - The Compatibility and HTML macro libraries are disabled here. You can see that because their tabs are greyed out. A disabled library is installed in Confluence but not usable within any page. • Selection - The Basic macro library is selected, and 6 out of it's 7 macros are enabled currently. Disabled macros or libraries You can disable individual macros or entire libraries through this macro management interface. A disabled macro will not be usable within Confluence. If it is used, a simple error message will be printed and the macro will not be run. For a disabled library, none of it's macros will execute.

Document generated by Confluence on Oct 10, 2007 11:54

Page 125

For example in the screenshot above, the Compatibility and HTML macro libraries are disabled - their tabs are greyed out. Also, in the selected Basic macro library, the noformat macro is currently disabled - it has a red background rather than a green one. Enabling and Disabling To disable a macro - locate it's macro library, then click the 'disable' link next to it. To enable a macro - as above, except click the 'enable' link. To disable a library - click on the enabled library's name in the tab list on the left of screen, then click 'Disable library' at the top. To enable a library - click on the disabled library's name in the tab list on the left of screen, then click 'Enable library' at the top.

Document generated by Confluence on Oct 10, 2007 11:54

Page 126

__ConfluenceHosted
This page last changed on May 25, 2007 by rosie@atlassian.com.

If you are using Confluence Hosted, please note that some Confluence features only apply to the installed version (see the feature comparison). Also please see Confluence Hosted Resources.

Document generated by Confluence on Oct 10, 2007 11:54

Page 127

TreeNavigation
This page last changed on May 28, 2007 by rosie@atlassian.com.

Document generated by Confluence on Oct 10, 2007 11:54

Page 128

Administration Guide Attachments Directory
This page last changed on Feb 01, 2006 by rosie@atlassian.com.

This page contains the attachments for the Administrators Guide.

Document generated by Confluence on Oct 10, 2007 11:54

Page 129

_ConfluenceHostedNA1
This page last changed on Sep 03, 2007 by smaddox.

Not applicable to Confluence Hosted This page does not apply if you are using Confluence Hosted. Read more about the feature limitations in Confluence Hosted.

Document generated by Confluence on Oct 10, 2007 11:54

Page 130

.bookmarks
This page last changed on Sep 10, 2007 by .

Confluence Bookmarks This page is a container for all the bookmarks in this space. Do not delete or move it or you will lose all your bookmarks. Bookmarks in Confluence | Links for Confluence

Bookmarks
There are no bookmarks to display.

Document generated by Confluence on Oct 10, 2007 11:54

Page 131

Confluence Documentation Home
This page last changed on Sep 27, 2007 by smaddox.

For New Users Features Live Demo Independent Reviews System Requirements Free Trial

Guides

Resources Plugins & Tools FAQ Technical Support Community Forum Community Development Hub Release Notes Feature Requests & Bugs

User Guide Administration Guide Install Guide • Database Configuration • Server Configuration Upgrade Guide Wiki Adoption Guide

This documentation applies to Confluence 2.6 onwards, though some features are unavailable to hosted users. • Resources For Hosted Users • Download the Confluence documentation documentation for older versions. ° Confluence 2.0 to 2.5.3 ° [Confluence 2.5.4 to 2.5.7] updated pages. Error rendering macro: java.lang.NullPointerException RSS Feed of recent updates. Click to view

Click to view recently

Document generated by Confluence on Oct 10, 2007 11:54

Page 132

Administrators Guide
This page last changed on Oct 04, 2007 by smaddox.

Confluence 2 Administrator's Guide Configuring Confluence Data and Backups System Administration Importing Data Mail Configuration Security User Management Design and Layout Integrating Confluence and JIRA Plugin Management Performance Tuning Character Encoding Support

Search

Download

You can download the Confluence Admin Guide in PDF, HTML or XML formats.

Additional Resources Visit the Configuration Guide for documentation on configuring databases and application servers. The Confluence User Guide has information on how to use Confluence as a collaborative tool. Go to Documentation Home for links to more resources.

Site Administrator? The Confluence Administrators 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. If you are using Confluence Hosted, please refer to the Confluence Hosted Administrator's Guide.

Configuring Confluence
Site Configuration Configuring the Site Homepage Editing the Site Title Editing the Site Welcome Message View Space Goes to Browse Space Editing the Global Logo Configuring the Server Base URL Configuring HTTP Timeout Settings Recognised System Properties Customising Default Space Content Optional Settings Enabling Remote APIs

User Management
Confluence User Management Global Groups Overview Global Permissions Overview Setting up Anonymous Access Adding a New User Editing User Details Removing a User Enabling or Disabling Public Signup Adding or Removing a User from a Group Adding a Group Removing a Group Viewing Members of a group Restoring Passwords To Recover Admin User Rights External User Management

Document generated by Confluence on Oct 10, 2007 11:54

Page 133

Enabling Rich Text Editing Option Making Rich Text Editing default Enabling CamelCase Linking Enabling Trackback Enabling Threaded Comments Attachment Storage Configuration NEW in 2.2! Configuring Attachment Size Display Settings Configuring Indexing Language Number of Ancestors to Show in Breadcrumbs Configuring Character Encoding Configuring Time and Date Formats Configuring Number Formats Thumbnail Settings Configuring Shortcut Links

Understanding User Management in Confluence Activating External User Management LDAP Integration Overview Confluence Caching OSUser Provider Changes in osuser.xml from 1.0.3a to 1.1.x Requesting External User Management Support Troubleshooting the "Not Permitted" Screen under LDAP Integration Crowd User Management Integrating Confluence with Crowd JIRA User Management Delegating User Management in Confluence to JIRA Delegating User Management in Confluence 1.0 to JIRA Override properties in JIRA to Confluence Bridge

Data and Backups
Backups Configuration Configuring Daily Backups Changing Time of Daily Backup 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 Scheduled Jobs Scheduled Jobs

Design and Layout
Configuring Layouts Customising Look and Feel Overview Customising Colour Schemes Customising Layouts Working With Decorator Macros Global Templates Configuring Themes Themes Overview Creating a Theme Applying a Theme To A Site Including Cascading Stylesheets in Themes

System Administration
System Configuration Information Viewing System Information Viewing and Editing License Details Cache Statistics Cluster Administration page System Administration Content Index Administration Upgrading Confluence Moving Confluence Between Servers Migrate to a Different Database Migrate Or Clone Confluence Between Servers Important Directories and Files Rebuilding the Ancestor Table

Integrating Confluence and JIRA
Integrating JIRA and Confluence Configuring Jira Issues Icon mappings Add Confluence EAR-WAR to JIRA Standalone

Plugin Management
Installing and Configuring Plugins manually Installing and Configuring Plugins using the Plugin Repository Confluence Plugin Guide

Document generated by Confluence on Oct 10, 2007 11:54

Page 134

Importing Data
Importing From JSPWiki Build JSPWiki-exporter from source Snip Snap Import

Macros Configuring User Macros Writing Macros Editing and Removing macros Enabling HTML Macros Enabling the html-include Macro

Mail Configuration
Configuring a Server for Outgoing Mail The Mail Queue Enabling the 'Mail Page' plugin NEW in 2.4!

Performance Tuning
Memory usage and requirements Configuring a Large Confluence Installation Tuning Tips Profiling using the YourKit Plugin

Security
Advisory Security advisories Java Policy Security with Confluence Security Options Spam Prevention (Captcha) NEW in 2.2! Managing External Referrers Hiding External Referrers Hiding External Links From Search Engines Excluding External Referrers User Email Visibility Anonymous Access to Remote API Adding SSL for Secure Logins and Page Security

Character Encoding
Configuring Encoding Troubleshooting Character Encodings

Support
How to Get Support

Document generated by Confluence on Oct 10, 2007 11:54

Page 135

Administration
This page last changed on Feb 03, 2006 by vidya.

• • • • • • •

• • • • • • • • • • • •

Cache Statistics Changing time of Daily Backup Confluence Data Directory Configuration Confluence home directory contents Content Index Administration Important Directories and Files Manually Backing Up The Site ° Configuring Daily Backups - User Submitted Backup & Restore Scripts Migrate Or Clone Confluence Between Servers Moving Confluence Between Servers Rebuilding the Ancestor Table Restoring a Site Restoring a Space ° Changing the version of a space backup Restoring Data from other Backups Restoring Data from the Administration Console Retrieve file attachments from a backup Troubleshooting failed XML site backups Viewing and Editing License Details Viewing System Information Where Is My ConfluenceHome Directory?

Document generated by Confluence on Oct 10, 2007 11:54

Page 136

Cache Statistics
This page last changed on Oct 05, 2007 by smaddox.

Confluence provides statistics about its internal caches that allow you to track the size and hit ratio of each cache and tune it for better performance (if necessary). See Performance Tuning for more information. To view the cache statistics, go to the 'Administration Console' and click 'Cache Statistics' in the left panel. There you will find a list of all objects cached within Confluence. Click on 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

Flush Flush

About the generated numbers :

Percent Used: Effectiveness: Objects / Size: Hit / Miss / Expiry:

=(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 flushes the cache

Flush: For instance to calculate Percent Used :
Percent Used = Objects / Size Percent Used = 4023/5000 = 80%

and to calculate Effectiveness :
Effectiveness = (Hits)/(Hits + Misses) Effectiveness = 374550 / (374550 + 140460) = 73%

The clustered versions of Confluence use distributed cache called Tangosol Coherence.
Performance Tuning

If you need to tune your application when under high usage, you may like to review this document for suggestions.
RELATED TOPICS

Cache Statistics Viewing and Editing License Details

Document generated by Confluence on Oct 10, 2007 11:54

Page 137

Viewing System Information

Document generated by Confluence on Oct 10, 2007 11:54

Page 138

Changing time of Daily Backup
This page last changed on Sep 19, 2007 by smaddox.

By default, Confluence runs its daily backup at 2.00 AM. You can configure Confluence to perform the backup at a time that is best suited to you or your organisational needs. Confluence uses Quartz for scheduling periodic jobs. To change the time of your daily backup, you will need to edit the Quartz configuration. To change the time of your daily backup

1. Open the Quartz configuration file schedulingSubsystemContext.xml located under confluence/ WEB-INF/classes/ 2. Find the following section of the file:
<bean id="backupTrigger" class="org.springframework.scheduling.quartz.CronTriggerBean"><property name="jobDetail"><ref bean="backupJob"/></property><property name="cronExpression"><value>0 0 2 * * ?</value></ property></bean>

3. The string '0 0 2 * * ?' sets up a Cron Trigger for the job to run at the zeroth second of the zeroth minute of the 2nd hour, every day of every month, every day of the week. 4. You can set a new time by editing this string. Note that the date and time format in this configuration file is in this order: Second minute hour day 5. Restart Confluence. For example, to set the new time to twenty past ten PM, change the string to '0 20 22 * * ?'. If you wanted to back up only once a week, for example, at midnight on Sundays, you would change the string to '0 0 0 ? * SUN'. For complete details on the formatting of the cron string, please see http://www.opensymphony.com/ quartz/api/org/quartz/CronTrigger.html.
RELATED TOPICS

Backup FAQ Changing time of Daily Backup Configuring Daily Backups Manually Backing Up The Site Site Backup and Restore

Document generated by Confluence on Oct 10, 2007 11:54

Page 139

Confluence Data Directory Configuration
This page last changed on May 23, 2006 by david.soul@atlassian.com.

Here is a link listing important Confluence files. The home directory defines the location of the directory where Confluence will store it's data, including attachments, indexes and backups. Administrators can set this location by defining a value for the file <MY-INSTALL>/confluence/WEB-INF/classes/confluence-init.properties. To find what your home directory is currently set to, open this file and check the confluence.home property. It is unset on new installations. Windows Configuration On Windows, the path
C:\confluence\data

will be written as:
confluence.home=C:/confluence/data

Note that all backslashes (\) are written as forward slashes (/). UNIX/Linux/Mac Configuration On any UNIX-based system, the property is defined using the normal directory syntax:
confluence.home=/var/confluence/
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.

Fixing the Confluence Configuration
The Confluence configuration file: confluence-cfg.xml inside the home directory may contain references to the original location of your Confluence home. You will need to edit this file to update these references to also point to the new location. The two properties in this file that need to change are: • daily.backup.dir if you have not configured your backups to be placed elsewhere already • hibernate.connection.url if you are using the embedded HSQL database.

Document generated by Confluence on Oct 10, 2007 11:54

Page 140

Confluence home directory contents
This page last changed on Sep 21, 2007 by don.willis@atlassian.com.

The Confluence home directory contains data that work in concert with the Confluence database to provide the wiki experience. This document outlines the purpose of the various files and directories in the Confluence home directory.

Files and directories
confluence.cfg.xml
This file is the most critical file in the Confluence home directory. It 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:
/attachments/PAGE_ID/ATTACHMENT_ID/VERSION

An alternative directory may be specified 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

An alternative directory may be specified for backups by setting the daily.backup.dir property in confluence.cfg.xml.

bundled-plugins
This directory exists for Confluence 2.3 and above Recent versions of Confluence ship 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 and as such contains all Confluence runtime data. Instances configured to run using an external database such as MySQL will not use this directory.

Document generated by Confluence on Oct 10, 2007 11:54

Page 141

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
This directory exists for Confluence 2.3 and above As of Confluence 2.3, all Confluence plugins are now 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. As such, 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.

Confluence 2.2 and older
The following files and directories were used by versions of Confluence older than 2.3

config
The config directory is used to store data used by Confluence's bandana data persistence framework. This system is used by Confluence to store the global instance settings and is used by various plugins for their own configuration and data persistence needs. Confluence versions 2.3 and later store these data in the Confluence database and do not use this directory. The most important file in this directory is the confluence-global.bandana.xml file. This file is used to store all of the settings from the Administration console in Confluence.

Document generated by Confluence on Oct 10, 2007 11:54

Page 142

plugins
The plugins directory is where Confluence stores all installed plugin JARs. It is possible to install and remove plugins by placing and deleting plugin JARs from this directory.

default-formatting.properties
This properties file contains various formatting information such as the formats for decimal numbers and dates used in the Confluence user interface. These configuration data where relocated to the Confluence database from Confluence 2.3 and onwards.

Document generated by Confluence on Oct 10, 2007 11:54

Page 143

Content Index Administration
This page last changed on Jun 25, 2007 by smaddox.

The Content Index powers Confluence's search functionality and is also used for a number of related functions such as building email threads in the mail archive. While the index is maintained automatically, you may need to rebuild it manually under these circumstances: • If you find that your searching and mail threading are malfunctioning. • After an upgrade (if a reindex is required after an upgrade, it will be noted in upgrade section of the release notes). To manually rebuild the content index,

1. Go to the 'Administration Console' and click on 'Content Indexing' under the heading 'Administration' in the left panel. For reasons of efficiency, content is not immediately added to the index. New and modified Confluence content is first placed in a queue, and the queue is processed once every minute. 2. Click 'Rebuild Index'. Slow reindexing? Indexing can take a long time to complete, depending on the number of pages, number, type and size of attachments and the amount of memory allocated to Confluence. It may help to increase the heap memory allocation of Confluence by following these instructions. 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).
RELATED TOPICS

Configuring Indexing Language Content Index Administration Working with Macros [!Administration Guide Attachments directory^adminhome.gif!]

Document generated by Confluence on Oct 10, 2007 11:54

Page 144

Important Directories and Files
This page last changed on May 15, 2007 by rosie@atlassian.com.

The Install Directory
This is the directory into which the downloaded Confluence application has been unpacked. Confluence does not modify or store any data in this 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. • 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. • 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.

The Temp Directory
The temp directory is configured in the Java runtime and some Confluence components write temporary files or lockfiles into this directory. Typically, this directory is /tmp on Unix systems, or C:\Temp on Windows. To change the location of this directory, you should start the Java Virtual Machine in which confluence is running with the argument: -Djava.io.tmpdir=/path/to/your/own/temp/directory.

The Confluence Home Directory
This is the directory in which Confluence stores its configuration information, search indexes, custom decorators and page attachments. Also, if you're using the embedded HSQL database, the database is also stored in this directory. Administrators can expect the Confluence Home Directory to grow quite large in a busy site. The location of this directory is configured by the Confluence administrator during installation (see confluence-init.properties above). Important Files and Directories • confluence.cfg.xml : Confluence's core configuration file; includes the configuration for connecting to its database. • default-formatting.properties : Some auxiliary configuration data concerning default number and date formats. • attachments/ : All file attachments in the Confluence site are stored under this directory. This is the only place Confluence keeps attachment files. • backups/ : If Confluence is configured to produce daily backups, these are kept in this directory. Administrators should occasionally delete old or unwanted backups from this directory to prevent it from growing too large. • config/ : Miscellaneous global and per-space configuration files are kept in this directory. • database/ : If Confluence is being run from the embedded HSQL database, the database files will be kept in this directory.

Document generated by Confluence on Oct 10, 2007 11:54

Page 145

• index/ : The full-text search index is kept in this directory. Removing or modifying files in this directory may cause search to no longer function. Rebuilding the search index from Confluence's global administration screen will completely regenerate the contents of this directory. • plugins/ : Dynamically uploaded plugins are stored in this directory. Administrators can install new plugins by copying them into this directory and triggering a scan from the plugin management page. • temp/ : Confluence stores temporary files in this directory, especially during backups and exports. A daily job within Confluence deletes files that are no longer needed. • thumbnails/ : Stores temporary files for image thumbnails. The contents of this directory can be safely deleted, as Confluence will 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 being 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

Attachments directory^dochome.gif!]

[!Administration Guide

Document generated by Confluence on Oct 10, 2007 11:54

Page 146

Manually Backing Up The Site
This page last changed on Jun 25, 2007 by smaddox.

Confluence is configured to make a daily backup of your data and store it as a zipped XML file in the 'backups' folder under the Confluence Home Directory. A site administrator can also manually backup the data from the Administration Console. To manually backup your site,

1. Go to the 'Administration Console' and click on 'Backup and Restore' in the left panel. 2. Select 'Archive to Backups Folder' to store a copy of the backup in the same folder as Confluence's daily backups (if you do not archive the backup it will be made available for you to download, and then deleted from the server after 24 hours). 3. Select 'Backup Attachments' to include attachments in your backup. 4. Click 'Backup'. Please note that this process will take a few minutes. 5. Once the backup is completed, you will be prompted to download the zipped backup file.
RELATED TOPICS

Backup FAQ Changing time of Daily Backup Configuring Daily Backups Manually Backing Up The Site Site Backup and Restore

Document generated by Confluence on Oct 10, 2007 11:54

Page 147

Configuring Daily Backups
This page last changed on Aug 01, 2007 by smaddox.

Confluence backs up your data on a daily basis into a zipped XML file. By default, the backup is performed at 2.00 am and the backup files are stored in the backups folder under the Confluence Home Directory. The default naming convention for the backup files is 'daily-backup-yyyy_MM_dd'. Confluence can write backups to both local and mapped network drives. From the Administration Console, you can: • • • • Enable or disable backups Include or exclude attachments in back ups Configure a different path to store backup files Change the naming format used for the files.

To configure your daily backups,

Go to the Administration Console and click 'Daily Backup Administration' under 'Configuration'. 1. Select 'Disable' to disable backups. 2. Select 'Custom' if you want to provide an alternate path to store backup files. The directory must be on either a local drive or a mounted network drive. 3. Select 'Off' beside 'Backup Attachments' to exclude attachments from backups. By default, this is 'on'. 4. To use a different naming prefix format, enter the new format in the 'Backup File Prefix' input field. 5. To use a different date format, enter it in in the 'Backup File Date Pattern' input field using the syntax described in this document. 6. 'Save' your changes. Below is an example of daily backup being disabled.

RELATED TOPICS

Backup FAQ Changing time of Daily Backup Configuring Daily Backups Manually Backing Up The Site Site Backup and Restore

Document generated by Confluence on Oct 10, 2007 11:54

Page 148

User Submitted Backup & Restore Scripts
This page last changed on Aug 09, 2007 by smaddox.

These scripts are user-submitted and should be used with caution as they are not covered by Atlassian technical support. If you have questions on how to use or modify these scripts, please post them to the Confluence user forum. Feel free to submit new scripts or post updates by logging in and adding them to the page as a comment.

Delete Old Backups - Wscript Script On Windows
This script examines backup filename and deletes them if necessary, it may need to be edited.
'If you want 3 day old files to be deleted then insert 3 next to Date - "your number here" 'This script will search out and delete files with this string in them ".2005-12-04-" This of course depends on the number you enter. 'You can always do a wscript.echo strYesterday or strFileName to see what the script thinks you are searching for. dtmYesterday = Date - 3 strYear = Year(dtmYesterday) strMonth = Month(dtmYesterday) If Len(strMonth) = 1 Then strMonth = "0" & strMonth End If strDay = Day(dtmYesterday) If Len(strDay) = 1 Then strDay = "0" & strDay End If strYesterday = strYear & "-" & strMonth & "-" & strDay strFileName = "C:\test*." & strYesterday &"-*" Set objFSO = CreateObject("Scripting.FileSystemObject") objFSO.DeleteFile(strFileName)

Delete Old Backups - Basic Bash Script For Linux
Old XML backups can be deleted automatically by inserting a nightly or weekly automation script or cron similar to the following:
ls -t <path to your backup dir>/* | tail -n +6 | xargs -i rm {}

Or, using the older form of the tail command if your system does not support the standard form:
ls -t <path to your backup dir>/* | tail +6 | xargs -i rm {}

Delete Old Backups - Advanced Bash Script For Linux
Old XML backups can be deleted automatically by inserting a nightly or weekly automation script or cron similar to the following. Set the BACKUP_DIR and DAYS_TO_RETAIN variables to appropriate values for your site. Between runs, more files than DAYS_TO_RETAIN builds up.
#!/bin/sh # Script to remove the older Confluence backup files. # Currently we retain at least the last two weeks worth # of backup files in order to restore if needed. BACKUP_DIR="/data/web/confluence/backups" DAYS_TO_RETAIN=14

Document generated by Confluence on Oct 10, 2007 11:54

Page 149

find $BACKUP_DIR -maxdepth 1 -type f -ctime +$DAYS_TO_RETAIN -delete

Manual Database & Home Backup - Bash Script For Linux
This backs up a mySQL database and the Confluence home directory.
#!/bin/bash CNFL=/var/confluence CNFL_BACKUP=/backup/cnflBackup/`date +%Y%m%d-%H%M%S` rm -rf $CNFL/temp/* mkdir $CNFL_BACKUP mysqldump -uroot -p<password> confluence|gzip > $CNFL_BACKUP/confluence.mysql.data.gz tar -cjvf $CNFL_BACKUP/data.bzip $CNFL > $CNFL_BACKUP/homedir.status

Related Topics
• Site Backup and Restore • Backup FAQ

Document generated by Confluence on Oct 10, 2007 11:54

Page 150

Migrate Or Clone Confluence Between Servers
This page last changed on Sep 03, 2007 by david.soul@atlassian.com.

To copy a Confluence instance from one server to another, for example to transfer the current production snapshot to a test server as permitted in the licence agreement: On the original server: 1. 2. 3. 4. Stop Confluence Copy your Confluence install directory Copy your Confluence home directory Use your database administration tool to access your external database and create a Confluence database export 5. Start Confluence On the target server: 1. If you are not using Standalone Confluence, setup the same version of the application server use on the original 2. Setup the database to be an exact clone of the original a. Setup the same database version and driver b. Setup the database user to have the same permissions as the original c. Import the Confluence database export 3. Place the Confluence install directory but do not start Confluence yet 4. Place the Confluence home directory 5. If the home directory is in a different location, go to the Confluence install directory and edit .. \confluence\WEB-INF\classes\confluence-init.properties. The home directory is set under confluence.home 6. 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 7. Start Confluence The target instance will be a clone of the original instance.

Related Tasks
Add LDAP Integration Adding SSL for Secure Logins and Page Security Customising Look and Feel Overview Database Configuration Installing the Confluence EAR-WAR edition Troubleshooting & Technical Support Upgrading Confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 151

Moving Confluence Between Servers
This page last changed on Oct 17, 2006 by david.soul@atlassian.com.

Adminstrators may need to move a Confluence instance from one server to another for upgrades or downtime. Avoid upgrades while transferring If you are planning to switch databases, application servers or Confluence versions, perform the transfer and test that it is successful separately to any other changes.

Transferring Confluence Standalone To Another Server Using The Same Operating System
If you are using Confluence Standalone and the operating systems on both servers are the same, then the home and install folders can be copied straight into an identical external database and user management setup. 1. On the original server, create zips of the Confleunce install and home directories. Copy the zips to the new server. 2. On the new server, unzip the install and home directories. Windows users should avoid unzipping with the Windows built-in extractor, instead use Winzip or the free 7Zip. 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. This next step is dependent on your database: • For users of the internal database, the content is stored inside the home directory. You should consider switching to an external database after the transfer is successful. • For 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. • For external databases stored locally: A. On the original server, create a manual database backup. B. Copy the database backup to the new server. C. On the new server, install or upgrade the database version to match the original server. D. Import the database backup. E. Add a database user account with the same username and password as the original. F. Provide the user with the full access to the imported mdatabase. G. Use a database administration tool to confirm that the user can login from the localhost. 4. 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. 5. If you configured Confluence as a Windows service, repeat those instructions.

All Other Transfers
Create a backup and import into the new server. 1. Create a backup from Confluence by going to 'Administration' -> 'Backup & Restore', checking the 'Backup Attachments' and selecting 'Backup'. 2. Identify the current version of Confluence your are using, displayed at the bottom of each Confluence page. 3. Download the same version as you are currently using to the new server, which may be the current Confluence release, or an older version. 4. Using the same version, follow the Upgrading Confluence guide.

Document generated by Confluence on Oct 10, 2007 11:54

Page 152

Rebuilding the Ancestor Table
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

In Confluence, the ancestor table controls the breadcrumb navigation at the top of each Confluence page. Occassionally, the ancestor table will become out of sync. When this happens, you can rebuild the table to restore everything to normal. Simply access this URL:
http://yoursite/admin/permissions/rebuild_ancestor_table.action

RELATED TOPICS

Document generated by Confluence on Oct 10, 2007 11:54

Page 153

Restoring a Site
This page last changed on Jun 25, 2007 by smaddox.

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 in the data being restored. Confluence supports Backward Compatibility for site backups (note: not 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 v 2.4.3, it cannot be restored into a Confluence v2.2.2. It can however, be restored in 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 both a database backup and backups of your confluence home directory, then it is still possible to restore from these backups. You can not restore a particular space only from the entire site backup when the backup contains more then one space.
RELATED TOPICS

Confluence 2.6 Manually Backing Up The Site Restoring a Site Restoring a Space Restoring Data from the Administration Console

Document generated by Confluence on Oct 10, 2007 11:54

Page 154

Restoring a Space
This page last changed on Jul 12, 2007 by ivan@atlassian.com.

Confluence will only allow you to restore a space if a space by that name does not already exist 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. Before you begin Confluence only supports Forward Compatibility and Backward Compatibility for individual space import and export when executed within the same major version of Confluence instances. 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 v2.4.5, it cannot be imported into a Confluence v2.2.2. 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 v 2.2.2 can not be imported into v 2.4.5. However, it can be restored in 2.2.10. (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.

To restore a space,

Go to the 'Administration Console' and click on 'Backup and Restore' in the left 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 filesystem • 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. • Click 'Restore'. Restoring Spaces between Major Releases As described in the warning above, you cannot restore a space directly between two major versions. i.e. an individual Space backup from 2.2.x cannot be imported into a 2.3.x. Whilst there is presently no functionality in Confluence that allows you to do so, there is however a manual workaround to this problem. Please follow the procedure below: 1. Create a manual Site Backup 2. Configure a separate installation of the Confluence version you want the space export for i.e. the version in which you want the Space Export for 3. Use one of the two restoration methods listed here to import the Site Backup. 4. After restoring the site backup, create the XML Backup for the Space you want. 5. Import this backup into your main Confluence instance and you now have that Space. This procedure is a manual workaround until proper functionality is implemented. Remember: Always backup your data before attempting this procedure. Alternative Other way is to change the version of a space backup

Document generated by Confluence on Oct 10, 2007 11:54

Page 155

RELATED TOPICS

Confluence 2.6 Manually Backing Up The Site Restoring a Site Restoring a Space Restoring Data from the Administration Console

Document generated by Confluence on Oct 10, 2007 11:54

Page 156

Changing the version of a space backup
This page last changed on Jul 11, 2007 by mryall.

Confluence prevents the import of space backups which aren't from the same major version. The reason for this is that any schema change between the export and imported version of Confluence will cause the import to fail, leaving you with an incomplete import. Even worse, the failure can be database-dependent, so it may work fine on one particular database but your backup will fail to import later. 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.

Document generated by Confluence on Oct 10, 2007 11:54

Page 157

Restoring Data from other Backups
This page last changed on Sep 13, 2007 by dave@atlassian.com.

Typically, Confluence data is restored from the Administration Console or from the Confluence Setup Wizard. If you are experiencing problems restoring from an zipped XML backup file, it is still possible to restore provided you have: 1. a backup of your home directory 2. a backup of your database (if you're using an external database) Instructions for this method of restoring differ depending on whether you are using the embedded database or an external database (like Oracle, MS SQL Server, MySQL or Postgres). Embedded Database If you are running against the embedded database, the database is located inside the database folder of your Confluence Home Directory. Hence, all you need to do is: 1. retrieve the most recent backup of your home directory 2. unpack the Confluence distribution and point the confluence-init.properties file to this directory External Database If you're using an external database, you need to: 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

Migrate to a Different Database

Document generated by Confluence on Oct 10, 2007 11:54

Page 158

Restoring Data from the Administration Console
This page last changed on Jun 25, 2007 by smaddox.

Use this option if you want to restore data into your current instance of Confluence. If you want to restore data into a new instance, follow the instructions here. CAUTION: Restoring a backup of an entire confluence site (consisting of multiple spaces) will: • Wipe out all confluence content in the database. Ensure that you your database is backed up. • Log you out after the restore process. Make sure you know your login details in the data being restored. To restore data from backup,

Go to the 'Administration Console' and click on 'Backup and Restore' in the left 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 filesystem • 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. • Click 'Restore'.
RELATED TOPICS

Confluence 2.6 Manually Backing Up The Site Restoring a Site Restoring a Space Restoring Data from the Administration Console

Document generated by Confluence on Oct 10, 2007 11:54

Page 159

Retrieve file attachments from a backup
This page last changed on Jan 03, 2007 by ivan@atlassian.com.

File attachments on pages can be retrieved from a backup without needing to import the the backup into Confluence. This is useful for recovering attachments that have been deleted by users. Both daily and manual backups allow this, as long as the 'Include attachments' property was set. Users wanting to restore pages, spaces or sites should check out the Administrators Guide instead. Before following the instructions for recovering attachments, please review how backups store file and page information.

How Backups Store File and Page Information
The backup zip file contains entities.xml, an XML file containing the Confluence content, and a directory for storing attachments.

Backup Zip File Structure
Page attachments are stored under the attachments directory by page and attachment id. Here is an example listing:
Listing for test-2006033012_00_00.zip \attachments\98\10001 \attachments\98\10002 \attachments\99\10001 entities.xml

Inside the attachment directory, each numbered directory inside is one page, and the numbered file inside is one attachment. The directory number is the page id, and the file number is the attachment id. For example, the file \attachments\98\10001 is an attachment with page id 98 and attachment id 10001. You can read entities.xml to link those numbers to the original filename. Entities.xml also links each page id to the page title.

Entities.xml Attachment Object
Inside the entities.xml is an Attachment object written in XML. In this example, the page id is 98, the attachment id is 10001 and the filename is myimportantfile.doc. The rest of the XML can be ignored:
<object class="Attachment" package="com.atlassian.confluence.pages"><id name="id">98</id><property name="fileName"><![CDATA[myimportantfile.doc]]></property> ... <property name="content" class="Page" package="com.atlassian.confluence.pages"><id name="id">10001</id></property> ... </object>

Entities.xml Page Object
This XML describes a page. In this example, the page id is 98 and the title is Editing Your Files. The rest of the XML can be ignored:
<object class="Page" package="com.atlassian.confluence.pages"><id name="id">98</id><property name="title"><![CDATA[Editing Your Files]]></property> ... </object>

Instructions for Recovering Attachments
Each file must be individually renamed and re-uploaded back into Confluence by following the instructions below. Choose one of the three methods:

Document generated by Confluence on Oct 10, 2007 11:54

Page 160

Choice A - Recover Attachments By Filename Best if you know each filename you need to restore, especially if you want just a few files: 1. Unzip the backup directory and open entities.xml. 2. Search entities.xml for the filename and find the attachment object with that filename. Locate its page and attachment id. 3. Using the page and attachment id from entities.xml, go to the attachments directory and open that directory with that page id. Locate the file with the attachment id. 4. Rename the file to the original filename and test it. 5. Repeat for each file. 6. To import each file back into Confluence, upload to the original page by attaching the file from within Confluence. Choice B - Restore Files By Page Best if you only want to restore attachments for certain pages: 1. Unzip the backup directory and open entities.xml. 2. Search entities.xml for the page title and find the page object with that title. Locate its page id. 3. Go to the attachments directory and open that directory with that page id. Each of the files in the directory is an attachment that must be renamed. 4. Search entities.xml for attachment objects with that page id. Every attachment object for the page will have an attachment id and filename. 5. Rename the file with that attachment id to the original filename and test it. 6. Repeat for each page. 7. To import each file back into Confluence, upload to the original page by attaching the file from within Confluence. Choice C - Restore All Files Best if you have a small backup but want to restore many or all the attachments inside: 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 unrenamed 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

Document generated by Confluence on Oct 10, 2007 11:54

Page 161

Troubleshooting failed XML site backups
This page last changed on Mar 23, 2007 by dave@atlassian.com.

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

Resolve Errors With Creating An XML Backup
The errors may be caused by a slightly corrupt database. If you're seeing errors such as 'Couldn't backup database data' in your logs, this guide will help you correct the error on your own. We strongly recommend that you backup your database and your Confluence home directory beforehand, so that you can restore your site from those if required. If you are unfamiliar with SQL, we suggest you contact your database administrator for assistance.

To Identify And Correct The Problem
To work out where the data corruption or problems are, increase the status information reported during backup, then edit the invalid database entry: 1. Stop Confluence. 2. If you have an external database, use a database administration tool to create a manual database backup. 3. Backup your Confluence home directory. You will be able to restore your whole site using this and the database backup. 4. Open the my_confluence_install/confluence/WEB-INF/classes/log4j.properties and add this to the bottom and save:
log4j.logger.com.atlassian.confluence.importexport.impl.XMLDatabinder=DEBUG, confluencelog log4j.additivity.com.atlassian.confluence.importexport.impl.XMLDatabinder=false

5. Find your Confluence output logs. On standalone, this is the /logs directory under your Confluence install. Move or delete all existing Confluence logs to makes it easier to find the relevant logging output. 6. Restart Confluence and login. 7. Begin a backup so that the error reoccurs. 8. You must now check your log files to find out what object could not be converted into XML format. Open my_confluence_install/logs/catalina.out. 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)

Document generated by Confluence on Oct 10, 2007 11:54

Page 162

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 table needs fixing. To work out what table an object maps to in the database, here's a rough guide: • Pages, blogposts, comments --> CONTENT table • attachments --> ATTACHMENTS table 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 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.

To Help Prevent This Issue From Reoccuring
1. If you are using the embedded database, be aware that it is bundled for evaluation purposes and does not offer full transactional integrity in the event of sudden power loss, which is why an external database is recommended for production use. You should migrate to an external database. 2. If you are using an older version of Confluence than the latest, you should consider upgrading at this point.
RELATED TOPICS

Document generated by Confluence on Oct 10, 2007 11:54

Page 163

Viewing and Editing License Details
This page last changed on Sep 21, 2007 by smaddox.

The 'License Details' page tells you: • How many users your Confluence instance is licensed to support, and how many are currently registered. Note: The number of registered users only includes users who have 'use Confluence' permission. Deactivated users are not included). 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 licence ° is the same for all servers in a cluster. From Confluence release 2.5.5, the 'License Details' page shows Server ID instead of License ID. To view the details of your Confluence license,

1. Log into Confluence as a user with admin access. 2. Go to the 'Administration Console' and click 'License Details' under the heading 'Administration in the left panel. To look up your license details on the Atlassian website, please login to my.atlassian.com To update your Confluence license,

1. Log into Confluence as a user with admin access. 2. Go to the 'Administration Console' and click 'License Details' under the heading 'Administration in the left panel. 3. 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.) Screenshot : License Details

Document generated by Confluence on Oct 10, 2007 11:54

Page 164

RELATED TOPICS

Apache and Tomcat load balancing Cache Statistics Cluster Administration page Cluster safety mechanism Cluster Troubleshooting

Document generated by Confluence on Oct 10, 2007 11:54

Page 165

Viewing System Information
This page last changed on Jun 25, 2007 by smaddox.

The System Information screen provides information about Confluence's configuration, and the environment in which Confluence has been deployed. Your system configuration information is helpful to us when diagnosing errors you may face using Confluence. If you file a support request or bug report, the more detail you can provide about your installation and environment the faster we will be able to help. To view your system information, go to the 'Administration Console' and click on 'System Configuration'. The handy Memory Graph helps you keep track of Confluence's memory usage.
RELATED TOPICS

Cache Statistics Viewing and Editing License Details Viewing System Information

Document generated by Confluence on Oct 10, 2007 11:54

Page 166

Where Is My ConfluenceHome Directory?
This page last changed on Mar 05, 2004 by vidya.

Often in the documentation, you'll see a reference to the "ConfluenceHome" directory. This is the directory in which Confluence stores its configuration information, search indexes, custom decorators and page attachments. Also, if you're using the embedded HSQL database, the database is also stored in this directory. When Confluence first starts up, it reads a file called confluence-init.properties, which is located inside the confluence/WEB-INF/classes directory under where you unpacked the distribution. This file contains a single line telling Confluence where the ConfluenceHome directory is. If you ever forget where you put your home directory, check confluence-init.properties.

Document generated by Confluence on Oct 10, 2007 11:54

Page 167

Cluster Administration page
This page last changed on Mar 14, 2007 by rosie@atlassian.com.

Overview
Any copy of Confluence which uses a clustered license has a Cluster Administration Page which includes information about the active cluster. 1. Click 'Administration', available at the top-right of every Confluence page. 2. Click 'Cluster Configuration' in the left-hand menu, in the section called 'Clustering'.

Availability
To access this functionality, you must: • be a Confluence site administrator (i.e. have global Administrate Confluence permission) • be using Confluence 2.3 or later • 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:

Document generated by Confluence on Oct 10, 2007 11:54

Page 168

• enable a clustered cache • migrate attachments from file system to the database • publish database connection information so other nodes can join the cluster. All access to Confluence will be locked while this take 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
Confluence Cluster Installation Cluster Troubleshooting

Document generated by Confluence on Oct 10, 2007 11:54

Page 169

Cluster Troubleshooting
This page last changed on Feb 22, 2007 by rosie@atlassian.com.

Symptoms
Below is a list of potential problems with a Confluence cluster, and their likely solutions. The solutions are listed below.

Problem Cluster panic errors at startup Error in log: The interface is not suitable for multicast communication Multicast being sent, but not received (detectable with tcpdump) Any issue not covered here

Likely solutions Add multicast route, Check firewall Change multicast interface, Add multicast route Check firewall, Check intermediate routers, Increase multicast TTL Contact support

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.

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. Captures network traffic on the given interface. Most useful on an interface that only receives cluster traffic.

netstat -rn tcpdump -i interface

Add multicast route
Multicast networking requirements vary across operating systems. Some operating systems require little configuration, while some require the multicast address to be explicitly added to a network interface before Confluence can use it. Usually, adding a route for all multicast traffic to use the correct interface will fix multicast traffic. The example below is for a Ubuntu Linux system:
route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0

To support multiple applications using multicast on different interfaces, you may need to specify a route specific to the Confluence multicast address.

Check firewall
Ensure your firewall allows UDP traffic on the multicast address and port used by Confluence.

Document generated by Confluence on Oct 10, 2007 11:54

Page 170

Change multicast interface
Confluence might have selected the incorrect interface for multicast traffic, which means it cannot connect to other nodes in the cluster. To override the interface used for multicast traffic after initial setup, edit confluence.cfg.xml in the Confluence home directory and add a property (or change the existing one) to select your desired network interface. For example to tell Confluence to use eth1:
<property name="confluence.cluster.interface">eth1</property>

Increase multicast TTL
The multicast time-to-live (TTL) specifies how many hops a multicast packet should be allowed to travel before it is discarded by a router. It should be set to the number of routers in between your clustered nodes: 0 if both are on the same machine, 1 if on two different machines linked by a switch or cable, 2 if on two different machines with one intermediate router, and so on. Create a file in the Confluence home directory called tangosol-coherence-override.xml. Add the following to it, setting the TTL value appropriately (1 is the default):
<?xml version='1.0'?><coherence><cluster-config><multicast-listener><time-to-live systemproperty='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.

Check intermediate routers
Advanced switches and routers have the ability to understand multicast traffic, and route it appropriately. Unfortunately sometimes this functionality doesn't work correctly with the multicast management information (IGMP) published by the operating system running Confluence. If multicast traffic is problematic, try disabling advanced multicast features on switches and routers in between the clustered nodes. These features can prevent multicast traffic being transmitted by certain operating systems. For best results, use the simplest network topology possible for the cluster traffic between the nodes. For two nodes, that means a single network cable. For larger numbers, try using a single high-quality switch.

Advanced Tangosol configuration
If the solution to your problem involves changes to the Tangosol configuration, these changes should not be made to the Confluence configuration in confluence/WEB-INF/classes/. Instead, to ensure your configuration survives upgrades, make your changes via: • Tangosol system properties • creating a tangosol-coherence-override.xml file in the Confluence home directory. Examples of making these changes are shown in the increasing the TTL section.

Didn't find a solution? Contact Atlassian support
We have dedicated staff on hand to support your installation of Confluence. Please follow the instructions for raising a support request and mention that you're having trouble setting up your Confluence cluster.

Document generated by Confluence on Oct 10, 2007 11:54

Page 171

Configuring Confluence
This page last changed on Feb 03, 2006 by vidya.

• Optional Settings ° Attachment Storage Configuration ° Enabling CamelCase Linking ° Enabling Remote APIs ° Enabling Rich Text Editing Option ° Enabling Threaded Comments ° Enabling Trackback ° Making Rich Text Editing default ° WebDAV Configuration • Other Settings ° Configuring Attachment Size ° Configuring Character Encoding ° Configuring HTTP Timeout Settings ° Configuring Indexing Language ° Configuring Jira Issues Icon mappings ° Configuring Number Formats ° Configuring Shortcut Links ° Configuring Time and Date Formats ° Number of Ancestors to Show in Breadcrumbs ° Thumbnail Settings • Site Configuration ° Configuring the Server Base URL ° Configuring the Site Homepage ° Customising Default Space Content ° Editing the Global Logo ° Editing the Site Title ° Editing the Site Welcome Message ° View Space Goes to Browse Space

Document generated by Confluence on Oct 10, 2007 11:54

Page 172

Optional Settings
This page last changed on Feb 01, 2006 by vidya.

• • • • • • • •

Attachment Storage Configuration Enabling CamelCase Linking Enabling Remote APIs Enabling Rich Text Editing Option Enabling Threaded Comments Enabling Trackback Making Rich Text Editing default WebDAV Configuration

Document generated by Confluence on Oct 10, 2007 11:54

Page 173

Attachment Storage Configuration
This page last changed on Jul 02, 2007 by smaddox.

Confluence 2.2 introduces the ability to store Attachments in one of three places: • Filesystem - locally in the Confluence home directory • Database - in Confluence's configured database • WebDAV - remotely on a WebDAV server Local filesystem In the past, Confluence has stored Attachments in the attachments directory within the configured Confluence home folder. This remains the default in version 2.2. Database Confluence 2.2 gives administrators the option to store attachments in the database that Confluence is configured to use. There are a number of reasons why, as an administrator, you may want to choose this storage system: • Ease of backup • Avoid issues with certain characters in attachment filenames 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 of Confluence WebDAV Confluence also allows administrators to set an external WebDAV repository as the location for Attachment storage. Migration between Attachment storage systems An improvement introduced in Confluence 2.2 is the ability to "migrate" between different Attachment storage systems. All existing Attachments will be moved over to the new Attachment storage system. 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 process occurs. Access will be restored as soon as the migration is complete. To perform a migration, follow the steps below: 1. View the 'Administration Console' 2. Click on 'Attachment Storage'. The current configuration will be displayed.

Attachment storage configuration 3. Click on the 'Edit' button to modify the configuration. Select the storage system you desire.

Document generated by Confluence on Oct 10, 2007 11:54

Page 174

Edit attachment storage 4. Click on the 'Save' button to save the changes. 5. A screen will appear, asking you to confirm your changes. Clicking 'Migrate' will take you to a screen that displays the progress of the migration.

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:
log4j.logger.com.atlassian.confluence.pages.persistence.dao=DEBUG,confluencelog log4j.additivity.com.atlassian.confluence.pages.persistence.dao=false log4j.logger.org.apache.webdav=DEBUG,confluencelog log4j.additivity.org.apache.webdav=false
RELATED TOPICS

Attachment Storage Configuration Important Directories and Files WebDAV Configuration

Document generated by Confluence on Oct 10, 2007 11:54

Page 175

Enabling CamelCase Linking
This page last changed on Jun 25, 2007 by smaddox.

CamelCase linking is a form of markup used in many wikis where words capitalized and compounded together without spaces 'LikeThis', are used to create links. By default, CamelCasing is not enabled in Confluence. To use CamelCasing, a site administrator will need to enable this option from the 'Administration Console'. To enable CamelCasing,

1. 2. 3. 4.

From the 'Administration Console' click on 'General Configuration' in the left panel. This will display the 'Options and Settings' screen. Click 'Edit'. Select 'On' beside 'Camelcasing'. Click 'Save'.

RELATED TOPICS

Attachment Storage Configuration Enabling CamelCase Linking Enabling Remote APIs Enabling Rich Text Editing Option Enabling Threaded Comments [!Administration Guide Attachments directory^adminhome.gif!]

Document generated by Confluence on Oct 10, 2007 11:54

Page 176

Enabling Remote APIs
This page last changed on Jun 25, 2007 by smaddox.

Confluence provides XML-RPC and SOAP remote APIs. A site administrator will need to enable the APIs from the Administration Console before you can access Confluence remotely. To enable the Remote API,

1. 2. 3. 4.

Go to the 'Administration Console' and click on 'General Configuration' in the left panel. Click 'Edit' at the bottom of the 'Options and Settings' screen. Select 'On' beside 'Remote API'. 'Save' your changes.

RELATED TOPICS

Remote API Specification RPC Plugins Confluencer.NET

Document generated by Confluence on Oct 10, 2007 11:54

Page 177

Enabling Rich Text Editing Option
This page last changed on Jun 25, 2007 by smaddox.

With Confluence 2.0 and later versions, users have the option of using the Rich Text editor to create pages. By default, this is set to 'On'. If desired, a site administrator can disable 'Rich Text Editing' from the Administration Console. To disable Rich Text editing,

1. 2. 3. 4.

Go to the Administration Console, click on 'General Configuration' in the left panel. In the 'Options and Settings' screen, click 'Edit'. Select 'Off' beside 'Rich Text Editing'. Click 'Save'.

RELATED TOPICS

Enabling Rich Text Editing Option Making Rich Text Editing default Rich Text Editor Overview

Document generated by Confluence on Oct 10, 2007 11:54

Page 178

Enabling Threaded Comments
This page last changed on Jun 25, 2007 by smaddox.

Comments on pages or news items are displayed in one of two views: • Threaded: Shows the comments in a hierarchy of responses. Each subsequent 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 Flat mode. To enable or disable the 'threaded view',

1. 2. 3. 4.

Go to the 'Administration Console', click on 'General Configuration' in the left panel. In the 'Options and Settings' screen, click 'Edit'. Select "On'beside 'Threaded Comments'. Click 'Save'.

RELATED TOPICS

Commenting on a Page Viewing Comments

Document generated by Confluence on Oct 10, 2007 11:54

Page 179

Enabling Trackback
This page last changed on Jun 25, 2007 by smaddox.

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 'Administration Console', click on 'General Configuration' in the left panel. 2. In the 'Feature Settings' screen, click 'Edit'. 3. Select "On' beside 'Trackback' and click 'Save'.
RELATED TOPICS

Attachment Storage Configuration Enabling CamelCase Linking

Document generated by Confluence on Oct 10, 2007 11:54

Page 180

Making Rich Text Editing default
This page last changed on Jun 25, 2007 by smaddox.

A site administrator can configure whether the default mode of editing on the site is 'Rich Text' or 'Wiki Markup'. Users will still be able to configure their individual preferences from the 'Edit' tab of a page. To Make Rich Text Editing Default,

1. From the 'Administration Console' click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. 3. Select 'On' beside 'Users see rich text editor by default'. Select 'Off' to make 'Wiki Markup' editing default. 4. Click 'Save'.
RELATED TOPICS

Enabling Rich Text Editing Option Making Rich Text Editing default Rich Text Editor Overview [!Administration Guide Attachments directory^adminhome.gif!]

Document generated by Confluence on Oct 10, 2007 11:54

Page 181

WebDAV Configuration
This page last changed on Jul 02, 2007 by smaddox.

WebDAV allows users to access Confluence content via a WebDAV client, such as 'My Network Places' in Microsoft Windows. Provided that the user has permission, they will be able to read and write to spaces, pages and attachments in Confluence. They will be asked to log in, and the standard Confluence permissions apply. On the 'WebDav Configuration' page, you can: • allow/disallow specific actions on pages and attachments via WebDAV. The configurable actions are: create/move, edit and delete. • enable/disable access to specific virtual files/folders. • The 'WebDav Configuration' page will only be available if the WebDAV plugin has been enabled (see Installing and Configuring Plugins using the Plugin Repository). • The settings on the 'WebDav Configuration' page do not apply to external attachment storage configuration. To configure WebDAV options for pages and attachments ,

1. Go to the 'Administration Console'. 2. Click 'WebDav Configuration' under 'Configuration' in the left panel. The 'WebDAV Configuration' page is displayed. 3. Check or uncheck the options in the 'Permissions' section as required. 4. Check or uncheck the options in the 'Virtual Files and Folders' section as required. 5. Click the 'Save' button. Screenshot: WebDAV configuration

RELATED TOPICS

Attachment Storage Configuration(Confluence 2.6) Important Directories and Files(Confluence 2.6) WebDAV Configuration(Confluence 2.6) WebDAV Plugin(Confluence Extension)

Document generated by Confluence on Oct 10, 2007 11:54

Page 182

Document generated by Confluence on Oct 10, 2007 11:54

Page 183

Other Settings
This page last changed on Feb 01, 2006 by vidya.

• • • • • • • • • •

Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Jira Issues Icon mappings Configuring Number Formats Configuring Shortcut Links Configuring Time and Date Formats Number of Ancestors to Show in Breadcrumbs Thumbnail Settings

Document generated by Confluence on Oct 10, 2007 11:54

Page 184

Configuring Attachment Size
This page last changed on Jun 25, 2007 by smaddox.

Confluence gives you the option of limiting the maximum size of a single file attachment. Site administrators should keep in mind that the amount of disk space used by Confluence is directly proportional to the number and size of attachments put into the system. To configure the maximum size of an attachment,

1. 2. 3. 4.

Go to the 'Administration Console' and click on 'General Configuration' in the left panel. Click 'Edit' at the bottom of the 'Options and Settings' screen. Beside 'Attachment Maximum Size', enter the maximum size. The default is 10 mb. 'Save' your changes.

RELATED TOPICS

Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats

Document generated by Confluence on Oct 10, 2007 11:54

Page 185

Configuring Character Encoding
This page last changed on Jun 25, 2007 by smaddox.

Confluence uses UTF-8 character encoding to deliver its pages. While it is possible to change the character encoding, unless you are certain of what you are doing, we recommend that you leave this as it is. To change the character encoding,

1. 2. 3. 4.

Go to the 'Administration Console' and click on 'General Configuration' in the left panel. Click 'Edit' at the bottom of the 'Options and Settings' screen. Beside 'Encoding', enter the new character encoding of your choice. '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

Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats

Document generated by Confluence on Oct 10, 2007 11:54

Page 186

Configuring HTTP Timeout Settings
This page last changed on Aug 07, 2006 by tom@atlassian.com.

This feature is available in 2.2.8 and later versions of Confluence When macros such as the RSS macro, the Calendar macro or the Repository Client Plugin make HTTP requests to servers which are down, a long timeout value is used. You can set this timeout value through a system parameter to avoid this. If you are using Tomcat, you can add this to the catalina.bat/sh file:
JAVA_OPTS=-Dhttp.timeout=timeInSecondsHere

Document generated by Confluence on Oct 10, 2007 11:54

Page 187

Configuring Indexing Language
This page last changed on Jun 25, 2007 by smaddox.

Changing the Indexing Language setting may improve the accuracy of Confluence search results if the majority of the content of your site is in some language other than English. Since Confluence v. 2.2.5, the content indexing support is provided in German, Russian, Chinese, CJK, French, Brazilian, Czech and Greek besides English (default). To configure a different indexing language,

1. 2. 3. 4.

Go to the 'Administration Console' and click on 'General Configuration' in the left panel. Click 'Edit' on the right hands side of the 'Formatting and International Settings' section. There is a drop-down list of 'Indexing Language' currently supported in Confluence. 'Save' your changes.

RELATED TOPICS

Configuring Indexing Language Content Index Administration Working with Macros

Document generated by Confluence on Oct 10, 2007 11:54

Page 188

Configuring Jira Issues Icon mappings
This page last changed on Jun 25, 2007 by smaddox.

If you are using the {jiraissues} macro to retrieve information from a JIRA server, you will have to tell Confluence where to find the icons for any custom statuses or issue types you have configured in JIRA. Confluence is configured by default with all JIRA's standard issue type and status icons. You will only need to change these settings if you have customised additional statuses or issue types for JIRA or have changed JIRA's default icons. To configure custom icons,

1. Go to the 'Administration Console' and click on 'Jira Issue Icon Mappings' in the left panel. 2. For each icon you wish to configure, enter the name of the issue type or status into the Jira entity field, and the filename of its icon into the filename field. Ensure that the icon with that filename is located in the /images/icons directory of the JIRA server. 3. You may edit existing icon mappings by clicking on the remove link by an existing mapping, then readding it with a new icon filename.
RELATED TOPICS

Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats

Document generated by Confluence on Oct 10, 2007 11:54

Page 189

Configuring Number Formats
This page last changed on Jun 25, 2007 by smaddox.

To change the number formats,

1. Go to the 'Administration Console' and click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. • There are two number format settings: ° Long Number Format ° Decimal Number Format 3. Change the formats using the guidelines in this document. 4. 'Save' your changes.
RELATED TOPICS

Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats

Document generated by Confluence on Oct 10, 2007 11:54

Page 190

Configuring Shortcut Links
This page last changed on Jan 03, 2007 by mryall.

Shortcut links provide a quick way of linking to resources frequently referenced from Confluence. When you create a shortcut link, you are assigning a key to a url so that when a user edits Confluence documents they can type the key instead of the complete url. Here is an example: Most Google searches look like this: http://www.google.com/search?q=. If you create a shortcut for this search with the key 'google', every time a user needs to use http://www.google.com/search? q=searchterms, they can just type [searchterms@google] instead. Here is a screenshot showing the shortcuts currently defined on http://confluence.atlassian.com:

Shortcut links are added and maintained by site administrators from the Administration Console. To create a shortcut link,

1. Go to the 'Administration Console' and click on 'Shortcut Links' in the left panel. 2. Enter a 'Key' for your shortcut. This is the shortcut name a user will use to reference the url. 3. Enter the 'Expanded Value'. This is the url for the link. You can use '%s' in the URL to specify where the user's input is inserted. If there is no '%s' in the URL, the user's input will be put at the end. 4. (Optional. Available in Confluence version 2.3 and later.) Enter a 'Default Alias'. This is the text of the link which will be displayed on the page where the shortcut is used, with the user's text being substituted for '%s'. 5. Click 'Save'.

Using Shortcut Links Simply specify in the link what should go on the end of the shortcut URL, followed by an at-sign and the key of the shortcut. Shortcut names are case-insensitive. So, for example, using the keys shown in the above screenshot:

To link to... a JIRA issue

Type this [CONF-1000@JIRA]

Resulting URL

Demonstration

http:// CONF-1000 jira.atlassian.com/ secure/ QuickSearch.jspa? searchString=CONF-1000 http:// www.google.com/ search?q=Atlassian +Confluence Atlassian Confluence@Google

a Google search

[Atlassian Confluence@Google]

Shortcut links can have titles just like any other link:

Document generated by Confluence on Oct 10, 2007 11:54

Page 191

To link to... Internet Movie Database Google Cache

Type this [Fight Club| tt0137523@IMDB]

Resulting URL http://us.imdb.com/ Title?tt0137523

Demonstration Fight Club

[Cached Homepage| http:// Cached Homepage www.atlassian.com@cache] www.google.com/ search? q=cache:www.atlassian.com

Deleting Shortcut Links Once you create a shortcut link, it is listed under 'Shortcut Links' in the 'Administration Console'. Click 'Remove' to delete the shortcut.
RELATED TOPICS

Document generated by Confluence on Oct 10, 2007 11:54

Page 192

Configuring Time and Date Formats
This page last changed on Jun 25, 2007 by smaddox.

Confluence allows you to localise the formats used to display dates and times within the web interface. The settings use the syntax of Java's SimpleDateFormat class (described below). To change the time and date formats,

1. Go to the 'Administration Console' and click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. • There are three time and date format settings: ° Time Format : displaying only the time of day (for example, when each news item is posted) ° Date Time Format : displaying both the date and the time of day (for example, in historical versions of pages) ° Date Format : displaying only the date (for example, the creation and most recent modification dates of pages) 3. Change the formats using the guidelines in this document. 4. 'Save' your changes.
RELATED LINKS

• Java 1.4.2 SimpleDateFormat API
RELATED TOPICS

Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats

Document generated by Confluence on Oct 10, 2007 11:54

Page 193

Number of Ancestors to Show in Breadcrumbs
This page last changed on Jun 25, 2007 by smaddox.

Whenever there are three or more page links to be displayed in the breadcrumbs, Confluence will use an ellipsis like this '...' and display only the topmost and lowermost page links. Clicking on the ellipsis will display the page links in between. Note that the Dashboard and space homepage links are always displayed at the start of the breadcrumbs, and are not counted as ancestors for the purpose of this setting. Screenshot: Breadcrumbs

You can configure how many immediate ancestors you want displayed in the breadcrumbs when you go to the page. To configure the number of ancestors to show in the breadcrumbs,

1. Go to the 'Administration Console' and click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. 3. Beside 'Number of Ancestors to show in Breadcrumbs', enter a number. For example, if you enter 2, two immediate ancestors for the page will be displayed following the dots. 4. 'Save' your changes.

Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats

Document generated by Confluence on Oct 10, 2007 11:54

Page 194

Thumbnail Settings
This page last changed on Jun 25, 2007 by smaddox.

The thumbnail settings allow you to define the height and width of images when they are displayed as thumbnails. To configure thumbnail settings,

1. Go to the 'Administration Console' and click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. 3. Under the heading 'Thumbnail Settings', enter a value in pixels for: • Maximum Height: 200 pixels by default. • Maximum Width: 200 pixels by default. 4. 'Save' your changes.

RELATED TOPICS

Gallery Macro Thumbnail Macro Uploading a Profile Picture

Document generated by Confluence on Oct 10, 2007 11:54

Page 195

Site Configuration
This page last changed on Feb 01, 2006 by vidya.

• • • • • • •

Configuring the Server Base URL Configuring the Site Homepage Customising Default Space Content Editing the Global Logo Editing the Site Title Editing the Site Welcome Message View Space Goes to Browse Space

Document generated by Confluence on Oct 10, 2007 11:54

Page 196

Configuring the Server Base URL
This page last changed on Jun 25, 2007 by smaddox.

The Server Base URL is the url via which users access Confluence. The base url must be set to the same URL by which browsers will be viewing your Confluence site. Confluence will autodetect the base url during setup, but you may need to set it manually if your site's URL changes, or if you set up Confluence from a different URL to the one that will be used to access it publicly. To configure the Server Base Url,

1. 2. 3. 4. .

Go to the 'Administration Console' and click on 'General Configuration' in the left panel. Click 'Edit' at the bottom of the 'Options and Settings' screen. Beside 'Server Base URL', enter the new url. 'Save' your changes.

Warning 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.
RELATED TOPICS

Configuring the Server Base URL Configuring the Site Homepage Customising Default Space Content Editing the Global Logo Editing the Site Title

Document generated by Confluence on Oct 10, 2007 11:54

Page 197

Configuring the Site Homepage
This page last changed on Jun 25, 2007 by smaddox.

You can configure Confluence to direct users to any of the space homepages on the site when they login, rather than to the Dashboard. To configure the site-wide homepage,

1. Go to the 'Administration Console' and click 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. 3. Select the space you want to set as homepage from the 'Set Homepage' drop-down menu . Ensure that the 'View Space Goes to Browse Space' setting is set to 'OFF' if you want users to be sent to the space homepage and not the summary page The spaces available to be set as your homepage will depend on the access permissions of the space and the site. • If your site allows anonymous access, the site homepage must also be anonymously accessible. • If your site does not allow anonymous access, the site homepage must be accessible to the 'confluence-users' group. Screenshot : Configuring the site homepage

RELATED TOPICS

Configuring the Server Base URL Configuring the Site Homepage Customising Default Space Content Editing the Global Logo Editing the Site Title

Document generated by Confluence on Oct 10, 2007 11:54

Page 198

Customising Default Space Content
This page last changed on Sep 27, 2007 by smaddox.

Site administrators can define default content for a space home page. This content will appear on the home page whenever someone adds a new space. You can define different content for global spaces and for personal spaces. Notes: • The default content will appear only for new spaces created after you have defined the content. Content in existing home pages will not be changed. • Confluence will replace the text '{0}' with the space name. To define default content for home pages in global 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. Enter the content which you want to appear on the home page for new global spaces. 3. Click the 'Save' button. 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. 4. Click the 'Save' button. To undo your most recent changes,

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.

Screenshot : Defining default space content

Document generated by Confluence on Oct 10, 2007 11:54

Page 199

RELATED TOPICS

Configuring the Server Base URL Configuring the Site Homepage Customising Default Space Content Editing the Global Logo Editing the Site Title

Document generated by Confluence on Oct 10, 2007 11:54

Page 200

Editing the Global Logo
This page last changed on Jun 25, 2007 by smaddox.

By default, the global logo appears beside the page title on all pages in the site. You can disable the logo or replace it with one of your own. To edit the global logo,

1. From the 'Administration Console' click on 'Global logo' under the heading 'Look and Feel' in the left panel. 2. In the screen displayed, select 'Off' to disable logo. 3. To upload a new logo, click 'Browse' to select a new image and click 'Upload Logo'.

RELATED TOPICS

Configuring the Server Base URL Configuring the Site Homepage Customising Default Space Content Editing the Global Logo Editing the Site Title

Document generated by Confluence on Oct 10, 2007 11:54

Page 201

Editing the Site Title
This page last changed on Jun 25, 2007 by smaddox.

The site title appears in your browser's title bar. By default, it is set to 'Confluence'. To change the title of your Confluence instance,

1. Go to the 'Administration Console' and click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. 3. Enter a new title for your site in the input field beside 'Site Title' and 'Save'.

RELATED TOPICS

Configuring the Server Base URL Configuring the Site Homepage Customising Default Space Content Editing the Global Logo Editing the Site Title

Document generated by Confluence on Oct 10, 2007 11:54

Page 202

Editing the Site Welcome Message
This page last changed on Jun 25, 2007 by smaddox.

The site welcome message appears on the Dashboard. It can be used to provide users with an introduction of the site, or as a "message of the day". To edit the site welcome message,

1. Go to the 'Administration Console' and click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen.. 3. In the text-entry box beside 'Site Welcome Message' enter your text using regular Confluence markup. 4. 'Save' your changes.

RELATED TOPICS

Configuring the Server Base URL Configuring the Site Homepage Customising Default Space Content Editing the Global Logo Editing the Site Title

Document generated by Confluence on Oct 10, 2007 11:54

Page 203

View Space Goes to Browse Space
This page last changed on Jun 25, 2007 by smaddox.

By default, when you click on a space link, you are taken to the space's homepage. If you wish, you can configure Confluence to redirect all space links on the site to the 'Browse Space' view of the space instead. To direct the space link to the 'browse space' view,

1. Go to the 'Administration Console' click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. . 3. Select 'ON' beside 'View Space goes to Browse Space' and click 'Save'.

RELATED TOPICS

Configuring the Server Base URL Configuring the Site Homepage Customising Default Space Content Editing the Global Logo Editing the Site Title

Document generated by Confluence on Oct 10, 2007 11:54

Page 204

Configuring Encoding
This page last changed on Apr 10, 2007 by mjensen.

Confluence allows the configuration of which character encoding is used to deliver pages. 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.

Document generated by Confluence on Oct 10, 2007 11:54

Page 205

Troubleshooting Character Encodings
This page last changed on Jul 19, 2007 by ivan@atlassian.com.

Often users may have problems with certain characters in a Confluence instance. Symptoms may include: • • • • Non-ASCII characters appearing as question marks (?) Page links with non-ASCII characters not working Single characters being displayed as two characters Garbled text appearing

In most cases, it is due to a mis-configuration in one of the components that Confluence uses. Follow these steps to diagnose the problem:

1. Run the encoding test
Confluence includes an encoding test that can reveal problems with your configuration. To perform the test, view the /admin/encodingtest.action page on your 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. Example:
http://confluence.atlassian.com/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. A successful test looks like the following:

MySQL 3.x

Document generated by Confluence on Oct 10, 2007 11:54

Page 206

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.

2. Ensure the same encoding is used across all components
As mentioned in the Configuring Encoding document, the same character encoding should be used across the database, application server and web application (Confluence). • To change the character encoding used in Confluence, see Configuring Character Encoding. • To change the character encoding used in the application server, please ensure you set the Application Server URL encoding and view your application server's documentation on any other settings required to enable your encoding. • To change the character encoding used in the database, see Configuring Database Character Encoding.

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

Document generated by Confluence on Oct 10, 2007 11:54

Page 207

"€" Euro character
This page last changed on Sep 18, 2006 by cmiller.

The € (euro) symbol is a three byte character, with byte values in file (UTF-8) of 0xE2, 0x82, 0xAC. Sometimes, if the character encoding is not set consistently among all participating entities of the system, Confluence, server and the database, one may experience strange behaviour. ... I write a page with a Euro sign in it (€). All is well, the Euro sign shows up in the wiki markup text-box, and the preview, and the display of the saved page. One day later, the Euro sign has changed into a question mark upside down! ... What is going on? Why does the Euro sign mysteriously change? How do I prevent it? Interestingly enough the character encoding test passes with no problems, demonstrating that Confluence and the connected Database both recognise the € symbol. There are two potential reasons for this behaviour: Database and Confluence is using utf-8 encoding. The connection is not. When data transferred to it via the connection which does not use utf-8 encoding gets encoded incorrectly. Hence, updating the connection encoding may resolve this problem from now on, yet it probably would not affect already existing data. Database is not using utf-8. Confluence and your connection are. If your Database encoding is not set to UTF-8, yet is using some other encoding such as latin1, it could be one of the potential reasons why you lose the "€" characters at some stage. It could be occurring due to caching. When Confluence saves data to the database, it may also keep a local cached copy. If the database encoding is set incorrectly, the Euro character may not be correctly recorded in the database, but Confluence will continue to use its cached copy of that data (which is encoded correctly). The encoding error will only be noticed when the cache expires, and the incorrectly encoded data is fetched from the database.

For instance the latin1 encoding would store and display all 2-byte UTF8 characters correctly except for the euro character which is replaced by '?' before being stored. As Confluence's encoding was set to UTF-8, the 2-byte UTF-8 characters were stored in latin1 database assuming that they were two latin1 different characters, instead of one utf8 character. Nevertheless, this is not the case for 3-byte utf8 characters, such as the Euro symbol. Please ensure that you set the character encoding to UTF-8 for all the entities of your system as advised in this guide.

Document generated by Confluence on Oct 10, 2007 11:54

Page 208

MySQL 3.x Character Encoding Problems
This page last changed on Mar 22, 2006 by jeremy@atlassian.com.

MySQL 3.x is known to have some problems upper- and lower-casing certain (non-ASCII) characters.

Diagnosing the problem
1. Follow the instructions for Troubleshooting Character Encodings. 2. If the upper- and lower-cased strings displayed on the Encoding Test are different, then your database is probably affected. An example (faulty) output of the Encoding Test is shown below:

Solution
Upgrade to a newer version of MySQL. (4.1 is confirmed to work.)

Document generated by Confluence on Oct 10, 2007 11:54

Page 209

Configuring Mail
This page last changed on Feb 03, 2006 by vidya.

• Configuring a Server for Outgoing Mail • Enabling the 'Mail Page' plugin • The Mail Queue

Document generated by Confluence on Oct 10, 2007 11:54

Page 210

Configuring a Server for Outgoing Mail
This page last changed on Jun 25, 2007 by smaddox.

Configuring your Confluence server to send outgoing mail allows Confluence users to: • receive Daily Reports • send a page via email To configure Confluence Standalone to send outgoing mail,

1. Go to the 'Administration Console' and click 'Mail Servers' under 'Configuration' in the left panel. This will list all currently configured SMTP servers. 2. Click 'Add New SMTP Server' (or edit an existing server) • Name: By default, this is set to 'SMTP Server'. • From: Enter the email id that will be displayed in the 'from' field for email messages originating from this server. • Subject Prefix: Enter a subject prefix, if required. 3. Configuring the Host Address, Username and Password. • Manually enter your 'Host Address', 'Username' 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 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. javamail-x.x.x.jar 2. activation-x.x.x.jar 3. mail-x.x.x.jar Ideally, these should be: • javamail-1.3.2.jar • activation-1.0.2.jar • mail-1.3.2.jar You will then need to move these into the proper directory: Standalone Version Please move the above three jar files from thee confluence/WEB-INF/lib directory to the common/lib directory and restart Confluence. EAR/WAR Version

To Be Confirmed
RELATED TOPICS

Configuring a Server for Outgoing Mail Enabling the 'Mail Page' plugin The Mail Queue

Document generated by Confluence on Oct 10, 2007 11:54

Page 211

Enabling the 'Mail Page' plugin
This page last changed on Jun 25, 2007 by smaddox.

The 'Mail Page' plugin allows anyone with the 'View' space permission to email a Confluence page. Confluence versions 2.4 and later come with the 'Mail Page' plugin preinstalled. The 'Mail Page' plugin is disabled by default. This is because, when someone emails a Confluence page, they can select from a list of all Confluence users and groups (note, however, that email addresses are not visible), or even mail the page to arbitrary addresses. If you have enabled anonymous access or self-signup, visitors could potentially use this feature to send spam or nuisance email through your Confluence server. Please note that this plugin only works when the mail server is configured. To enable the 'Mail Page' plugin,

1. Go to the 'Administration Console' and click 'Plugins' (under 'Configuration' in the left panel). 2. This will list all plugins that are currently installed in your Confluence system. Click 'Mail Page Plugin'. 3. This will display the 'Mail Page Plugin' details. To enable the 'Mail Page' plugin, click 'Enable plugin'. 4. Ensure that both of the following are enabled: • 'Mail Page Link' — displays the 'E-mail' link next to the 'Copy' link on the 'Page Info' screen (see 'Emailing a page') • 'mailpageactions' — enables the e-mail operation to be performed.
RELATED TOPICS

Configuring a Server for Outgoing Mail Enabling the 'Mail Page' plugin The Mail Queue

Document generated by Confluence on Oct 10, 2007 11:54

Page 212

The Mail Queue
This page last changed on Jun 25, 2007 by smaddox.

Email messages waiting to be sent out are queued in a 'Mail Queue' and periodically flushed from Confluence once a minute. A site administrator can also manually flush emails from the mail queue. If there is an error sending messages, the failed emails are sent to an 'Error Queue' from which you can either try to resend them or delete them. To view the mail queue,

1. Go to the 'Administration Console' and click on 'Mail Queue' in the left panel. This will display the emails currently in the queue. 2. Click 'Flush Mail Queue' to send all emails immediately. 3. 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

Configuring a Server for Outgoing Mail Enabling the 'Mail Page' plugin The Mail Queue
RELATED TOPICS

Document generated by Confluence on Oct 10, 2007 11:54

Page 213

Confluence and JIRA
This page last changed on Feb 02, 2006 by vidya.

• Add Confluence EAR-WAR to JIRA Standalone • Integrating JIRA and Confluence • Override properties in JIRA to Confluence Bridge

Document generated by Confluence on Oct 10, 2007 11:54

Page 214

Add Confluence EAR-WAR to JIRA Standalone
This page last changed on Mar 16, 2007 by david.soul@atlassian.com.

This document will assist you in adding Confluence to your existing JIRA Standalone.

Step 0 - Consider alternatives
This guide is for experts only. If you run into any difficulties with this process, Atlassian technical support may provide limited assistance outside of helping users switch to running Confluence Standalone separately. Before embarking on this process, consider whether you could not rather run JIRA and Confluence in separate Tomcat instances running behind an Apache frontend server (see guides for Confluence and JIRA). There are some benefits to keeping them separate: • Each app can be restarted without affecting the other. • If one webapp hangs for any reason (eg. running out of memory), it doesn't affect the other. • Any problems can be debugged more easily. Logs are separate and product-specific, rather than everything going to catalina.out. Thread and heap dumps are smaller and more relevant. • It reduces the likelihood of jar conflicts (eg. jars that must be installed in common/lib), particularly if you later want to install a third webapp not from Atlassian. Offsetting this is the extra complexity of having to run Apache. If you wish to proceed, please follow these instructions:

Step 1 - Download and extract WAR
1. Download the Confluence WAR file 2. Extract the downloaded zip file. It should extract to a folder called confluence-<version>. Inside this folder you'll find a folder called "confluence". Make a note of the absolute path to this directory (as you will need to use it later). Note: Do not copy the confluence folder to the webapps folder inside tomcat - this may cause Confluence to be deployed more than once.

Step 2 - Configure confluence-init.properties
1. Open confluence/WEB-INF/classes/confluence-init.properties in a text editor 2. Set the confluence.home property to a directory of your choosing. This is the directory that will contain all of Confluence's configuration, backup and attachment files.

Step 3 - Edit tomcat context descriptors
If you are deploying to JIRA version 3.3 or higher: 1. Create a file called confluence.xml in your JIRA standalone's conf/Catalina/localhost directory (if you have set up a different hostname for your JIRA tomcat instance, please specify that instead of localhost) 2. Open confluence.xml and add these lines:
<Context path="/confluence" docBase="c:/applications/confluence-2.1.3/confluence" debug="0" reloadable="true"><Logger className="org.apache.catalina.logger.FileLogger" prefix="atlassianconfluence." suffix=".log" timestamp="true"/></Context>

3.

For docBase specify the value you noted down earlier. This is the full path to the confluence folder in your confluence-<version> installation folder, not the confluence home folder. It should look like: c:/<path to confluence installation>/confluence-<version>/confluence.

Otherwise (for older versions of JIRA): 1. Open conf/server.xml in a text editor 2. Find the block that begins: <Context path="" docBase="../atlassian-jira" debug="0" reloadable="true"> and ends with </Context> block. 3. After the </Context>, append the following:

Document generated by Confluence on Oct 10, 2007 11:54

Page 215

<Context path="/confluence" docBase="c:/applications/confluence-2.1.3/confluence" debug="0" reloadable="true"><Logger className="org.apache.catalina.logger.FileLogger" prefix="atlassianconfluence." suffix=".log" timestamp="true"/></Context>

4.

For docBase specify the value you noted down earlier. This is the full path to the confluence folder in your confluence-<version> installation folder, not the confluence home folder. It should look like: c:/<path to confluence installation>/confluence-<version>/confluence. 5. Remove the commons-logging-1.0.4.jar file from the confluence\WEB-INF\lib directory Do not delete the existing Jira <Context> block. Insert the code above after the Jira <Context> block.

Step 4 - Modify your setenv.sh/bat (ONLY IF YOU ARE RUNNING A SUN MICROSYSTEMS JVM)
1. Open JIRA's bin/setenv.sh/bat (.sh on unix, .bat on windows) in a text editor. 2. Find the line that says: "... JAVA_OPTS=... " and add -XX:MaxPermSize=128m to its end. The Java Virtual Machine sets aside a portion of memory as the "permanent space", for objects that it never expects to have to garbage-collect. Because JIRA and Confluence are both quite large applications, it is possible that this permanent space will be filled up. Increasing the application heap size will not help, because the permanent generation size is a separate setting. This flag is only supported on JVM's created by Sun Microsystems. If you include this flag while running another vendors JVM (such as JRocket, or IBM's JVM) they will not start.

Step 5 - Restart the Server
1. Shut down, and then restart the standalone server 2. Confluence should now be accessible on the same server as your existing JIRA standalone, under the confluence directory. For example, if your JIRA is running at http://jira.example.org:8080/, Confluence will be running on http://jira.example.org:8080/confluencereuse When setting up the Confluence database do not reuse the JIRA database. Create a new database for Confluence.

Troubleshooting
When I try to send a test mail from Confluence, I getjavax.mail.NoSuchProviderException: smtp In some circumstances, Confluence will be unable to send email after being deployed in the same application-server as JIRA. If, when you try to send a test mail from the administration tool, you get the error: "javax.mail.NoSuchProviderException: smtp", please follow these instructions to fix it. I have installed JIRA and Confluence in some other application server than Tomcat These instructions only apply to the standalone Tomcat version of JIRA. Other application servers have not been tested in this configuration, and users have specifically reported difficulties deploying the two applications together in Orion Server and JBoss. We hope to resolve these issues soon. Confluence is slow, and dumps enormous amounts of information to its logfiles If you are seeing a large amount of DEBUG logging output, then ensure that you have removed the commons-logging-1.0.4.jar file from the confluence\WEB-INF\lib directory

Document generated by Confluence on Oct 10, 2007 11:54

Page 216

Integrating JIRA and Confluence
This page last changed on Oct 05, 2007 by smaddox.

If you are looking for a technical guide to the process, see Add Confluence EAR-WAR to JIRA Standalone JIRA and Confluence were designed to complement each other. We've all seen projects where people try to store all their knowledge in the issue tracker, and we've seen projects where people have suffered trying to track issues in a knowledge management tool. We say: collect your team's thoughts, plans and knowledge in Confluence, track your issues in JIRA, and let the two applications work together to help you get your job done. Here are four ways you can get JIRA and Confluence working together: use Confluence shortcuts to make easy links to JIRA issues, use trackback for two-way linking between Confluence and JIRA, use macros to include JIRA reports in Confluence pages, and integrate your JIRA and Confluence user management.

Combine Confluence Shortcuts and JIRA Quick Search
The simplest ideas can often be the most useful. In our Confluence site's global configuration Administration > Shorcut Links, we have the following shortcut defined:
JIRA: http://jira.atlassian.com/secure/QuickSearch.jspa?searchString=

This way, it's simple to create links using Confluence's shortcut notation. Link directly to JIRA issues: CONF-1000, or use JIRA's intuitive quick-search functionality to create links to particular groups of issue: CONF open improvements will link to a list of all open issues in the Confluence project of type "Improvement" (try it and see!)

Use Trackback for easy two-way linking
Activate Trackback in JIRA and Confluence, and if someone makes a link from one application to the other, the link will automatically lead both ways: create a link from a JIRA issue to an example in a Confluence page, and the Confluence page will automatically know to link back to the JIRA issue, and vice versa. This is the perfect way to keep discussion connected to an issue. • Document your user stories or use-cases in Confluence, and see at a glance which issues affect each use-case. • If a JIRA issue requires more discussion or thought than can be conveniently held in comments, link them to a Confluence page. (Note: as of Confluence 1.0 and JIRA 2.6, there is no mechanism for trackback to log in to JIRA or Confluence, so the use of trackback is limited to pages that are visible to anonymous visitors. In a protected Intranet environment, you may wish to open up Anonymous access to JIRA and Confluence to

Document generated by Confluence on Oct 10, 2007 11:54

Page 217

allow trackback to take place. Future revisions of the applications will give you the opportunity to allow Confluence to "log in" to JIRA and vice versa, avoiding this limitation)

Use the {jiraissues} macro to embed JIRA reports into your Confluence site
Any JIRA search-result can be embedded in a Confluence page using the {jiraissues} macro with your choice of included fields and field ordering. This way you can incorporate information from JIRA into the normal flow of your knowledge management. Combined with other macros like {junitreport}, {rss} and {html-include} and the FatCow suite, you can create dashboards in Confluence consolidating information from across your project, with Confluence and JIRA at the centre.

Link to Confluence pages from JIRA issues
While it is possible to simply paste links to Confluence pages into text fields of an issue (e.g. descriptions), the JIRA Linker Plugin provides a custom field that helps you find the correct page.

Integrate JIRA and Confluence user-management
To save you having to enter users into both JIRA and Confluence, you may benefit from using Atlassian Crowd as the user-repository for both applications. Alternatively you can configure Confluence to use JIRA's user database (this requires that you are using JIRA with an external database; it will not work if you are using JIRA with an embedded HSQL database).

And much more coming...
When you buy a license for JIRA or Confluence, you are automatically entitled to a year of updates. We listen to our customers needs, and having our products complement and work well with each other is very important to us. So if there is any way you think Confluence and JIRA could be made to work better, suggest it in our discussion space, and it may very well end up in a future version.

Document generated by Confluence on Oct 10, 2007 11:54

Page 218

Override properties in JIRA to Confluence Bridge
This page last changed on May 11, 2005 by vidya.

Overriding properties used in the JIRA and Confluence Bridge If, for some reason, you need to override the name of a column or a table used in Confluence's bridge to JIRA, you may do so in osuser.xml (see below). This is most likely something you would consider doing if columns names were failing because your database is case sensitive.
<provider class="bucket.user.providers.CachingCredentialsProvider"><property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcCredentialsProvider</ property><property name="chain.datasource">java:comp/env/jdbc/JiraDS</property></ provider><provider class="bucket.user.providers.CachingAccessProvider"><property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcAccessProvider</ property><property name="chain.datasource">java:comp/env/jdbc/JiraDS</property></ provider><provider class="bucket.user.providers.CachingProfileProvider"><property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcProfileProvider</ property><property name="chain.datasource">java:comp/env/jdbc/JiraDS</property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property></ provider>

Simply add the <property name="chain.PROPERTY_NAME_HERE">NEW_VALUE</property> element, to override a property (see below) with a new value. Name Value Pairs for JiraJdbcAccessProvider, JiraJdbcProfileProvider and JiraJdbcCredentialsProvider

Property userTable userName userPassword groupTable groupName membershipTable membershipUserName membershipGroupName userId membershipId

Default value userbase userName password_hash groupbase groupname membershipbase user_name group_name id userId

Document generated by Confluence on Oct 10, 2007 11:54

Page 219

Confluence Security
This page last changed on Jul 19, 2007 by david.soul@atlassian.com.

Application Security Overview
As a public-facing web application, Confluence's application-level security is obviously important. This document answers a number of questions that commonly arise when customers ask us about the security of our product. This document is for system administrators looking to evaluate the security of the Confluence web application. It does not address Confluence's internal security – user/ group management and content permissions – except as it relates to the overall application security. Password Storage When Confluence's internal user management is used, passwords are hashed through SHA1 before being stored in the database. There is no mechanism within Confluence to retrieve a user's password – when password recovery is performed, a new random password is generated and mailed to the user's registered address. When external user management is enabled, password storage is delegated to the external system. Buffer Overflows Confluence is a 100% pure Java application with no native components. As such it is highly resistant to buffer overflow vulnerabilities – possible buffer overruns are limited to those that are bugs in the Java Runtime Environment itself. SQL Injection Confluence interacts with the database through the Hibernate Object-Relational mapper. Database queries are generated using standard APIs for parameter replacement rather than string concatenation. As such, Confluence is highly resistant to SQL injection attacks. Script Injection Confluence is a self-contained Java application and does not launch external processes. As such, it is highly resistant to script injection attacks. Cross-site Scripting As a content-management system that allows user-generated content to be posted on the web, precautions have been taken within the application to prevent cross-site scripting attacks: • The wiki markup language in Confluence does not support dangerous HTML markup • Macros allowing the insertion of raw HTML are disabled by default • HTML uploaded as a file attachment is served with a content-type requesting the file be downloaded, rather than being displayed inline • Only global administrators can make HTML-level customisations of the application When cross-site scripting vulnerabilities are found in the Confluence web application, we endeavour to fix them as quickly as possible. Transport Layer Security Confluence does not directly support SSL/TLS. Administrators who are concerned about transport-layer security should set up SSL/TLS at the level of the Java web application server, or the HTTP proxy in front of the Confluence application. For more information on configuring Confluence for SSL, see: Adding SSL for Secure Logins and Page Security

Document generated by Confluence on Oct 10, 2007 11:54

Page 220

Session Management Confluence delegates session management to the Java application server in which it is deployed. We are not aware of any viable session-hijacking attacks against the Tomcat application server shipped with Confluence Standalone. If you are deploying Confluence in some other application server, you should ensure that it is not vulnerable to session hijacking. Plugin Security Confluence administrators install third party plugins at their own risk. Plugins run in the same virtual machine as the Confluence server, and have access to the Java runtime environment, and the Confluence server API. Administrators should always be aware of the source of the plugins they are installing, and whether they trust those plugins. Administrator Trust Model Confluence is written under the assumption that anyone given global administrator privileges is trusted. Global administrators are able, either directly or by installing plugins, to perform any operation that the Confluence application is capable of. As with any application, you should not run Confluence as the root/Administrator user. If you want Confluence to listen on a privileged network port, you should set up port forwarding or proxying rather than run Confluence with additional privileges. The extra-careful may consider running Confluence inside a chroot jail.

Vulnerabilities, Advisories and Patches.
If you find a security bug in Confluence Open an issue on http://jira.atlassian.com in the Confluence project. • Set the priority of the bug to "Blocker" • Provide as much information on reproducing the bug as possible • Set the security level of the bug to "Developer and Reporters only" All communication about the vulnerability should be performed through JIRA, so we can keep track of the issue and get a patch out as soon as possible. Confluence Security Advisories When a security issue in Confluence is discovered and resolved, we will inform customers through the following mechanisms: • A security advisory will be posted on this page • A copy of the advisory will be sent to the confluence-users and confluence-announce mailinglists (subscribe here). These lists are mirrored on our forums • If the person who reported the issue wants to publish an advisory through some other agency (for example, CERT), we'll assist in the production of that advisory, and link to it from our own. Our Patch Policy When a security issue is discovered, we will endeavour to: • issue a new, fixed Confluence version as soon as possible • issue a patch to the current stable version of Confluence • issue patches for older versions of Confluence if feasible Patches will generally be attached to the relevant JIRA issue.

Document generated by Confluence on Oct 10, 2007 11:54

Page 221

Past Security Advisories Confluence Community Security Advisory 2006-01-19 Confluence Security Advisory 2005-02-09 Confluence Security Advisory 2005-12-05 Confluence Security Advisory 2006-01-20 Confluence Security Advisory 2006-06-14 Confluence Security Advisory 2007-07-26 Confluence Security Advisory 2007-08-08 Java Policy Security with Confluence — If you would like to secure the confluence webapp to make sure plugins (or other code executed) cannot access unwanted system resources, the following will restrict file system access. • NoFollow Support • • • • • • • • Related Server Security Pages

Adding SSL for Secure Logins and Page Security Java Policy Security with Confluence to user and group permissions. Assigning Space Permissions Confluence Security Hiding the People Directory How do I tell if a user has permission to...? HTML Macro Revoking Space Permissions Security Overview Space Permissions Overview Click to see pages related

Document generated by Confluence on Oct 10, 2007 11:54

Page 222

Confluence Community Security Advisory 2006-01-19
This page last changed on Jan 20, 2006 by jeremy@atlassian.com.

This security advisory is not endorsed by Atlassian - this is a public service advisory from a member of the confluence community. Please remember to backup any modified files, and use these instructions at your own risk. While this information is based on Confluence v2.1.2, it may have uses with older affected versions of Confluence. The official security advisory is located atConfluence Security Advisory 2006-01-20

Problem
There is a possibility of XSS exploitation of the Full Name user profile field when displayed.

Solution
The problem was unescaped outputting of the fullname - wrapping the output in $generalUtil.htmlEncode() resolve it. The vast majority of the problem can be resolved by changing / confluence/template/includes/macros.vm in the distribution on the following lines: • • • • • 180 186 200 340 893

I have attached the modified macros.vm file here which you can copy into your distribution.

Scope
There are other places which are still affected which Atlassian have been made aware of, a complete resolution should be provided by Atlassian in their own offical advisory. I hope this helps some of you!

Document generated by Confluence on Oct 10, 2007 11:54

Page 223

Confluence Security Advisory 2005-02-09
This page last changed on Feb 09, 2005 by jnolen.

A flaw has been found in Confluence by which attackers can bypass Confluence security and change content on the site. Atlassian STRONGLY recommends that all Confluence customers apply the fix described below immediately, or upgrade to Confluence 1.3.3

Vulnerability
By crafting custom URLs, any person with the ability to browse Confluence can modify content on the site, bypassing security settings. This vulnerability does not allow users to view content they would not normally be able to view, or escalate their privileges in other ways. This flaw affects all versions of Confluence prior to 1.3.3, including the 1.4-DR development releases.

Fix
This vulnerability is fixed in Confluence 1.3.3 and later. Customers who do not wish to migrate to 1.3.3 can fix this bug using the procedure below: 1. Edit the file confluence/WEB-INF/classes/xwork.xml 2. Find the following section near the top of the file (around line 34):
<interceptor-stack name="defaultStack"><interceptor-ref name="profiling"><param name="location">Before defaultStack</param></interceptor-ref><interceptor-ref name="transaction"/><interceptor-ref name="authentication"/><interceptor-ref name="requestParameterHack"/><interceptor-ref name="eventnotifier"/><interceptorref name="autowire"/><interceptor-ref name="params"/><interceptor-ref name="servlet"/ ><interceptor-ref name="pageAware"/><interceptor-ref name="permissions"/><interceptorref name="profiling"><param name="location">After defaultStack</param></interceptor-ref></ interceptor-stack>

3. Locate the "autowire" and "params" entries:
<interceptor-ref name="eventnotifier"/> --> <interceptor-ref name="autowire"/> --> <interceptor-ref name="params"/> <interceptor-ref name="servlet"/> <-<--

4. Swap the two lines around. The whole stack should now look like this:
<interceptor-stack name="defaultStack"><interceptor-ref name="profiling"><param name="location">Before defaultStack</param></interceptor-ref><interceptor-ref name="transaction"/><interceptor-ref name="authentication"/><interceptor-ref name="requestParameterHack"/><interceptor-ref name="eventnotifier"/><interceptorref name="params"/><interceptor-ref name="autowire"/><interceptor-ref name="servlet"/ ><interceptor-ref name="pageAware"/><interceptor-ref name="permissions"/><interceptorref name="profiling"><param name="location">After defaultStack</param></interceptor-ref></ interceptor-stack>

5. Restart Confluence.

Document generated by Confluence on Oct 10, 2007 11:54

Page 224

Confluence Security Advisory 2005-12-05
This page last changed on Dec 05, 2005 by cmiller.

A flaw has been found in Confluence by which attackers to inject malicious HTML code into Confluence. Atlassian STRONGLY recommends that all Confluence customers apply the fix described below immediately, or upgrade to Confluence 2.0.2

Vulnerability
By entering HTML code into the Confluence search input fields, attackers can cause arbitrary scripting code to be executed by the user's browser in the security context of the Confluence instance. This flaw affects all versions of Confluence between 1.4-DR releases and 2.0.1. (Atlassian was not informed of the problem before it was published by third-party security researchers. You can read the third-party security advisory here: http://secunia.com/advisories/17833/. The vulnerability was originally reported here.)

Fix
This vulnerability is fixed in Confluence 2.0.2 and later. Customers who do not wish to migrate to 2.0.2 can fix this bug using the procedure below: 1. Edit the confluence/decorators/components/searchresults.vmd 2. Replace the following reference (around line 48):
$action.getText("search.result", [$start, $end, $total, $queryString])

with
$action.getText("search.result", [$start, $end, $total, $generalUtil.escapeXml($queryString)]).

3. Edit the confluence/search/searchsite-results.vm. 4. Replace the following reference (around line 11):
Searched for <b>$action.searchQuery.queryString</b>

with
Searched for <b>$generalUtil.escapeXml($action.searchQuery.queryString)</b>

5. Restart Confluence. Alternatively, you can download the patched source files from CONF-4825. If you are patching a 2.0.x installation, then use the files with the .2.0 suffix. If you are patching a 1.4.x installation, then use the files with the .1.4 suffix.

Document generated by Confluence on Oct 10, 2007 11:54

Page 225

Confluence Security Advisory 2006-01-20
This page last changed on Jan 20, 2006 by jeremy@atlassian.com.

A flaw has been found in Confluence by which attackers to inject malicious HTML code into Confluence. Atlassian STRONGLY recommends that all Confluence customers apply the fix described below immediately, or upgrade to Confluence 2.1.3.

Vulnerability
By entering HTML/JavaScript code into the full name of a user's profile, attackers can cause arbitrary scripting code to be executed by the user's browser in the security context of the Confluence instance. This flaw affects all versions of Confluence between 1.4-DR releases and 2.1.2. This issue was initally reported by Ricardo Sueiras and a fix was quickly documented by Dan Hardiker at the Confluence Community Security Advisory 2006-01-19 page. Our thanks to them for bringing this to our attention. There is an issue in JIRA at CONF-5233.

Fix
This vulnerability is fixed in Confluence 2.1.3 and later. Customers who do not wish to migrate to 2.1.3 can fix this bug using the procedure below: Steps to fix: 1. Copy macros.vm to your confluence/template/includes folder 2. Restart Confluence Note: If you are using version 1.4.4, please download and copy this file instead. You will need to rename it back to macros.vm. If you are not using any of the above versions, you will need to replace wrap calls to display full names of users in $generalUtil.htmlEncode(). Alternatively, send us an email. We do however encourage you to use the latest stable point release regardless of the version you are using.

Document generated by Confluence on Oct 10, 2007 11:54

Page 226

Confluence Security Advisory 2006-06-14
This page last changed on Jun 14, 2006 by cmiller.

Vulnerability
By crafting a custom HTTP request, an attacker can delete or modify global permissions settings on a Confluence site. This flaw affects all Confluence versions between 1.4 and 2.2.2. 2.2.3 and later are not vulnerable.

Fix
This issue has been fixed in Confluence 2.2.3. Patches are also available for all versions of Confluence betwen 1.4 and 2.2.2. For more information, please see this issue report. Atlassian STRONGLY recommends that all customers either upgrade to Confluence 2.2.3, or apply the patch.

Document generated by Confluence on Oct 10, 2007 11:54

Page 227

Confluence Security Advisory 2007-07-26
This page last changed on Jul 26, 2007 by smaddox.

In this advisory: • Users with view permission in a space can copy and save a page • Space name and key are not validated nor escaped

Users with view permission in a space can copy and save a page
Vulnerability A user who has only view permissions in a space can copy a page and then save it in the space. In this way, users can create a page in a space where they have only view permission. This flaw affects only Confluence version 2.5.4. Fix This issue has been fixed in Confluence 2.5.5. A patch is also available for Confluence 2.5.4. For more information, including instructions on applying the patch, please see this issue report. If you are using Confluence 2.5.4, Atlassian strongly recommends that you upgrade to Confluence 2.5.5 or apply the patch.

Space name and key are not validated nor escaped
Vulnerability The input for space name and key is not validated properly - any characters are allowed. This makes a Confluence instance vulnerable to an XSS attack. Fix This issue has been fixed in Confluence 2.5.5. For more information, please see this issue report. Atlassian recommends that you upgrade to Confluence 2.5.5.

Document generated by Confluence on Oct 10, 2007 11:54

Page 228

Confluence Security Advisory 2007-08-08
This page last changed on Aug 08, 2007 by smaddox.

In this advisory: • • • • • • • Input in the RSS Feed Builder is not validated Input when editing Space Permissions is not validated Number of labels that can be added to a page is not restricted Input when editing navigation themes is not validated Viewing of space content alphabetically is not validated Input when editing Space Name is not validated Input when viewing attachments by file-type is not validated

Input in the RSS Feed Builder is not validated
Vulnerability The input for the RSS Feed Builder is not required to be escaped. This can make a Confluence instance vulnerable to an XSS attack. Fix This issue has been fixed in Confluence 2.5.6. For more information, please see CONF-8993. Atlassian recommends that you upgrade to Confluence 2.5.6.

Input when editing Space Permissions is not validated
Vulnerability The 'Grant permission to' field on the 'Edit Space Permissions' screen is not validated. This can make a Confluence instance vulnerable to an XSS or DoS attack. Fix This issue has been fixed in Confluence 2.5.6. For more information, please see CONF-8980 and CONF-8979. Atlassian recommends that you upgrade to Confluence 2.5.6.

Number of labels that can be added to a page is not restricted
Vulnerability There is no restriction on the number of labels that can be added to a page at a time. This can make a Confluence instance vulnerable to a DoS attack. Fix This issue has been fixed in Confluence 2.5.6. For more information, please see CONF-8978. Atlassian recommends that you upgrade to Confluence 2.5.6.

Document generated by Confluence on Oct 10, 2007 11:54

Page 229

Input when editing navigation themes is not validated
Vulnerability The 'Navigation Page' specified in the 'Left Navigation Theme' configuration is not validated. This can make a Confluence instance vulnerable to a XSS attack. Fix This issue has been fixed in Confluence 2.5.6. For more information, please see CONF-8956. Atlassian recommends that you upgrade to Confluence 2.5.6.

Viewing of space content alphabetically is not validated
Vulnerability When viewing space content by alphabetic character, the input is not validated as being alphabetic. This can make a Confluence instance vulnerable to an XSS attack. Fix This issue has been fixed in Confluence 2.5.6. For more information, please see CONF-8952. Atlassian recommends that you upgrade to Confluence 2.5.6.

Input when editing Space Name is not validated
Vulnerability The 'Name' field on the 'Edit Space Details' screen is not validated. This can make a Confluence instance vulnerable to an XSS attack. Fix This issue has been fixed in Confluence 2.5.6. For more information, please see CONF-8951. Atlassian recommends that you upgrade to Confluence 2.5.6.

Input when viewing attachments by file-type is not validated
Vulnerability The 'Filter By Extension' field on the 'List Space Attachments' screen is not validated. This can make a Confluence instance vulnerable to an XSS attack. Fix This issue has been fixed in Confluence 2.5.6. For more information, please see CONF-8950. Atlassian recommends that you upgrade to Confluence 2.5.6.

Document generated by Confluence on Oct 10, 2007 11:54

Page 230

Java Policy Security with Confluence
This page last changed on Jan 15, 2007 by dhardiker@adaptavist.com.

If you would like to secure the confluence webapp to make sure plugins (or other code executed) cannot access unwanted system resources, the following will restrict file system access. Create the following .java.policy file and place it somewhere: .java.policy
grant { permission permission permission permission permission permission permission permission permission permission permission permission permission permission permission permission permission permission }; java.util.PropertyPermission "*", "read,write"; java.net.SocketPermission "*:-", "connect,accept,listen"; java.io.FilePermission "/tangosol-coherence-override.xml","read"; java.io.FilePermission "/tangosol-coherence-override-prod.xml","read"; java.io.FilePermission "/path/to/confluenceWebapp/-","read,write"; java.io.FilePermission "/path/to/confluence.home","read,write,delete"; java.io.FilePermission "/path/to/confluence.home/-","read,write,delete"; java.io.FilePermission "/path/to/resin/lib/-","read"; java.io.FilePermission "/tmp", "read"; java.io.FilePermission "/tmp/*", "read,write,delete"; java.io.FilePermission "quartz.properties", "read"; java.util.logging.LoggingPermission "control"; java.awt.AWTPermission "*"; java.lang.reflect.ReflectPermission "suppressAccessChecks"; java.io.SerializablePermission "*"; java.lang.RuntimePermission "*"; java.net.NetPermission "*"; ognl.OgnlInvokePermission "*";

Make sure the following are java options are defined:
-Djava.security.manager -Djava.security.policy=/path/to/.java.policy

Of course you might be able to get away with less - please edit with any improvements you have!

Document generated by Confluence on Oct 10, 2007 11:54

Page 231

NoFollow Support
This page last changed on May 23, 2005 by vidya.

NoFollow support is a new feature in the release of Confluence 1.4.

Nofollow Support
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. By default, all URLs inserted in a page (or in comments) will be given the nofollow tag. Inter-page links (i.e. Documentation Home) or shortcut links (i.e. CONF-2622@JIRA) will not be tagged. The site administrator can turn the feature off in General Configuration.

Document generated by Confluence on Oct 10, 2007 11:54

Page 232

Design and Layout
This page last changed on Feb 01, 2006 by vidya.

• Custom Decorator Templates • Customising Look and Feel Overview ° Customising Colour Schemes ° Customising Layouts - Upgrading Custom Layouts ° Global Templates ° Working With Decorator Macros • Themes Configuration ° Applying a Theme To A Site ° Creating a Theme - Adding a theme icon ° Customising the Left Navigation Theme ° Deploying the theme as a plugin ° Including Cascading Stylesheets in Themes ° Modifying Look and Feel (for themes) - Configuring the theme plugin ° Themes Overview

Document generated by Confluence on Oct 10, 2007 11:54

Page 233

Custom Decorator Templates
This page last changed on Jul 09, 2007 by smaddox.

About Decorators
Confluence is built on top of the Open Source SiteMesh library, a web-page layout system that provides a consistent look and feel across a site. SiteMesh works through "decorators" that define a page's layout and structure, and into which the specific content of the page is placed. If you are interested, you can read more on the SiteMesh website. What this means for Confluence is that you can customise the look and feel of almost all of your Confluence site through editing three decorators: • The "Main" decorator defines the look and feel of most pages on the site • The "Popup" decorator defines the look and feel of the popup windows such as the "Insert Link" and "History" pages. • The "Printable" decorator defines the look and feel of the printable versions of pages (available through the Cannot resolve external resource into attachment. icon on each page) 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.

Browsing the Default Decorators
At any time, you can browse the default decorators that come packaged with Confluence by following the "View Default" links on the "Site Layouts" page. The template browser also allows you to view the "#parsed" templates that are included within the template when it is compiled. While you can't edit these included templates, you will probably have to copy some or all of them into your custom template as you do your customisation.

Editing Custom Decorators: Add a Logo
To edit Confluence decorators, you should have a good knowledge of HTML, and some understanding of the Velocity templating language. The first thing you will see when you choose to create a custom "Main" decorator is... there's not much to edit. By default, most of the content of this decorator is included from other files:
<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

Document generated by Confluence on Oct 10, 2007 11:54

Page 234

## ## ## ## ##

#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")

We can add our logo, changing the "logocell" table cell:
<td width="60%" rowspan=2 class="logocell"> <img align="right" src=http://www.atlassian.com/images/atlassian_logo.gif width="203" height="60">#pagetitle("spacenametitle")</td>

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 Decorator Macros

If Something Goes Terribly Wrong
From the "Site Layouts" page in Confluence's administrative menu, you can delete your custom templates. When you do this, the default template will be restored, fixing anything that may have been broken. Alternatively, the custom templates are stored inside the confluence.home directory you defined in confluence-init.properties when installing Confluence. If you have somehow managed to render Confluence completely unuseable through editing your templates, simply delete the confluence.home/ velocity directory, and restart Confluence. The default templates will be restored. WARNING: Only delete the velocity directory! Changing anything else inside your confluence.home is dangerous, and you could lose important data!

For Advanced Users
The velocity directory is at the front of Confluence's velocity template search path. As such, you can override any of Confluence's velocity templates by placing an identically named file in the right place. While we don't recommend you do this unless you know exactly what you're doing, it does give you complete control over the look of every aspect of Confluence. It also means that you can edit your templates in a text-editor if you wish, rather than through the web interface. There are, however, two important caveats: 1. Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows to reload that page from disk. If you are editing the pages on disk, you will either have to turn off velocity's caching temporarily in WEB-INF/classes/velocity.properties, or restart the server to make your changes visible.

Document generated by Confluence on Oct 10, 2007 11:54

Page 235

2. Because we only officially support the modification of the three global decorator files, other 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.

Document generated by Confluence on Oct 10, 2007 11:54

Page 236

Customising Look and Feel Overview
This page last changed on Jun 25, 2007 by smaddox.

You can customise the 'look and feel' of Confluence at both the global and space levels. Any changes you make to the 'look and feel' of the site at the global level will be applied as the default 'look and feel' for all the spaces in the site. An individual space can be configured to have its own 'look and feel' through the space administration screens. 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 sorrounding controls appear in the page. • Themes : Use themes for advanced layout customisation.
RELATED TOPICS

Customising Colour Schemes Customising Layouts Customising Look and Feel Overview Global Templates Upgrading Custom Layouts

Document generated by Confluence on Oct 10, 2007 11:54

Page 237

Customising Colour Schemes
This page last changed on Jun 25, 2007 by smaddox.

A site administrator can configure a new colour scheme for the site dynamically from the Administration Console. The default colour scheme for the site will also become the default for all spaces within it. However, it is possible for space administrators to configure a different colour scheme for spaces from the space administration screens. To change the site's colour scheme,

1. Go to the 'Administration Console' and click 'Colour schemes' in the left panel. This will bring up a new screen. See Screenshot below. 2. Click 'Edit colour scheme'. 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. 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

Screenshot : Editing a site's colour scheme

Document generated by Confluence on Oct 10, 2007 11:54

Page 238

Handy Hint If you mess things up, just click the 'Reset Default Colour Scheme' button and then try again.
RELATED TOPICS

Customising Colour Schemes Customising Layouts Customising Look and Feel Overview Global Templates Upgrading Custom Layouts

Document generated by Confluence on Oct 10, 2007 11:54

Page 239

Customising Layouts
This page last changed on Jul 10, 2007 by smaddox.

You can customise the layout of your Confluence instance by editing the "decorators" that define the look and feel of the site. 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. Learn more about Velocity. Once you become familiar with Velocity, you can edit the decorator files to personalise the appearance of Confluence. You need to be a site administrator to edit site decorator files. • You can customise the layouts for a particular space or for the whole site. This page tells you how to customise layouts for the site as a whole. To customise the layouts for a space, use the 'Layout' menu on the 'Space Admin' page. • When you upgrade Confluence, you must reapply your custom layouts to the new default layouts. 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 news items: 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. To edit a site decorator file,

1. Go to the 'Administration Console' and click on 'Layouts' under 'Look and Feel' in the left navigation panel. The decorators are grouped under Site, Content and Group layouts. • Click 'View Default' to view the vmd file. • Click 'Create Custom' to edit the default vmd file. This will open up the vmd file in edit mode. 2. Make changes and click 'Update'.

If something goes wrong : Click 'Reset Default' to revert to the original layouts. Alternatively, the custom templates are stored inside the confluence.home directory you defined in confluence-init.properties when installing Confluence. If you have somehow managed to render Confluence completely unuseable through editing your templates, simply delete the confluence.home/ velocity directory, and restart Confluence. The default templates will be restored. CAUTION: Only delete the velocity directory! Changing anything else inside your confluence.home is dangerous, and you could lose important data! Using Velocity Macros When editing Custom Decorator Templates, there are a number of macros available to define complex or variable parts of the page such as menus and breadcrumbs. You may insert these macros anywhere in your templates. More information on Working With Decorator Macros. For Advanced Users

Document generated by Confluence on Oct 10, 2007 11:54

Page 240

The velocity directory is at the front of Confluence's velocity template search path. As such, you can override any of Confluence's velocity templates by placing an identically named file in the right place. While we don't recommend you do this unless you know exactly what you're doing, it does give you complete control over the look of every aspect of Confluence. It also means that you can edit your templates in a text-editor if you wish, rather than through the web interface. WARNING 1. Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows to reload that page from disk. If you are editing the pages on disk, you will either have to turn off velocity's caching temporarily in WEB-INF/ classes/velocity.properties, or restart the server to make your changes visible. 2. Because we only officially support the modification of the three global decorator files, other 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.
RELATED TOPICS

Customising Colour Schemes Customising Layouts Customising Look and Feel Overview Global Templates Upgrading Custom Layouts

Document generated by Confluence on Oct 10, 2007 11:54

Page 241

Upgrading Custom Layouts
This page last changed on Jul 10, 2007 by mjensen.

As Confluence evolves, so do the default layouts that drive the rendering of every page. As new functionality is added, or current functionally is changed, the default layouts are modified to support these changes. If you are using custom layouts based on defaults from a previous Confluence version, you run the risk of breaking functionality, or worse: missing out on great new features! Care must be taken 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 layout from your current version of Confluence 2. Reapply your customisations to the new default layouts.

Obtaining Your Custom Layouts
Before Confluence 2.3, custom layouts are stored in the velocity directory within your Conflunce home directory tree. You can open these files in any text editor. With Confluence 2.3 and after, 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 relevant for all SQL databases.

Reapply Your Customisations
You will need to manually apply the changes you made to the new default layouts provided by the new version of Confluence. Use the documentation on customising layouts to create a new custom layout and use the source obtained in step 1 to manually reintegrate them. WARNING 1. Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows to reload that page from disk. If you are editing the pages on disk, you will either have to turn off velocity's caching temporarily in WEB-INF/ classes/velocity.properties, or restart the server to make your changes visible. 2. Because we only officially support the modification of the three global decorator files, other 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.

Document generated by Confluence on Oct 10, 2007 11:54

Page 242

Global Templates
This page last changed on Sep 27, 2007 by smaddox.

A template is a pre-defined page that can be used as a prototype when creating new pages. Templates are useful for giving pages a common style or format. Global Templates are defined by site administrators and are available in every space across the site. Templates are written in regular Confluence markup, using special markup to define form fields that need to be filled in. To add a global template,

1. Go to the Administration Console and click 'Global templates' in the left navigation panel. 2. Click 'Add new global template'. 3. Enter a name for your template in the 'Name' text field and an optional description in the 'Description' text field. 4. Using regular Confluence 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

Creating a Page using a Template Form Field Markup for Templates

Document generated by Confluence on Oct 10, 2007 11:54

Page 243

Working With Decorator Macros
This page last changed on Jun 25, 2007 by smaddox.

Decorator Macros are Velocity macros which are used to draw complex or variable parts of the page such as menus and breadcrumbs when editing Custom decorators. Decorator macros can be inserted anywhere in your templates. The macro is called by inserting a string of the form: #macroName("argument1" "argument2" "argument3").There are no commas between the arguments. Unless otherwise noted, these macros take no arguments. NOTE: These macros will only work reliably when customising main.vmd. They may not work in other Velocity decorators. Decorator macros will not work inside normal confluence pages.

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. Displays the navigation bar as series of text links separated by | characters. 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. Draws the Cannot resolve external resource into attachment. help icon, and link to the Confluence help page. On pages where a printable version is available, draws the Cannot resolve external resource into attachment. printable page icon, linking to the printable version of the page. Otherwise, draws nothing 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

#includePage(pageTitle)

#searchbox()

#globalnavbar(type)

#globalnavbar("table")

#globalnavbar("text")

#usernavbar()

#helpicon()

#printableicon()

#pagetitle(class)

Document generated by Confluence on Oct 10, 2007 11:54

Page 244

call this with "spacenametitle" as the class: #pagetitle("spacenametitle") #poweredby() 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.

#bottomshadow()

#dashboardlink()
RELATED TOPICS

Editing and Removing macros Enabling HTML macros Enabling the html-include Macro User Macros Writing Macros

Document generated by Confluence on Oct 10, 2007 11:54

Page 245

Themes Configuration
This page last changed on Feb 01, 2006 by vidya.

• Applying a Theme To A Site • Creating a Theme ° Adding a theme icon • Customising the Left Navigation Theme • Deploying the theme as a plugin • Including Cascading Stylesheets in Themes • Modifying Look and Feel (for themes) ° Configuring the theme plugin • Themes Overview

Document generated by Confluence on Oct 10, 2007 11:54

Page 246

Applying a Theme To A Site
This page last changed on Sep 27, 2007 by smaddox.

Themes can can be applied across the site or to individual spaces. Themes are installed as plugins and added via the administration console by a site administrator. Once installed, themes become available to be applied across a site or to individual spaces. Any theme applied at the global level will become the default theme for all spaces in the site. Confluence 2.6 introduced a fresh, clean look for the Default theme. If you prefer the original Confluence look and feel, select the Confluence Classic Theme. To apply a theme across the site,

1. Ensure that the theme plugin you wish to apply has been installed. 2. Go to the 'Administration Console' and click 'Themes' under 'Look and Feel' in the left navigation panel. 3. If there are any themes installed, they will be listed here. 4. Select a theme and click 'Confirm'. Screenshot : Applying a theme

RELATED TOPICS

Adding a theme icon Applying a Theme To A Site Applying A Theme To A Space Creating a Theme

Document generated by Confluence on Oct 10, 2007 11:54

Page 247

Including Cascading Stylesheets in Themes

Document generated by Confluence on Oct 10, 2007 11:54

Page 248

Creating a Theme
This page last changed on Jun 25, 2007 by smaddox.

There are three steps involved involved in creating a theme: • Modifying the look and feel of Confluence: Work with the different components that define the look and feel of Confluence and modify them to suit your theme: ° Layout ° Colour Scheme (optional) ° Stylesheet (optional) • Configuring the atlassian-plugin.xml file: Edit the central configuration file for the theme plugin to reference the new files defining your theme. • Adding a theme icon: Add a preview icon for your theme. • Deploying the theme as a plugin : Bundle the files into a jar file and deploy the theme as a plugin into Confluence. Unsure what a theme is?
RELATED TOPICS

Adding a theme icon Applying a Theme To A Site Applying A Theme To A Space Creating a Theme Including Cascading Stylesheets in Themes

Document generated by Confluence on Oct 10, 2007 11:54

Page 249

Adding a theme icon
This page last changed on Jun 25, 2007 by smaddox.

A theme icon can be packed with a theme to give the user a little preview on how the theme will change the layout of Confluence. If you do not specify a custom icon for your theme, a default icon will be shown in the preview.

Defining the theme icon in the atlassian-plugin.xml
To include an icon in the theme, you will need to reference it as a Downloadable Plugin Resource from within the theme module. Here is an example where an icon called my-theme-icon.gif is being used in the Dinosaur Theme:
<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"/> <resource name="themeicon.gif" type="download" location="com/example/themes/dinosaur/my-themeicon.gif"> <property key="content-type" value="image/gif"/> </resource> </theme>

The resource parameter takes three arguments: • Name: The name of the icon ( has to be themeicon.gif). • Type: The type of resource-in this instance, 'download'. • Location: The location of the file represented in the jar archive you will use to bundle your theme. The icon will automaticly appear on the themes screen in the space and global administration and will be displayed next to the text and description of the theme.

Creating your own theme icon
In order to keep the look and feel of the icons consistent, we recommend to base the icon style on icons shipped with the Confluence themes. A good starting point when creating new icons is to use the default theme icon or the left navigation theme icon:

RELATED TOPICS

Adding a theme icon(Confluence 2.6)

Document generated by Confluence on Oct 10, 2007 11:54

Page 250

Applying a Theme To A Site(Confluence 2.6) Applying A Theme To A Space(Confluence 2.6) Creating a Theme(Confluence 2.6) Including Cascading Stylesheets in Themes(Confluence 2.6)

Document generated by Confluence on Oct 10, 2007 11:54

Page 251

Customising the Left Navigation Theme
This page last changed on Jun 14, 2007 by rosie@atlassian.com.

Introduction
Confluence comes bundled with the Left Navigation theme. This theme has a navigation menu on the lefthand side of the screen, which can be customised to contain additional links, sections and even macros.

Creating a custom navigation page

Custom left navigation By default, the left-navigation theme just displays the space icon (or profile icon for a personal space), and three menus: page operations, browse space, and add content. To add your own content to the top, create a page in your space called 'Navigation'. Put content there that you want to appear on the left navigation menu. A couple of tips: • items in a bulleted list show up as normal menu items • use 'h1' to add a section heading for your menu items.

Examples
As an example, create a page called 'Navigation' with the following content:
h1. Search engines

Document generated by Confluence on Oct 10, 2007 11:54

Page 252

* [Google|http://www.google.com] * [Yahoo|http://www.yahoo.com] * [MSN|http://search.msn.com]

This will give a left navigation menu like the image on the side of this page. You can see another example of customised left-navigation theme on the Codegeist space with its associated Navigation page.

See Also
To insert an expandable/collapsible left navigation menu, see the PageTree Plugin. Note that this looks better on the 'Default' theme rather than on the 'Left Navigation Theme'.

Document generated by Confluence on Oct 10, 2007 11:54

Page 253

Deploying the theme as a plugin
This page last changed on Jun 25, 2007 by smaddox.

In order to deploy your custom Confluence theme, you will have to have Ant installed. To learn how to install and use Ant, please follow the instructions on the projects website. To deploy the theme, execute the following command from within the theme directory in your Confluence installation:
ant build -Dtheme=<specifynameoftheme>

For example to build a theme with the name dinosaur, you will have to type:
ant build -Dtheme=dinosaur

You will find the build jar of the dinosaur theme in you Confluence install directory under .../themes/ dinosaur/dist_ directory.

Installing the theme
To install the theme you can simply drop the previously created .jar file into the .../confluence/WEBINF/lib directory in your Confluence installation as described under Installing and Configuring Plugins. As a second option, you can also call the following ant command instead of the one found above to install the theme and copy the jar automatically in the appropriate directory.
ant install -Dtheme=<specifynameoftheme>

Read more about plugins To change the time and date formats,

1. Go to the 'Administration Console' and click on 'General Configuration' in the left panel. 2. Click 'Edit' at the bottom of the 'Options and Settings' screen. • There are three time and date format settings: ° Time Format : determines the time format for when each news item is posted ° Date Time Format : determines date and time format for historical versions of pages. ° Date Format : determines date and time format for all new and modified content. 3. Change the formats using the guidelines in this document. 4. 'Save' your changes.
RELATED TOPICS

Adding a theme icon(Confluence 2.6) Applying a Theme To A Site(Confluence 2.6) Applying A Theme To A Space(Confluence 2.6) Creating a Theme(Confluence 2.6) Including Cascading Stylesheets in Themes(Confluence 2.6)

Document generated by Confluence on Oct 10, 2007 11:54

Page 254

Including Cascading Stylesheets in Themes
This page last changed on Jun 25, 2007 by smaddox.

Confluence allows you to integrate your own stylesheets within the theme plugin so you can have greater control over the appearance of your site. Confluence's main stylesheet is a useful reference when overriding styles and can be found in the Confluence install directory under ...confluence/WEB-INF/ classes/styles/site-css.vm.

Step One: Defining the stylesheet in the atlassian-plugin.xml
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:
<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:
#pluginSpaceStylesheet("com.atlassian.confluence.themes.leftnavigation:main""leftnav.css" $spaceKey)

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:
.navItemOver { color: $action.navSelectedTextColor; }
RELATED TOPICS

Adding a theme icon(Confluence 2.6)

Document generated by Confluence on Oct 10, 2007 11:54

Page 255

Applying a Theme To A Site(Confluence 2.6) Applying A Theme To A Space(Confluence 2.6) Creating a Theme(Confluence 2.6) Including Cascading Stylesheets in Themes(Confluence 2.6)

Document generated by Confluence on Oct 10, 2007 11:54

Page 256

Modifying Look and Feel (for themes)
This page last changed on Jun 25, 2007 by smaddox.

Here's how you can define a new look and feel for Confluence in your theme: 1. Layout : Edit Confluence's layout by modifying the decorator files that are used to define it. • Working with Decorators • Velocity Template Overview • Configuring the atlassian.plugin.xml file to reference the decorators 2. Colour schemes : Configure a new colour scheme for your theme. Optional • Configuring a new colour scheme • Configuring the atlassian.plugin.xml file to include the new colour scheme 3. Stylesheet : Include a stylesheet to define your theme. Optional Note that for every component you edit, you will need to configure the atlassian-plugin.xml which is the central configuration file for the plugin to override the default files with the new files you've created.

Layout: Working with decorators
What are decorators? Confluence is built on top of the Open Source SiteMesh library, a web-page layout system. To edit the layout of Confluence, you will need to modify these decorator files. A decorator file is a vmd file and is written in a very simple programming language called Velocity. Learn more about Velocity. Confluence comes bundled with a set of decorator or VMD files that you can customize. Broadly these are categorised into Site, Content and Export decorators. These are further grouped into categories called contexts and under each context has various modes (ways of viewing the context). To make editing easier, layout for similar screens (example: view and edit page screens) is configured through the same VMD file. So, if you want to customize how the Confluence View Page Screen or Edit Page Screen looks, you can make both of these changes inside one decorator file: page.vmd.

Decorator page.vmd

Context page

Mode 'view', 'edit', 'editpreview', 'viewinformation', and 'viewattachments' 'view', 'edit', 'editpreview', and 'remove'

Comment

blogpost.vmd

blogpost (news)

We prefer to use 'news' as an end-user term; all templates and classes use 'blogpost' to indicate RSS related content

mail.vmd space.vmd

mail space-pages, spacemails, space-blogposts, space-templates, space-operations, space-administration

'view', 'view-thread' and 'remove' CONTEXT: "spacepages". MODES: "listalphabetically", "listrecently-updated", "listcontent-tree", "createpage". CONTEXT: "spacemail". MODES: "viewmail-archive". 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)

Document generated by Confluence on Oct 10, 2007 11:54

Page 257

CONTEXT: "spaceblogposts". MODES: "view-blogposts", "create-blogpost". CONTEXT: "spacetemplates". MODES: "view-templates". CONTEXT: "spaceoperations". MODES: "view-spaceoperations". CONTEXT: "spaceadministration". MODES: "view-spaceadministration", "listpermission-pages". global.vmd global 'dashboard', 'viewprofile', 'edit-profile', 'change-passwordprofile', 'editnotifications-profile' main.vmd is used to control the header and footer of each page, not the page specific presentation logic

main.vmd

n/a (header and footer formatting)

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).
#* 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 ...

Step One: Copying the decorators
The easiest way to begin configuring a new layout is by copying the default decorator files and editing them to suit your theme. 1. Go to the 'Administration Console' and click on Layouts in the left panel. This will display options to view and edit the default decorators. 2. Copy the files that you intend to modify and place them in a directory structure that makes sense to you. See example below.

Step Two: Creating a directory structure for the decorators:
You should place your decorators in a directory hierarchy which makes sense to you. We recommend that you place the atlassian-plugin.xml file at the top level of the directory structure, and then place the decorators in directories which make a meaningful division of what they do. Here is an example:
atlassian-plugin.xml com/atlassian/confluence/themes/mytheme/

Document generated by Confluence on Oct 10, 2007 11:54

Page 258

com/atlassian/confluence/themes/mytheme/global.vmd com/atlassian/confluence/themes/mytheme/space.vmd com/atlassian/confluence/themes/mytheme/mail.vmd com/atlassian/confluence/themes/mytheme/blogpost.vmd com/atlassian/confluence/themes/mytheme/main.vmd com/atlassian/confluence/themes/mytheme/page.vmd

Step Three: Editing the decorators
To edit the decorators, you will require knowledge of a very simple programming language called Velocity. Learn more about Velocity. Decorator Macros When editing the decorators, you will need to use Decorator Macros to draw complex or variable parts of the page such as menus and breadcrumbs. See Working with Decorator Macros Theme Helper Object When editing decorator files you will also come across a variable called $helper - this is the theme helper object. The following table summarises what this object can do:

Behaviour $helper.domainName

Explanation displays the base URL of your Confluence instance on your page. This is useful for constructing links to your own Confluence pages. returns the current space key or null if in a global context. 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
key.key1=A piece of text

$helper.spaceKey $helper.spaceName $helper.renderConfluenceMacro("{create-spacebutton}") $helper.getText("key.key1")

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

Document generated by Confluence on Oct 10, 2007 11:54

Page 259

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 'Administration Console' and click on 'Colour scheme' in the left panel. 2. 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

Expressing the colour scheme as XML
Once, you have decided on the colours for the different UI elements, you will need to configure the atlassian.plugin.xml to include the new colour scheme. How to do this is explained in detail in Configuring the theme plugin.
RELATED TOPICS

Adding a theme icon Applying a Theme To A Site Applying A Theme To A Space Creating a Theme Including Cascading Stylesheets in Themes

Document generated by Confluence on Oct 10, 2007 11:54

Page 260

Configuring the theme plugin
This page last changed on Jun 25, 2007 by smaddox.

Each plugin is described in its own atlassian-plugin.xml file, which specifies attributes of the plugin, including a description of each module it contains. Once you have modified the different components to define a new look and feel for your theme, you will need to configure this file so Confluence knows where to look when overriding the default files. The easiest way to begin is by copying the atlassian-plugin.xml from one of the default themes bundled with confluence and modifying it for your theme. The structure of an atlassian-plugin.xml file is fairly self-explanatory. In the code segment below you will find a full example of an atlassian-plugin.xml:
<atlassian-plugin key="com.atlassian.confluence.themes.tabless" name="Plain Theme"><plugininfo><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" 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>

Document generated by Confluence on Oct 10, 2007 11:54

Page 261

<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></atlassian-plugin>

Modifying the {{atlassian-plugin.xml}}file
We will configure this file section by section Plugin information
<atlassian-plugin key="com.atlassian.confluence.themes.tabless" name="Plain Theme"><plugininfo><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 colourscheme 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 module complete 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>

Document generated by Confluence on Oct 10, 2007 11:54

Page 262

class : The class which each decorator, or layout, is mapped to must implement com.atlassian.confluence.themes.VelocityDecorator. 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

Adding a theme icon Applying a Theme To A Site Applying A Theme To A Space Creating a Theme Including Cascading Stylesheets in Themes

Document generated by Confluence on Oct 10, 2007 11:54

Page 263

Themes Overview
This page last changed on Jun 25, 2007 by smaddox.

Themes are pre-defined styles that can be applied to alter the appearance of your site. Use themes when you want to add new functionalities or to change the appearance of Confluence. For example, you will need to use themes to apply a left-navigation scheme instead of the default topnavigation scheme. Themes are installed as plugins and added via the Administration Console by a site administrator. Once installed, themes can be applied across the site or to individual spaces. What do you want to do? Apply a theme Create a new theme Include cascading stylesheets in a theme
RELATED TOPICS

Adding a theme icon Applying a Theme To A Site Applying A Theme To A Space Creating a Theme Including Cascading Stylesheets in Themes

Document generated by Confluence on Oct 10, 2007 11:54

Page 264

Importing Data
This page last changed on Feb 01, 2006 by vidya.

• Snip Snap Import

Document generated by Confluence on Oct 10, 2007 11:54

Page 265

Snip Snap Import
This page last changed on Jun 25, 2007 by smaddox.

The snipsnap importer allows you to import a Snip Snap XML backup file into a space in Confluence. Currently, attachments are not imported, and Confluence does not recognise duplicate users. To import a SnipSnap backup file,

1. Go to the Administration Console and click on 'Snip Snap Import' in the left panel. 2. Enter the location of the backup file in the input field displayed. You can also 'browse' and locate the file. 3. Select a space to import the content into and click 'Save'. You cannot import content into multiple spaces.
RELATED TOPICS

Snip Snap Import(Confluence 2.6) Confluence File Uploader(Confluence Extension) Perl XML-RPC client(Confluence Extension) Wiki Importer(Confluence Extension)

Document generated by Confluence on Oct 10, 2007 11:54

Page 266

Macros
This page last changed on May 29, 2007 by rosie@atlassian.com.

Macros allow you to perform programmatic functions within a page, and can be used for generating more complex content structures. Generally speaking, a macro is simply a command wrapped inside curly braces {...}. To learn how to write your own macro, or use macros written by other people, read the Confluence Plugin Guide. • Editing and Removing macros • Enable The Flowchart Macro • Enabling HTML macros ° Enabling the html-include Macro • Troubleshooting the Gallery Macro

Document generated by Confluence on Oct 10, 2007 11:54

Page 267

Editing and Removing macros
This page last changed on Jun 25, 2007 by smaddox.

To edit or remove a user macro,

1. Go to the 'Administration Console' and click on 'User Macros' in the left panel. This will list the currently configured user macros with options to 'Edit' or 'Remove' each macro. • Click 'Edit'. This will display the edit screen for the macro. Make changes in the 'template' input field and click 'Save'. Templates are in HTML, not wiki markup. • Click 'Remove' to delete the macro.
RELATED TOPICS

Editing and Removing macros Enabling HTML macros Enabling the html-include Macro User Macros Writing Macros

Document generated by Confluence on Oct 10, 2007 11:54

Page 268

Enable The Flowchart Macro
This page last changed on Jul 06, 2007 by smaddox.

Installation
This plugin must be installed by a Confluence administrator. 1. 2. 3. 4. Install GraphViz Install Apache Ant If running on Windows, restart your computer Instructions to insert the GraphViz installation directory path into PATH variable depend on your operating system. Windows Users 1. Open the directory GraphViz is installed under and confirm the path. An example path is C: \Program Files\ATT\Graphviz\bin 2. Go to Start > Control Panel > System 3. Select the 'Advanced' tab, then 'Environment Variables' 4. Under 'System Variables', select the 'Path' variable 5. Select 'Edit' and view the 'Variable value' text 6. Confirm that path to the bin directory of GraphViz is appended to this string in the MS-DOS 8.3 standard and separated by a semicolon. An example might be ;C:\PROGRA~1\ATT\Graphviz\bin Linux, OS X or Unix Users 1. Open the directory GraphViz is installed under and confirm the path 2. Login as the user who runs Confluence or starts the Confluence service 3. Append the path to the bin directory of GraphViz to the 'Path' variable 5. Build the GraphViz plugin from source. 2. Stop Confluence 3. Open a command window in your Confluence install directory and go to the plugins directory 4. From the plugins directory, compile the GraphViz by running ant -Dlibrary=graphviz install 5. Start Confluence

Usage
See the Flowchart Macro in the User Guide.

Troubleshooting
Error Message flowchart: No useable executable name defined in graphviz.properties graphviz: No useable executable name defined in graphviz.properties spacegraph: No useable executable name defined in graphviz.properties Solution 1. Check that the system 'Path' variable includes a path to dot.exe, the executable file contained in the Graphviz bin directory. 2. Restart Confluence server

Document generated by Confluence on Oct 10, 2007 11:54

Page 269

Enabling HTML macros
This page last changed on Jun 25, 2007 by smaddox.

The {html} macro allows you to use HTML code within a Confluence page. The {html-include} macro allows you to include the contents of an HTML file in a Confluence page. CAUTION: Including unknown HTML inside a webpage 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. By default, the html macros are disabled. You should only turn on these macros if you trust all your users not to attempt to exploit them. To enable the HTML macros,

1. Go to the 'Administration Console' and click 'Plugins' in the left panel. This will display the installed plugins active for this Confluence installation. 2. Click' 'HTML macros', then click 'Enable Plugin'
RELATED TOPICS

Editing and Removing macros Enabling HTML macros Enabling the html-include Macro User Macros Writing Macros

Document generated by Confluence on Oct 10, 2007 11:54

Page 270

Enabling the html-include Macro
This page last changed on May 24, 2007 by rosie@atlassian.com.

The {html-include} macro allows you to include the contents of an HTML file in a Confluence page. The {html} macro allows you to include snippets of HTML within an existing page.

Why are they disabled?
Including unknown HTML inside a webpage 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. You should only turn on these macros if you trust all your users not to attempt to exploit them.

How do I enable them?
You will need: • Confluence 1.1 or later ° Instructions for 1.0 are included below • Global "Administrate Confluence" permissions Instructions: 1. 2. 3. 4. Go to the Administrative Console and click on the Plugins section Select the "HTML Macros" library Click the "Enable Library" link If they are not now automatically enabled, enable the specific macros you wish to use

If you are using Confluence 1.0.3a or earlier
You should consider upgrading. It's a free upgrade and there are hundreds of things that we have added, fixed or improved since then.

The instructions below are historical documentation that applies only to Confluence 1.0.3a and earlier. If you are using Confluence 1.1. or later, use the instructions above. Find the file wikiSubsystemContext.xml. It will be in the application's WEB-INF directory. You will find the following lines commented out.
<!-<!-<entry key="html-include"><ref local="htmlIncludeMacro"/></entry>--> <entry key="html"><ref local="html"/></entry>-->

Remove the XML comments as shown below, and restart Confluence. The macros should now be available.
<entry key="html-include"><ref local="htmlIncludeMacro"/></entry> <entry key="html"><ref local="html"/></entry>

Confluence 1.1 will allow the site administrator to enable and disable macros from within Confluence without editing any files.

Usage
Example - To embed an external page
{html-include:url=http://www.example.com}

Document generated by Confluence on Oct 10, 2007 11:54

Page 271

Troubleshooting the Gallery Macro
This page last changed on May 29, 2007 by rosie@atlassian.com.

Gallery Macro

Usage: Description: Example: Input: Output:

{gallery:columns=3\|title=Example Title} {gallery}

Forms a thumbnail gallery of all images attached to a page
{gallery:columns=3\|title=Example Title} {gallery}

optional: columns=<int n>|title=<title string> a thumbnail gallery with the number of columns specified (default 4) and a heading for the title parameter yes

Bundled with Confluence?:

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

Also see CONF-1737 Please note that gallery-ext.jar is available at CONF-6620

Document generated by Confluence on Oct 10, 2007 11:54

Page 272

Performance Tuning
This page last changed on Jun 18, 2007 by mryall.

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 this document: Requesting Performance Support

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.

Choice of Database
The embedded database that is provided with Confluence is meant only to be used for evaluation, or for low-volume Confluence sites. Once your site grows, you will almost 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.

Antivirus Software
Antivirus Software can greatly decrease the performance of Confluence. Antivirus Software that intercepts all access to the hard disk is particularly detrimental, and may even cause errors with Confluence. If possible configure your software to ignore the Confluence home directory, or at least its index directory.

Database Indexes
If Confluence is running slowly, the most likely cause is that there is some kind of bottleneck in the database. If you have the luxury of access to a DBA, it would be worthwhile having her tune the database specifically to the demands that your particular Confluence installation is placing on it. If you do not have a DBA, 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). Future versions of Confluence will allow you to tune the size of this cache from within the web application. In Confluence versions prior to 2.3 cache is entirely configured from the file confluence/WEB-INF/ classes/ehcache.xml. In Confluence 2.3 and above cache is Configured in confluence/WEB-INF/ classes/confluence-coherence-cache-config.xml (or confluence/WEB-INF/classes/confluence-

Document generated by Confluence on Oct 10, 2007 11:54

Page 273

coherence-cache-config-clustered.xml for clustered versions). More information about cache Coherence configuration can be found on Coherence cache reference. There is also cache status page provided with Confluence. It is not linked from anywhere in the interface, but administrative users can access it at the url http://your.confluence.install.example.com/ admin/cachestatistics.action. This page will show you the size of each cache, and its hit ratio. Important Caches • com.atlassian.confluence.core.ContentEntityObject should be set to at least 20-30% of the number of content entity objects (pages, comments, emails, news items) in your system. To find the number of content entity objects, use the query select count(*) from CONTENT. • com.atlassian.confluence.core.ContentEntityObject.bodyContents should be set to at least 20% of the number of content entity objects (pages, comments, emails, news items) in your system. To find the number of content entity objects, use the query select count(*) from CONTENT. • com.atlassian.confluence.security.PermissionCheckDispatcher.isPermitted() should be set to at least the number of concurrent users you expect to access Confluence at the same time • com.atlassian.confluence.user.DefaultUserAccessor.deactivatedUsers must be set to at least the number of users with USE_CONFLUENCE permission (don't worry, it only takes up a few bytes per user). To find an upper bound for this, use the query select count(*) from OS_USER, or if you have configured atlassian-user.xml to use the Hibernate repository, select count(*) from users. • com.atlassian.confluence.security.SpacePermission should be set to the number of space permissions in your deployment (a good rule of thumb is 20 times the number of spaces). You can find the number of space permissions using the query select count(*) from SPACEPERMISSIONS. The following are more specific performance problems that can be resolved from tuning the cache. "Edit Page" screen takes a long time to load If you're 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:
> select count(*) from SPACEPERMISSIONS

Now locate the cache entry for SpacePermissions in your ehcache.xml file. It looks like this:
<cache name="com.atlassian.confluence.security.SpacePermission" maxElementsInMemory="10000" eternal="false" timeToIdleSeconds="3600" timeToLiveSeconds="0" overflowToDisk="false" />

The equivalent for confluence-coherence-cache-config.xml would be:
<local-scheme> <scheme-name>cache:com.atlassian.confluence.security.CachingSpacePermissionManager.permissions</ scheme-name> <scheme-ref>default</scheme-ref> <high-units>10000</high-units> <expiry-delay>0s</expiry-delay> </local-scheme>

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.

Adjust Application Server Memory Settings
See Managing Application Server Memory Settings.

Document generated by Confluence on Oct 10, 2007 11:54

Page 274

Use A Web Server
For high-load environments, performance can be improved by using a web server such as Apache in front of the application server. There is a configuration guide to running Confluence behind Apache. When configuring your new web server, make sure you configure sufficient threads/processes to handle the load. This applies to both the web server and the application server connector, which are typically configured separately. If possible, you should enable connection pooling in your web server connections to the application server.

Document generated by Confluence on Oct 10, 2007 11:54

Page 275

Configuring a Large Confluence Installation
This page last changed on Jan 25, 2007 by noam@atlassian.com.

Deploying any application to several thousand users requires care and planning, expecially if those users are going to be relying on the application to get their work done.

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.

Configuring your Application Server, Web Server and Database
Because Confluence can be deployed in so many server combinations, we do not currently have guides on the best tuning parameters for each individual server. We will be happy to provide support, however. If you have any tuning parameters that you find particularly useful for Confluence instances, feel free to share them with other Confluence users in the Confluence Community space.

Things to Keep an Eye On
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)

Database Connection Pool
Confluence will need a database connection for each simultaneous user connection to the server. It is also a good idea to have 5-10 connections spare for Confluence internal processes such as backups, reindexing or daily notification jobs. Running out of pooled connections will cause the server to slow down as more users are waiting for a connection to be freed before starting their own request, and will eventually cause visible system errors as Confluence times out waiting for a database connection.

Document generated by Confluence on Oct 10, 2007 11:54

Page 276

If you are using Confluence's internal connection pool, you can increase the number of available connections by modifying the hibernate.c3p0.max_size property in {confluence_home}/confluencecfg.xml, and restarting Confluence. Make sure you have also configured your database to be able to support that many simultaneous connections.

Cache Sizes
The Performance Tuning page includes some useful rules of thumb for configuring the sizes of Confluence's internal caches.

Document generated by Confluence on Oct 10, 2007 11:54

Page 277

Confluence Performance Enhancement
This page last changed on Oct 25, 2005 by jnolen.

One of our current tasks is improving Confluence's performance, in time and space. This page lists some of the things we've done to speed up Confluence, and to reduce its memory footprint. • Creating Memory Leaks with Spring • Filtering Regular Expression Application

Document generated by Confluence on Oct 10, 2007 11:54

Page 278

Creating Memory Leaks with Spring
This page last changed on Oct 25, 2005 by jnolen.

I've spent the last few days looking at Confluence's memory footprint. The biggest win so far (besides turning off all the caches ) has been in Spring.

Confluence uses dependency injection everywhere, both for its services and to initialise short lived objects like xwork actions. It seems that Spring doesn't directly cater for the latter use, and is very easy to misuse if you aren't careful. Spring keeps track of dependencies between the beans it manages, so if you inject bean A into bean B, Spring will record the fact. Spring will call B.setA(A) of course, to perform the injection. Then it adds the name of B to the list of beans which depend on A, so that during shutdown it can remove B before A. Confluence autowires beans using the DefaultListableBeanFactory.autowireBeanProperties() method. This assumes that the bean is a singleton, and registers it. It also doesn't check whether the bean it is registering is already a dependent of the bean being injected. So the linked list of dependencies grows with every page view. Five hundred views go it up to almost 10MB! Spring does allow non-singleton beans, and it understands that they shouldn't be registered as dependents, but DefaultListableBeanFactory doesn't provide a way of autowiring a non-singleton bean. I created a new factory to do the job:
privatestatic class BucketListableBeanFactory extends DefaultListableBeanFactory { public BucketListableBeanFactory(ApplicationContext context) { super(context); } public void autowireNonSingletonBeanProperties(Object existingBean, int autowireMode, boolean dependencyCheck) throws BeansException { if (autowireMode != AUTOWIRE_BY_NAME && autowireMode != AUTOWIRE_BY_TYPE) { thrownew IllegalArgumentException("Just constants AUTOWIRE_BY_NAME and AUTOWIRE_BY_TYPE allowed"); } RootBeanDefinition bd = new RootBeanDefinition(existingBean.getClass(), autowireMode, dependencyCheck); bd.setSingleton(false); populateBean(existingBean.getClass().getName(), bd, new BeanWrapperImpl(existingBean)); } }

That's just a copy of autowireBeanProperties(), with the addition of a call to setSingleton(). Confluence's calisthenics and orthodontia is under way. Soon we'll be running light without overbyte!

Document generated by Confluence on Oct 10, 2007 11:54

Page 279

Filtering Regular Expression Application
This page last changed on Oct 25, 2005 by jnolen.

Confluence uses (mostly) regular expressions to convert wiki style markup into html. These are simple to write, fairly simple to compose (that is, you can add another regular expression which gets applied on top of the ones you already have), and most importantly, are forgiving. It wouldn't be too hard to write a grammar expressing the markup language, but when a user enters markup which the system doesn't understand, you need to fail softly – not throwing away any input, and not presenting the user with an error message. The mechanics of the markup process must be invisible to the user. Regular expressions can be expensive to apply – for instance, when viewing a 100 line page in Confluence 1.4, 17% of the CPU time used during the request is used in java.util.regex.Matcher.replaceAll(). A typical regular expression is
"(^|\\s)---(\\s|$)"

which finds
---

and replaces it with an emdash,
&#8212;

which renders as — . It's simple to see when this regular expression certainly doesn't apply to some wiki text – when that text doesn't include
---

You can do an analagous test for each of our many regular expressions, just look for a constant part of the regex. Of course, the existence of the constant part is a necessary, not a sufficient condition to know that the regex will match, but it works well enough to be worthwhile. A simple
wikiText.indexOf(constantPart) > 0

check before each application of a regular expression reduces that 17% to 9%, on a page of 100 lines which has bold and italic markup on every other line. It's interesting that replaceAll() doesn't try that itself. Presumably its optimised for the case when the string you give it does match the expression, which is probably the most common situation. A very simple but worthwhile saving. The only situation we need to worry about is if many of the lines in our pages have many types of markup on them, because then we not only pay for the replaceAll(), but also pay for the indexOf.

Document generated by Confluence on Oct 10, 2007 11:54

Page 280

How Adaptavist Runs Confluence
This page last changed on Sep 20, 2006 by brendan.patterson@gmail.com.

Key information about performance tuning and how Adapatavist runs many instances of Confluence. This was posted to the mailing list but not captured in the forums so I wanted to copy it here:

Confluence Performance Recommendations from Adaptavist
Hi, > 1) Opterons – for better or worse, we're solely an Intel shop at this point (i.e. I'll get some resistance going down the AMD path). It seems like the latest Woodcrest Xeons have caught up with the Opterons performance-wise (although AMD was smacking around Intel for a while before that). Have you the Woodcrest Xeons at all? (I'm guessing at this point you're probably just interested in pursuing an Opteron path but figured I'd ask.) We found the Opterons are perfect for running multithreaded apps - especially when running lots of Confluence / JIRA installs on a server in their own Resin containers. In addition, the Opterons use a less electrical power than their Intel counterparts which reduces our energy bills - for that reason we've not tried the Woodcrest chip yet. The chassis used for Opteron chips is also more established than the Woodcrest counterpart and is thus cheaper at the moment and has more options. Any dual-core will likely give better results, but you'll obviously need your OS and other software on the server to be set-up to take advantage of them. > 2) Resin vs. Tomcat – would you mind guessing at performance numbers from what you've seen? In a ton of Googling, it seems like people are saying that Tomcat was slow back with 4.x but got much faster with 5.x and even more with 5.5.x. See the comments in the first link. Resin, properly configured, is still faster In addition, it uses a lot less RAM (important when you have 50 web apps in their own containers). We spent a lot of time super-fine-tuning Resin (about 4 months if memory serves - huge thanks to Caucho and the chaps at BeJUG) to run Confluence very nicely indeed. I can't vouch for it's speed with regards to other apps. We've found Resin to be highly stable (when correctly configured) and it deals very well with that elusive Confluence memory leak (something you notice on a site like JavaPolis[1] with over 17,600 registered users). It's garbage collection, again when properly tuned, was better than Tomcat and we found many tasks easier to automate with Resin as compared to Tomcat. Admittedly, a lot of the reasons that we chose Resin for are geared to an environment where we're running up to 50 Confluences on a single server, each in their own web app. That's quite a different scenario to what you are doing where you maybe have one or two Confluences on a server. Although, having said that, we use the same set-up for our dedicated hosting (we're hosting some real BIG Confluence installs as you'll know if you followed the discussion about the import routine we've been working on) and it works great in that environment too. We use the commercial version of Resin[2] - it's much better than the OS version as it has fewer bugs, runs more smoothly and has some real nice features (read: absolutely critically essential for the sanity of our staff thus reducing our monthly bills for padded cells and therapy) for the type of environment we use it in. We also really liked Caucho's licensing of resin[3]: $500 per physical server with 2 cores (additional cores @ $500/core which is very reasonable) regardless of the number of Resin containers on that server. It should be noted that some of the stats you provided links to were done on Windows running Cygwin - hardly an ideal server environment The second link (with all the graphs that people like me understand) was far more representative. We run on SuSE Linux 10 EMT64 (or something like that whatever the latest version of their 64-bit OS is) so there's no Windows bloat getting in the way of the web apps, etc. > 3) Memory. I think I'll go for DDR667 and see if I can bump Confluence up to 2 GB. Is there ever a point where you can allocate too much RAM? (i.e. java and/or Confluence just don't handle tracking that many cached objects well) I think we're up to 16GB in most of our servers now. Confluence does enjoy more RAM (although containers such as Resin bring the overall RAM consumption down a fair bit - very noticeable on servers with 50 containers/apps). More RAM means more space to cache and longer gaps between forced GC. RAM allocation is also vital when it comes to the nightly backup (or "the dreadded backup hour" as we refer to it) - you can imagine the CPU and RAM spikes caused by 50 large Confluence installations all deciding to backup at the same time (roll on Confluence 2.3!)... Should you have too much memory, you can always run a Quake server on there :o)

Document generated by Confluence on Oct 10, 2007 11:54

Page 281

FYI: We also separate our database out on to a separate server. Best Regards, Guy [1]http://www.javapolis.com - at last year's conference the Belgian's were somewhat annoyed at the term "SOA" which is an obscenity over there. They were also less than happy about the spoons in sexual positions plastered all over Antwerp (and several thousand Javapolians wearing the conference t-shirts). So this year Stephan and the crew have decided to push the boundaries to hitherto unimaginable levels anyone who's seen the promo video will know exactly what I mean (and no, not the white painted bloke next to the urinal - the video goes waaaay beyond that - how they got James Gosling to... well, you'll have to wait and see) [2]http://www.caucho.com/resin-3.0/features/overview.xtp [3]http://www.caucho.com/sales/sales.xtp Dan will probably be along in the morning to correct any mistakes I've made -

Document generated by Confluence on Oct 10, 2007 11:54

Page 282

Memory usage and requirements
This page last changed on Oct 05, 2007 by dave@atlassian.com.

Managing Confluence's performance and memory usage really depends on what resources are available - Confluence will run faster if you give it lots of memory for its caches, but it should still be able to run quite well in low-memory environments, with the right tuning. Below are some tips on getting the most out of your Confluence site:

Increasing the amount of memory available to Confluence
See JIRA:Increasing JIRA memory for details on how to increase the memory available to web application servers typically used to run Confluence.

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. The default size of these caches will be reduced significantly in Confluence 1.5 (although this means that administrators of larger Confluence sites may need to configure the size of their caches to improve performance). To customise confluences cache to meet your needs, see cache tuning. To increase the amount of memory available to confluence, see allocating more memory to tomcat.

Mail error queue
Confluence keeps a copy of all emails that it failed to send within an internal error queue. In the event of intermittent failures such as network connectivity issues, the emails in this queue can be manually resent when the problem is fixed. Under certain circumstances, the mail queue can fill up with large objects. Since Confluence 1.4.1 the queue is regularly flushed, but if you get a lot of mail errors, you might get a spike in memory usage.

Attachments
The indexing of large attachments requires that the attachment be loaded into memory. In the case of large attachments, this can cause a temporary strain on the systems resources, and may result in indexing failing because the attachment could not be fully loaded into memory.

System backup / resort
The Confluence backup and resort process scales linearly with the size of data. This can have a significant impact on large Confluence instances where the amount of data exceeds the amount of available memory. If you are experiencing OutOfMemoryErrors during either a backup or restore, you with either need to move to per space backups or increase the memory allocated to Confluence. This is addressed in the upcoming Confluence 2.0. If you are attempting to restore a backup and encountering the OutOfMemoryError, how much memory will you need to make it work? A good rule of thumb is to have a look at the size of the entities.xml file in your backup. This file contains all of the data Confluence will be loading, so at least that much is required. Add another 64-128Mb to ensure that Confluence has enough memory to load and function and that should be enough. This problem has been resolved in Confluence post 1.4.x. To increase the amount of memory available to confluecne, see allocating more memory to tomcat.

Document generated by Confluence on Oct 10, 2007 11:54

Page 283

Known issues that we do not have control over.
There are also some memory issues we don't have any control over. For example, • There's a memory leak in the Oracle 10g JDBC drivers. Not much we can do about that. • one customer found a rather nasty memory leak that appeared to originate inside Tomcat 5, but only using the IBM JDK on PowerPC. If you're having problems that appear to be a memory leak, file an issue on http://support.atlassian.com. Our memory profiler of choice is YourKit, so if you can get a memory dump from that tool showing a leak

Confluence is taking long periods of time to respond to some actions
A common cause of random pauses in Confluence is the jvm running garbage collection. To determine if this is what is happening, enable verbose garbage collection and look at how long java is taking to free up memory. If the random pauses match when java is running its garbage collection, garbage collection is the cause of the pause. Verbose garbage collection will generate log statements that indicate when java is collecting garbage, how long it takes, and how much memory has been freed. To enable gc logging, start Confluence with the option -XX:+PrintGCDetails -XX:+PrintGCTimeStamps -verbose:gc -Xloggc:gc.log. Replace gc.log with an absolute path to a gc.log file. For example, with a Windows service, run:
tomcat5 //US//Confluence ++JvmOptions="-XX:+PrintGCDetails -XX:+PrintGCTimeStamps -verbose:gc Xloggc:c:\confluence\logs\gc.log"

or in bin/setenv.sh, set:
export CATALINA_OPTS="$CATALINA_OPTS -XX:+PrintGCDetails -XX:+PrintGCTimeStamps -verbose:gc Xloggc:${CATALINA_BASE}/logs/gc.log"

If you modify bin/setenv.sh, you will need to restart Confluence for the changes to take effect. What can you do to 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 minimize the impact that garbage collection has on the running application.

Document generated by Confluence on Oct 10, 2007 11:54

Page 284

java.util.zip.ZipFile.open causes OutOfMemoryError for large zip files
This page last changed on Nov 30, 2006 by ivan@atlassian.com.

Problem
For large backup zip files (bigger than 1GB) OutOfMemoryErrors can occur during restore, even though the maximum heap size is way above this value. The error will look something like this:
Cause: javax.servlet.ServletException: Servlet execution threw an exception at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:275) caused by: java.lang.OutOfMemoryError at java.util.zip.ZipFile.open(Native Method)

However, when looking at the system information you will find that there is still a lot of memory available on the heap.
Memory Information: Total Memory: 2480 MB Free Memory: 2385 MB Used Memory: 95 MB

Solution
The problem seems to be a bug in Java. The method java.util.zip.ZipFile.open does not actually use the allocated memory of the heap, it maps the entire zip file into virtual memory outside the heap. If you run into this problem, you should try to reduce your heap size to about 600MB and try the restore again. This seems to accord with the experience of other developers: if you set a small value for max heap size, it works correctly, but if you specify too large a value, then OutOfMemoryErrors occur. There is no obvious relationship between the max heap size, the size of the zip file, and the computer's available memory. With a max heap size less than about 600 MB, errors never occur. Large than that, and they occur. A 1.2 GB zip file always opens correctly, but a 1.4 GB one never does (if the max heap size is larger than 600 MB). I have tested this on computers with both 256 MB of RAM and 2 GB of RAM, and the behavior is nearly identical.

Related topics
Allocating more memory

Document generated by Confluence on Oct 10, 2007 11:54

Page 285

Requesting Performance Support
This page last changed on Jun 18, 2007 by mryall.

If you are having performance issues with Confluence, and the advice on Performance Tuning has not helped, you can always ask us for help. Performance issues can be hard to diagnose, however, and we often spend a lot of time going back and forth looking for more information about what may be causing Confluence to be slow for you. The best way to get a speedy resolution to your issue is to provide this information up front. Please gather all of the information listed below and include it in your support request, even if you think you have a good idea what's causing the problem. That way we don't have to ask for it later.

System Information
Confluence Server • Take a screenshot of Confluence's Administration # System Information (or save the page as HTML) • Take a screenshot of Confluence's Administration # Cache Statistics (or save the page as HTML) • Find out the exact hardware Confluence is running on ° How many CPUs? What make and model? What MHz? ° How much memory is installed on the machine? ° How much memory is assigned to Confluence's JVM? (i.e. what are the -Xmx and -Xms settings for the JVM?) ° What other applications are being hosted on the same box? Confluence Content • How many users are registered in Confluence? • How many spaces are there in your Confluence server? • Approximately how many pages? (Connect to your database and perform 'select count(*) from content where prevver is null and contenttype = 'PAGE'') 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?

Document generated by Confluence on Oct 10, 2007 11:54

Page 286

° 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?

Access logs • Enable 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. Profiling and Logs • Enable Confluence's built-in profiling for long enough to demonstrate the performance problem using Troubleshooting Slow Performance Using Page Request Profiling. ° If a single page is reliably slow, you should make several requests to that page ° If the performance problem is intermittent, or is just a general slowness, leave profiling enabled for thirty minutes to an hour to get a good sample of profiling times • Find Confluence's standard output logs (which will include the profiling data above). Take a zip of the entire logs directory. • Take a thread dump during times of poor performance CPU Load • If you are experiencing high CPU load, please install the YourKit profile and attach two profiler dumps taken during a CPU spike. If the CPU spikes are long enough, please take the profiles 30-60 seconds apart.

Next Step
Open a ticket on http://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.

Document generated by Confluence on Oct 10, 2007 11:54

Page 287

Troubleshooting Slow Performance Using Page Request Profiling
This page last changed on Mar 12, 2007 by david.soul@atlassian.com.

If Confluence is responding slowly, an internal timing trace of the slow page request can help to identify the cause of the delay.

Profiling An Activity
You will need access to the Confluence server to view a profile. 1. Locate Confluence's standard screen output, or stdout, on the Confluence server. Users running Confluence as a Windows service may have this logged to the /logs/stdout.log file under the Confluence install directory, while users running Confluence using startup.bat under Windows have stdout written to the command prompt window. Enable profiling using ?profile=on 2. Enable profiling by accessing any page in your Confluence instance. Modify the URL by appending ?profile=on to the end of the URL for static pages, or &profile=on if the URL is dynamic and already has parameters. For example, if your Dashboard link is
http://localhost:8080/dashboard.action

You would manually add ?profile=on to the end of the URL and visit
http://localhost:8080/dashboard.action?profile=on

3. 4.

5. 6.

Profiles for every page hit, for all users, will now be logged to stdout until Confluence is restarted. Note that each time a user visits a link, a single profile is printed. Confirm that profiles are being printed to stdout. Perform the activity that is resulting in unusually slow response time and copy the profile for that action. The relevant profiles are for 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. If you were instructed to profile your instance by Atlassian technical support, attach all relevant profiles to your support ticket. Turn profiling off again by appending ?profile=off to the end of the URL for static pages, or &profile=off if the URL is dynamic and already has parameters. For example, if your Dashboard link is
http://localhost:8080/dashboard.action

You would add ?profile=off to the end of the URL and visit
http://localhost:8080/dashboard.action?profile=off

7. Confirm that profiles are no longer being printed to stdout

Example Profile
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()) ...

Document generated by Confluence on Oct 10, 2007 11:54

Page 288

Related Topics
Requesting Performance Support

Document generated by Confluence on Oct 10, 2007 11:54

Page 289

Profiling using the YourKit Plugin
This page last changed on Sep 18, 2007 by don.willis@atlassian.com.

Introduction
There is a plugin for Confluence 2.2 and later which allows easy profiling using the YourKit profiler. No license is required to generate a memory or CPU snapshot, but you will need at least an evaluation license to analyse the results. JIRA also has a plugin to profile JIRA's CPU and memory usage with YourKit.

Configuring YourKit in your JVM
Download YourKit 6.0 for your platform, and install it by following the installation instructions. The following instructions apply to Confluence Standalone and Tomcat installations with Sun JDK 1.5. They should be easily applicable to other application servers and JVMs, however. The YourKit documentation covers this in more detail. Windows configuration On Windows, add to your PATH environment variable the bin/win32/ directory underneath the YourKit installation directory. For example, you might add "C:\Program Files\YourKit Java Profiler 6.0.12\bin \win32" to your PATH, via Control Panel, System, Advanced, Environment Variables. To configure Confluence's JVM to use the YourKit agent, you need to add a parameter to JAVA_OPTS in the bin/setenv.bat file in your Confluence application directory. This file controls the startup parameters for Tomcat, so you'll need to restart it after making the changes. Add the 'agentlib' parameter to the end like this:
set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx256m -agentlib:yjpagent

Linux/Mac OS X configuration On Unix-based systems, include the installation directory in the library path environment variable, as shown below: • For the Mac: export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/path/to/yourKitAgent • For other Unix-based systems: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ yourKitAgent In general, to configure a Sun 1.5 JDK, you add the agentlib parameter:
java -agentlib:yjpagent ...

You can add this to Tomcat's bin/setenv.sh like this:
JAVA_OPTS="-Xms128m -Xmx256m $JAVA_OPTS -Djava.awt.headless=true -agentlib:yjpagent "

Performance impact
Running YourKit can have detrimental effects on performance. To minimize performance problems use the following modifications to the agentlib parameter:
-agentlib:yjpagent=disablecounts,disablealloc,disablej2ee

See also "Profiling overhead: how to reduce or avoid" in the YourKit documentation.

Installing the YourKit plugin
Download the plugin and upload it into Confluence through the Administration, Plugins page.

Document generated by Confluence on Oct 10, 2007 11:54

Page 290

A new menu option will appear under the 'Administration' heading. Click it and you should see the options to take a memory or CPU snapshot.

YourKit Profiling menu item This profiler dump will be saved to a local temp directory, and the path shown once it is complete. For the CPU snapshot, this will take at least 30 seconds. For the memory snapshot, 10-15 seconds.

You can take either a memory or CPU snapshot

Why would I do this?
Analysing a profiler dump enables Atlassian Support (or you, if you are interested) to see exactly what is happening in your application: what classes are using the memory, what is using CPU and so on. This can help us debug tricky performance problems which would otherwise be impossible to analyse remotely. Take a CPU snapshot if: • Confluence is sometimes unresponsive • Pages take a long time to load • Confluence's CPU usage is peaking. Take a memory snapshot if: • Confluence's memory usage is higher than you expect • You are getting OutOfMemoryError's in your logs.

Plugin source code
The source code for this Confluence plugin is available from Subversion and browseable in Fisheye. To rebuild the JAR attached to this page, you need to run maven jar, and then extract the YourKit controller dependency (yjp-controller-api-redist-6.0.14.jar) and include that in the 'mashed' JAR too.

Document generated by Confluence on Oct 10, 2007 11:54

Page 291

Recognised System Properties
This page last changed on Jul 24, 2007 by smaddox.

Confluence has a small number of obscure configuration and debugging settings that can be enabled through Java system properties. System properties are usually set by passing the -D flag to the Java virtual machine in which Confluence is running.

Property confluence.home

Since 1.0

Possible Values Any filesystem path

Module... Confluence and atlassian-config

Effect If this system property is set, Confluence will ignore the contents of the confluenceinit.properties file, and use this property as the setting for the Confluence Home directory. Enables additional debugging options that may be of use to Confluence developers. Do not enable this flag on a production system. By default, Confluence will only run its database schema update when it detects that it has been upgraded. This flag will force Confluence to perform the schema update on system startup. Confluence will normally log a severe error message if it detects that DEBUG level logging is enabled (as DEBUG logging generally causes a significant degradation in system performance). Setting this property will

confluence.devmode1.0

true

Confluence

atlassian.forceSchemaUpdate 1.0

true

atlassian-config

confluence.ignore.debug.logging 1.0

true

Confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 292

suppress the error message. confluence.i18n.reloadbundles 1.0 true Confluence Setting this property will cause Confluence to reload its i18n resource bundles every time an internationalised string is looked up. This can be useful when testing translations, but will make Confluence run insanely slowly. Setting this property will disable conditional get and expires: headers on some web resources. This will significantly slow down the user experience, but is useful in devlopment if you are frequently changing static resources and don't want to continually flush your browser cache.

atlassian.disable.caches 2.4

true

atlassian-plugins, atlassian-cacheservlet

Document generated by Confluence on Oct 10, 2007 11:54

Page 293

Scheduled Jobs
This page last changed on Oct 04, 2007 by smaddox.

This page provides a quick overview of the jobs that are scheduled to run regularly in your Confluence instance.

Job Name backupJob mailQueueFlushJob referralQueueFlushJob taskQueueFlushJob cleanTempDirectoryJob dailyReportJob clearOldMailErrorsJob

Description performs a site backup sends notifications that have been queued up referrals to Confluence pages are queued up. This job writes this referrals to the database flushes the task queue this cleans up temp files created in Confluence home temp directory (created by exports etc.) sends out an email summary of all changes in Confluence to all subscribers notifications that fail to send due to errors are added tot he mail error queue. This job resets this clear periodically. each content update to Confluence needs to be updated in index so search results are accurate. This job flushes changes to the index. index optimization is performed to compact the index and maintain searching performance. This task is expensive and does not need to be performed too regularly. If you see Confluence performance deteriorate around 3pm, you can try scheduling this job for 3am only and check that search performance remains reasonable. this job is responsible for periodically triggering an Index Queue clean to ensure that size of the index queue does NOT grow indefinately. polls POP accounts on all spaces that have them configured. ensures that only one cluster is ever writing to the database at one time. For non-clustered instances, this job is still useful for alerting customers that have accidentally deployed two instances of Confluence against the same database.

indexQueueFlushJob

indexOptimizerJob

indexQueueCleanJob

mailPollJob clusterSafetyJob

Document generated by Confluence on Oct 10, 2007 11:54

Page 294

Search
This page last changed on Jun 22, 2007 by smaddox.

Setup Confluence To Index External Sites Setup External Search Tool To Index Confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 295

Setup Confluence To Index External Sites
This page last changed on May 07, 2007 by david.soul@atlassian.com.

Confluence Indexing External Sites
Confluence cannot easily index external sites due to technical reasons, but there are two alternatives: 1. Embed External Pages Into Confluence 2. Replace Confluence Search

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.

Embed External Pages Into Confluence
If you only have a small number of external sites to index, you may prefer to enable the HTML-include Macro and use it embed the external content inside normal Confluence pages.

Replace Confluence Search
Use your own programmer resources to replace Confluence's internal search with a crawler that indexes both Confluence and external sites. This advanced option is easier than modifying the internal search engine. It requires removing Confluence internal search from all pages and replacing the internal results page with your own crawler front-end. 1. Setup a replacement federated search engine to index the Confluence site, as well as your other sites, and provide the results that way. You would need to host a web crawler, such as these opensource crawlers. Note that you can perform a search in Confluence via the remote API 2. Replace references to the internal search by modifying the site layout so that it links to your search front-end 3. Host another site containing the search front-end. You may wish to insert it into a suitable context path in your application server so that it appears to be from a path under Confluence. Tomcat sets Confluence's paths from the Confluence install\confluence\WEBINF\web.xml file.

Document generated by Confluence on Oct 10, 2007 11:54

Page 296

Setup External Search Tool To Index Confluence
This page last changed on Jul 06, 2007 by david.soul@atlassian.com.

Any web crawler can be configured to index Confluence content. If a login is required to 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.

Document generated by Confluence on Oct 10, 2007 11:54

Page 297

Security
This page last changed on Feb 01, 2006 by vidya.

Adding SSL for Secure Logins and Page Security Anonymous Access to Remote API Enabling or Disabling Public Signup Hiding External Links From Search Engines Hiding the People Directory Managing External Referrers ° Excluding external referrers ° Hiding external referrers • User Email Visibility • • • • • •

Document generated by Confluence on Oct 10, 2007 11:54

Page 298

Adding SSL for Secure Logins and Page Security
This page last changed on Sep 05, 2007 by smaddox.

This document describes how to configure Confluence to use a HTTPS encrypted secure socket layer for user logins and page data. Unencrypted confidential data within Confluence may be intercepted by an attacker. To secure user logins, you can enable access via HTTPS (HTTP over SSL), and require its use for pages where passwords are sent. In some cases where issue data is sensitive, all pages can be set to be accessed over HTTPS. Enabling SSL access is different for each application server, but specifying which pages to require protection for is generic. This document is specific to Tomcat, the default application server shipped with Confluence.

Adding Secure User Logins
Adding HTTPS requires a valid SSL certificate. If you have a Certificate prepared, skip to the 'Modify the <INSTALL>/conf/server.xml File' section.

Creating A New SSL Certificate
On Windows, perform the following at the command prompt:
"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA

Or on other platforms, perform the following at the command prompt:
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

Some questions will be asked, including a password for the certificate (the default is 'changeit'). Please note down what you choose, as it will be used in the next step. Modify the <INSTALL>/conf/server.xml File In the confluence directory, open the conf/server.xml file and insert one of the following just after the closing </Engine> tag: 1. For users of Confluence 2.2 or later: Open conf/server.xml, uncomment the lines:
<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" URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>" />

Or for users of Confluence 2.1.x or earlier, add or uncomment the following lines:
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8443" minProcessors="5" maxProcessors="75" enableLookups="true" acceptCount="100" debug="0" scheme="https" secure="true" useURIValidationHack="false" disableUploadTimeout="true" URIEncoding="UTF-8"> <Factory className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory" clientAuth="false" protocol="TLS" keystorePass="<MY_CERTIFICATE_PASSWORD>" /> </Connector>

2. Change <MY_CERTIFICATE_PASSWORD> to the password you entered for the certificate when you generated it.

If you have a Certificate Prepared
If you just created your new Certificate or your existing one is in the default location, skip to the 'Testing SSL' section. By default, Tomcat will look for the certificates in C:\Documents and Settings \\#CURRENT_USER#\.keystore on Windows or ~/.keystore on Unix. If your Certificate is not in this

Document generated by Confluence on Oct 10, 2007 11:54

Page 299

location, you will need to update your <INSTALL>/conf/server.xml file as outlined below, so that Tomcat can find it. Advanced users who require an official CA-issued key pair for their Certificate can find instructions in the Tomcat documentation. 1. For users of Confluence 2.2 or later: Open conf/server.xml, add the keystoreFile="<MY_CERTIFICATE_LOCATION>" parameter to the Connector tag as shown below:
<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" URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>" keystoreFile="<MY_CERTIFICATE_LOCATION>" />

Or for users of Confluence 2.1.x or earlier, change the <Factory> tag to following:
<Factory className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory" clientAuth="false" protocol="TLS" keystoreFile="<MY_CERTIFICATE_LOCATION>" keystorePass="<MY_CERTIFICATE_PASSWORD>" />

2. Change <MY_CERTIFICATE_LOCATION> to the path of the Certificate.

Testing SSL
Restart Tomcat and access your instance on https://<MY_BASE_URL>:8443/ For more detailed information on setting up SSL with Tomcat (including additional configuration options), have a look at Tomcat 4 SSL Howto or Tomcat 5.5 SSL Howto. Although HTTPS is now activated and available, the old HTTP URLs (http://localhost:8080) are still available. In most situations one wants these URLs to continue working, but for some to redirect to their HTTPS equivalent. If you have changed the port that the SSL connector is running on from the preconfigured 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. To configure which URL's you want secured, edit the confluence/WEB-INF/web.xml file and add to the end the following declaration:
<security-constraint><web-resource-collection><web-resource-name>Login and Restricted Space URLs</web-resource-name><url-pattern>/login.action</url-pattern></web-resource-collection><userdata-constraint><transport-guarantee>CONFIDENTIAL</transport-guarantee></user-data-constraint></ security-constraint>

Note that the example above specifies a url-pattern for the login URL /login.action. This means that whenever a user tries to access the unprotected version of the login page, they will be redirected automatically to the secured version of it. If you want to protect individual spaces, there isn't a complete way of doing this at the moment. You can add a pattern like this:
<security-constraint><web-resource-collection><web-resource-name>Login and Restricted Space URLs</ web-resource-name><url-pattern>/login.action</url-pattern><url-pattern>/display/SALARIES/*</ url-pattern></web-resource-collection><user-data-constraint><transport-guarantee>CONFIDENTIAL</ transport-guarantee></user-data-constraint></security-constraint>

This will redirect all URL's for page views in the SALARIES space. This does not however, protect pages that are accessed via a URL like /pages/viewpage.action?pageId=123. Confluence generates these types of URL's for pages that have non-ASCII characters in the title. Hence this is not a complete solution. If you want to protect all pages and spaces, use:

Document generated by Confluence on Oct 10, 2007 11:54

Page 300

<security-constraint><web-resource-collection><web-resource-name>Restricted URLs</web-resourcename><url-pattern>*.action</url-pattern></web-resource-collection><user-data-constraint><transportguarantee>CONFIDENTIAL</transport-guarantee></user-data-constraint></security-constraint>

Once this change is made, restart Confluence and access http://localhost:8080. You should be redirected to https://localhost:8443/login.action. There does not seem to be an easy way to make subsequent pages revert to HTTP after logging in via HTTPS - see JRA-7250 Note for users of Confluence versions prior to 2.2 You are required to configure a Realm, even though the security-constraint above does not access it. Add this realm tag inside the Engine tag:
<Engine ... <Realm className="org.apache.catalina.realm.MemoryRealm" /> ... </Engine>

You can protect other paths as necessary, but be aware that if attachments are protected, they will not be downloadable from Internet Explorer (see this issue).

Document generated by Confluence on Oct 10, 2007 11:54

Page 301

Anonymous Access to Remote API
This page last changed on Jun 25, 2007 by smaddox.

Sites may wish to disable anonymous access to the remote API to make it harder for malicious users to write 'bots' that perform bulk changes to the site. If you wish to enable the Remote APIs but do not want anonymous users to access Confluence remotely, you can disable anonymous access from the Administration Console. To disable anonymous access to Remote APIs,

1. 2. 3. 4.

Go to the 'Administration Console' and click on 'General Configuration' in the left panel. Click 'Edit' at the bottom of the 'Options and Settings' screen. Select 'Off' beside 'Anonymous Access to API'. 'Save' your changes.

RELATED TOPICS

Adding SSL for Secure Logins and Page Security Anonymous Access to Remote API Enabling or Disabling Public Signup Excluding external referrers Hiding External Links From Search Engines

Document generated by Confluence on Oct 10, 2007 11:54

Page 302

Enabling or Disabling Public Signup
This page last changed on Jun 25, 2007 by smaddox.

Enabling 'Public Signup' allows users to sign themselves up to the site. If you want to restrict your site to a particular set of users, you may want to disable 'Public Signup'. In this instance, site administrators can add new users from the Administration Console. To enable or disable 'Public Signup',

1. 2. 3. 4.

From the 'Administration Console' click on 'General Configuration' in the left panel. This will display the 'Options and Settings' screen. Click 'Edit'. Beside 'Public Signup', select 'On' to enable Public Signup. Select 'Off' to disable it. Click 'Save'.

RELATED TOPICS

Adding a Group Adding a New User Adding or Removing a User from a Group Adding SSL for Secure Logins and Page Security Anonymous Access to Remote API

Document generated by Confluence on Oct 10, 2007 11:54

Page 303

Hiding External Links From Search Engines
This page last changed on Jun 25, 2007 by smaddox.

Hiding external links from search engines helps to discourage spammers from posting links on your site. If you turn this option on, any urls inserted in pages and comments will be given the "nofollow" attribute, which prevents search engines from following them. Shortcut links and links to other pages within Confluence are not affected. To hide external links from search engines,

1. 2. 3. 4.

Go to the 'Administration Console' and click on 'General Configuration' in the left panel. This will display the 'Options and Settings' screen. Click 'Edit'. Select 'On' beside 'Hide External Links From Search Engines'. 'Save' your changes.

RELATED TOPICS

Adding SSL for Secure Logins and Page Security Anonymous Access to Remote API Enabling or Disabling Public Signup Excluding external referrers Hiding External Links From Search Engines

Document generated by Confluence on Oct 10, 2007 11:54

Page 304

Hiding the People Directory
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

The People Directory provides a list of all users in your Confluence system. If you need to disable the People Directory set the following system properties on your application server command line: • To disable the People Directory foranonymous users,
-Dconfluence.disable.peopledirectory.anonymous=true

• To disable the People Directory entirely,
-Dconfluence.disable.peopledirectory.all=true

These two properties are available in Confluence 2.5.2 and later. Note that the 'People Directory' link will still appear on the dashboard, so you will need to modify the following file to remove the link: /decorators/global.vmd (In Confluence Standalone, this is located in the confluence directory)

Document generated by Confluence on Oct 10, 2007 11:54

Page 305

Managing External Referrers
This page last changed on Jun 25, 2007 by smaddox.

An external referrer is any site that links to your Confluence instance. By default, external referrers for a page are listed under 'Incoming Links' under the 'Info' tab of the page. Here's how you can manage your external referrers: 1. Hide all external referrers : By default, Confluence lists all external referrers under the 'Info' tab of a page. If you turn this option on, external referrers will not be listed here. 2. Specify which external referrers to exclude : You can decide which referrers you want to exclude from being displayed on your site.
RELATED TOPICS

Adding SSL for Secure Logins and Page Security(Confluence 2.6) Anonymous Access to Remote API(Confluence 2.6) Enabling or Disabling Public Signup(Confluence 2.6) Excluding external referrers(Confluence 2.6) Hiding External Links From Search Engines(Confluence 2.6)

Document generated by Confluence on Oct 10, 2007 11:54

Page 306

Excluding external referrers
This page last changed on Jun 25, 2007 by smaddox.

Excluding external referrers prevents them from being displayed anywhere on your site. There are two instances where you may want to do this: 1. If you are running a Confluence installation that is open to public: In a site that is open to public, one unfortunate problem is that malicious sites can "spam" a page's incoming links statistics. This is usually done to get the site's URL to appear in the sidebar. By adding these sites to the 'excluded referrers' list, you can prevent them from being listed on your site. 2. If Confluence is installed on a server with multiple domain names or IP addresses: Confluence will consider any url originating from the domain name where Confluence is installed as an internal link. However, if Confluence is installed on a server with multiple domain names or IP addresses, you will need to add the other domain name prefixes to this list to let Confluence know that any links from these domains should not be considered external links. You need to be a site administrator and know the url of the site to add it to the excluded referrers list. To add a url to the excluded referrers list,

1. Go to the Administration Console and click on 'Manage External Referrers' in the left panel. 2. Add the URL to the 'Excluded External Referrer Prefixes' section. You must include 'http://' at the front of the URL. You can add more than one url by separating each new url with a new line. Once saved, all incoming links URLs that match the blocked list will no longer be recorded. Referrer URLs are blocked if they start with any of the URLs in the exclusion list. So http://evilspamsite.blogspot.com will also match http://evilspamsite.blogspot.com/nastypage.html
RELATED TOPICS

Adding SSL for Secure Logins and Page Security Anonymous Access to Remote API Enabling or Disabling Public Signup Excluding external referrers Hiding External Links From Search Engines

Document generated by Confluence on Oct 10, 2007 11:54

Page 307

Hiding external referrers
This page last changed on Sep 17, 2007 by don.willis@atlassian.com.

By default, Confluence lists all external referrers under the 'Info' tab of a page. You can configure Confluence to hide referrers from this view. To hide external referrers,

1. Go to the 'Administration Console' and click on 'Manage Referrers' in the left panel. 2. Click 'Off' beside 'External Referrers'
RELATED TOPICS

Adding SSL for Secure Logins and Page Security Anonymous Access to Remote API Enabling or Disabling Public Signup Excluding external referrers Hiding External Links From Search Engines

Document generated by Confluence on Oct 10, 2007 11:54

Page 308

User Email Visibility
This page last changed on Jul 25, 2007 by smaddox.

Confluence provides three options for email address privacy which can be configured by a site 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. • Private: only site administrators can see the email addresses. Note that, if you select Private, email addresses will not be available in the 'User Search' popup (e.g. when setting Page Restrictions). Anyone in the confluence-admininistrators group will still be listed (with their email address) on the administrators page, although their addresses will be masked. To configure user email visibility,

1. 2. 3. 4.

From the 'Administration Console' click on 'General Configuration' in the left panel. This will display the 'Options and Settings' screen. Click 'Edit'. Beside 'User email visibility', select one of the options: 'Public', 'Masked', or 'Private'. 'Save' your changes.

Screenshot : email visibility

RELATED TOPICS

Adding SSL for Secure Logins and Page Security Anonymous Access to Remote API Enabling or Disabling Public Signup Excluding external referrers Hiding External Links From Search Engines

Document generated by Confluence on Oct 10, 2007 11:54

Page 309

Spam Prevention (Captcha)
This page last changed on Jun 02, 2007 by ernest@atlassian.com.

Captcha Configuration
If your Confluence site is open to the public you may find that automated spam is being added, in the form of comments or new pages. You can configure Confluence to deter automated spam by asking users to prove that they are human before they are allowed to: • • • • Sign up for an account Add a comment Create a page Edit a page

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. When Captcha is enabled, users are required to read some text from an image (example on the right) and type it into the form. When it is 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. You can choose which users don't have to complete Captchas. You can exempt signed-in users (they will have completed a Captcha when they signed up), or members of particular groups. You can also customise the Captcha image (see Advanced Configuration below). To enable captchas for Confluence, You need to be a site administrator to enable captcha.

1. Click on the 'Administration' link in the top right corner of the screen. 2. Choose Spam Configuration' from the Configuration menu on the left. 3. Click on 'Change Space Logo' in the left panel under the heading 'Look and Feel'. This will bring up a new screen. 4. Turn on captchas by clicking the 'ON' link. To disable captcha for certain groups, By default captchas will not be shown to registered users. Only anonymous users will have to perform the captcha test when creating comments or editing pages. If you don't trust all registered users, captchas can also be disabled for only a certain group/groups of users.

1. Select the 'Members of Group' and click the 'Save' button. 2. Use the 'Group Picker' in the Groups menu and click the 'Add' button to add a single or multiple groups to the list. 3. To remove a group from the list, click the 'Remove Symbol' behind the group name.

Document generated by Confluence on Oct 10, 2007 11:54

Page 310

Take me back to [Confluence 2.0 Home]

Advanced Configuration
You can also control which type of image is presented to your users. This requires editing the applicationContext.xml file which you can find in the confluence/WEB-INF/classes directory under your Confluence installation. The section of this file which configures Captchas looks like this:
<!-- Image capture service --> <!-- this is a very easy captcha generator. If you want difficult captures, uncomment the DefaultGimpyEngine below, or use an engine class from http://jcaptcha.sourceforge.net --> <bean id="captchaEngine" class="com.atlassian.confluence.security.ConfluenceCaptchaEngine" autowire="byName"/> <!--bean id="captchaEngine" class="com.octo.captcha.engine.image.gimpy.DefaultGimpyEngine" autowire="byName"--> <bean id="captchaManager" class="com.atlassian.confluence.security.DefaultCaptchaManager" autowire="byName"/>

You can replace the 'captchaEngine' class with any text-based engine from jcaptcha.

Document generated by Confluence on Oct 10, 2007 11:54

Page 311

Troubleshooting slow search performance and "Too many open files" problem
This page last changed on Mar 16, 2007 by dave@atlassian.com.

The purpose of this document is to provide a workaround for customers using Confluence version 2.2.x and who are experiencing slow search performance and/or Too many open files error in their logs. This problem has been properly addressed as of Confluence 2.3. If upgrading is an option for you, we recommend upgrading to the latest stable version.

The workaround
The workaround for this problem involves two steps. 1. Reducing the frequency of index optimisation Index optimisation is performed over your entire search index periodically to maintain good search performance. However, this process will lock down the index for the entire duration that it occurs. Searching will not be possible during this time. For small Confluence instances with small indexes, optimisation time is negligible. However, for larger instances, where optimisation is potentially expensive to perform, it could cause a noticeable inconvenience for users. In Confluence 2.2.x, index optimisation is scheduled to occur every time the index queue is flushed (every minute). Optimisation does not need to performed this regularly. To fix this: 1. Extract DefaultConfluenceLuceneIndexManager.zip to your confluence/WEB-INF/classes/com/ atlassian/confluence/search/lucene directory. This patch will allow you to specify a JVM parameter to adjust the frequency of optimization. For example if you want it to occur on every 20th flush of the index queue start Confluence with this JVM parameter:
-Dconfluence.optimize.index.modulo=20

Setting it back to 1 will revert back to normal behaviour (optimize on every flush). 2. Restart Confluence 2. Apply a patched bonnie jar To address the Too many open files issue, you need to download the patched bonnie jar attached to this issue: http://jira.atlassian.com/browse/CONF-7401. Copy the jar to your {[confluence/WEB-INF/ lib}} directory and remove the old one. Now restart and rebuild the index. If are still experiencing problems after this, please file a support request at http://support.atlassian.com and we'll investigate the issue further.

Document generated by Confluence on Oct 10, 2007 11:54

Page 312

User Management
This page last changed on Feb 01, 2006 by vidya.

• Confluence User Management ° Adding a Group ° Adding a New User ° Adding or Removing a User from a Group ° Changing Usernames ° Editing User Details ° Global Groups Overview ° Global Permissions Overview ° Migrating to new User Management ° Removing a Group ° Removing a User ° Setting up Anonymous Access ° Viewing members of a group • How to Improve User Search Performance — If your Confluence instance contains thousands of user accounts and you are experiencing performance issues when searching for users, the following migration guide is for you. • Integrating with Crowd • JIRA User Management ° Delegate user management to use JIRA logins - Revert from JIRA to internal user management ° JIRA User Management FAQ • LDAP User Management ° Activating External User Management ° Add LDAP Integration - Automatically Adding LDAP users to the confluence-users Group - Customising atlassian-user.xml ° Add LDAP Integration For User Authentication Only ° atlassian-user.xml reference ° Changes in osuser.xml from 1.0.3a to 1.1.x ° Configuring multiple LDAP repositories ° Confluence Caching OSUser Provider ° Importing LDAP Users ° LDAP FAQ - Connect to LDAP via SSL ° Troubleshooting the "Not Permitted" Screen under LDAP Integration - Cannot login with Confluence admin account • Migrating users from Confluence to JIRA — There is currently no way to delegate user management from JIRA to Confluence. So, if you are in a situation where your users are defined in Confluence and would like to take advantage of Confluence's ability to use JIRA user management, you will need to transfer all of your existing Confluence users into JIRA. You can do this manually, or if you have a large number of users, you can use the attached XML-RPC script. • Requesting External User Management Support • Understanding User Management in Confluence • User Management Frequently Asked Questions

Document generated by Confluence on Oct 10, 2007 11:54

Page 313

Confluence User Management
This page last changed on Feb 01, 2006 by vidya.

• • • • • • • • • • • •

Adding a Group Adding a New User Adding or Removing a User from a Group Changing Usernames Editing User Details Global Groups Overview Global Permissions Overview Migrating to new User Management Removing a Group Removing a User Setting up Anonymous Access Viewing members of a group

Document generated by Confluence on Oct 10, 2007 11:54

Page 314

Adding a Group
This page last changed on Jun 25, 2007 by smaddox.

To add a new group,

1. Go to the 'Administration Console' and click on 'Manage Groups' in the left panel. 2. Enter a name for your group in the 'Add Group' input field and click 'Save'.

You are now ready to start adding users to the group.
RELATED TOPICS

Adding or Removing a User from a Group Global Groups Overview Removing a Group Viewing members of a group [!Administration Guide Attachments directory^adminhome.gif!]

Document generated by Confluence on Oct 10, 2007 11:54

Page 315

Adding a New User
This page last changed on Jun 25, 2007 by smaddox.

There are two ways a new user can be added to Confluence: Public Signup: Enabling public signup from the Administration Console allows users to sign themselves up to the site. By Site Administrators : If you want to restrict your site to a select group of users, you may want to disable 'Public Signup'. In this instance, site administrators can add new users from the Administration Console. To add a new user to Confluence from the Administration Console,

1. 2. 3. 4.

Go to the 'Administration Console' and click on 'Manage Users' in the left panel. Click on the link 'Add new user' listed at the top of the page. In the form displayed, enter the user's details: username, password, name and email id. Click 'Create' to add the user.

RELATED TOPICS

Adding a Group Adding a New User Adding or Removing a User from a Group Changing Usernames Editing User Details

Document generated by Confluence on Oct 10, 2007 11:54

Page 316

Adding or Removing a User from a Group
This page last changed on Jun 25, 2007 by smaddox.

To add or remove a user from a group,

1. Go to the 'Administration Console' and click on 'Manage Users' in the left panel. All members of the Confluence-Users group are listed in alphabetical order (first name). To find a user, you can either browse through the pages; or do a search on the user's mail id or the group to which they belong. 2. Click on the user link. This will display the user's current details and links to edit them. 3. Click 'Edit Groups'. This will display two lists of groups: • 'Not a member of groups': All groups to which the user doesn't belong. To add the user to a group, select a group and click 'Join'. Hold Ctrl and click to select more than one group. • 'Member of groups': All groups to which the user belongs. Select a group and click 'Leave' to remove the user from the group.

You cannot use the Edit Groups option to add or remove users from external groups, as Confluence access to LDAP and JIRA groups is read only.
RELATED TOPICS

Adding a Group Adding a New User Adding or Removing a User from a Group Changing Usernames Editing User Details

Document generated by Confluence on Oct 10, 2007 11:54

Page 317

Changing Usernames
This page last changed on Jun 25, 2007 by smaddox.

A username is the name used to login to Confluence, eg. jsmith. There is no support for changing a username via Confluence yet, but you can to vote towards a feature request to allow usernames to be changed from the web interface.

Instructions For Changing Usernames
Usernames can only be changed through direct update to the Confluence database. 1. If you have a database administrator, request that they approve the database-related steps described below 2. If you are using JIRA user management, Revert from JIRA To Internal User Management 3. Backup Confluence 4. Creating a usermigration table:
create table usermigration ( oldusername varchar, newusername varchar )

5. Usernames that will be changed must be placed in the usermigration table with their current and planned usernames:
insert into usermigration (oldusername, newusername) values ('oldusername', 'newusername');

6. If your DB administration tool does not support multiple SQL queries, these must be entered individually.
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 lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update content set creator = newusername from usermigration u where creator = u.oldusername; update content set username = newusername from usermigration u where username = 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 links set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update links set creator = newusername from usermigration u where creator = u.oldusername;

Document generated by Confluence on Oct 10, 2007 11:54

Page 318

update notifications set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update notifications set creator = newusername from usermigration u where creator = u.oldusername; update pagetemplates set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update pagetemplates set creator = newusername from usermigration u where creator = 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 spacepermissions set permusername = newusername from usermigration u where permusername = 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 contentlock set creator = newusername from usermigration u where creator = u.oldusername; update contentlock set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername; update os_user set username = newusername from usermigration u where username = u.oldusername; update trackbacklinks set creator = newusername from usermigration u where creator = u.oldusername; update trackbacklinks set lastmodifier = newusername from usermigration u where lastmodifier = u.oldusername;

7. If using Confluence 2.1 or newer, run the following command:
update user set name = newusername from usermigration u where name = u.oldusername;

8. Reassign personal spaces 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.
update spaces set spacekey = '~newusername'

Document generated by Confluence on Oct 10, 2007 11:54

Page 319

where spacekey = '~oldusername';

9. 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 fullname in the user or os_user table. All old usernames in Confluence should now be replaced with the new usernames from the usermigration table.
RELATED TOPICS

Adding a Group Adding a New User Adding or Removing a User from a Group Changing Usernames Editing User Details

Document generated by Confluence on Oct 10, 2007 11:54

Page 320

Editing User Details
This page last changed on Jun 25, 2007 by smaddox.

To update a user's details,

1. Go to the 'Administration Console' and click on the link 'Manage Users' in the left panel. 2. Locate the user by doing a search on the user's mail id or the groups to which they belong. 3. Click on the user link. This will display the user's current details and links to edit them. • View Profile : View the user's profile. • Edit Groups : Add or remove this user from a group. • Edit Details : Edit the user's name and email address. Changing a user's username is not supported through the application, see Changing Usernames for other solutions. • Set Password : Edit the user's password details. • Deactivate : It is not possible to 'remove' a user if the user is responsible for content on the site because Confluence will need the user information to maintain history of pages. In this instance, you can deactivate the user so that they can no longer log in to Confluence. • Remove : You can remove a user permanently if the user has not added or edited any content on the site. Deactivating users This functionality was removed in Confluence 2.1.x. See Removing a User for more information. Screenshot : User Details

RELATED TOPICS

Adding a New User Adding or Removing a User from a Group Editing User Details Global Permissions Overview Removing a User

Document generated by Confluence on Oct 10, 2007 11:54

Page 321

Global Groups Overview
This page last changed on Jun 25, 2007 by smaddox.

There are two special default groups in Confluence: 1. Confluence-Administrators: This is a 'super-group' of users who can access the 'Administration Console' from which site-wide administration is performed. A user from this group has permission to do anything in the site regardless of any other setting. 2. Confluence-Users: This is a default group of all new users. Permissions you assign to this group will be assigned to all new signed-up users of Confluence. Other user-groups : A site administrator can also group users together into user-groups for more convenient administration. Once created, user-groups become available at the space and page levels to allow for flexible permissioning. 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'. Enabling anonymous 'Use permission' allows non-registered users to browse pages and spaces in Confluence.
RELATED TOPICS

Adding a Group Adding a New User Adding or Removing a User from a Group Changing Usernames Editing User Details

Document generated by Confluence on Oct 10, 2007 11:54

Page 322

Global Permissions Overview
This page last changed on Sep 21, 2007 by smaddox.

Permissions determine the actions which a user is allowed to perform within Confluence. Global permissions are one of the levels of permission provided by Confluence. Global permissions control access across the whole Confluence site as follows : • Can Use: This is the most basic permission that allows users to access the site. Users with this permission count towards the number of users allowed by your license. See the information on removing/deactivating users. • Attach Files to User Profile: This allows the user to upload files to be stored in their user profile. Attaching files to a user profile was a feature made obsolete by personal spaces. This permission is therefore not relevant since Confluence 2.2. • Personal Space: This permission allows the user to create a personal space. • Create Space(s): This permission allows users to create new spaces within a Confluence site. When a space is created, the creator automatically has the 'Admin' permission for that space and can perform space-wide administrative functions. • Administer Confluence: This permission allows users to access the Administration Console that controls site-wide administrative functions. Global Permissions are granted in the Global Permissions section of the Administration Console. In order to assign these permissions, a user must already have the global 'Administer Confluence' permission. Site administrators can assign global permissions to groups, individual users, and anonymous users. Further permissions are granted from the space administration screens.
Note about 'Administer Confluence' permission

Granting a user 'Administer Confluence' permission will not automatically grant her access to all spaces in the site. It will only grant the user access to the Administration Console. Automatically being an administrator of all spaces is only available to the special 'confluenceadministrators' group (internally called the superuser group). There is an outstanding enhancement request to replace the superuser group with something better. Be aware, however, that users with 'administer' permission must still be trusted. They have access to modify users and groups in Confluence, so can always add themselves to the 'confluence-administrators' group and become a superuser.
RELATED TOPICS

Adding a Group Adding a New User Adding or Removing a User from a Group Changing Usernames Editing User Details Enabling or Disabling Public Signup Global Groups Overview Global Permissions Overview Removing a Group Removing a User Security Overview Setting up Anonymous Access Viewing members of a group

Document generated by Confluence on Oct 10, 2007 11:54

Page 323

Migrating to new User Management
This page last changed on May 18, 2007 by ganand.

In order to support advanced forms of User Management, Confluence now uses new user management which can store users through hibernate instead of delegating the user management to OSuser. By default Confluence still delegates User Management to OSuser. However, you may wish to migrate your users away from OSuser, either in preparation to use external user management, or because you are having problems with OSuser, such as CONF-5218. These migration instructions are only valid since version 2.2 of Confluence.

Step 1 - Upgrade Confluence
Please check that you are running the latest version of Confluence. If not, we strongly recommend that you consider upgrading Confluence according to this guide. Confirm that you have upgraded successfully before trying to add LDAP to the new version.

Step 2 - Confluence user migration
1. You will need to find out your Confluence base URL. To check this from Confluence, go to Administration > General Configuration > Base Url. Record this for later in the process. 2. Make a backup of your: • database • Confluence home directory • confluence/WEB-INF/classes/atlassian-user.xml (only if you have made changes) If you do not create a backup, you cannot rollback to the old version if the migration is unsuccessful. 3. Download hibernate_osuser_atlassian-user.xml and rename to atlassian-user.xml. Then copy this file to your confluence/WEB-INF/classes directory (you can overwrite the one that's there). 4. Restart Confluence. 5. Login as an Administrator, copy the address http://<BASEURL>/<contextpath>/admin/ osuser2atluser.jsp and paste it into your browser's address bar. Edit the <BASEURL> to your actual base URL and <contextpath> to your context path (usually 'confluence') and follow the link. 6. Click the link Begin migration. You will know the migration has been successful if you see this reported:
Migrating users ... Users migrated successfully! Migrating propertyset data ... Propertyset data migrated successfully! Migrating groups ... Groups migrated successfully\!

7. 8. 9. 10.

If you encounter errors, please create a support ticket at http://support.atlassian.com and attach your application server logs. Stop Confluence. Start up Confluence and check that you can login using the admin account you first set up when running through the Confluence Setup Wizard. If not, re-examine your steps and repeat from there. Download hibernate_cache_atlassian-user.xml, rename it to atlassian-user.xml then copy to your <INSTALL>/confluence/WEB-INF/classes directory. It should overwrite the previous atlassianuser.xml. Restart Confluence. Check that your users can still log in.

Document generated by Confluence on Oct 10, 2007 11:54

Page 324

Removing a Group
This page last changed on Jun 25, 2007 by smaddox.

To remove a group,

1. Go to the 'Administration Console' and click on 'Manage Groups' in the left panel. A list of all existing groups is displayed along with links to remove them. 2. Click 'Remove' beside the group you want to remove. You will need to confirm your action before the group is deleted.

RELATED TOPICS

Configuring Attachment Size Configuring Character Encoding Configuring HTTP Timeout Settings Configuring Indexing Language Configuring Number Formats

Document generated by Confluence on Oct 10, 2007 11:54

Page 325

Removing a User
This page last changed on Sep 21, 2007 by smaddox.

It is not possible to remove a user if the user is responsible for content on the site, because Confluence will need the user information to maintain a history of pages. If you wish to prevent such a user from accessing Confluence, you can deactivate a user so that they can no longer log in to Confluence. You can remove a user if the user has not added or edited any content on the site. To deactivate or remove a user,

1. Go to the 'Administration Console' and click 'Manage Users' in the left panel. 2. Find the user by searching on the username, full name or email address. You can also click 'Show all users' to browse the list of all users. 3. Click the username. This will display the user's current details and links to edit them. 4. Click 'Remove' if the user is not responsible for any content on the site. 5. If the user is responsible for content on the site, you will need to deactivate the user: • Remove the user from all groups that have the global 'Can Use' permission. Click 'Edit Groups' to remove the person from the group(s). • If the specific user has the global 'Can Use' permission, you will also need to remove this permission. Number of users and your license The License Details page tells you how many users your Confluence instance is licensed to support, and how many are currently registered The number of registered users includes only users who have the 'Can Use' global permission. Deactivated users, as described above, are not included. Deactivating users in Confluence 2.0.x and earlier Earlier Confluence releases provide a 'Deactivate' link. If you click this link, the user will be prevented from logging in to the Confluence site. This function was removed from Confluence 2.1.x and later for performance reasons. Screenshot: Adding and removing users to/from groups

RELATED TOPICS

Adding a Group Adding a New User Adding or Removing a User from a Group Changing Usernames

Document generated by Confluence on Oct 10, 2007 11:54

Page 326

Editing User Details

Document generated by Confluence on Oct 10, 2007 11:54

Page 327

Setting up Anonymous Access
This page last changed on Jun 25, 2007 by smaddox.

You can enable public access to your site by granting the 'Use Confluence' permission to 'Anonymous' users from the Administration Console. This user category has been created for convenient administration of users who have not logged into the site. Permissions assigned to this group apply to all anonymous users of the site. To enable public access to your site,

1. Go to the 'Administration Console' and click 'Global Permissions' in the left panel. 2. Click 'Edit Permissions'. 3. Under 'Anonymous Access' check 'Can Use' Confluence. Once you grant this permission, further permissions can be granted from the space administration screens to control the viewing and editing privileges of anonymous users. See Space Permissions Overview.

To turn off "Anonymous Access", uncheck the "Can Use" option.
RELATED TOPICS

Adding a New User Adding or Removing a User from a Group Editing User Details Global Permissions Overview Removing a User

Document generated by Confluence on Oct 10, 2007 11:54

Page 328

Viewing members of a group
This page last changed on Jun 25, 2007 by smaddox.

To view the members of a group,

1. Go to the 'Administration Console' and click on 'Manage Groups' in the left panel. This will list all the existing groups on the site along with the number of users in each group (displayed within parenthesis). 2. Click on the number within the paranthesis to display all the users in the group.

RELATED TOPICS

Adding or Removing a User from a Group Global Groups Overview Removing a Group Viewing members of a group

Document generated by Confluence on Oct 10, 2007 11:54

Page 329

How to Improve User Search Performance
This page last changed on Sep 04, 2007 by mryall.

If your Confluence instance contains thousands of user accounts and you are experiencing performance issues when searching for users, the following migration guide is for you.

Background
In Confluence 2.1, we introduced a new system for user management inside Confluence (atlassian-user) that was more powerful than the previous system (OSUser). However, to avoid potential upgrade issues, we continued to use OSUser when storing users in the local Confluence database. The native atlassian-user storage format provides much more efficient searching, and greatly improves the performance of user administration and Confluence's 'user picker' pop-up. We plan on migrating all Confluence instances to the new format around version 2.6 or 2.7, but until then Confluence instances with large numbers of users can still take advantage of these performance improvements by performing the migration manually.

Migration procedure
Do not use this procedure if you have LDAP user management enabled. This guide assumes that you are using Confluence's local users and groups. If you have already configured Confluence for LDAP user/group management and are experiencing user management slowness, please follow the guide for Requesting External User Management Support. This guide applies to Confluence 2.1 and later. Follow these steps to migrate your Confluence instance to atlassian-user: 1. You will need to find out your Confluence base URL. To check this from Confluence, go to Administration > General Configuration > Base Url. Record this for later in the process. 2. You must create backups in order to rollback to the old version if the migration is unsuccessful. Make a backup of your: • database • Confluence home directory (see Important Directories and Files for instructions on locating this) • confluence/WEB-INF/classes/atlassian-user.xml (only if you have made changes) 3. Right-click on atlassian-user.xml and download it to your confluence/WEB-INF/classes directory (you can overwrite the one that's there). 4. Are you using Confluence 2.3.x ? If so, right-click on osuser2atluser.jsp and download it to the \confluence\admin subdirectory of your Confluence install. Overwrite the existing osuser2atluser.jsp file. 5. Restart Confluence. Login as an administrator, and go to this URL:
<BASEURL>/admin/osuser2atluser.jsp

Please ensure you replace <BASEURL> with the URL that you currently use to access Confluence. For example, http://confluence.atlassian.com or http://foobar.com/confluence. 6. Click the link Begin migration. You will know the migration has been successful if you see the following:
Migrating users ... Users migrated successfully! Migrating propertyset data ... Propertyset data migrated successfully! Migrating groups ... Groups migrated successfully\!

For installations with groups that contain a large number of users, this may take a few hours to complete.

Document generated by Confluence on Oct 10, 2007 11:54

Page 330

1. If you encounter problems, please create a support ticket at http://support.atlassian.com and attach your application server logs. 2. Stop Confluence. 3. Remove this line from confluence/WEB-INF/classes/atlassian-user.xml:
<osuser key="osuserRepository" name="OSUser Repository"/>

4. Start up Confluence and check that you can login using the administrator account you first set up when running through the Confluence Setup Wizard. If not, re-examine your steps and repeat from there. If you still cannot login, please create a support ticket at http://support.atlassian.com.

Document generated by Confluence on Oct 10, 2007 11:54

Page 331

Integrating with Crowd
This page last changed on Mar 20, 2007 by rosie@atlassian.com.

Atlassian's Crowd identity management system can be integrated with Confluence. Please see Integrating Crowd with Confluence.

Document generated by Confluence on Oct 10, 2007 11:54

Page 332

JIRA User Management
This page last changed on Feb 01, 2006 by vidya.

• Delegate user management to use JIRA logins ° Revert from JIRA to internal user management • JIRA User Management FAQ

Document generated by Confluence on Oct 10, 2007 11:54

Page 333

Delegate user management to use JIRA logins
This page last changed on Jun 25, 2007 by smaddox.

If you already have a significant user base set up inside JIRA, it makes sense to connect Confluence up to it so user management is centralised and not duplicated. This document outlines how to delegate Confluence's user authentication and group management to JIRA so that you can use your JIRA users to login to Confluence.

Read Before Proceeding
1. The examples used in this document are based on Tomcat Application Server and the MySQL database, but the same concepts (but not the verbatim examples) can be applied to other application servers or databases. 2. Always install Confluence with a new database. Do not attempt to use the existing Jira database, with either JDBC or data source. Do not add any spaces or content once Confluence installation is complete. Users in Confluence will no longer be valid once you switch over to using your JIRA users 3. If JIRA is using LDAP for authentication, you should not use JIRA for Confluence user management. Use Add LDAP Integration instead 4. If you have existing users or groups in Confluence, these users will not be available once you switch to using JIRA's user management. Any existing content will no longer be associated with valid users 5. If you run into a problem, check the Troubleshooting section

Technical Overview
In the configuration described below, Confluence will use JIRA's database for its user and group information. The Confluence application will have two database connections: 1. A connection to the primary database, set up during Confluence installation. This database stores all the normal Confluence data: spaces, pages, comments, etc. 2. A read-only data source connection to JIRA's database, set up after Confluence is installed. Confluence reads information about users and groups from this database. The reason this works is because both JIRA and Confluence use the same user management library, OSUser. The OSUser database schema is the same in JIRA and Confluence, so Confluence can easily read from JIRA's tables to get the user and group information.

Step One: Installing Confluence
Skip this step if you have installed Confluence already and completed the setup wizard. 1. If you are running JIRA standalone please follow these instructions for installing Confluence. 2. If you have JIRA deployed under your own tomcat server, please follow these instructions. 3. Ensure that Confluence is running and has been set up, that is, you have completed the setup wizard and verified that you can create pages. 4. Shutdown Confluence.

Step Two: Setting up datasource to JIRA's database
To enable Confluence to delegate all user authentication attempts and group membership queries to JIRA, it needs to made of aware of JIRA's database (and hence the user tables in JIRA's database). In Tomcat this is achieved by specifying JIRA's database as a resource. You will need to declare it inside the <context> descriptor you set up in Step One. If there is an existing block of <Resource> in the <context> descriptor, please do not replace it. Rather, just add the following <Resource> block inside the <context> descriptor. If you are running Confluence WAR/EAR version separate to Jira, or under Jira standalone 3.3 and later, your Confluence context will be in the confluence.xml file.

Document generated by Confluence on Oct 10, 2007 11:54

Page 334

If you are running Confluence standalone separate to Jira, or Confluence WAR/EAR version under an older version of Jira, your Confluence context will be in the server.xml file. You should never have a Confluence context in both. If you are running Confluence stand-alone (or Confluence inside a JIRA stand-alone) and aren't sure which version of Tomcat you are using, check your log files. You'll see *INFO: Starting Servlet Engine: Apache Tomcat/5.5.nn* if you are using Tomcat 5.5. The DataSource configuration below is using MySQL as an example. You will need to modify these settings according to the database that you are using. • Tomcat 4.x and Tomcat 5.0.x: Sample context descriptor
<Context path="/confluence" docBase="C:/programs/confluence" swallowOutput="true"><Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/><ResourceParams name="jdbc/JiraDS"><parameter><name>username</name><value>your_db_username</ value></parameter><parameter><name>password</name><value>your_db_password</value></ parameter><parameter><name>driverClassName</name><value>com.mysql.jdbc.Driver</ value></parameter><parameter><name>url</name><value>jdbc:mysql://your.domain.com/ jira_database_name?autoReconnect=true</value></parameter><parameter><name>factory</ name><value>org.apache.commons.dbcp.BasicDataSourceFactory</value></parameter></ ResourceParams></Context>

• Tomcat 5.5.x: This version of Tomcat has a new syntax for specifying resources (note that you don't add a new context to server.xml, just add the Resource to your existing Context):
<Context path="/confluence" docBase="C:/programs/confluence" swallowOutput="true"> <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource" username="your_db_username" password="your_db_password" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://your.domain.com/jira_database_name?autoReconnect=true"/> </Context>

Step Three: Installing the JDBC driver
Ensure that your JDBC driver is on the classpath of your application server. In this example, a jar for the mysql driver should be in the /common/lib folder. 1. Download the mysql driver from here. 2. Copy the jar file into the /common/lib folder

Step Four: Modify osuser.xml
Please perform this step after you have completed the Confluence setup wizard. 1. Find the osuser.xml file in the /confluence/WEB-INF/classes folder and open in a text editor. Comment out the following block of code:
<provider class="bucket.user.providers.CachingCredentialsProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingAccessProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</ property><property name="chain.configuration.provider.class">bucketuser.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingProfileProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider>

2. Uncomment this block:

Document generated by Confluence on Oct 10, 2007 11:54

Page 335

<provider class="bucket.user.providers.CachingCredentialsProvider"> <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcCredentialsProvider</ property> <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property> </provider> <provider class="bucket.user.providers.CachingAccessProvider"> <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcAccessProvider</ property> <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property> </provider> <provider class="bucket.user.providers.CachingProfileProvider"> <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcProfileProvider</ property> <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property> <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property> </provider>

Your osuser.xml should now look like this:
<opensymphony-user> <!-Authenticators can take properties just like providers. This smart authenticator should work for 'most' cases - it dynamically looks up the most appropriate authenticator for the current server. --> <authenticator class="com.opensymphony.user.authenticator.SmartAuthenticator"/> <!-- JIRA User management (with caching) --> <!-- Note: Do not add any line breaks or spaces when specifying the chain.classname, otherwise a ClassNotFoundException will be thrown --> <provider class="bucket.user.providers.CachingCredentialsProvider"> <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcCredentialsProvider</ property> <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property> </provider> <provider class="bucket.user.providers.CachingAccessProvider"> <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcAccessProvider</ property> <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property> </provider> <provider class="bucket.user.providers.CachingProfileProvider"> <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcProfileProvider</ property> <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property> <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property> </provider> <!-<provider class="bucket.user.providers.CachingCredentialsProvider"> <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</ property> <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property> </provider>

Document generated by Confluence on Oct 10, 2007 11:54

Page 336

<provider class="bucket.user.providers.CachingAccessProvider"> <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</ property> <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property> </provider> <provider class="bucket.user.providers.CachingProfileProvider"> <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</ property> <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property> </provider> --> <!--<provider class="com.opensymphony.user.provider.memory.MemoryCredentialsProvider" /> <provider class="com.opensymphony.user.provider.memory.MemoryAccessProvider" /> <provider class="com.opensymphony.user.provider.memory.MemoryProfileProvider" />--> </opensymphony-user>

Please make sure your file looks like this. In this example, JiraDS is the name of the JIRA datasource you are sharing with Confluence. If you have changed the name in step 2 of this documentation, you will need change all occurences of the value here too. You can also download the already configured file here.

Step Five: Customize osuser.xml
In some cases you may need to customize the behavior of the JiraJdbc classes, you can do this by setting properties within the osuser.xml file. This process is documented here.

Step Six: Creating Confluence Groups in JIRA
1. Add confluence-users and confluence-administrators groups in JIRA 2. Add yourself to both these groups. • To give your existing JIRA users access to Confluence, you have two options. • Manually edit the groups of these users inside JIRA and give them membership to one or both of these confluence groups OR • Startup Confluence. Log in using your JIRA account, and go to Administration and then Global Permissions. Now add USE permission to your desired JIRA groups. In order to use Confluence, users must be a member of the confluence-users group (or have confluence USE permission).

Step Seven: Activating External User Management
Since user management is now conducted in JIRA and outside of Confluence, you will need to switch external user management on. NOTE: Activating external user management will remove user and group management options from Confluence. Your users will also no longer be able to edit their full name or email address inside Confluence (if they want to, they would have to do so in JIRA). To do this: 1. 2. 3. 4. Log into Confluence using your JIRA account. Go to the Administration Console and click General Configuration in the left panel Click 'Edit' at the bottom of the 'Options and Settings' screen. Select 'ON' beside 'External User Management'.

Document generated by Confluence on Oct 10, 2007 11:54

Page 337

For answers relating to JIRA User Management, click on any query below.

Troubleshooting
Confluence login page

loads with 'NullPointerException' system error

If the page loads with 'System error' with cause 'java.lang.NullPointerException at com.atlassian.user.impl.osuser.OSUUserManager.getOpensymphonyUser(OSUUserManager.java:85)' and output logs shows 'user.provider.jdbc.BaseJDBCProvider] init Could not look up DataSource using JNDI location' error, either the Resource for the DataSource is not being loaded by the application server, or it is being loaded but the resource names do not match. Check the names first, so if '/confluence/WEB-INF/ classes/osuser.xml' specifies a datasource named 'java:comp/env/jdbc/JiraDS', the datasource specified in server.xml or confluence.xml must be 'jdbc/JiraDS'. Confluence login page loads with 'HTTP Status 404' and output log shows 'java.lang.ClassNotFoundException' for driver, eg 'com.mysql.jdbc.Driver' Missing the database driver library. On standalone or Apache Tomcat, download the database jar to the common\lib directory. Confluence login page loads but login fails with 'Username and password are incorrect' and output log shows 'Access denied for user' Caused by an incorrect database URL or login in the datasource. Confluence login page loads but login fails with 'Username and password are incorrect' and output log shows 'Cannot create JDBC driver' If your log outputs an error with "FATAL [user.provider.jdbc.JDBCCredentialsProvider] Could not list users. org.apache.commons.dbcp.SQLNestedException: Cannot create JDBC driver of class '' for connect URL 'null'", you are using the incorrect Tomcat format for specifying the Datasource resource. You should check your Tomcat version and use the alternative format. I cannot get my JIRA

integration to work, where can I get technical support?

See Requesting External User Management Support for information on logging a support request.
RELATED TOPICS

Delegate user management to use JIRA logins Migrating users from Confluence to JIRA Revert from JIRA to internal user management

Document generated by Confluence on Oct 10, 2007 11:54

Page 338

Revert from JIRA to internal user management
This page last changed on Oct 26, 2006 by david.soul@atlassian.com.

Administrators can revert a Confluence instance that uses JIRA for user management back to internal user management. With few users, it is easier to manually recreate the JIRA users and groups in Confluence. For more users, migrate JIRA users and groups into the Confluence database instead.

Option A - Manually Recreate Users In Confluence
This option is too time consuming for hundreds or thousands of users. After completing the reversion, links to users who created or updated Confluence content may go to error screens. To manually recreate the users, you must first have an instance of Confluence with internal user management and your data. • If you have made limited customisations to Confluence and migrating would be desirable - follow the upgrade guide and import your data to a new installation. • Alternatively, if you have made extensive customisations or do not wish to migrate - go to delegating user management to JIRA and remove your JIRA user management by undoing the instructions in revese order. These steps are specific to your instance so cannot be covered here. Then manually create JIRA's groups and users in Confluence. If you have assigned permissions in Confluence to a group which exists in JIRA, you must create a group in Confluence with the same name. If a user who exists in JIRA has created content or has had permissions assigned to them, you must also create that user in Confluence.

Option B - Transfer JIRA Users & Groups To Confluence
This option manually migrates JIRA users into the Confluence database, but requires knowledge of SQL. Users not using mySQL Users of non-mySQL databases must be experienced enough to modify the SQL to work in their database as examples are provided for mySQL only. If you adapt the SQL to another database, please consider posting the SQL you used to the comments. Users of Confluence 2.0 or older Pre-Confluence 2.0 users may need to modify the instructions to your older schema, or upgrade Confluence. For example, on Confluence 2.1.5 and older, SQL references to the property table must be updated to be called OS_PROPERTYENTRY in all upper-case.

Stage One - Create Backups
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 backup including attachments. Stop Confluence. Take a backup copy of the Confluence home and install directories. Repeat the above steps for JIRA. From your mySQL admin tool, create a database backup for the JIRA and Confluence databases.

Stage Two - Replace Confluence User Management
Replace the Confluence user and group permissions with JIRA by transferring table content. The SQL provided is specific to mySQL and must be modifed for other databases. For each SQL statement, do a find and replace on the JIRA and Confluence table names to your table names. In the examples, they are called confluence224 and jira364. 1. Login to a DBA tool that can execute SQL on your DB. 2. Erase user and group content from the Confluence DB:

Document generated by Confluence on Oct 10, 2007 11:54

Page 339

deletefrom deletefrom deletefrom deletefrom

confluence224.os_propertyentry where entity_name='OSUser_user'; confluence224.os_user_group; confluence224.os_group; confluence224.os_user;

3. Copy JIRA's groupbase table into Confluence's os_group table:
insert into confluence224.os_group (id, groupname) select * from jira364.groupbase;

4. Copy JIRA's userbase table into Confluence's os_user table:
insert into confluence224.os_user (id, username, passwd) select * from jira364.userbase;

5. Copy JIRA's membershipbase table into Confluence's os_user_group table.
insert into confluence224.os_user_group (group_id, user_id) select distinct groupbase.id as "group_id", userbase.id as "user_id"from jira364.groupbase, jira364.membershipbase, jira364.userbase where membershipbase.user_name = userbase.username and membershipbase.group_name = groupbase.groupname;

6. Merge relevant content from JIRA's propertyentry and propertystring tables into Confluence's os_propertyentry table. Some versions of SQL use "0" instead of "false" for boolean values.
insert into confluence224.os_propertyentry (entity_name, entity_id, entity_key, key_type, boolean_val, double_val, string_val, text_val, long_val, int_val, date_val) select 'OSUser_user', propertyentry.entity_id, propertyentry.property_key, 5, false, 0, propertystring.propertyvalue, '', 0, 0, null from jira364.propertyentry, jira364.propertystring where propertyentry.entity_name='OSUser' and propertyentry.id=propertystring.id;

Stage Three - Revert To Local Management
• If you have made limited customisations to Confluence and migrating would be desirable - Install a new instance of Confluence using the upgrade guide and use Method 1 to import your updated database. • Alternatively, if you have made extensive customisations or do not wish to migrate - go to Delegating User Management to JIRA and remove your JIRA user management by undoing the instructions in revese order. These steps are specific to your instance so cannot be covered here. Done! Note that the original administrator may not display their groups correctly, however their groups are still present.

Document generated by Confluence on Oct 10, 2007 11:54

Page 340

JIRA User Management FAQ
This page last changed on Jan 15, 2007 by david.soul@atlassian.com.

For answers relating to JIRA User Management, click on any query below.

Troubleshooting
Confluence login page

loads with 'NullPointerException' system error

If the page loads with 'System error' with cause 'java.lang.NullPointerException at com.atlassian.user.impl.osuser.OSUUserManager.getOpensymphonyUser(OSUUserManager.java:85)' and output logs shows 'user.provider.jdbc.BaseJDBCProvider] init Could not look up DataSource using JNDI location' error, either the Resource for the DataSource is not being loaded by the application server, or it is being loaded but the resource names do not match. Check the names first, so if '/confluence/WEB-INF/ classes/osuser.xml' specifies a datasource named 'java:comp/env/jdbc/JiraDS', the datasource specified in server.xml or confluence.xml must be 'jdbc/JiraDS'. Confluence login page loads with 'HTTP Status 404' and output log shows 'java.lang.ClassNotFoundException' for driver, eg 'com.mysql.jdbc.Driver' Missing the database driver library. On standalone or Apache Tomcat, download the database jar to the common\lib directory. Confluence login page loads but login fails with 'Username and password are incorrect' and output log shows 'Access denied for user' Caused by an incorrect database URL or login in the datasource. Confluence login page loads but login fails with 'Username and password are incorrect' and output log shows 'Cannot create JDBC driver' If your log outputs an error with "FATAL [user.provider.jdbc.JDBCCredentialsProvider] Could not list users. org.apache.commons.dbcp.SQLNestedException: Cannot create JDBC driver of class '' for connect URL 'null'", you are using the incorrect Tomcat format for specifying the Datasource resource. You should check your Tomcat version and use the alternative format. I cannot get my JIRA

integration to work, where can I get technical support?

See Requesting External User Management Support for information on logging a support request.

Document generated by Confluence on Oct 10, 2007 11:54

Page 341

LDAP User Management
This page last changed on May 18, 2007 by ganand.

Grouping page for external user management documentation (including LDAP, ActiveDirectory, etc). What resource do you need? • • • • Overview of external user management Help with troubleshooting external user management Guide to adding LDAP integration with group management LDAP FAQ

Check the listing of children pages below for other useful resources.

Document generated by Confluence on Oct 10, 2007 11:54

Page 342

Activating External User Management
This page last changed on Aug 09, 2007 by smaddox.

If your user management is being handled outside of Confluence by JIRA you will need to turn on the external management option from the Administration Console. Running Confluence with Crowd: • If you would like to handle your user management outside of Confluence via Crowd, you will need to turn on the external management option. • For Confluence 2.5.6 and later: External user management when running with Crowd is optional. You can leave external user management off and still run Confluence under Crowd. But external user management is recommended, because it allows you to use Crowd's powerful cross-directory administration features instead of Confluence's more limited Confluence-centric user management. If your user management is being done with LDAP, you must not turn on external user management, although users and groups which exist in your LDAP repository cannot be modified. Activating an external user management sytem will remove all user and group management options from Confluence. The assignment of permissions to groups and users is still carried out within Confluence, but the creation of groups and users is not. This will also disable users from signing up to the site, as well as editing their name, email and password particulars from within Confluence. To activate an external user management system,

1. 2. 3. 4.

Go to the 'Administration Console', click on 'General Configuration' in the left panel. In the 'Security and Privacy' screen, click 'Edit'. Select 'On' beside 'External User Management'. Click 'Save'.

RELATED TOPICS

Activating External User Management Add LDAP Integration For User Authentication Only Changes in osuser.xml from 1.0.3a to 1.1.x Confluence Caching OSUser Provider Importing LDAP Users

Document generated by Confluence on Oct 10, 2007 11:54

Page 343

Add LDAP Integration
This page last changed on Sep 27, 2007 by smaddox.

Try Atlassian Crowd for powerful LDAP integration Atlassian's Crowd is a web-based single sign-on (SSO) tool that simplifies application provisioning and identity management. Confluence can delegate user authentication to LDAP and use LDAP group memberships to set the user's Confluence access permissions. This also allows Active Directory (AD) integration. This guide is for both users enabling LDAP, and those upgrading their LDAP scheme to support group management. It applies to LDAP over HTTP and SSL/HTTPS. Once the LDAP is enabled and LDAP users are using Confluence, you cannot revert to local user management without those users being disabled. However, you can create new local users while using LDAP integration.

Who is this guide for?
To decide if this is the correct document for you, please answer these 2 questions: 1. Are you using Atlassian-User LDAP on Confluence 2.1.x? If so, follow the 2.1.x LDAP Upgrade Instructions instead. 2. Are you using a version of Confluence older than 2.1? If you are using 2.0.x, follow OSUser LDAP integration instead. If it is older than 2.0, you must upgrade Confluence.

Step 1 - Upgrade Confluence
Please check that you are running the latest version of Confluence. If not, we strongly recommend that you consider upgrading Confluence according to this guide. Confirm that you have upgraded successfully before trying to add LDAP to the new version.

Step 2 - Contact your LDAP/AD Administrator
Integration can only be setup by an administrator confident with running user queries against their LDAP directory. You should request assistance from your LDAP or Active Directory administrator for the following steps.

Step 3 - Check your LDAP server
Confirm this information about your LDAP server. 1. Check your server LDAP version. Supported versions are v2 and v3. Supported LDAP servers include OpenLDAP, Microsoft Active Directory, Novell eDirectory, and any server that uses Java JNDI-LDAP mapping. 2. Your LDAP or Active Directory server must support static groups. This means that the user DNs must be stored against a membership attribute inside an LDAP groups. An example of a static group is shown below:
Dn: CN=Sales and Marketing,CN=Users,DC=ad,DC=atlassian,DC=com objectClass: top; group; cn: Sales and Marketing; distinguishedName: CN=Sales and Marketing,CN=Users,DC=ad,DC=atlassian,DC=com; name: Sales and Marketing; ... member: CN=John Smith,CN=Users,DC=ad,DC=atlassian,DC=com member: CN=Sally Smith,CN=Users,DC=ad,DC=atlassian,DC=com ...

The membership attribute in this case is member, but this is not required. Note that the full DNs of John and Sally Smith are listed. If the values against member are not full DNs, but are just usernames, then you need to add the flag

Document generated by Confluence on Oct 10, 2007 11:54

Page 344

<useUnqualifiedUsernameForMembershipComparison>true </useUnqualifiedUsernameForMembershipComparison>

to your LDAP configuration. Open Directory on OS X uses this configuration. 3. You must not have LDAP groups called 'confluence-users' or 'confluence-administrators'. 4. You must have at least one existing Confluence administrator whose username does not exist in the LDAP server (see Step 4).

Step 4 - Check the Administrator account
This step assumes that you have at least one Confluence user account which has permissions to administer your Confluence site. For this account, please check that there isn't an account on your LDAP system that has the exact same username. If there is an LDAP account with the exact same username, and you do not have another local Confluence account that has administration rights, then you should perform one of the following: • create another account, that doesn't exist on LDAP, to act as the administrator OR: • rename your local Confluence administrator account to use another username that doesn't exist in LDAP OR: • rename your LDAP account This will ensure that you will have an account that has sufficient rights to administer your site after you migrate your users.

Step 5 - Prepare for Confluence user migration
1. Find out your Confluence base URL. To check this from Confluence, go to Administration > General Configuration > Base Url. Record this for use in Step 6. 2. Create backups in order to rollback to the old version if the migration is unsuccessful. Make a backup of your: • database • Confluence home directory • confluence/WEB-INF/classes/atlassian-user.xml (only if you have made changes)

Step 6 - Migrate Confluence users and configure your LDAP repository
There are two ways to do this: • METHOD A: Migrate Confluence users first, then configure LDAP.(This method allows your users to continue using Confluence after migration, even before you have finished the LDAP configuration.) • METHOD B: Configure LDAP users first, then migrate Confluence users.(This method ensures that the migration ignores users who have the same username as an LDAP user. This will prevent duplicate users in Confluence when you have both LDAP and local Confluence users enabled.) The recommended method is: • If you are running a Confluence version earlier than 2.6, follow METHOD A. • If you are running Confluence version 2.6 or later, and none of your existing Confluence users have the same usernames as LDAP users, follow METHOD A. • If you are running Confluence version 2.6 or later, and any of your existing Confluence users have the same usernames as LDAP users, follow METHOD B. METHOD A: Migrate Confluence users first, then configure LDAP 1. Download hibernate_osuser_atlassian-user.xml and rename to atlassian-user.xml and copy to your confluence/WEB-INF/classes directory. (You can overwrite the one that's there) 2. Restart Confluence. Login as an Administrator, and go to this URL:

Document generated by Confluence on Oct 10, 2007 11:54

Page 345

<BASEURL>/admin/osuser2atluser.jsp

Replace <BASEURL> with the URL you currently use to access Confluence. For example, http:// confluence.atlassian.com or http://foobar.com/confluence. 3. Click the link Begin migration. You will know the migration has been successful if you see this reported:
Migrating users ... Users migrated successfully! Migrating propertyset data ... Propertyset data migrated successfully! Migrating groups ... Groups migrated successfully\!

4. 5. 6. 7. 8. 9.

If you encounter errors, please create a support ticket at http://support.atlassian.com and attach your application server logs. Stop Confluence. Start up Confluence and check that you can login using the admin account you first set up when running through the Confluence Setup Wizard. If not, re-examine your steps and repeat from there. If you can't successfully login with this account, please check that the username of this account does not already exist in your LDAP server. If usernames are the same, Confluence recognisesLDAP accounts over local Confluence accounts. Download ldap_hibernate_cache_atlassian-user.xml, rename it to atlassian-user.xml then copy to your <INSTALL>/confluence/WEB-INF/classes directory. It should overwrite the previous atlassian-user.xml. Follow Customising atlassian-user.xml Go to step 7.

METHOD B: Configure LDAP, then migrate Confluence users 1. Download ldap_hibernate_osuser_atlassian-user.xml, rename it to atlassian-user.xml then copy to your <INSTALL>/confluence/WEB-INF/classes directory. It should overwrite the previous atlassian-user.xml. Your atlassian-user.xml file should have LDAP, hibernate and osuser repositories (in this order) enabled. 2. Follow Customising atlassian-user.xml 3. Restart Confluence. Login as an Administrator, and go to this URL:
<BASEURL>/admin/osuser2atluser.jsp

Replace <BASEURL> with the URL you currently use to access Confluence. For example, http:// confluence.atlassian.com or http://foobar.com/confluence. 4. Click the link Begin migration. You will know the migration has been successful if you see this reported:
Migrating users ... Users migrated successfully! Migrating propertyset data ... Propertyset data migrated successfully! Migrating groups ... Groups migrated successfully\!

If you encounter errors, please create a support ticket at http://support.atlassian.com and attach your application server logs. 5. Stop Confluence. 6. Edit atlassian-user.xml file and comment out the <osuser> repository. 7. Start up Confluence and check that you can login using the admin account you first set up when running through the Confluence Setup Wizard. If not, re-examine your steps and repeat from there.

Step 7 - Grant access to LDAP users and groups
To grant Confluence login access to your LDAP groups and users: 1. From Confluence, go to Administration > Global Permissions 2. Click to Edit Permissions for Groups 3. In the textbox to Grant Browse Permission, enter the name of an LDAP group that should have Confluence access. Click Add. 4. Tick the Can Use box for the LDAP group. If the group is not found, it was not present in your LDAP server. 5. For other LDAP groups that need access to Confluence, add them using the same method.

Document generated by Confluence on Oct 10, 2007 11:54

Page 346

6. If you are integrating LDAP with Confluence for authentication only, no LDAP groups will appear in Confluence. All the individual LDAP users will have to be manually added to an internal Confluence group having with Can Use permissions enabled before they can have access to Confluence. 7. Setup your Confluence page and space permissions for these LDAP groups and users. To setup all LDAP users as members of particular Confluence internal groups, use the LDAP Dynamic Groups Plugin. Installation complete!

Related Pages
• Confluence LDAP Documentation Index

Troubleshooting Resources
• • • • LDAP FAQ If LDAP users or groups are not displayed in Confluence, download the Paddle diagnostic tool List of known, unresolved LDAP bugs Comments on this page

Failing that, lodge a support request. Be sure to attach your atlassian-user.xml, Paddle logs and a zip of your Confluence logs.

Document generated by Confluence on Oct 10, 2007 11:54

Page 347

Automatically Adding LDAP users to the confluence-users Group
This page last changed on Mar 01, 2007 by tom@atlassian.com.

This Authenticator adds users to confluence-users as they log in. To use it, change the line: <authenticator class="com.atlassian.confluence.user.ConfluenceAuthenticator"/> in seraph-config.xml to: <authenticator class="com.atlassian.confluence.user.ConfluenceGroupJoiningAuthenticator"/> If you are using Confluence 2.2 you need to download the ConfluenceGroupJoiningAuthenticator.class file and put it in WEB-INF/classes/com/atlassian/confluence/user. Confluence 2.3 and later include this class as standard.

Document generated by Confluence on Oct 10, 2007 11:54

Page 348

Customising atlassian-user.xml
This page last changed on Jul 26, 2007 by ivan@atlassian.com.

The LDAP server connection is specified by manually editing the file atlassian-user.xml. Confluence 2.3 onwards supports multiple LDAP servers by repeating the instructions below for each server so that there are multiple repositories defined.

Stage 1 - Configure Connection Details
1. Edit the file .../confluence/WEB-INF/classes/atlassian-user.xml and configure the connection for either AD or LDAP. • Connections in Active Directory • Connections in other LDAP servers 2. If your Active Directory Server allows anonymous searches, then you do not need to specify a securityPrincipal and securtyCredential at all. For an example of how you would configure Confluence to allow anonymous authentication, see Enable Anonymous Authentication in LDAP or Active Directory 3. To connect to LDAP over SSL, see Connect to LDAP via SSL 4. Check your configuration against the example connection details shown below.
<ldap key="ldapRepository" name="LDAP Repository@hecate.atlassian.com" cache="true"><host>hecate.atlassian.com</host><port>389</ port><securityPrincipal>cn=admin,dc=atlassian,dc=private</ securityPrincipal><securityCredential>secret</securityCredential><securityProtocol>plain</ securityProtocol><securityAuthentication>simple</ securityAuthentication><baseContext>dc=atlassian,dc=private</baseContext> ....

Stage 2 - Map LDAP Data Tree
1. Configuring the mappings in atlassian-user.xml for either AD or LDAP. • Mapping Active Directory • Mapping other LDAP servers 2. Check your configuration against the example connection details shown below.
... <baseUserNamespace>dc=staff,dc=perftest,dc=atlassian,dc=private</ baseUserNamespace><baseGroupNamespace>dc=groups,dc=perftest,dc=atlassian,dc=private</ baseGroupNamespace><usernameAttribute>cn</ usernameAttribute><userSearchFilter>(objectClass=inetorgperson)</ userSearchFilter><firstnameAttribute>givenname</firstnameAttribute><surnameAttribute>sn</ surnameAttribute><emailAttribute>mail</emailAttribute><groupnameAttribute>cn</ groupnameAttribute><groupSearchFilter>(objectClass=groupOfNames)</ groupSearchFilter><membershipAttribute>member</membershipAttribute></ldap>

Stage 3 - Directory Search Depth Settings
These are the default settings:
... <userSearchAllDepths>false</userSearchAllDepths><groupSearchAllDepths>false</groupSearchAllDepths>

The above settings configure the search depth on users and groups. If you set either attribute to: • false - Confluence will search only for users/groups directly defined in <baseUserNamespace> and <baseGroupNamespace>. • true - Confluence will search for users/groups defined in the above namespaces and also in namespaces nested within them. For example, if your users are distributed across multiple namespaces, you should set this option to true. Setting the value to true may have a high cost in performance for large directories, because Confluence will search the whole tree and not just the immediate namespace.

Document generated by Confluence on Oct 10, 2007 11:54

Page 349

Stage 4 - Optional LDAP Settings
The following settings do not appear in the default atlassian-user.xml file:
<poolingOn>true</poolingOn><maxSize>0</maxSize><initSize>10</initSize><prefSize>10</ prefSize><debugLevel>none</debugLevel><securityProtocol>plain ssl</ securityProtocol><authentication>simple</authentication><timeout>0</ timeout><initialContextFactory>com.sun.jndi.ldap.LdapCtxFactory</ initialContextFactory><batchSize>100</batchSize><timeToLive>0</timeToLive>

However, if you want to override the default values listed above, you can add the value onto the end like so:
... <groupnameAttribute>cn</groupnameAttribute><groupSearchFilter>(objectClass=groupOfNames)</ groupSearchFilter><membershipAttribute>member</membershipAttribute><initSize>20</initSize></ldap>

It is important that the connection pool timeout value be set to 0, as this will force Atlassian User (via the JNDI layer) to clean up lingering connections that have lived past one request. More information about LDAP pools here.

Stage 5 - Configure LDAP for User Authentication only
Description There are two kinds of Confluence/LDAP integration available:

User Authentication LDAP Without Groups LDAP With Groups

Internal Users

Internal Groups

LDAP Users

LDAP Groups

This section covers LDAP without groups, where if a username exists in both Confluence and LDAP, they use their LDAP password to login. You still maintain users from Confluence and use internal Confluence groups for group permissions. Alternatively, you may use LDAP with Groups to have users and groups automatically updated from LDAP, and use LDAP groups for group permissions. Applies For • Enabling LDAP for the first time • Upgrading existing LDAP without enabling group management Important Points • Only the password lookup is done against LDAP and only if the Confluence username coincides with the LDAP username. Users and user profiles are still managed in Confluence. See technical explanation below. • Each LDAP user in Confluence must be added to an internal Confluence group having Can Use permissions in order for those LDAP users to access Confluence.If a password is created for an LDAP user in Confluence,it will be ignored as the LDAP password will override it. • User management in Confluence 2.0 and earlier is handled by OSUser. OSUser is configured through the osuser.xml file located in confluence/WEB-INF/classes.

Document generated by Confluence on Oct 10, 2007 11:54

Page 350

Instructions If you do not wish Confluence to retrieve any of your LDAP groups and display them inside Confluence then you can do this by specifying a dummy value for the groupSearchFilter filter in your atlassianuser.xml file. That is update your atlassian-user.xml file with the following:
<groupSearchFilter>(objectClass=dummyValue)</groupSearchFilter>

An example atlassian-user.xml file:
<baseUserNamespace>cn=users,dc=ad,dc=atlassian,dc=com</ baseUserNamespace><baseGroupNamespace>ou=groups,dc=ad,dc=atlassian,dc=com</ baseGroupNamespace><usernameAttribute>sAMAccountName</ usernameAttribute><userSearchFilter>(objectClass=user)</ userSearchFilter><firstnameAttribute>givenname</firstnameAttribute><surnameAttribute>sn</ surnameAttribute><emailAttribute>mail</emailAttribute><groupnameAttribute>cn</ groupnameAttribute><groupSearchFilter>(objectClass=dummyValue)</ groupSearchFilter><membershipAttribute>member</membershipAttribute><userSearchAllDepths>false</ userSearchAllDepths><groupSearchAllDepths>false</groupSearchAllDepths>

Please note: You will still have to provide a valid LDAP DN for baseGroupNamespace. You could use the base DN for example.

Configuring multiple LDAP repositories
For some LDAP servers, it might be necessary to configure Confluence to connect to multiple LDAP servers. This functionality is available in Confluence 2.3 and above, and has a separate guide: Configuring multiple LDAP repositories.

Related pages
Add LDAP Integration Configuring multiple LDAP repositories

Document generated by Confluence on Oct 10, 2007 11:54

Page 351

Add LDAP Integration For User Authentication Only
This page last changed on Jun 25, 2007 by smaddox.

Description
There are two kinds of Confluence/LDAP integration available:

User Authentication LDAP Without Groups LDAP With Groups

Internal Users

Internal Groups

LDAP Users

LDAP Groups

This guide covers LDAP without groups, where if a username exists in both Confluence and LDAP, they use their LDAP password to login. You still maintain users from Confluence and use internal Confluence groups for group permissions. Alternatively, you may use LDAP with Groups to have users and groups automatically updated from LDAP, and use LDAP groups for group permissions. Applies For • Enabling LDAP for the first time • Upgrading existing LDAP without enabling group management Important Points • Only the password lookup is done against LDAP and only if the Confluence username coincides with the LDAP username. Users and user profiles are still managed in Confluence. See technical explanation below. • Confluence account must be created for each LDAP user, as they do not automatically have access. For an LDAP user to access Confluence, a site administrator will still need to create an account for them. The password in this Confluence account will be ignored as the LDAP password will override it. • User management in Confluence 2.0 and earlier is handled by OSUser. OSUser is configured through the osuser.xml file located in confluence/WEB-INF/classes.

Instructions
CAUTION: Make sure that when you first set up Confluence, you make no changes to the default osuser.xml. Once Confluence is up and running, you can then apply the changes described here to enable LDAP integration.

Step One: Open the osuser.xml file located in your home directory under WEB-INF/ classes
In the osuser.xml file, the CredentialsProviders are responsible for authenticating passwords. The default CachingCredentialsProvider looks in the Confluence database. To enable LDAP aunthentication, you will need to add a LDAPCredentialsProvider, so that LDAP users can also be authenticated: Here's what the default osuser.xml contains:
<provider class="bucket.user.providers.CachingCredentialsProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingAccessProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</

Document generated by Confluence on Oct 10, 2007 11:54

Page 352

property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingProfileProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property></ provider>

Step Two: Edit the osuser.xml file as shown below:
For Confluence version 2.1 and later:
<provider class="com.atlassian.confluence.user.ConfluenceLDAPCredentialsProvider"><property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property><property name="java.naming.provider.url">ldap://localhost:389</property><property name="searchBase">dc=atlassian,dc=com</property><property name="uidSearchName">cn</property> <!-<property name="java.naming.security.principal">cn=Manager,dc=atlassian,dc=com</property><property name="java.naming.security.credentials">secret</property><property name="exclusive-access">true</ property> --> </provider><provider class="bucket.user.providers.CachingCredentialsProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingAccessProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingProfileProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property></ provider>

For older verisons of Confluence
<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider"><property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property><property name="java.naming.provider.url">ldap://localhost:389</property><property name="searchBase">dc=atlassian,dc=com</property><property name="uidSearchName">cn</property> <!-<property name="java.naming.security.principal">cn=Manager,dc=atlassian,dc=com</property><property name="java.naming.security.credentials">secret</property><property name="exclusive-access">true</ property> --> </provider><provider class="bucket.user.providers.CachingCredentialsProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingAccessProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</ property></provider><provider class="bucket.user.providers.CachingProfileProvider"><property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</ property><property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property></ provider>

• Update the following properties to suit your LDAP server: ° url (currently set to ldap://localhost:389) ° searchBase (currently set to dc=atlassian,dc=com) ° uidSearchName (currently set to cn)

Document generated by Confluence on Oct 10, 2007 11:54

Page 353

• If your LDAP server is not configured to allow anonymous lookups, you need to: ° remove comment tags ° enter the username; including searchBase (currently set to cn=Manager,dc=atlassian,dc=com) ° enter password (currently set to secret) The Credentials (password) checking is a separate operation from user-profile lookups. The profile can be loaded from the Confluence database, but the password is looked up from LDAP. Furthermore, multiple credentials providers can be specified (here, LDAP and OSUser), and if one fails, the other will be used. This allows non-LDAP users to log in with their Confluence password.
RELATED TOPICS

Activating External User Management Add LDAP Integration For User Authentication Only Changes in osuser.xml from 1.0.3a to 1.1.x Confluence Caching OSUser Provider Importing LDAP Users

Document generated by Confluence on Oct 10, 2007 11:54

Page 354

atlassian-user.xml reference
This page last changed on Sep 18, 2006 by dave@atlassian.com.

This page describes the function of each of the tags in an atlassian-user.xml file. Child tags of the <ldap> tag:

host

The host name of the machine running the LDAP server. This must resolve from the machine running Confluence. The port number that the LDAP server is running on. This should usually be 389. The distinguished name of a user who is allowed to browse the entire LDAP repository. This is omitted if the repository has anonymous access enabled. That user's password. This is omitted if the repository has anonymous access enabled. Must be 'plain'. This is omitted if the repository has anonymous access enabled. Must be 'simple', or 'none' if the repository has anonymous access enabled. This should be set to a context at the 'top' of your LDAP tree. This should be set to a context which contains all your user entities. A filter which matches only user entities. This should be set to a context which contains all your group entities A filter which matches only group entities The name of the attribute on a user entity which contains the Confluence user name of the user. The name of the attribute on a user entity which contains the first name of the user. The name of the attribute on a user entity which contains the surname of the user. The name of the attribute on a user entity which contains the email address of the user. The name of the attribute on a group entity which contains the Confluence group name of the group. The name of an attribute on a group entity which contains the distinguished name of a member of a group. This should occur multiple times on a group to indicate multiple members of the group.

port securityPrincipal

securityCredential securityProtocol securityAuthentication baseContext baseUserNamespace userSearchFilter baseGroupNamespace groupSearchFilter usernameAttribute firstnameAttribute surnameAttribute emailAttribute groupnameAttribute membershipAttribute

userSearchAllDepths

Document generated by Confluence on Oct 10, 2007 11:54

Page 355

Set to 'true' to search the baseUserNamespace level and all nodes underneath for users. Defaults to 'false'. groupSearchAllDepths Set to 'true' to search the baseGroupNamespace level and all nodes underneath for groups. Defaults to 'false'.

useUnqualifiedUsernameForMembershipComparison Set to 'true' to use the value of the usernameAttribute for membership comparisons instead of the distinguished name. Defaults to 'false'.

Document generated by Confluence on Oct 10, 2007 11:54

Page 356

Changes in osuser.xml from 1.0.3a to 1.1.x
This page last changed on Sep 14, 2006 by david.soul@atlassian.com.

If you have setup Confluence to: • delegate user management to JIRA (as per our documentation here) or • use LDAP/Active directcory authentication (as per our documentation here) Then you will need to make the following changes to your osuser.xml file: 1. replace
com.atlassian.confluence.user.providers.Caching

with
bucket.user.providers.Caching

Doing this will effectively convert the following:
com.atlassian.confluence.user.providers.CachingCredentialsProvider com.atlassian.confluence.user.providers.CachingAccessProvider com.atlassian.confluence.user.providers.CachingProfileProvider

to
bucket.user.providers.CachingCredentialsProvider bucket.user.providers.CachingAccessProvider bucket.user.providers.CachingProfileProvider

2. and replace
com.atlassian.confluence.user.ConfluenceHibernateConfigProvider

with
bucket.user.BucketHibernateConfigProvider

Alternatively You can just reconfigure the new osuser.xml with your changes.

Document generated by Confluence on Oct 10, 2007 11:54

Page 357

Configuring multiple LDAP repositories
This page last changed on May 18, 2007 by ganand.

Availability
Confluence 2.3 and above support multiple LDAP servers configured in atlassian-user.xml. Instructions are below. Confluence releases prior to 2.3 do not support multiple LDAP repositories.

Prerequisites
Before reading this, ensure you understand the configuration details outlined in Customising atlassianuser.xml. This describes how to configure a single LDAP repository in Confluence, and is prerequisite knowledge for following the instructions below. For brevity, all examples on this page are partial examples. A complete atlassian-user.xml LDAP configuration can be found in Customising atlassian-user.xml.

Configuration
To configure multiple LDAP repositories in Confluence, put multiple <ldap>...</ldap> entries into confluence/WEB-INF/classes/atlassian-user.xml. The order of the entries in the file will be the order that the repositories are searched for users. That is, if a user tries to log in with the username jsmith, the first repository in atlassian-user.xml will be searched for the user with the username jsmith. If no user is found in that repository, the second repository specified in atlassian-user.xml will be searched. Here is a partial configuration that connects Confluence to two different LDAP servers. They are given the identifiers ldap1 and ldap2, and connect to the servers ldap-sf.example.org and ldapnyc.example.org respectively.
<atlassian-user><repositories><ldap key="ldap1" name="San Francisco Example Repository" cache="true"><host>ldap-sf.example.org</host><port>389</port><!-- ... remainder of server configuration ... --></ldap><ldap key="ldap2" name="New York City Example Repository" cache="true"><host>ldap-nyc.example.org</host><port>389</port><!-- ... remainder of server configuration ... --></ldap><hibernate key="hibernate" name="Hibernate Repository" description="Hibernate Repository" /></repositories></atlassian-user>

Points to note: • each server must have a unique key attribute • each server must include the full LDAP configuration, including baseUserNamespace, baseGroupNamespace and so on • Confluence's internal repository, the <hibernate> repository, must be specified last • you can include more than two LDAP repositories, but please read the Side effects section below.

Side effects
The main side effect of configuring multiple LDAP servers is degrading performance. There are many activities in Confluence where user or group information is retrieved: • logging in • user/group searches • permission checks when viewing or editing a page. Confluence tries to cache as much information as possible from the LDAP queries, but almost certainly adding multiple LDAP servers will degrade the performance of the application. This is especially true if any of the LDAP servers are geographically distant from Confluence, where any LDAP query has a significant latency (> 50 ms roundtrip).

Document generated by Confluence on Oct 10, 2007 11:54

Page 358

Two connections to the same server
It also possible, but not usually recommended, for Confluence to connect twice to the same server. When connecting twice to the same server, you must not have overlapping group or user namespaces in the LDAP tree. Here is an partial configuration, retrieving two separate LDAP user branches, but only one LDAP group branch. To configure only a single group branch, the group filter in the second LDAP repository searches for a non-existent value so it will not return any results. (This is generally fast as long as your LDAP server has an index on objectClass for the given tree section.)
<atlassian-user><repositories><ldap key="ldap1" name="Example Repository, SF user tree" cache="true"><host>ldap.example.org</host><port>389</port><!-- ... remainder of connection configuration ... --><!-- user search filter --><baseUserNamespace>cn=San Francisco,dc=ldap,dc=example,dc=org</baseUserNamespace><userSearchFilter>(objectClass=user)</ userSearchFilter><!-- ... remainder of user configuration ... --><!-- group search filter --><baseGroupNamespace>cn=Groups,dc=ldap,dc=example,dc=org</ baseGroupNamespace><groupSearchFilter>(objectClass=group)</groupSearchFilter><!-- ... remainder of server configuration ... --></ldap><ldap key="ldap2" name="Example Repository, NYC user tree" cache="true"><host>ldap.example.org</host><port>389</port><!-- ... remainder of connection configuration ... --><!-- user search filter --><baseUserNamespace>cn=New York City,dc=ldap,dc=example,dc=org</baseUserNamespace><userSearchFilter>(objectClass=user)</ userSearchFilter><!-- ... remainder of user configuration ... --><!-- group search filter --><baseGroupNamespace>cn=Groups,dc=ldap,dc=example,dc=org</ baseGroupNamespace><groupSearchFilter>(objectClass=nothing)</groupSearchFilter><!-- ... remainder of server configuration ... --></ldap><hibernate key="hibernate" name="Hibernate Repository" description="Hibernate Repository" /></repositories></atlassian-user>

Points to note: • each repository will have its own connection pool, so Confluence will use twice as many connections to the LDAP server • performance will typically be degraded, as discussed in Side effects above • each server must have a unique key attribute • each server must include the full LDAP configuration, including baseUserNamespace, baseGroupNamespace and so on • Confluence's internal repository, the <hibernate> repository, must be specified last.

Related pages
Customising atlassian-user.xml Add LDAP Integration

Document generated by Confluence on Oct 10, 2007 11:54

Page 359

Confluence Caching OSUser Provider
This page last changed on Apr 06, 2004 by mryall.

During some operations such as rendering pages, Confluence makes a large number of queries to the user management subsystem (OSUser). To cater for this, the OSUser providers built in to Confluence in v1.0 performed a certain amount of in-memory caching of user identities. Unfortunately, this means that if you configure Confluence to use some other provider (such as LDAP or JIRA), this caching is no longer performed, and the application slows significantly as a result. This document is aimed at Confluence users who have, or wish to have Confluence use an external user management through customising their osuser.xml file. If you are just using Confluence's built-in usermanagement, you do not need to read this document. Note While the caching providers should work with any OSUser provider, we have only tested them against Confluence's built-in user-management, and the JIRA provider that ships with Confluence.

Provider Configuration
Confluence 1.0.1 introduces the following OSUser providers: com.atlassian.confluence.user.providers.CachingCredentialsProvider, com.atlassian.confluence.user.providers.CachingAccessProvider, com.atlassian.confluence.user.providers.CachingProfileProvider. They are written as caching wrappers around another provider that does all the real work. So, for example, this is the default CredentialsProvider configuration that ships with Confluence:
<provider class="com.atlassian.confluence.user.providers.CachingCredentialsProvider"> <property name="chain.classname"> com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider </property> <property name="chain.configuration.provider.class"> com.atlassian.confluence.user.ConfluenceHibernateConfigProvider </property> </provider>

To configure the caching provider, you need to supply: 1. The class-name of the provider that will ultimately be providing the credentials, as the property chain.classname 2. Any properties that need to be passed to that next provider. If the next provider requires a property configuration.provider.class, then you can pass that property to the provider by prepending chain. to the property name: chain.configuration.provider.class The configuration for the Access and Profile providers is identical.

Document generated by Confluence on Oct 10, 2007 11:54

Page 360

Importing LDAP Users
This page last changed on Jun 25, 2007 by smaddox.

Deprecation Notice A new improved LDAP integration was introduced in Confluence 2.1. This document describes the old style LDAP integration and has been deprecated. If you are new to Confluence and have not set up LDAP integration before, we recommend using the new LDAP integration. To import users from your LDAP server into Confluence,

1. 2. 3. 4.

Download the LDAP user importer. Open ldap2confluence.sh (Unix) or ldap2confluence.bat (Windows) Set the Base URL to the URL of your Confluence system (e.g. http://my.server/confluence). Set the 'ADMINUSER' and 'ADMINPASSWORD' variables to the username and password of your Confluence Admin user. 5. Setup the connection.properties file as described here. 6. Setup the mappings.properties file as described here. 7. Run ldap2confluence to import your users.
RELATED TOPICS

Activating External User Management Add LDAP Integration For User Authentication Only Changes in osuser.xml from 1.0.3a to 1.1.x Confluence Caching OSUser Provider Importing LDAP Users

Document generated by Confluence on Oct 10, 2007 11:54

Page 361

LDAP FAQ
This page last changed on May 30, 2007 by dave@atlassian.com.

For answers relating to LDAP User Management, click on any query below.

Troubleshooting
I just added LDAP

integration, why can't I login using my original account?

If there is an LDAP user with the same username as your administrator account, you must now use their password to login. LDAP logins override internal logins. Why do my LDAP users

sees 'Not Permitted' screens when they login?

To login, the user must be a member of one or more groups that have been granted 'Can Use' permission from the Administration -> Global Permissions -> Group Permissions. Confluence fails to start with error 'Error creating bean with name 'userManager' defined in class path resource [atlassianUserContext.xml]'? Your atlassian.xml file may contain filters with characters that must be escaped from XML. Check here for details.

Editing a user under Administration -> Manage Users throws an error 'org.apache.velocity.exception.MethodInvocationException' If you see an error: "org.apache.velocity.exception.MethodInvocationException: Invocation of method 'isUserDeactivated' in class com.atlassian.confluence.user.actions.ViewUserAction threw exception class java.lang.NullPointerException : null" You should open \confluence\WEB-INF\classes\atlassian-user.xml and check that your Hibernate Repository is not wrapped in a comment tag (<!-- and -->). The line to uncomment is: <hibernate name="Hibernate Repository" key="hibernateRepository" description="Hibernate Repository" /> After setting up LDAP, I

cannot see LDAP users or groups from the Confluence user or group browser

Are your users or groups located in subtrees beneath the directory returned by the search filter? If so, you may need to add <usersearchalldepths>TRUE</usersearchalldepths> or <groupsearchalldepths>TRUE</groupsearchalldepths> to your altassian-user.xml See Map LDAP Users and Groups for details. Cannot edit user groups

under Administration -> Manage Users as nothing happens

If nothing happens when you add or remove membership to an internal group, you should check that your OSUser Repository is commented out as described in Add LDAP Integration. To do so, go to your

Document generated by Confluence on Oct 10, 2007 11:54

Page 362

Confluence install directory and open \confluence\WEB-INF\classes\atlassian-user.xml. Find the entry below.
<osuser key="osuserRepository" name="OSUser Repository"/>

If not commented out, you should stop Confluence then remove or comment out that line. Cannot edit groups for

LDAP users

Confluence has read-only access to LDAP groups, they cannot be updated from within Confluence. However you should be able to edit the internal group memberships for all users. If nothing happens when you add or remove membership to an internal group, you should check that your OSUser Repository is commented out as described in Add LDAP Integration. To do so, go to your Confluence install directory and open \confluence\WEB-INF\classes\atlassian-user.xml. Find the entry below.
<osuser key="osuserRepository" name="OSUser Repository"/>

If not commented out, you should stop Confluence then remove or comment out that line. I cannot see an LDAP/AD

group in Confluence

Is the group in a subtree? If so, you will need to edit atlassian-user.xml and add a groupSearchAllDepths=true parameter to the LDAP repository to set Confluence to search subtrees of the base group namespace. See Map LDAP Users and Groups for details. I cannot get my LDAP to

work, where can I get technical support?

See Requesting External User Management Support for information on logging a support request.

General Questions
How can I enable LDAP? See Add LDAP Integration. Are all users in LDAP visible in Confluence administration? Can they can be assigned groups/permissions? All LDAP users with 'Can Use' permission can be viewed from the user browser, even if they have never logged in. When an LDAP user logs in for the first time, a Confluence user account is created automatically to store their information. You have read-only access to LDAP groups, and can add/remove Confluence internal groups to any user. How are LDAP/AD users

counted toward my license limit?

Your user count is determined by the number of internal users plus the number of LDAP users who can potentially login. LDAP users that are a member of an LDAP group with 'Can Use' permission granted in Confluence can all potentially login, which means that all members of groups with this permission granted

Document generated by Confluence on Oct 10, 2007 11:54

Page 363

will be counted towards your license. To manage your license usage, only grant login permission to AD groups where all members need accounts. You may like to setup a special confluence LDAP group if no combination of your existing groups is suitable. When a user is deleted from LDAP, how does Confluence handle this? Is the user's assignment to one or more groups still visible? Users are not deleted from Confluence, but their logins are disabled within one hour as they expire in the cache. Only non-LDAP groups are retained. Refer to the overview for more detail. How can I assign an

LDAP user a Confluence account?

LDAP groups or users granted 'Can Use' permission under 'Global Permissions' can login to Confluence. Can we user LDAP and Confluence groups simultaneously, as a "mixed mode", where some groups are kept in Confluence and others in LDAP? Yes.} If a user is in Confluence with one password, and an LDAP user with the same username is added, which password gets used? The LDAP login has priority over the Confluence login. If LDAP 'Can Use' permission is removed or the user is deleted, the Confluence login will still work. I enabled LDAP and some

users are now returned twice under the user browser

When LDAP is enabled, it is normal for the user browser to return two copies of users who have both LDAP and internal users accounts. If you are interested in a fix for this, please vote towards 'User browser shows duplicate accounts when a user exists both locally and in LDAP'. The original internal user had a lowercase username, but the LDAP user has the same username in Uppercase, does it matter which one I use? As mentioned above, LDAP login has priority over the confluence login; however only the password is taken into account here. You can log in with either the lowercase or UPPERCASE username.

Active Directory Questions
Can it make distinctions

between security and distribution groups, or group types?

No, Confluence has no group types. However, you can configure Confluence to only recognise some of these groups over others. For example, you can configure Confluence to only recognise distribution groups. this is done by adjusting the groupSearchFilter in your atlassian-user.xml file.

Document generated by Confluence on Oct 10, 2007 11:54

Page 364

be retrieved from multi-domain forests?

Can group memberships

Yes, you can do this by configuring multiple repositories: one for each domain. More instructions on how to do this can be found here: http://confluence.atlassian.com/x/AgDUAg Can Confluence support

multiple Active Directory repositories? Yes.

Can it handle nesting? No, each child group must be individually specified instead. You may wish to vote towards support for nested groups at CONF-6755.

Other Questions
For troubleshooting, please create a problem report. General enquiries should be posted to a support ticket

Document generated by Confluence on Oct 10, 2007 11:54

Page 365

Connect to LDAP via SSL
This page last changed on Jul 26, 2007 by ivan@atlassian.com.

Atlassian User LDAP supports connecting to an LDAP server over SSL/HTTPS. 1. Import your LDAP server's public certificate into the Confluence JVM keystore 2. Edit the file in your Confluence install directory, \confluence\WEB-INF\classes\atlassianuser.xml and set the <securityProtocol>ssl</securityProtocol> 3. Switch the LDAP connection to the SSL port if different from the default LDAP port. If you're using the most common LDAPS port, set <port>636</port> 4. Add the self-signed root certificate to your default Java keystore with the following command:
keytool -import -alias serverCert -file <RootCertificate.crt> -keystore %JRE_HOME%/lib/ security/cacerts

The keytool will ask you for a password. The default password is "changeit" without the quotes 5. Verify that the certificate has been added successfully by entering the following command:
keytool -list -keystore %JRE_HOME%/lib/security/cacerts

Document generated by Confluence on Oct 10, 2007 11:54

Page 366

Troubleshooting the "Not Permitted" Screen under LDAP Integration
This page last changed on Jun 15, 2006 by mryall.

If you have set up Confluence with AtlassianUser integration and attempted a login with an LDAP/AD account and got a page titled "Not Permitted" here are the steps to troubleshoot this: • Have you assiged USE permission to the relevant LDAP groups from the Administration > Global Permissons page? Before an LDAP user can login and use Confluence, the LDAP group they belong to must be given USE permission directly. (Please note: nested groups is not supported in Confluence as yet, so you cannot specify the parent group. If you want this feature, please vote for it here.) • Does an account exist on your LDAP/AD server that has the same name as your local admin account? (for example, is there an acccount on LDAP called 'admin'?) If so, then you will not be able to login with your local admin account once you enable LDAP integration. To rectify this, you need to either rename your LDAP admin account or rollback your LDAP integration and create another Confluence admin account. • You have assigned USE permission to the relevant LDAP groups, but LDAP users in those groups still get "Not Permitted"? Here, you need to check if Confluence is actually aware that your LDAP users belong to those LDAP groups. To work this out, here is what we need from you: 1. login as the local admin account you created when you first set up Confluence. 2. enable profiling by appending ?profile=on to the end of a Confluence URL (say the URL of the dashboard, if you happen to be on that page) and hit enter to refresh the page. This setting will now be enabled and cause additional information to be written to your log files to help us diagnose the problem. 3. Now browse to the Administration > Manage Users screen and do a search for any LDAP user. 4. Now click on the user to view their details (including the groups they belong to). 5. Now submit a support ticket at http://support.atlassian.com and attach: • a screenshot of the user details page • your server logs files If you are feeling brave, you can attempt to decipher the logs yourself. Here's how: 1. your logs should display something similar to this:
[0ms] com.atlassian.user.impl.ldap.adaptor.LDAPStaticGroupAdaptor_search((&(objectClass=groupOfNames) (member=cn=confadmin,ou=users,ou=people,ou=functest,dc=atlassian,dc=com))) [0ms] - com.atlassian.user.impl.ldap.repository.DefaultLDAPRepository_getLDAPContext [0ms] com.atlassian.user.impl.ldap.adaptor.LDAPStaticGroupAdaptor_search_JNDI_RAW_((&(objectClass=groupOfNames) (&(objectClass=groupOfNames) (member=cn=confadmin,ou=users,ou=people,ou=functest,dc=atlassian,dc=com))))

This means that Confluence is using this LDAP search filter (&(objectClass=groupOfNames) (member=cn=confadmin,ou=users,ou=people,ou=functest,dc=atlassian,dc=com)) to find the groups that the user 'confadmin' belongs to. Obviously, the objectClass and member attributes may differ in your install, but the filter should be similar. 2. connect to your LDAP/AD server with JXplorer or an LDAP tool of your choice, and issue the above filter and check that you get the results you expect. This should help you to identify if and why the filter is incorrect and what it should be. Please add what you find in this step to the support ticket if you are unable to resolve it from here.

Document generated by Confluence on Oct 10, 2007 11:54

Page 367

Cannot login with Confluence admin account
This page last changed on Aug 21, 2006 by dave@atlassian.com.

By 'admin account', we are referring to the account that was setup during the Confluence setup wizard. If you have just integrated Confluence with LDAP or Active Directory, but find yourself not being able to login with this account but instead get a 'not permitted' screen: here's the explanation and fix: Explanation This is caused by there being an account on LDAP with the same username as your admin account. (so for example, your Confluence admin account is 'admin' and there's a user on LDAP that also has username 'admin'). Fix 1. Shutdown Confluence 2. Open confluence/WEB-INF/classes/atlassian-user.xml in a text editor and comment out the LDAP statements for now. For example:
<atlassian-user> <repositories> <osuser key="osuserRepository" name="OSUser Repository"/> <!-<ldap key="ldapRepository" name="LDAP Repository@hecate.atlassian.com" cache="true"> <host>hecate.atlassian.com</host> <port>389</port> <securityPrincipal>cn=admin,dc=atlassian,dc=private</securityPrincipal> <securityCredential>secret</securityCredential> <securityProtocol>plain</securityProtocol> <securityAuthentication>simple</securityAuthentication> <baseContext>dc=atlassian,dc=private</baseContext> <baseUserNamespace>dc=staff,dc=perftest,dc=atlassian,dc=private</baseUserNamespace> <baseGroupNamespace>dc=groups,dc=perftest,dc=atlassian,dc=private</baseGroupNamespace> <usernameAttribute>cn</usernameAttribute> <userSearchFilter>(objectClass=inetorgperson)</userSearchFilter> <firstnameAttribute>givenname</firstnameAttribute> <surnameAttribute>sn</surnameAttribute> <emailAttribute>mail</emailAttribute> <groupnameAttribute>cn</groupnameAttribute> <groupSearchFilter>(objectClass=groupOfNames)</groupSearchFilter> <membershipAttribute>member</membershipAttribute> </ldap> --> <hibernate name="Hibernate Repository" key="hibernateRepository" Repository" /> </repositories> </atlassian-user> description="Hibernate

Notice the <!-- and --> symbols added before and after the <ldap> tags. 3. Start up Confluence. You should now be able to login with your admin account 4. Create another admin account that has a different name to the one that exists in LDAP or Active Directory. 5. Undo the changes you made to atlassian-user.xml and restart Confluence. Alternative Fix Alternatively, you can either rename or remove the admin account present on LDAP or Active Directory. But if this is not an option, stick to the fix above.

Document generated by Confluence on Oct 10, 2007 11:54

Page 368

Migrating users from Confluence to JIRA
This page last changed on Sep 07, 2006 by mryall.

There is currently no way to delegate user management from JIRA to Confluence. So, if you are in a situation where your users are defined in Confluence and would like to take advantage of Confluence's ability to use JIRA user management, you will need to transfer all of your existing Confluence users into JIRA. You can do this manually, or if you have a large number of users, you can use the attached XMLRPC script.

You should backup your JIRA installation before running this script. This is an experimental script that has not gone through the same extensive testing as the Confluence and JIRA products.

Getting the migration tool
• Download the attached rpc-tools-0.9.zip. • Extract the ZIP file to a temporary directory on your computer.

Patching Confluence 2.0.x
A patched RPC plugin is included in the ZIP file to allow remote retrieval of a full list of users from Confluence 2.0.x. To install it: • In your Confluence webapp, move confluence/WEB-INF/lib/confluencerpc.jar to a backup location • Copy plugins-confluencerpc.jar from the patch/ directory in the extracted ZIP file to confluence/WEB-INF/lib. No patch is required for Confluence 2.1 and later.

Running the migration tool
• Back up your JIRA database. • If you do not have an 'admin' username with password 'admin' in both JIRA and Confluence, create it now. • Ensure JIRA and Confluence have remote API access enabled. In both applications, it is configured in the General Configuration screen in Administration. • Edit connection.properties in the extracted ZIP file to the set the XML-RPC URLs for JIRA and Confluence. The XML-RPC URLs in the default file correspond to the following application base URLs: ° JIRA - http://localhost:8080 ° Confluence - http://localhost:8080/confluence • Run java -jar tools.jar in the extracted ZIP file directory. A successful run will generate output like the following:
$ java -jar tools.jar Transferring group: confluence-administrators Transferring group: confluence-users Transferring user: testuser1 Transferring user: testuser2

Things to note:
• This script requires that both the Confluence and JIRA remote APIs are available and accessible to a username 'admin', password 'admin'. You can temporarily add this user to both system to run the script, then remove it afterwards. • A random password will be assigned to each user that is transferred because it is not possible to access password information via the XML-RPC API. Therefore they will have retrieve a new password via the password reminder. • Jira does not allow users to sign up if they do not have a valid email address. Therefore we will assign them an email address of type username@example.com to any Confluence users that do not

Document generated by Confluence on Oct 10, 2007 11:54

Page 369

have a email address. This will allow you to find the users and help them to create a password or change the email address.

Trouble running the script?
• Ensure you have created a user 'admin' with password 'admin' in both Confluence and JIRA. • Ensure both applications have remote API access enabled (see above). • Ensure you have patched the Confluence RPC plugin if running Confluence 2.0.x. If you're still having trouble, please raise a support request, and include a copy of the error you're getting.

Document generated by Confluence on Oct 10, 2007 11:54

Page 370

Requesting External User Management Support
This page last changed on Oct 03, 2007 by ktran.

If you are having external user management issues with Confluence, and the advice on Add LDAP Integration has not helped, you can always ask us for help. External user management issues can be hard to diagnose, however, and we often spend a lot of time understanding the particular configuration you have. The best way to get a speedy resolution to your issue is to provide this information up front. Please gather all of the information listed below and include it in your support request (http:// support.atlassian.com), even if you think you have a good idea what's causing the problem. That way we don't have to ask for it later. Confluence server • Take a screenshot of Confluence's Administration # System Information (or save the page as HTML) • Take a screenshot of Confluence's Administration # Global Permissions, if you are having problems with logging in • Take a screenshot of the Space permissions page, if you are having problems with space or page permissions. Confluence configuration files • Attach a copy of atlassian-user.xml, found in confluence/WEB-INF/classes • Attach a copy of osuser.xml, found in confluence/WEB-INF/classes. If you are running Confluence 2.1 you will have to attach the following file instead of atlassian-user.xml • Attach a copy of atlassianUserContext.xml, found in confluence/WEB-INF/classes User management system • What is the name and version of your LDAP server? • Does your LDAP server use dynamic or static groups? Using Active Directory for LDAP? Please include LDAP Studio Entry Editor snaphots with the information specified on this page Diagnostics • Enable profiling (as described here) • Enable detailed user management logging by editing confluence/WEB-INF/classes/ log4j.properties: Change this section:
### # Atlassian User ### #log4j.logger.com.atlassian.user=DEBUG, confluencelog #log4j.additivity.com.atlassian.user=false #log4j.logger.com.atlassian.confluence.user=DEBUG,console #log4j.additivity.com.atlassian.confluence.user=false #log4j.logger.bucket.user=DEBUG,console #log4j.additivity.bucket.user=false

To this:
### # Atlassian User ### log4j.logger.com.atlassian.user=DEBUG, confluencelog log4j.additivity.com.atlassian.user=false

Document generated by Confluence on Oct 10, 2007 11:54

Page 371

log4j.logger.com.atlassian.confluence.user=DEBUG,confluencelog log4j.additivity.com.atlassian.confluence.user=false log4j.logger.bucket.user=DEBUG,confluencelog log4j.additivity.bucket.user=false log4j.logger.com.atlassian.seraph=DEBUG, confluencelog log4j.additivity.com.atlassian.seraph=false log4j.logger.com.opensymphony.user=DEBUG, confluencelog log4j.additivity.com.opensymphony.user=false

• 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. An example location might be confluence-2.2.2-std/logs. If you are using LDAP, download Paddle and run it. Attach the logs created to the support ticket.

Document generated by Confluence on Oct 10, 2007 11:54

Page 372

Understanding User Management in Confluence
This page last changed on Oct 08, 2007 by smaddox.

Looking for help with your user management configuration? See Requesting External User Management Support. Try Atlassian Crowd for powerful user administration Atlassian's Crowd is a web-based single sign-on (SSO) tool that simplifies application provisioning and identity management, including LDAP integration. For more information, please see the Crowd documentation on Integrating Crowd with Confluence.

Components of user management
1. 2. 3. 4. Authentication - determining what user identity is making a request to Confluence User management - storing and retrieving core information about users Group membership - storing and retrieving groups, and group membership Profile information - providing metadata associated with users.

It's important to understand that these are separate components of the user management system. The term LDAP integration is not really meaningful, because you could use LDAP repository for any or all of the above tasks. For example, in OSUser authentication can be performed against different repository to that used for group membership queries. In AtlassianUser/Polis, authentication and group membership can be retrieved from LDAP, but profile information is still stored in the Confluence database.

Authentication
Seraph Almost all authentication in Confluence (and JIRA) is performed through Seraph, Atlasian'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 performs no user management itself. 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 subsystem. If you were looking to integrate Confluence with a Single Sign-On (SSO) infrastructure, you would do so by writing a custom Seraph authenticator (and in fact, many customers have done so). XML-RPC and SOAP Authentication Authentication for requests performed by the remote API do not go through Seraph, so they can't take advantage of Seraph authenticators. XML-RPC and SOAP authentication requests are checked directly against the user-management framework, and tokens are assigned directly by the remote API subsystem. Password Authentication and User Management By default, password authentication is delegated from Seraph to the user management system. This is not necessary, however. Single Sign-On systems may have no password authentication at all, and get all the necessary credentials from the SSO provider.

Document generated by Confluence on Oct 10, 2007 11:54

Page 373

Confluence user management frameworks
The rest of this document covers the user management frameworks used by Confluence: AtlassianUser and OSUser. AtlassianUser AtlassianUser is a new user and group management framework developed by Atlassian, and is the core framework used in Confluence since version 2.1. AtlassianUser was developed with the following goals in mind: • Support LDAP as a fully functional repository for authentication, group management and profile information (profile information not yet implemented). • Compatibility with both JIRA and Confluence (JIRA support not yet implemented). • Be simple to configure (partially complete, needs better migration and UI integration). We plan to release AtlassianUser as an open source project some time in the future (probably under the name Polis), but right now the system is still under heavy development inside Atlassian. AtlassianUser provides user, group and profile management services to Confluence. It does so by delegating tasks to configurable repositories. Multiple repositories can be configured, so for example Confluence can draw user information from both the database _and _ an LDAP server.
Default configuration

By default, Confluence's AtlassianUser configuration delegates all user, group, profile and password authentication to OSUser. This is done to minimise the impact of the migration from OSUser to AtlassianUser. At some time in the future, we will migrate all user management to AtlassianUser's native providers, and the OSUser delegation will only be needed by customers who are still relying on the OSUser/JIRA bridge, or the old-style OSUser LDAP support. Configuration of AtlassianUser is done through the atlassian-user.xml file (in Confluence 2.2+) or atlassianUserContext.xml (in Confluence 2.1).
Database (Hibernate) Support

AtlassianUser can store user, group and profile data directly in Confluence's database. This will be the default behaviour for Confluence once we have completed the migration from OSUser.
LDAP support

AtlassianUser currently supports password authentication, user management and group management with an LDAP server. There are instructions on how to configure AtlassianUser LDAP integration. At this point, only read-only access to LDAP is planned. Java's JNDI-LDAP interface does not support updating an LDAP repository, and the administration tools that come with LDAP servers such as Microsoft Active Directory are generally comprehensive and already available in enterprise IT departments.
JIRA integration?

AtlassianUser will not support delegating Confluence user management to JIRA. Instead, our goal is to implement AtlassianUser as the JIRA user management framework as well. Once this is done, both Confluence and JIRA can use the same LDAP server for their authentication and group management. OSUser OpenSymphony User was Confluence's core user management framework up until it was replaced by AtlassianUser in version 2.1. OSUser is still heavily used within Confluence through AtlassianUser's OSUser repositories, and for the time being remains the default user, group and profile repository for Confluence. OSUser is also built around the model of pluggable providers, but its LDAP support is limited.

Document generated by Confluence on Oct 10, 2007 11:54

Page 374

OSUser Database (Hibernate) Providers

In its default configuration, Confluence's OSUser providers store a list of users and groups together with profile information in tables in the Confluence database: • • • • os_user (authentication) os_group (group membership) os_user_group (group membership) os_propertyentry (profile information)

The hashed password in the os_user table is used to authenticate the user unless LDAP support is enabled. The os_user_group table is queries for group membership information. OSUser configuration is controlled through the osuser.xml file.
LDAP support

OSUser only supports authentication against an LDAP server. That is, you can check user passwords against LDAP, but all other user information must be shadowed in the Confluence database. There are instructions on how to configure OSUser LDAP authentication. If you need support for LDAP user information or group membership as well, AtlassianUser should be used instead (see above).
Delegating user management to JIRA

Confluence can use OSUser to retrieve information for authentication, group membership and profile information from JIRA. If you look at the discussion of OSUser's implementation above, you can see how this can works pretty easily. A data source to JIRA database is configured in Confluence which lets Confluence read directly from JIRA's os_* tables. For example, when a user is created in JIRA, the username and password goes in the os_user table in the JIRA database. Confluence looks at the same table in the JIRA database to authenticate the user. Access to the JIRA database is read-only. For this reason, Confluence maintains a subset of the user's profile information (things like last login time and user preferences that Confluence needs to be able to modify) locally in the Confluence database. There are instructions on how to configure OSUser delegation to JIRA.

Related pages
HTTP authentication with Seraph DEV:Single Sign-on Integration with JIRA and Confluence Add LDAP Integration Adding LDAP Integration To Confluence 2.0.x Delegate user management to use JIRA logins

Document generated by Confluence on Oct 10, 2007 11:54

Page 375

User Management Frequently Asked Questions
This page last changed on Jan 18, 2007 by david.soul@atlassian.com.

This page has been split into the LDAP FAQ and JIRA User Management FAQ.

Document generated by Confluence on Oct 10, 2007 11:54

Page 376

Configuration Guide
This page last changed on Jul 30, 2007 by david.soul@atlassian.com.

The Configuration Guide contains instructions on installing and configuring Confluence. If you cannot find what you are looking for, try the Search box in the top right-hand corner.

TOPICS
Installation and Setup
Requirements Installing Confluence Standalone Installing Confluence EAR-WAR Standalone Setup Wizard Custom Installation Confluence Cluster Installation

Application Server Configuration
To install the Confluence EAR-WAR edition in an application server, click here. • • • • • • • • • • Known Issues for Apache Tomcat Known Issues for JBoss Known Issues for Jetty Known Issues for Resin 2.x Known Issues for Resin 3.x Known Issues for SAP Application Server Known Issues for WebLogic Known Issues for Websphere List Of Supported Application Servers Websphere 6 Install Walkthrough

Upgrading Confluence
Upgrading Confluence Release Notes

General Guides
Start Confluence automatically on system startup Known Issues with Enterprise or Webhosting environments Pull down RSS Feeds or use the Repository plugin through a web proxy Set JAVA_HOME variable in Windows Setup a mail session in standalone version Where Is My ConfluenceHome Directory? Configure Web Proxy Support for Confluence

Database Configuration
To configure Confluence with an external database, click here. Database Setup Guides Improving Database Performance Known Issues For Supported Databases List Of Supported Databases Migrate to a Different Database Troubleshooting External Database Connections • Troubleshooting the Embedded Database (hSQL DB) • Upgrading From HSQL 1.7.1 to 1.8 • • • • • •

Webserver Configuration
Running Confluence behind Apache Setting up Confluence with IIS Using Apache with mod_proxy Using Apache with mod_jk

RELATED CONTENT
Documentation Home Administrators Guide Frequently Asked Questions Confluence Community Development Hub Extensions

Document generated by Confluence on Oct 10, 2007 11:54

Page 377

Adding SSL on Confluence 2.1.5a and earlier
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

How to setup SSL/HTTPS access in Confluence Standalone
This section describes how to enable secure access on a Confluence Standalone instance (running Tomcat 4.1.30). The configuration details may be slightly different for newer versions of Tomcat and different application servers. Users of Confluence 2.2.0 and newer Please follow this guide instead. Create an SSL certificate using keytool Before configuring SSL, an SSL certificate must be created. If you have already configured one, you can skip this step.
Windows configuration

On Windows, perform the following at the command prompt:
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
Unix/Linux configuration

On Unix/Linux, perform the following at the command prompt:
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

This will also apply to MacOS X systems. Some questions will be asked, including a password for the certificate (the default is 'changeit'). Please note down what this is, as it will be used in the next step. Modify the conf/server.xml file In the confluence directory, open the conf/server.xml file and insert one of the following just after the closing </Engine> tag: For Tomcat 4 (Confluence 2.1.x and below):
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8443" minProcessors="5" maxProcessors="75" enableLookups="true" acceptCount="100" debug="0" scheme="https" secure="true" useURIValidationHack="false" disableUploadTimeout="true"> <Factory className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory" clientAuth="false" protocol="TLS" keystorePass="#CERT_PASSWORD#" /> </Connector>

For Tomcat 5.5 (Confluence 2.2 and above):
<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" URIEncoding="UTF-8" keystorePass="#CERT_PASSWORD#" />

Please note that the above configuration is included in the Confluence Standalone conf/server.xml file, and only needs to be uncommented. Change #CERT_PASSWORD# to the password you entered for the certificate when you generated it.

Document generated by Confluence on Oct 10, 2007 11:54

Page 378

By default, Tomcat will look in C:\Documents and Settings\\#CURRENT_USER#\.keystore (Windows) or ~/.keystore (Unix) for the certificates. If you have previously generated an SSL certificate and it is located in a different location, you will need to add an additional attribute in the conf/server.xml file. On Tomcat 4 change the <Factory> tag to following:
<Factory className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory" clientAuth="false" protocol="TLS" keystoreFile="#KEYSTORE_LOCATION#" keystorePass="#CERT_PASSWORD#" />

On Tomcat 5.5 change the <Connector> tag to following:
<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" URIEncoding="UTF-8" keystorePass="#CERT_PASSWORD#" keystoreFile="#KEYSTORE_LOCATION#" />

Also replace the #KEYSTORE_LOCATION# and #CERT_PASSWORD#. After that, restart Tomcat and access your instance on https://host.domain:8443/. For more detailed information on setting up SSL with Tomcat (including additional configuration options), have a look at Tomcat 4 SSL Howto or Tomcat 5.5 SSL Howto.

Document generated by Confluence on Oct 10, 2007 11:54

Page 379

Application Server Configuration
This page last changed on Jun 22, 2007 by smaddox.

Before deploying the EAR/WAR version of Confluence in your choice of application server, please review the setup notes and any known issues. Known Issues for Apache Tomcat Known Issues for JBoss Known Issues for Jetty Known Issues for Resin 2.x Known Issues for Resin 3.x Known Issues for SAP Application Server Known Issues for WebLogic Known Issues for Websphere

Document generated by Confluence on Oct 10, 2007 11:54

Page 380

Known Issues for Apache Tomcat
This page last changed on May 26, 2006 by mryall.

• • • • •

Configuring a MySQL Datasource in Apache Tomcat Configuring Tomcat's URI encoding Max size of HTTP POST request and Confluence page size NotSerializableException on shutdown Running Tomcat on a Different Port

Document generated by Confluence on Oct 10, 2007 11:54

Page 381

Configuring a MySQL Datasource in Apache Tomcat
This page last changed on Jul 19, 2006 by david.soul@atlassian.com.

Instructions on setting up a MySQL DataSource connection for Confluence Standalone or EAR/WAR. autoReconnect=true is required The Confluence database connection URL must have autoReconnect=true added to the end to prevent disconnection issues.

Shut down Tomcat
• Run bin/shutdown.sh or bin/shutdown.bat to bring Tomcat down while you are making these changes

Install the Drivers
• download the MySQL JDBC drivers from http://www.mysql.com/downloads/api-jdbc-stable.html. • After unpacking the file you have downloaded, you'll find a file called something like mysqlconnector-java-3.0.10-stable-bin.jar. • Copy this file into the common/lib directory of your Tomcat installation.

Configure Tomcat
The configuration is different for Conflence 2.2 onwards due to an upgrade to Tomcat 5.5 For users of Confluence 2.2 and later • If you are using the Standalone distribution. edit the conf/server.xml file in your Tomcat installation. Users running their own Tomcat instance must edit the xml file where they declared the Confluence Context descriptor. • If editing conf/server.xml, find the following lines:
<Context path="" docBase="../confluence" debug="0" reloadable="true"> <!-- Logger is deprecated in Tomcat 5.5. Logging configuration for Confluence is specified in confluence/WEB-INF/classes/log4j.properties -->

• Within the Context tags, directly after the opening <Context.../> line, insert the DataSource Resource tag:
<Resource name="jdbc/confluence" auth="Container" type="javax.sql.DataSource" username="yourusername" password="yourpassword" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost:3306/confluence?autoReconnect=true" validationQuery="Select 1" />
° °

°

Replace the username and password parameters with the correct values for your database In the url parameter, replace the word 'confluence' with the name of the database your confluence data will be stored in. If you plan to use non-latin characters, you will also need to add "&useUnicode=true&characterEncoding=utf8" on the end of the above URL. These options are not required for any database other than MySQL.

For users of Confluence 2.1.x and earlier • Edit the conf/server.xml file in your Tomcat installation • Find the following lines:
<Context path="" docBase="../confluence" debug="0" reloadable="true"> <Logger className="org.apache.catalina.logger.FileLogger" prefix="atlassian-confluence." suffix=".log" timestamp="true"/>

• Directly after the <Logger.../> line, (before the next </Context> line), insert the following:

Document generated by Confluence on Oct 10, 2007 11:54

Page 382

<Resource name="jdbc/confluence" auth="Container" type="javax.sql.DataSource"/> <ResourceParams name="jdbc/confluence"> <parameter> <name>factory</name> <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> </parameter> <parameter> <name>maxActive</name> <value>20</value> </parameter> <parameter> <name>maxIdle</name> <value>10</value> </parameter> <parameter> <name>maxWait</name> <value>10000</value> </parameter> <parameter> <name>username</name> <value>yourusername</value> </parameter> <parameter> <name>password</name> <value>yourpassword</value> </parameter> <parameter> <name>driverClassName</name> <value>com.mysql.jdbc.Driver</value> </parameter> <parameter> <name>url</name> <value>jdbc:mysql://localhost:3306/confluence?autoReconnect=true</value> </parameter> </ResourceParams>
°

° °

°

You may want to choose different maxActive and maxIdle values: these are how many total database connections will be allowed at one time, and how many will be kept open even when there is no database activity Replace the username and password parameters with the correct values for your database In the url parameter, replace the word 'confluence' with the name of the database your confluence data will be stored in. If you plan to use non-latin characters, you will also need to add &useUnicode=true&characterEncoding=utf8 on the end of the above URL. These options are not required for any database other than MySQL.

Configure the Confluence web application
• Edit confluence/WEB-INF/web.xml in your confluence installation • Go to the end of the file and just before </web-app>, insert the following:
<resource-ref> <description>Connection Pool</description> <res-ref-name>jdbc/confluence</res-ref-name> <res-type>javax.sql.Datasource</res-type> <res-auth>Container</res-auth> </resource-ref>

Configure Confluence
• If you have not yet set up Confluence ° Follow the steps in the Confluence Setup Guide ° In the Database Setup section, choose the "Datasource Connection" option. ° Set the JNDI name to java:comp/env/jdbc/confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 383

° Set the Database dialect to MySQL. • If you are changing an existing Confluence installation over to using a Tomcat datasource ° Find your ConfluenceHome directory (see: Where Is My ConfluenceHome Directory? if you don't know where it is). ° Edit the confluence.cfg.xml file ° Delete any line that contains a property that begins with hibernate. ° Insert the following at the start of the <properties> section.

<property name="hibernate.setup"><![CDATA[true]]></property> <property name="hibernate.dialect"><![CDATA[net.sf.hibernate.dialect.MySQLDialect]]></ property> <property name="hibernate.connection.datasource"><![CDATA[java:comp/env/jdbc/ confluence]]></property>

Restart Confluence
• Run bin/startup.sh or bin/startup.bat to start Tomcat with the new settings.

F.A.Q.
I see "Can't call commit when autocommit=true" during an upgrade of Confluence or otherwise. Check out http://jira.atlassian.com/browse/CONF-1710 This error can be fixed by adding: &relaxAutoCommit=true to the end of your JDBC url. Example: jdbc:mysql://localhost/confdb?autoReconnect=true&relaxAutoCommit=true This JDBC url can be found in your confluence.cfg.xml file located in your confluence home folder.

Document generated by Confluence on Oct 10, 2007 11:54

Page 384

Configuring Tomcat's URI encoding
This page last changed on May 26, 2006 by mryall.

By default, Tomcat uses ISO-8859-1 character encoding when decoding URLs received from a browser. This can cause problems when Confluence's encoding is UTF-8, and you are using international characters in attachment or page names. 1. Edit conf/server.xml and find the line where the Coyote HTTP Connector is defined. It will look something like this, possibly with more parameters:
<Connector port="8080"/>

2. Add a URIEncoding="UTF-8" property to the connector:
<Connector port="8080" URIEncoding="UTF-8"/>

3. Restart Tomcat If you are using mod_jk You should apply the same URIEncoding parameter as above to the AJP connector if you are using mod_jk, and add the following option to your Apache mod_jk configuration:
<Connector port="8009" protocol="AJP/1.3" URIEncoding="UTF-8"/> JkOptions +ForwardURICompatUnparsed

More information using Apache with Tomcat For comprehensive examples of how to use Tomcat and Apache with Confluence, see Running Confluence behind Apache.

Document generated by Confluence on Oct 10, 2007 11:54

Page 385

Max size of HTTP POST request and Confluence page size
This page last changed on Aug 02, 2006 by ivan@atlassian.com.

There is no maximum limit stipulated on a page size in Confluence. However, if a page larger then 2Mb is created, an user can experience two problems:

Rendering of a page is slow
Understandably, rendering of a large page is going to take excessive time. Don't try to put the entire content of a book into one page, split it into pages/chapters. It is easier to manage and fast to render too.

HTTP POST error when Tomcat 5 is used
java.lang.IllegalStateException: Post too large at org.apache.catalina.connector.Request.parseParameters(Request.java:2361)

This error manifests that a page is far too large, larger then 2 MB. Apache Tomcat 5, by default, sets the maximum size of acceptable HTTP POST request to 2MB. You can reconfigure Tomcat to accept larger requests. This can be done by increasing the allowable limit or just simply disabling this functionality. The file you need to edit is <Tomcat-Dir>/server.xml. Set the Tomcat configuration parameter maxPostSize for the HTTPConnector to a larger value (in bytes) to increase the limit. Setting it to 0 will disable the size check. See the Tomcat Configuration Reference for more information. maxPostSize - "The maximum size in bytes of the POST which will be handled by the container FORM URL parameter parsing. The feature can be disabled by setting this attribute to a value inferior or equal to 0. If not specified, this attribute is set to 2097152 (2 megabytes)."

Document generated by Confluence on Oct 10, 2007 11:54

Page 386

NotSerializableException on shutdown
This page last changed on Jul 09, 2007 by ivan@atlassian.com.

You may see an exception similar to this:
StandardManager[/confluence]: IOException while loading persisted sessions: java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: bucket.search.lucene.SearchWordsLister java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: bucket.search.lucene.SearchWordsLister at java.io.ObjectInputStream.readObject0(ObjectInputStream.java:1278) at java.io.ObjectInputStream.defaultReadFields(ObjectInputStream.java:1845) at java.io.ObjectInputStream.readSerialData(ObjectInputStream.java:1769)

This is because Confluence's HTTP sessions may contain objects which cannot be serialized to disk. Tomcat tries to serialize existing sessions by default during shutdown. You can add the following configuration parameter into Tomcat's server.xml file between the <Context> tags to disable this:
<Manager className="org.apache.catalina.session.PersistentManager" saveOnRestart="false"/>

Related topic
For more information regarding the saveOnRestart parameter, please refer to the Server Configuration Reference for the Manager Component

Document generated by Confluence on Oct 10, 2007 11:54

Page 387

Running Tomcat on a Different Port
This page last changed on May 24, 2007 by malam.

By default Confluence's Tomcat instance listens on port 8080 for connections, and port 8005 for the command to shut down. If you see errors like:
java.net.BindException: Address already in use:8080

in your logs, then you need to change the port number Confluence listens on (or you may be trying to start Confluence twice).

Confluence WAR/EAR edition
Modify Tomcat conf/server.xml, change the ports used on the Server tag and HTTP Connector tag. If you don't know what this means, see the example in the Standalone configuration below.

Confluence Standalone 2.2 and newer
Edit conf/server.xml in your Confluence application directory, and change the ports on the Server tag and the Connector tag to unused ports on your system. The following example shows the relevant section of server.xml where they are changed to 8100 (Server) and 8180 (HTTP Connector). In this configuration you would access Confluence on the URL: http://localhost:8180/confluence.
<Server port="8100" shutdown="SHUTDOWN" debug="0"><Service name="Tomcat-Standalone"> <Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8180" minProcessors="5" maxProcessors="75" enableLookups="true" redirectPort="8444" acceptCount="10" debug="0" connectionTimeout="20000" useURIValidationHack="false" URIEncoding="UTF-8"/>

Confluence prior to 2.2
You can change the port number by editing the file <confluence install directory>/conf/ server.xml. Find the line:
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8080" minProcessors="5" maxProcessors="75"

and change 8080 to the port you want to use. If you are running two Tomcat instances, you'll also need to change the shutdown port in the line:
<Server port="8005" shutdown="SHUTDOWN" debug="0">

Document generated by Confluence on Oct 10, 2007 11:54

Page 388

Known Issues for JBoss
This page last changed on Dec 01, 2006 by jon@atlassian.com.

A Quick Note about Confluence and JBoss
Confluence does not make any use of the JBoss container beyond its embedded Tomcat web application server, as can be easily demonstrated by the fact that our standalone Confluence ships with, and runs entirely inside, Tomcat. In addition deploying Confluence inside JBoss can cause additional problems, as described below. While JBoss is a supported platform, and (subject to the limitations below) you can deploy Confluence into it successfully, we recommend that unless there is some overriding reason to run JBoss - i.e. you are making use of its specific management features, or you're already running several other JBoss servers and want to keep your deployments consistent - you just run Confluence directly under Tomcat instead.

JBoss and Multiple Application Deployments
Atlassian do not currently support configuring Confluence on the same JBoss instance as an existing Confluence or JIRA server. Due to JBoss's inventive interpretation of the J2EE Classloader specification, multiple applications deployed on the same JBoss instance can interfere with each other. The most common symptom of this problem from the Confluence side is for a user to be unable to edit their profile (although it causes many other seemingly random problems). As such, we do not recommend running Confluence on the same JBoss instance as any other J2EE application. This issue is reported in CONF-1635. Some customers have reported success having Confluence share a server with other Confluence or JIRA instances by tweaking their classloader settings or server configurations. A number of recipes for doing so are mentioned below in comments. We currently have not verified these configurations at Atlassian. You're welcome to try them yourself, but if they do not work for you, we can not currently provide support getting them to work.

JBoss Root Logging
On starting up Confluence under JBoss, you may see the following message logged to the console:
ERROR [lifecycle] The root log4j logger is set to DEBUG level. This may cause Confluence to run slowly. ERROR [lifecycle] If you are running Confluence under JBoss, please read http:// confluence.atlassian.com/x/PtAB ERROR [lifecycle] To disable this error message, start Confluence with the system property Dconfluence.ignore.debug.logging=true

By default, JBoss ships with the root confluence logger set to DEBUG level. This means that Confluence (and any other log4j-enabled application deployed in the JBoss server) will spend a lot of time generating debugging information that will just end up wasting processor cycles and disk space. To fix this problem, edit the conf/log4j.xml file in your JBoss server installation. Find the following section: Before
<root><appender-ref ref="CONSOLE"/><appender-ref ref="FILE"/></root>

Replace it with this: After
<root><priority value ="warn" /><appender-ref ref="CONSOLE"/><appender-ref ref="FILE"/></root>

Document generated by Confluence on Oct 10, 2007 11:54

Page 389

This will raise the default log level to WARN, which is where Confluence is most comfortable running dayto-day. Logging at INFO level should also be safe, but it will result in a lot more unnecessary information being logged. We recommend you keep Confluence logging at WARN level unless something is going wrong that you need to diagnose (or you're asked to log at a lower level by support). Additional log4j.xml Configuration The Confluence log4j.properties file includes some additional logging configuration, which is overridden by JBoss's log4j.xml. To set logging to the same level as the standard Confluence distribution, you should include the following in log4j.xmlimmediately above the root declaration you edited above. Putting this anywhere else in the file will probably break your JBoss logging configuration.

Additional Logging
<logger name="com.atlassian.confluence.lifecycle" additivity="false"><level value="INFO"/><appender-ref ref="FILE"/><appender-ref ref="CONSOLE"/></logger><logger name="com.atlassian.confluence.upgrade" additivity="false"><level value="INFO"/><appender-ref ref="FILE"/><appender-ref ref="CONSOLE"/></logger>

Document generated by Confluence on Oct 10, 2007 11:54

Page 390

Known Issues for Jetty
This page last changed on Jun 16, 2006 by christopher.owen@atlassian.com.

Form sizes
Jetty limits form submission sizes to 200000 bytes by default. This can cause the following error to occur when attempting to edit a large page in Confluence.
java.lang.IllegalStateException: Form too large

This limit may be adjusted via the org.mortbay.http.HttpRequest.maxFormContentSizesystem property passed to the JVM on startup. Setting this value to 500000 may be a good start to avoid this problem but please note that setting this value too high can leave your server vulnerable to denial of service attacks.

Document generated by Confluence on Oct 10, 2007 11:54

Page 391

Known Issues for Resin 2.x
This page last changed on Nov 10, 2006 by mryall.

Resin caching breaks Confluence stylesheets
Resin 2 has a broken caching algorithm that for certain URLs will always return a 304 Not-Modified status and return no content, even when the client does not send a Last-Modified header. This usually results in broken stylesheets in Confluence. To fix this disable caching in Resin by commenting out the following line in resin.conf:
<!-- <cache dir='cache' size='4096' entries='4096'/> -->

Document generated by Confluence on Oct 10, 2007 11:54

Page 392

Known Issues for Resin 3.x
This page last changed on Jun 29, 2007 by smaddox.

Confluence requires extra configuration to run in Resin 3. As of Confluence 2.3 you can just need to update web.xml for Resin 3 with the shipped resin3 version of web.xml. In older versions, follow the instructions below.

The Symptoms
Whenever you use Confluence under Resin 3.0: • You can't seem to stay logged in, and are continually asked to enter your username and password • The Edit tab (or other links) only appear if you grant Anonymous users permission to perform those functions See also: • • • • CONF-1000 CONF-1509 CONF-1511 CONF-3397 Resin 2 Users Confluence has always run without modification on Resin 2.1.11 and later. These instructions only apply to Resin 3.0 Resin and SOAP If you want to use Confluence's SOAP interface under Resin, you will need to follow these instructions as well: Confluence and SOAP on Resin

The Solution
Resin 3.0 does not correctly support the Servlet 2.3 specification. Confluence relies on this specification to function. The workaround is to modify Confluence's web.xml file so that it is conformant with the Servlet 2.4 specification. A big thankyou to Matthew Schmidt for supplying us with this workaround.

Premodified files
You can download one of the premodified web.xml files that are attached to this page. After downloading rename to web.xml and place in the $confluenceWebapp/WEB-INF/ directory, overwriting the existing web.xml in there. Don't forget to keep a backup!

Confluence Release 2.1 2.1.2 2.1.4 2.2.1a 2.2.4

File resin-3.conf-2.1-web.xml resin-3.conf-2.1.2-web.xml resin-3.conf-2.1.4-web.xml resin-3.conf-2.2.1a-web.xml resin-3.conf-2.2.4-web.xml

Please only use the file with the exact version of Confluence you are using. An incorrect web.xml file can cause strange problems. You can follow the instructions below to patch any other version.

Document generated by Confluence on Oct 10, 2007 11:54

Page 393

Modifying web.xml manually
Step One: The web.xml header

First, you will need to change the XML preamble for the web.xml file. Servlet 2.3 validates against a DTD, Servlet 2.4 validates against a schema. Also note that the <display-name> and <description> elements have reversed orders. Before:
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN""http://java.sun.com/dtd/web-app_2_3.dtd"><web-app><display-name>Confluence</ display-name><description>Confluence Web App</description>

After:
<?xml version="1.0" encoding="UTF-8"?> <web-app id="ConfluenceWebApp" version="2.4" xmlns="http://java.sun.com/xml/ns/ j2ee"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/webapp_2_4.xsd"> <description>Confluence Web App</description><display-name>Confluence</display-name>
Step two: filter-mapping dispatchers

Move down web.xml until you find the definition of the login filter-mapping. You need to change the definitions of the login, security and sitemesh filters: Before:
<filter-mapping><filter-name>login</filter-name><url-pattern>/*</url-pattern></filtermapping><filter-mapping><filter-name>security</filter-name><url-pattern>/*</url-pattern></filtermapping><filter-mapping><filter-name>sitemesh</filter-name><url-pattern>*.action</url-pattern></ filter-mapping><filter-mapping><filter-name>sitemesh</filter-name><url-pattern>*.vm</url-pattern></ filter-mapping><filter-mapping><filter-name>sitemesh</filter-name><url-pattern>/display/*</urlpattern></filter-mapping>

After:
<filter-mapping><filter-name>login</filter-name><url-pattern>/*</url-pattern><dispatcher>REQUEST</ dispatcher><dispatcher>FORWARD</dispatcher></filter-mapping><filter-mapping><filter-name>security</ filter-name><url-pattern>/*</url-pattern><dispatcher>REQUEST</dispatcher><dispatcher>FORWARD</ dispatcher></filter-mapping><filter-mapping><filter-name>sitemesh</filter-name><urlpattern>*.action</url-pattern><dispatcher>REQUEST</dispatcher><dispatcher>FORWARD</dispatcher></ filter-mapping><filter-mapping><filter-name>sitemesh</filter-name><url-pattern>*.vm</ url-pattern><dispatcher>REQUEST</dispatcher><dispatcher>FORWARD</dispatcher></filtermapping><filter-mapping><filter-name>sitemesh</filter-name><url-pattern>/display/*</urlpattern><dispatcher>REQUEST</dispatcher><dispatcher>FORWARD</dispatcher></filter-mapping>

Confluence 2.0 In Confluence 2.0, you will need to add dispatcher tags to another of the sitemesh filter mappings:
<filter-mapping><filter-name>sitemesh</filter-name><url-pattern>/label/*</urlpattern><dispatcher>REQUEST</dispatcher><dispatcher>FORWARD</dispatcher></filtermapping>

You will also need to find all the <display-name> servlet attributes and remove them as well. For example: Before
<servlet><servlet-name>dwr-invoker</servlet-name><display-name>DWR Servlet</displayname><servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class>

Document generated by Confluence on Oct 10, 2007 11:54

Page 394

After
<servlet><servlet-name>dwr-invoker</servlet-name><servletclass>uk.ltd.getahead.dwr.DWRServlet</servlet-class>

This will need to be done for the dwr-invoker, labels-javascript, editpagejavascript, wysiwyg-javascript, labels and tinymce servlets.

Confluence 2.1 In addition to the Confluence 2.0 modifications you will also need to remove the Selenese servlet and mappings:
<servlet><servlet-name>SeleneseServletSpike</servlet-name><servletclass>com.thoughtworks.selenium.outbedded.CommandBridge</servlet-class></ servlet><servlet-mapping><servlet-name>SeleneseServletSpike</servlet-name><urlpattern>/selenium-driver/driver</url-pattern></servlet-mapping>

Otherwise you might get the following error when starting up resin:
com.caucho.config.LineConfigException: WEB-INF/web.xml:582: `com.thoughtworks.selenium.outbedded.CommandBridge' is not a known servlet. Servlets belong in the classpath, often in WEB-INF/classes.

Confluence 2.2 The removal of the <display-name/> element from the dwr-invoker, labels-javascript, editpage-javascript, wysiwyg-javascript, labels and tinymce servlets, as described in the Confluence 2.0 appendage, is no longer required.
Done

Confluence should now run under Resin 3.0. Please report any other bugs as you find them.

Document generated by Confluence on Oct 10, 2007 11:54

Page 395

Confluence and SOAP on Resin
This page last changed on Apr 26, 2006 by cmiller.

Symptom
The WSDL generated by Confluence on the Resin application server is invalid. Attempting to parse it gives you an error like this (using Axis as the client): WSDLException (at /wsdl:definitions/types): faultCode=INVALID_WSDL: Encountered illegal extension element 'types' in the context of a 'javax.wsdl.Definition'. Extension elements must be in a namespace other than WSDL's.:

Cause
The default XML parser included with the Resin application server is incompatible with the Axis SOAP library, and causes Axis to generate an invalid WSDL file. You can find information about this issue here: • http://issues.apache.org/jira/browse/AXIS-2235

Solution
The solution is to override Resin's default XML parser by placing the following within the <server> section of resin.conf:
<system-property javax.xml.parsers.DocumentBuilderFactory="org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/ ><system-property javax.xml.parsers.SAXParserFactory="org.apache.xerces.jaxp.SAXParserFactoryImpl"/ >

(You can also make this configuration per web-app by putting it in the <web-app> section. For more information see this page: JAXP - specifying XML and XSLT implementations) The Confluence issue for this error is here: • http://jira.atlassian.com/browse/CONF-5953

Document generated by Confluence on Oct 10, 2007 11:54

Page 396

Updating web.xml for Resin 3
This page last changed on Mar 29, 2007 by christopher.owen@atlassian.com.

In order to run Confluence under Resin 3, you will need to use a special version of web.xml. This has been bundled in the main Confluence download as:
confluence/WEB-INF/web.resin3.xml

To enable it, simply remove the default confluence/WEB-INF/web.xml and then rename web.resin3.xml to web.xml. Now restart.

Document generated by Confluence on Oct 10, 2007 11:54

Page 397

Known Issues for SAP Application Server
This page last changed on Aug 22, 2007 by ivan@atlassian.com.

For the complete list of supported application servers, please view this document. SAP WebAS thinks that the Confluence responses are gzipped, which makes your setup page appear like this:

You need to reconfigure the HTTP server part of WebAS to disable gzip output. Make the change on this Visual Administrator screen:

Document generated by Confluence on Oct 10, 2007 11:54

Page 398

Known Issues for WebLogic
This page last changed on Jun 04, 2007 by ivan@atlassian.com.

WebLogic Configuration tips
Enabling logging Confluence sends its log output to standard out, so by default Weblogic does not record it. To redirect Confluence's log output to a file follow these instructions Redirecting System.out and System.err to a File Confluence must be deployed as an exploded war file to WebLogic. Otherwise you may experience errors as such:
java.lang.IllegalStateException: Spring Application context has not been set at bucket.container.SpringContainerContext.getComponent(SpringContainerContext.java:98)

Deploying Confluence on Weblogic 9.x
If you are seeing the following error -- or other NoSuchMethodErrors -- then this tip is for you!
java.lang.NoSuchMethodError: org.objectweb.asm.ClassVisitor.visit(ILjava/lang/String;Ljava/ lang/String;[Ljava/lang/String;Ljava/lang/String;)V

It appears that WLS 9 ships with an incompatible version of org.objectweb.asm.* packages which clash with the ones required by Hibernate. You can fix this by adding to the weblogic.xml deployment descriptor the settings.
<container-descriptor> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor>

WebLogic 8.1 performance problems
Creating a weblogic.xml file can improve the performance of Confluence within the WebLogic 8.1 series. This is particularly suitable in cases where WebLogic continually seeks to reload files from jars - which can be noticed when profiling Confluence in WebLogic and encountering excessive calls to java.util.zip.ZipFile.getEntry() Find a typical example immediately below with an explanation of terms following:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 8.1//EN""http:// www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd"> <weblogic-web-app><jsp-descriptor><jsp-param><param-name>pageCheckSeconds</param-name><paramvalue>-1</param-value></jsp-param><jsp-param><param-name>precompile</param-name><paramvalue>false</param-value></jsp-param><jsp-param><param-name>workingDir</param-name><paramvalue>./jsp_precompile_dir/confluence</param-value></jsp-param></jsp-descriptor><containerdescriptor><servlet-reload-check-secs>-1</servlet-reload-check-secs></containerdescriptor><context-root>confluence</context-root></weblogic-web-app>

This file should be created in the WEB-INF/ directory of your Confluence deployment. The full weblogic.xml syntax is described in BEA's documentation. Here we describe some important parameters you should consider setting. Disabling JSP reload checks Performance can be considerably affected by Weblogic's tendency to scan JSPs for changes on every page load. This can be disabled by setting pageCheckSeconds to -1.

Document generated by Confluence on Oct 10, 2007 11:54

Page 399

Disabling servlet reload checks Similar to the JSP reload checks, Weblogic will scan servlets for modifications every second (by default), hurting performance. This can be prevented by setting the servlet-reload-check-secs element to -1. Avoiding JSP recompiles on redeploy If you Weblogic instance is often restarted, performance can be improved by explicitly setting a directory to save compile JSPs to (the workingDir parameter), and setting precompile to 'false'. Character Encoding A JIRA user has reported that the following configuration can ensure that Chinese character sets are displayed correctly - add the following entry to the weblogic.xml file.
<weblogic-web-app><jsp-descriptor><jsp-param><param-name>encoding</param-name><param-value>UTF-8</ param-value></jsp-param><jsp-param><param-name>compilerSupportsEncoding</param-name><paramvalue>false</param-value></jsp-param></jsp-descriptor></weblogic-web-app>

Most of this page duplicates JIRA documentation - you might also like to read http://www.atlassian.com/ software/jira/docs/latest/servers/weblogic.html . Disabling the OSCache for Confluence 2.x Confluence 2.0 uses oscache 2.1.1, which causes problems when Confluence is deployed in a weblogic container. This problem will show up by the Confluence css file taking a very long time (upwards of 30mins) to load. To fix this, you will need to disable the oscache, by removing the following entry from the WEB-INF/web.xml file.
<filter><filter-name>CacheFilter</filter-name><filterclass>com.opensymphony.oscache.web.filter.CacheFilter</filter-class></filter>

We are currently investigating the root cause of this problem

Custom templates (decorators) do not work on WebLogic 8.1 SP2.
If, after creating a custom template, you see no result, check your velocity.log for a statement similar to:
2005-01-06 14:47:57,752 - ResourceManager : unable to find resource '/<space_key>/decorators/ main.vmd' in any resource loader.

where <space_key>, of course, matches your space key. This problem does not occur on WebLogic 8.1 SP3.

WebLogic 8.1 Soap issues
Axis 1.2 is known to not work out of the box with WebLogic 8.1. Please refer to the AXIS installation instructions for details. The following excerpt was taken from the AXIS documentation. WebLogic 8.1 ships with webservices.jar that conflicts with Axis' saaj.jar and prevents Axis 1.2 from working right out of the box. This conflict exists because WebLogic uses an older definition of javax.xml.soap.* package from Java Web Services Developer Pack Version 1.0, whereas Axis uses a newer revision from J2EE 1.4. However, there are two alternative configuration changes that enable Axis based web services to run on Weblogic 8.1. In a webapp containing Axis, set <prefer-web-inf-classes> element in WEB-INF/weblogic.xml to true. An example of weblogic.xml is shown below: <weblogic-web-app> <container-descriptor> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor> </weblogic-web-app>

Document generated by Confluence on Oct 10, 2007 11:54

Page 400

If set to true, the <prefer-web-inf-classes> element will force WebLogic's classloader to load classes located in the WEB-INF directory of a web application in preference to application or system classes. This is a recommended approach since it only impacts a single web module. In a script used to start WebLogic server, modify CLASSPATH property by placing Axis's saaj.jar library in front of WebLogic's webservices.jar. NOTE: This approach impacts all applications deployed on a particular WebLogic instance and may prevent them from using WebLogic's webservices. For more information on how WebLogic's class loader works, see WebLogic Server Application Classloading.

WebLogic 8.1 & HTTP Compression
There may be problems with WebLogic 8.1 and HTTP compression (by default disabled). This issue is being investigated and tracked at CONF-6304

ATT: HSQL or Embedded Database users - Webapp redeployment problems
A customer has reported that it is not possible to redeploy Confluence when it has been set up against a HSQL or embedded database. In general we do not recommend customers use the embedded database on production systems. If you want the ability to redeploy Confluence (particulary if you have other applications deployed in your weblogic server), you must use an external database in order for it to work. Thanks to Eric Black for this tip. We are investigating the potential re-deployment problems at CONF-8106

Document generated by Confluence on Oct 10, 2007 11:54

Page 401

Known Issues for Websphere
This page last changed on Oct 19, 2006 by david.soul@atlassian.com.

Version Requirements
To run Confluence on Websphere, you will need to be running Confluence 1.4.2 or higher, against Websphere 5.1.1 with fixpack 3 or higher installed (5.1.1.3 or higher). There are known issues running Confluence against earlier versions of Websphere.

Websphere and Oracle
Confluence can not currently use Websphere datasources to access an Oracle database. This is because in order to effectively store pages in the database, Confluence needs access to the raw Oracle connection object, rather than the wrapper that Websphere places around it. We are currently working on fixing this problem (CONF-3580), but for now the workaround is to not use a Websphere datasource. Use Confluence's internal connection pool instead (the "Direct JDBC Connection" option during setup).

Websphere on Windows platform
Most Windows OS have a file path limit of 255 characters. When an application is deployed with a long name, it is possible the deployed application files will reach this path limit. Currently, there is no check performed and the error messages when trying to create such long files are not very descriptive. Example of installing Confluence on Windows XP Professional '02 sp 2. and Websphere App Server v 6.0 produced by default this deployed location:
1) C:\Program Files\IBM\WebSphere\AppServer/profiles/default\wstemp \92668751\workspace\cells\bluetongueNode01Cell\applications\atlassianconfluence-2_2_8_war.ear\atlassian-confluence-2_2_8_war.ear

to get to the class structure of Confluence that needs to be used
2) atlassian-confluence-2_2_8.war\WEB-INF\classes\com\atlassian\confluence\user \actions\UserPickerAction$UsernameToUserTranslatingPaginationSupport

hence the length to that particular class
$ perl -e 'print length "C:\Program Files\IBM\WebSphere\AppServer/profiles/defa ult\wstemp\92668751\workspace\cells\bluetongueNode01Cell\applications\atlassian -confluence-2_2_8_war.ear\atlassian-confluence-2_2_8_war\atlassian-confluence-2 _2_8.war\WEB-INF\classes\com\atlassian\confluence\user\actions\UserPickerAction $UsernameToUserTranslatingPaginationSupport"'; 264

and consequently an error which is produced when attempted to run Confluence 1) + 2):
*Cause:* java.lang.NoClassDefFoundError: com/atlassian/confluence/user/actions/ UserPickerAction$UsernameToUserTranslatingPaginationSupport at java.lang.Class.getDeclaredConstructors0(Native Method)

Troubleshooting
I can not view any Confluence page with a space in the title Please see Fix 'Page Not Found' errors for pages with spaces in the title. When I visit some URL, I get a blank page This is a known issue, caused when you visit a page in Confluence that does not exist. Confluence's "Page Not Found" error page is not being displayed correctly by Websphere. For more information, please visit the issue in JIRA: CONF-3487.

Document generated by Confluence on Oct 10, 2007 11:54

Page 402

I am having trouble with the £ and € characters Confluence allows you to specify which character encoding should be used for its requests. To use the £ and € characters, you will need to use the "UTF-8" option. However, in some cases, WebSphere will encode the characters using ISO-8859-1 before they get to Confluence. If you have set the Confluence character encoding to "UTF-8" and are having problems, have a look at http://www-306.ibm.com/ software/globalization/j2ee/encoding.jsp for an explaination of WebSphere and Character encoding. In particular, the -Dclient.encoding.override=UTF-8 system property allows you to override WebSpheres defaults.

Document generated by Confluence on Oct 10, 2007 11:54

Page 403

List Of Supported Application Servers
This page last changed on Aug 22, 2007 by ivan@atlassian.com.

For more information, please read the Supported Platforms FAQ. Compatible / Supported • • • • • • Apache Tomcat (4.1 and 5.5) Weblogic (8.1 SP3 and above) Resin (2.11.11 and above) JBoss Orion (2.0.2 and above) Websphere (5.1.1.3 and above)

Compatible / No Technical Support • Macromedia JRun - untested • Microsoft IIS Server - untested Incompatible • Oracle OC4J - issue • Sun Application Server - issue • GlassFish - issue Setup Notes and List of Known Issues for Application Server Configuration can be found here

Document generated by Confluence on Oct 10, 2007 11:54

Page 404

Websphere 6 Install Walkthrough
This page last changed on Jan 18, 2007 by tom@atlassian.com.

This page describes installing Confluence on a plain Websphere 6.0 installation.

Installation
You need to start with a confluence.war file which has had the WEB-INF/classes/confluence-init.properties file modified to set confluence.home. Log on to the administration console, i.e. http://localhost:9060/ibm/console/secure/logon.do Choose the 'Install New Application' link. Specify a path to the confluence.war file on the local file system, and choose the context root which you want to deploy confluence at (this is the context you'll access Confluence on, i.e: http://yourserver/ context_root). Click Next. (You just accept the default from here on) On the 'Choose to generate default bindings and mappings' page, just click Next. On the 'Application Security Warnings' page, just click Continue. On 'Step 1', just click Next. On 'Step 2' and 'Step 3', just click Next. On 'Step 4' click finish. The installation will be performed. Click 'Save to Master Configuration', then click the Save button. At this point you can make adjustments to the exploded version of Confluence which Websphere has put in <WAS Install Dir>\AppServer\profiles\default\installedApps\<node id>\confluence_war.ear \confluence.war. You can edit confluence-init.properties or add JDBC drivers to WEB-INF/lib -- just remember that you'll need to do this again if you reinstall the application. When that completes you'll be returned to the console. Click 'Enterprise Applications', check the 'confluence_war' checkbox and click the Start button. Go to http://localhost:9080/confluence. You should get the setup page. You don't need to use 'parent last' classloading, the default 'parent_first' works, with the changes in the position of jar files mentioned below.

Known Problems
RSS Generation Fails
The error:

com.atlassian.core.exception.InfrastructureException: java.lang.NoClassDefFoundError: com/sun/ syndication/io/WireFeedOutput &nbsp;at com.atlassian.xwork.interceptors.XWorkTransactionInterceptor.intercept(XWorkTransactionInterceptor.java(Compile Code)) caused by: java.lang.NoClassDefFoundError: com/sun/syndication/io/WireFeedOutput &nbsp;at com.atlassian.xwork.results.RssResult.doExecute(RssResult.java:41)

To correct this, copy the files 'jdom-1.0.jar' and 'dom4j-1.4-full.jar' from Confluence's WEB-INF/lib directory into your <appServerRoot>/lib directory (that is, the lib subdirectory of the directory named AppServer in the default Websphere install)

URLs with International Characters Don't Work
For example, a personal space for the user häns generates a URL which Websphere doesn't correctly interpret. We don't have a solution for this at the moment.

Document generated by Confluence on Oct 10, 2007 11:54

Page 405

Error registering bean with name 'fileSystemAttachmentDataDao'
If you get that error message, it is because the path to a class file is longer than Windows can handle. You need to rename your war file to a shorter name.

Document generated by Confluence on Oct 10, 2007 11:54

Page 406

Application Server URL encoding
This page last changed on Mar 23, 2006 by david.soul@atlassian.com.

Application servers may have different settings for character encodings. We strongly suggest setting this to UTF-8 where possible. Information on setting the character encoding is available at: • Configuring Tomcat's URI Encoding

Document generated by Confluence on Oct 10, 2007 11:54

Page 407

Confluence Installation Guide
This page last changed on Sep 19, 2007 by smaddox.

Please review the system requirements before installing Confluence:

CLIENT REQUIREMENTS
Clients can access Confluence using: • Internet Explorer 6 or later • Firefox • Mozilla-based browsers (Some do not support Rich Text Editing)

SERVER REQUIREMENTS
Server load depends primarily on the number of users online at once and their usage of Confluence. Under 25 Online Users • 1GHz+ CPU Pentium 4 or equivalent • 256MB RAM Over 25 Online Users • Dual 2.4GHz CPU Pentium Xeon or equivalent • 512MB+ RAM See Server Hardware Requirements Guide for details.
OPERATING SYSTEM

Supported • • • • • • Windows Linux Mac OS X Solaris AIX Unix

Any OS that support J2EE 1.4
DISK SPACE

Confluence Install Directory - 250MB • Install files • Nightly site backups • Temporary files Confluence Home Directory or External Database - 250MB minimum • Text content • File attachments
JAVA

Confluence requires JDK 1.4 or later. JDK 1.6 is not yet fully supported

Document generated by Confluence on Oct 10, 2007 11:54

Page 408

DATABASE

Confluence is bundled with a pre-configured HSQL database for evaluation purposes only. For safe production use, Confluence must be configured to use one of the following databases: If your database does not appear on this list, please read the Supported Platforms FAQ. Fully Supported • • • • PostgreSQL 8+ MySQL 4.1+ (MySQL 5.0 is supported when used with Confluence 2.5 and above) Oracle 10g+ DB2 8.2+

Supported with Minor Workarounds • • • • PostgreSQL 7.1+ Oracle 8i, 9i or later Microsoft SQL Server 2000+ Sybase ASE 12.5.1+

If you have no preference, PostGreSQL is scalable, free and easy to setup. For database setup information, see Database Configuration.

SELECT CONFLUENCE EDITION
Confluence can be deployed in either:

Standalone Edition • Ready for production use after connection to an external database • Packaged with Apache Tomcat for performance and scalability • Recommended for evaluation users Next Standalone Install Guide
RELATED TOPICS

EAR-WAR Edition • Deploys into an existing application server • Suitable only for server administrators Next EAR-WAR Install Guide

Confluence Setup Guide Confluence Cluster Installation Confluence User Guide How to add Confluence to a JIRA Standalone installation Confluence Documentation Home Example Size & Hardware Specifications from Customer Survey

Document generated by Confluence on Oct 10, 2007 11:54

Page 409

Confluence Cluster Installation
This page last changed on Feb 22, 2007 by rosie@atlassian.com.

Overview
There are two methods of installing Confluence in a cluster, depending on whether you have existing data. This page describes a fresh installation with no existing data. See also Confluence Cluster Installation with Existing Data.

Installation with no existing data
To get Confluence running in a two-node cluster, you must do the following: 1. Ensure you meet the clustering requirements, including obtaining a clustered license key from Atlassian for each node 2. Install Confluence on a single node, configuring an external database and a cluster name 3. Load test the single node installation, see whether clustering is required 4. Shut down the first node, copy the Confluence application and Confluence home directory to the second node 5. Start the first node, wait until it is running, then bring up the second node and it will automatically join the cluster 6. Test the cluster is working correctly 7. Configure a load balancer in front of the two clustered nodes. Each of these steps will be described in detail below.

1. Clustering requirements
Your Confluence cluster installation must meet all the following criteria for clustering: • • • • you you you you must must must must be running Confluence 2.3 or later have a clustered license use an external database use a load balancer with session affinity in front of the cluster.

Clustered licenses are available through the Confluence website. A cluster can run using two copies of Confluence Standalone. However, cluster administrators must understand how to configure an application server and web server with load balancing, so we recommend you are comfortable installing Confluence as a EAR/WAR in your application server before proceeding with a clustered installation.

2. Installation on first node
Cluster administrators should already be comfortable with the normal installation method, so it won't be repeated here. There are two differences in the Confluence Setup Wizard from a normal installation: • you must use an external database • you must enter a cluster name.

Enter a cluster name to create a new cluster Technical note

Document generated by Confluence on Oct 10, 2007 11:54

Page 410

The cluster name will be converted into a unique multicast IP address and port for your Confluence cluster. UDP multicast traffic is used for Confluence to automatically discover other nodes in the cluster when they start up.

3. Load test the single node
Most Confluence installations do not need to be clustered. Ensure you have tested your single node installation with the number of users you expect to host before going ahead with the additional complexity of clustering. Check out our performance tuning tips for ways to improve the performance of a single instance of Confluence. You can upgrade your single node to a multi-node cluster at any time by resuming this guide from step 4 below.

4. Copy Confluence to second node
Confluence clusters must use the same JDK, application server and application. The easiest way to ensure this is to shut down Confluence on the first node, then copy its web application and home directory to the second node: 1. 2. 3. 4. Shut down Confluence on node #1. Shut down your application server on node #2, or stop it automatically loading web applications. Copy the Confluence web application from node #1 to node #2. Copy the Confluence home directory from node #1 to node #2.

Copying the web application ensures any modifications you have made to the application itself, custom LDAP settings (atlassian-user.xml), and any other advanced configuration are copied to node #2. Copying the home directory ensures the Confluence search index (the index/ directory), the database and cluster configuration (confluence.cfg.xml), and any other home directory settings are copied to node #2.

5. Start Confluence on the first node, wait, then start Confluence on second node
For the most stable start-up process, it is important to start Confluence one server at a time. 1. 2. 3. 4. Start Confluence on node #1. Wait for Confluence to become available on node #1. Start Confluence on node #2. Wait for Confluence to become available on node #2.

6. Test cluster connectivity
The Cluster Administration page (Administration, Cluster Configuration) includes information about the active cluster. When the cluster is running properly, this page displays: • a correct count of the nodes in the cluster • a status display for each node in the cluster • an uptime for each node that is accurate.

Document generated by Confluence on Oct 10, 2007 11:54

Page 411

Cluster Administration page A simple process to ensure your cluster is working correctly is: 1. 2. 3. 4. 5. Create a new document on node #1 Ensure the new document is visible by accessing it directly on node #2 Wait one minute (Confluence does batch indexing once per minute) Search for the new document on node #1, ensure it appears Search for the new document on node #2, ensure it appears. Technical note If Confluence detects more than one instance accessing the database but not in a working cluster, it will shut itself down in a cluster panic. This can be fixed by troubleshooting the network connectivity of the cluster.

7. Configure load balancer
For the moment, configuring the load balancer is outside the scope of this document. However, a simple Apache and Tomcat load-balancing configuration is available, which includes sample configuration for the Apache Tomcat and the Apache web server, using its load-balancing JK connector.

Troubleshooting
If you have problems with the above procedure, please see our Cluster Troubleshooting guide.

Upgrading a cluster
It is important that upgrades follow the procedure for Upgrading a Confluence Cluster.

Related documentation
Confluence Cluster Installation with Existing Data Confluence Installation Guide Upgrading a Confluence Cluster Cluster Administration page

Document generated by Confluence on Oct 10, 2007 11:54

Page 412

Apache and Tomcat load balancing
This page last changed on Aug 27, 2007 by pfragemann.

Overview
The following is a description of how to setup a Confluence Cluster on a Windows machine using Apache and mod_jk to handle the loadbalancing. The characteristics of this cluster are: • Session affinity: sessions are associated with single servers. • Failover: if a server dies, a connection will be directed to the nearest available server. (NOTE: sessions are not replicated) • Failback: when a server comes back online, it will rejoin the cluster. • Weighted load balancing: the load balancing can be controlled to take into account machine differences. (See the mod_jk documentation for details on this.) What do you need? 1. Download and install one copy of Apache httpd. Do not install Apache as a service, but set it to listen on port 8080. (Tested with Apache httpd 2.0.55.) 2. Download the latest version of mod_jk. Copy this file into the Apache modules/ directory and rename it to mod_jk.so. (Tested with JK-1.2.19.) 3. Download and extract one copy of the ZIP distribution of Apache Tomcat. (Tested with Tomcat 5.5.) 4. Download JDBC drivers for the external database you will be using. Put the drivers in Tomcat's common/lib/ directory. (Tested with Postgresql 8.1, postgresql-8.1-404.jdbc3.jar).

Apache configuration
Edit the main Apache config file, conf/http.conf: • add the following immediately after the other LoadModule directives:
LoadModule jk_module modules/mod_jk.so

• add the following just before the end of the file:
JkWorkersFile conf/workers.properties JkLogFile logs/mod_jk.log JkLogLevel info JkMount /confluence loadbalancer JkMount /confluence/* loadbalancer

Create a workers.properties file in the Apache conf/ directory. This version of the workers.properties file is configured to use 2 Tomcat instances: tomcat1 and tomcat2.
worker.list=loadbalancer worker.tomcat1.port=18081 worker.tomcat1.host=localhost worker.tomcat1.type=ajp13 worker.tomcat1.lbfactor=1 worker.tomcat2.port=28081 worker.tomcat2.host=localhost worker.tomcat2.type=ajp13 worker.tomcat2.lbfactor=1 worker.loadbalancer.type=lb worker.loadbalancer.balanced_workers=tomcat1, tomcat2 worker.loadbalancer.method=Busyness

Document generated by Confluence on Oct 10, 2007 11:54

Page 413

Tomcat configuration
The Tomcat configuration below will run multiple instances from the same binaries in the main Tomcat directory. For complete documentation of this configuration, see the RUNNING.txt file in the Tomcat distribution.
Create instance home directories

Create a directory for each instance of Tomcat, somewhere outside where you installed Tomcat. For example, if you extracted Tomcat to /opt/apache/tomcat-5.5, your instances could be in /var/tomcatinstances/tomcat1, /var/tomcat-instances/tomcat2. These folders will be referred to as the instance home directories. Copy the following folders from the Tomcat installation directory into each instance home directory. Some of the folders may be empty, but copy them anyway. • • • • conf logs shared webapps

Configure server.xml in each instance

Edit conf/server.xml in the instance home directories to include the Confluence application and have distinct listen ports for Server, HTTP Connector and AJP13 Connector. All nodes can use the same Confluence webapp as long as you set confluence.home via a system property (see startup scripts below). Attached are two sample configurations: • tomcat1/conf/server.xml - listens on port 18080 (http) and 18081 (ajp13) • tomcat2/conf/server.xml - listens on port 28080 (http) and 28081 (ajp13) To use these sample config files, you will need to edit them to set the Confluence web-app location and the data source configuration. If editing the configuration files yourself, the points to note are: • 'Server' port must be distinct • 'Connector' for HTTP must be uncommented and use a distinct port. Use this port for testing the node individually. • 'Connector' for AJP13 must be uncommented and use a distinct port. This port must match the port of the worker in the Apache workers.properties. • 'Engine' for localhost must have jvmRoute matching the name of the worker in Apache's workers.properties. • 'Context' for Confluence must be added inside the 'Host' tag, and include a 'Resource' for the datasource, as per normal Confluence installation under Tomcat.
Create a startup script for each instance

The startup scripts for each instance must set the CATALINA_BASE environment variable and confluence.home system property. The variables in the sample scripts below should reference: • • • • CATALINA_HOME - Tomcat installation directorty CATALINA_BASE - Tomcat instance home directory (distinct for each node) JRE_HOME - Java runtime directory JAVA_OPTS - include a confluence-home system property (distinct for each node)

tomcat1/startup.bat:
set CATALINA_HOME=C:\home\mryall\opt\apache\apache-tomcat-5.5.16 set CATALINA_BASE=C:\home\mryall\var\tomcat-instances\tomcat1 set JRE_HOME=C:\Java\jre1.5.0_06 set JAVA_OPTS=-Dconfluence.home=C:\home\mryall\data\confluence\cluster\tomcat1 -Xmx512m %CATALINA_HOME%\bin\startup.bat

Document generated by Confluence on Oct 10, 2007 11:54

Page 414

tomcat2/startup.bat:
set CATALINA_HOME=C:\home\mryall\opt\apache\apache-tomcat-5.5.16 set CATALINA_BASE=C:\home\mryall\var\tomcat-instances\tomcat2 set JRE_HOME=C:\Java\jre1.5.0_06 set JAVA_OPTS=-Dconfluence.home=C:\home\mryall\data\confluence\cluster\tomcat2 -Xmx512m %CATALINA_HOME%\bin\startup.bat

Continue setting up Confluence
Follow the Confluence Cluster Installation procedure with the steps following the app server setup.

Troubleshooting
General advice The above tomcat configurations enable HTTP connectors on each Tomcat instance so that you can connect to the nodes individually. To check whether the load balancer (Apache & mod_jk) is causing the problem, try connecting to the individual Tomcat instances. Please note that you should not allow users to directly access individual nodes in production mode: You don't want people to bookmark nodes since the node details might change, or single nodes may be taken out of the cluster for maintenance while the cluster itself is still available. Session-affinity doesn't seem to be working? Ensure the name you use for your worker in workers.properties (e.g. tomcat1) matches the jvmRoute attribute of the engine tag in your Tomcat server.xml. For an example, search for 'Engine' in the attached sample config. For troubleshooting your Confluence cluster, see Cluster Troubleshooting.

References
General http://raibledesigns.com/tomcat/ http://httpd.apache.org/ Tomcat Clustering support http://tomcat.apache.org/tomcat-5.0-doc/cluster-howto.html http://tomcat.apache.org/tomcat-5.0-doc/balancer-howto.html http://tomcat.apache.org/tomcat-3.3-doc/mod_jk-howto.html Clustering and Load Balancing in Tomcat 5, Part 1 Clustering and Load Balancing in Tomcat 5, Part 2

Document generated by Confluence on Oct 10, 2007 11:54

Page 415

Confluence Cluster Installation with Existing Data
This page last changed on Dec 29, 2006 by mryall.

Overview
There are two methods of installing Confluence in a cluster, depending on whether you have existing data. This page describes how to upgrade an existing Confluence instance into a cluster. See also Cluster installation without existing data.

Cluster installation from an existing copy of Confluence
To upgrade an existing copy of Confluence to run in a two-node cluster, you must do the following: 1. Ensure you meet the clustering requirements, including obtaining a clustered license key from Atlassian for each node 2. Upgrade the existing Confluence instance to a clustered license 3. Enable clustering and select a cluster name 4. Shut down the first node, copy the Confluence application and Confluence home directory to the second node 5. Start the first node, wait until it is running, then bring up the second node and it will automatically join the cluster 6. Test the cluster is working correctly 7. Configure a load balancer in front of the two clustered nodes. Each of these steps will be described in detail below.

1. Clustering requirements
Your Confluence cluster installation must meet all the following criteria for clustering: • • • • you you you you must must must must be running Confluence 2.3 or later have a clustered license use an external database use a load balancer with session affinity in front of the cluster.

Clustered licenses are available through the Confluence website. A cluster can run using two copies of Confluence Standalone. However, cluster administrators must understand how to configure an application server and web server with load balancing, so we recommend you are comfortable installing Confluence as a EAR/WAR in your application server before proceeding with a clustered installation. You can follow the instructions to Migrate Confluence to an external database.

2. Upgrade existing instance to clustered license
Once you've obtained your clustered license from Atlassian, you can simply update the license in your running Confluence instance: 1. Go to 'Administration'. 2. Go to 'License Details', and paste in the new license. 3. Click 'Save'. When you enter a clustered license, you will see a new line appear on this page: Licensed Clustered Nodes. This tells you how many nodes your Confluence license will allow.

Document generated by Confluence on Oct 10, 2007 11:54

Page 416

License Details page shows the number of cluster nodes permitted

3. Enable clustering and select a cluster name
When you change Confluence to use a cluster license, a new menu option will be revealed on the left: Cluster Configuration. Open this menu item to configure your cluster. On this page, you need to enter a name for your cluster, and possibly select which network interface on your server will be used for the cluster (only if you have more than one suitable interface). Clicking 'Start cluster' will migrate your attachments to the database, then prevent any access to Confluence until it is restarted. Technical note The cluster name will be converted into a unique multicast IP address and port for your Confluence cluster. UDP multicast traffic is used for Confluence to automatically discover other nodes in the cluster when they start up.

4. Copy Confluence to second node
For the remaining steps in setting up a cluster with existing data, please continue from step 4 in the normal Confluence cluster installation guide.

5. Start Confluence on the first node, wait, then start Confluence on second node
See comment in step 4.

6. Test cluster connectivity
See comment in step 4.

7. Configure load balancer
See comment in step 4.

Troubleshooting
If you have problems with the above procedure, please see our Cluster Troubleshooting guide.

Upgrading a cluster
It is important that upgrades follow the procedure for Upgrading a Confluence Cluster.

Related documentation
Confluence Cluster Installation Confluence Installation Guide Upgrading a Confluence Cluster Confluence User Guide

Document generated by Confluence on Oct 10, 2007 11:54

Page 417

Upgrading a Confluence Cluster
This page last changed on Jan 04, 2007 by mryall.

This page contains instructions for upgrading an existing Confluence cluster to a new version of Confluence. If you are not running a clustered instance of Confluence and wish to, see Confluence Cluster installation with existing data. You can download the latest version of Confluence from here.

Overview
The steps involved in upgrading a multi-node Confluence cluster are: 1. Backup your confluence instance. 2. Read the Release Notes for this version and check you have the required expertise to perform the upgrade. 3. Stop each node in the cluster. 4. Install the new version into the application server on the first node. 5. Install the new version into the application server onto the remaining nodes.

Step One: Backing up
We highly recommend that you backup your Confluence home and install directories and your database before proceeding. For specific files to backup see Upgrading Confluence.

Step Two: Things you need to check ...
• Always check the release-notes for the version of Confluence you are installing for upgrade instructions specific to that version. • To perform this upgrade you must be familiar with the usage of the application server running your Confluence Cluster, and the web server load balancing it. • Check the Configuration Guide for your application server and database, to make sure there isn't anything extra you need to do to get Confluence running. • Check that you know what configurations or customisations have been made to your Confluence instance. These may include specialised user management configurations and changes to Confluence's Java classes and Velocity templates.

Step Three: Stopping the cluster
It is vital that all nodes in the cluster are running the same version of Confluence. That's why the first step is to stop all the nodes. Stop the Confluence application on each node using your application server.

Step Four: Upgrading the first node
We advise configuring your load balancing web server to redirect traffic away from Confluence until the upgrade is complete on multiple nodes. Upgrading a cluster node uses the same process as "Method One" on Upgrading Confluence. 1. Unzip the new version. 2. Edit its confluence-init.properties to point to the existing home directory. 3. Port any immediately required customisations from the old version to the new one. Eg atlassianuser.xml. 4. Install the new version into the application server. Eg for Tomcat edit confluence.xml or server.xml to point to the new location, and restart Tomcat. 5. Wait for the Node to finish upgrading and confirm that you can log in and view pages before continuing to Step Five.

Document generated by Confluence on Oct 10, 2007 11:54

Page 418

6. Port any additional customisations from the old version to the new version. Eg modifications to Java classes or Velocity templates.

Step Five: Upgrading other nodes
Copy the confluence installation, complete with customisations, to the next node. 1. Edit its confluence-init.properties to point to the existing home directory. 2. Install the new version into the application server. Eg for Tomcat 5 edit confluence.xml to point to the new location, and restart Tomcat. 3. Wait for the Node to finish upgrading and confirm that you can log in and view pages before continuing with the next node.

Troubleshooting
For suggested troubleshooting techniques, see our Cluster Troubleshooting page.

Related documentation
Confluence Installation Guide Cluster Troubleshooting Confluence Cluster Installation Confluence Cluster Installation with existing data Confluence User Guide

Document generated by Confluence on Oct 10, 2007 11:54

Page 419

Confluence Unix and X11 Dependencies
This page last changed on Sep 20, 2007 by mryall.

If This Doesn't Help If you have X11 installed and thumbnailing still does not work, please ensure that you are running Java in headless mode: see the FAQ "Fix 'Error using thumbnails - No image support in Java runtime'"

Java X11 Dependencies
On Unix-based operating systems, the Java runtime makes use of certain parts of the platform's native X11 graphics libraries. The X Server does not have to be running, but the libraries must be available on the server. Confluence will run on a server that does not have Xlib installed, but parts of the application that manipulate graphics: PDF exports, image thumbnailing, the image gallery macro, CAPTCHA, and the resizing of profile pictures, will fail. Mac OS X You do not need to install X11 on Mac OS X, as it has its own graphics libraries. If X11 is not present, you may see any of the following errors • "This Confluence installation can not generate thumbnails: no image support in Java runtime" • "Exception in thread "main" java.lang.UnsatisfiedLinkError: /usr/local/j2sdk1.4.2_09/jre/lib/i386/ libawt.so: libXp.so.6: cannot open shared object file: No such file or directory" when exporting a PDF • "NoClassDefFoundError" when uploading a profile picture

Specific Installation Instructions
Fedora Core On Fedora Core, you will need to install the xorg-x11-deprecated-libs package. (https:// bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130239) Fedora Core 6, RHEL 5 • libXp • libXp-devel (if you wish to compile against this library) Debian Linux On Debian, you will need to instll the following packages (CONF-6411): apt-get install libx11-6 libx11-dev libxt6 libxt6-dbg libxext6 libxtst-dev libxtst6 xlibs-dbg xlibs-dev Gentoo Linux emerge libICE libSM libX11 libXext libXp libXt libXtst

Document generated by Confluence on Oct 10, 2007 11:54

Page 420

Error creating bean with name 'scheduler'
This page last changed on Mar 29, 2005 by vidya.

If you install Confluence 'out of the box' and encounter the error below, consider your location's way of calculating the current date. org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'scheduler' defined in class path resource [schedulingSubsystemContext.xml]: Initialization of bean failed; nested exception is org.quartz.SchedulerException: Based on configured schedule, the given trigger will never fire. It's possible to encounter this if your current country's way of reading timestamps differs from the norm. For example, one of our users encountered this problem in Thailand, which worked out the current year (2005) to be 2548. Simply change the operating system's calculation of the date to resemble "the norm" - i.e., European style calculation - and start your application server again. The scheduling subsystem in Confluence is based on Quartz .

Document generated by Confluence on Oct 10, 2007 11:54

Page 421

Example Size & Hardware Specifications From Customer Survey
This page last changed on Sep 17, 2007 by david.soul@atlassian.com.

Below are the results of a survey conducted by Atlassian in July 2007, showing some capacity statistics for Confluence users. The figures are broken down by industry and number of users.

Num Users

Length of time in production

Database

Application Server

Num CPUs/ Cores

Physical Memory/ RAM

Operating System

Satifaction with Confluence Performance

Banking/ Finance 26 - 50 3-6 Months Ago 2 Years Ago 3-6 Months Ago 3-6 Months Ago 3-6 Months Ago 2 Years Ago 10-12 Months Ago Microsoft SQL Server Sybase ASE Oracle Standalone/ 2 Apache Tomcat Weblogic >8 2G Windows Neutral

26 - 50 51 - 250

>16G 4G

Unix Unix

Satsfied Neutral

Standalone/ 2 Apache Tomcat Websphere 2

501 1,000 1,001 5,000 1,001 5,000 5,001 10,000 Education 1-25

Microsoft SQL Server Oracle

2G

AIX

Satsfied

Standalone/ 2 Apache Tomcat Websphere 4

4G

Windows

Satsfied

Oracle Microsoft SQL Server

>16G 16G

Solaris Linux

Extremely Satisfied Satsfied

Standalone/ 4 Apache Tomcat

2 Years Ago 10-12 Months Ago <3 Months Ago 10-12 Months Ago

DB2

Standalone/ 2 Apache Tomcat Standalone/ 2 Apache Tomcat Standalone/ Apache Tomcat Standalone/ 1 Apache Tomcat

2G

Linux

Satsfied

26 - 50

MySQL

2G

Linux

Extremely Satisfied Unsatisfied

51 - 250

Oracle

1G

Windows

51 - 250

Oracle

2G

Unix

Extremely Satisfied

Engineering/ Aerospace 251 - 500 Oracle 1 1G Mac OS X Satsfied

Document generated by Confluence on Oct 10, 2007 11:54

Page 422

7-9 Months Ago 1,001 5,000 7-9 Months Ago Microsoft SQL Server

Standalone/ Apache Tomcat JBoss 2 4G Linux Satsfied

Entertainment 1,001 5,000 Government 51 - 250 2 Years Ago MySQL Standalone/ 2 Apache Tomcat 2G Mac OS X Extremely Satisfied 10-12 Months Ago PostgreSQL Standalone/ 2 Apache Tomcat 8G Linux Extremely Satisfied

Technology 501 1,000 7-9 Months Ago MySQL Standalone/ 1 Apache Tomcat 2G Linux Satsfied

Telecommunications & Media 1-25 3-6 Months Ago 7-9 Months Ago 10-12 Months Ago Standalone/ Standalone/ 1 HSQL Apache Tomcat MySQL Standalone/ 1 Apache Tomcat Standalone/ 2 Apache Tomcat 2G Linux Satsfied

1-25

Linux

Satsfied

26 - 50

MySQL

2G

Linux

Satsfied

Document generated by Confluence on Oct 10, 2007 11:54

Page 423

Get A Confluence Licence
This page last changed on Jan 02, 2007 by david.soul@atlassian.com.

Don't have a licence yet? • New users can get a free multi-user Evaluation licence or two-user Personal licence immediately • For enterprise, non-profit, open source and educational licences, see Confluence Licencing and Pricing • Existing users can retrieve their key from the Licence Viewer • If you can't find your key or are having problems, contact sales@atlassian.com

Document generated by Confluence on Oct 10, 2007 11:54

Page 424

Installing Confluence Standalone
This page last changed on Sep 19, 2007 by smaddox.

This install guide is for users running Windows, Mac OS X, Solaris, Unix or Linux. Notes • You must be able to use a command prompt and install Java to continue. If not, please contact your system administrator to assist you or consider the Online Trial • Have your licence key ready. You can obtain a trial, free or commercial licence now, or retrieve your existing key • Help is available under Troubleshooting

STAGE 1 - Install The Java Developers Kit
Do you already have the Java Developers Kit 1.4 or newer installed? • Yes • No, or not sure (Mac users can go straight to STAGE 2, as OS X comes with a Java Development Kit.) • It is fine to be using JDK 1.4 but JDK 1.5 is the preferred Java platform as it is more reliable and faster. • JDK 1.6 is not yet fully supported.

JDK 1.5 Or Earlier You must confirm the JDK is installed correctly: 1. Open a command prompt. On Windows this is done by opening your Start menu and selecting Run, then typing cmd and pressing OK. 2. Type the following in the command prompt and then press Enter: • If you are using Windows OS: echo %JAVA_HOME% • If you are using Unix: echo $JAVA_HOME If a line is displayed such as C:\Progra~1\Java\jdk1.5.0_06 with the last two letters being dk, the JDK is installed. If nothing is displayed, or the last two letters in the path are not dk, follow the 'No, or not sure' instructions. 3. Users who have installed a non-Sun JDK must install the Sun JSSE package 4. Go to STAGE 2

JDK Unknown or Not Installed Install the JDK: 1. Download JDK 1.5_08 to the Confluence server 2. Once downloaded, run the installer. At one point, you will be asked to choose a directory to install to. Copy or write this directory down for use later 3. Windows users follow these instructions to set your JAVA_HOME environment variable to the directory you just installed the JDK in. The default directory is under C:\Program Files\Java 4. Go to STAGE 2

STAGE 2 - Download & Unzip Confluence
Select your operating system: • Windows • Unix, Linux or Solaris • Mac The Install Directory is also referred to as the <Confluence-Install> Directory.

Document generated by Confluence on Oct 10, 2007 11:54

Page 425

The Home Directory is also referred to as the <Confluence-Home> Directory.

Windows 1. The default Windows unzipper cannot unzip Confluence If you have already unzipped Confluence using the default Windows unzip, delete the directory created now 2. You will need a third-party unzip program like 7Zip or Winzip. If you do not have one, download and install one before continuing: • 7Zip Recommended. If in doubt, download the '32-bit .exe' version • Winzip 3. If you have not downloaded Confluence already, download the Standalone zip 4. Use your unzip program to unzip the install file to a directory such as c:\confluence, avoiding directories with spaces. To make upgrades easier, Windows users should aim to create a directory structure like below:
c:\confluence\confluence-2.2.10-std c:\confluence\data <-- <Confluence-Install> directory, unzipped now <-- <Confluence-Home> directory, created next

You have now created your <Confluence-Install> directory. This is the directory where you unzipped Confluence, for example c:\confluence\confluence-2.2.10-std 5. Go to STAGE 3

Unix, Linux or Solaris 1. Install these X11 libraries 2. If you have not downloaded Confluence already, download the Standalone TAR 3. Use your unzip program to unzip the install file to a directory such as /home/jsmith/ confluence-2.4.2-std/, avoiding directories with spaces. Linux or Unix users can use any unzip program to unzip Confluence, but Solaris users must use GNU Tar instead of Solaris Tar
/home/jsmith/confluence-2.4.2-std/ unzipped now /home/jsmith/confluence-data/confluence-2.4.2-std/ created next <-- <Confluence-Install> directory, <-- <Confluence-Home> directory,

You have now created your <Confluence-Install> directory. This is the directory where you unzipped Confluence, for example /home/jsmith/confluence-2.4.2-std/ 4. Go to STAGE 3

Mac OS X 10.3 or 10.4 1. Before you begin, it is recommended that you run Software Update to ensure that your operating system is up to date. 2. If you have not downloaded Confluence already, download the Standalone ZIP. 3. Find the downloaded file in the Finder. Double-click on the file to extract it to a directory called confluence-2.4.2-std (or similar). 4. Move this folder to wherever you want to keep your Confluence installation (for example, under your user's home folder). Ensure that there are no spaces in the folder name, or in the names of any of its parent folders. This folder that includes the Confluence application is called the <ConfluenceInstall> folder. 5. Create a folder named confluence-data. You can create this anywhere, e.g. in your home folder, but not inside the <Confluence-Install> directory. Ensure that there are no spaces in the folder name, or in the names of any of its parent folders. Create this folder in the Finder, using the 'New Folder' command in the 'File' menu. This folder is called the <Confluence-Home> folder. 6. You now need to set up an environment variable which tells Confluence where your Java Virtual Machine is installed. Inside the <Confluence-Install> folder, edit the file bin/setenv.sh. Open it with TextEdit, and add the following line as the first line of the file:
export JAVA_HOME=/Library/Java/Home

Document generated by Confluence on Oct 10, 2007 11:54

Page 426

7. Go to STAGE 3

STAGE 3 - Set Your Home Directory
This stage creates a Home directory where Confluence will store its configuration information, indexes and attachments. 1. Open your <Confluence-Install> directory 2. Under the install directory, find \confluence\WEB-INF\classes\confluence-init.properties

3. Open the file confluence-init.properties in a text editor such as Notepad (Windows) or TextEdit (Mac). 4. Scroll to the bottom and find the line
# confluence.home=c:/confluence/data

5. Remove the '#' and the space at the front of this line to uncomment it. It should now begin with 'confluence.home' 6. Choose what your <Confluence-Home> directory will be. • Windows users should use the default c:\confluence\data for simplicity but you can choose any directory that does not contain a space in the path. • Mac users should use the <Confluence-Home> folder they created earlier. 7. If you are using a different <Confluence-Home> directory from c:\confluence\data, edit the line now. • Windows users must use / characters to separate each directory in the path. Windows users can save the <Confluence-Home> directory as the default by saving the line as
confluence.home=c:/confluence/data

• Linux users should specify <Confluence-Home> using the absolute path instead of a symbolic link, e.g:
confluence.home=/home/jsmith/confluence-data/confluence-2.4.2-std/

• Mac users should place the cursor after the '=' sign, find the the <Confluence-Home> folder which you created earlier and drag it to TextEdit. This will insert the full path of the folder into the file. It's important to make sure that you deleted the leading '#' character, and that the path after the '=' sign starts with a '/' character. The line should now look something like this:
confluence.home=/Users/jsmith/confluence-data

You have now set your <Confluence-Home> directory.

STAGE 4 - Check the Ports
If you have another Tomcat instance running on the same machine, you may need to change the port which Confluence is listening on. By default, Confluence is listening on port 8080. If this port is already used in your installation, follow these instructions to change the port.

Document generated by Confluence on Oct 10, 2007 11:54

Page 427

STAGE 5 - Review Release Notes
Review the Release Notes for your Confluence version and apply any patches listed.

STAGE 6 - Start Confluence
To start Confluence for the first time, 1. Go to your <Confluence-Install> directory 2. Under your <Confluence-Install> directory, open the bin directory and run the startup script. Windows users run startup.bat while users with other operating systems run startup.sh

Mac users will be prompted by OS X to choose an application to use. Choose the Terminal application, which is inside the Utilities folder. immediately when started, click here for assistance If the window closes

An error is preventing Confluence from starting. To view this error: 1. Open a command prompt. On Windows, do this by clicking on your Start menu, then click Run. In the Run box, type cmd and press OK 3. From the command prompt, go to your <Confluence-Install> directory 4. Go into the bin subdirectory 5. Run startup.bat and read the error message 6. Find the solution to that error in the Troubleshooting section 3. Once Confluence is running, open a web browser and visit http://localhost:8080/. (If you changed the port earlier, use the port you specified in STAGE 4 above.) The Confluence Setup Wizard should appear for you to enter your licence key. If the address shows an error, check the Troubleshooting section

NEXT STEP
Proceed to the Confluence Setup Wizard Guide
TROUBLESHOOTING

Solutions to common issues with installing Confluence. Review your logs by opening the Confluence install directory and checking the /logs/catalina.out and /logs/catalina.out files for errors described below. Click on a problem to show the solution. Confluence window

closes immediately when started An error is preventing Confluence from starting.

1. Open a command prompt. On Windows, do this by clicking on your Start menu, then click Run. In the Run box, type cmd and press OK

Document generated by Confluence on Oct 10, 2007 11:54

Page 428

2. 3. 4. 5.

From the command prompt, go to your Confluence install directory Go into the bin subdirectory Run startup.bat and read the error message Find the solution to that error below Confluence won't start -

java.lang.NoClassDefFoundError IntraHibernateAttachmentCopier

If you are seeing "java.lang.NoClassDefFoundError: com/atlassian/confluence/pages/persistence/dao/ hibernate/AbstractHibernateAttachmentDao$IntraHibernateAttachmentCopier", you have unzipped Confluence using a program that cannot handle long filenames. You must delete your install directory and go back to the point in the instructions that covers unzipping Confluence using a third-party unzip program. Confluence won't start -

Exception in thread "main" java.lang.NoClassDefFoundError: ...

If http://localhost:8080 goes to an error page when you run Confluence, go to the install directory and find the /logs/catalina.out. If this file contains a single line error starting with "Exception in thread "main" java.lang.NoClassDefFoundError", your install path may contain spaces. The solution is to rename your install directory path so that there are no spaces, then restart Confluence. Confluence won't start -

Error creating Confluence Home directory

The confluence.home variable specified in confluence-init.properties cannot be created. To fix this, edit /confluence/WEB-INF/classes/confluence-init.properties and check the path specified exists. Make sure all the directory slashes use / and that the # has been removed. If you're stuck, try using confluence.home=c:/confluence/data Confluence won't start -

JAVA_HOME environment variable is not defined correctly

You have not installed the Java Development Kit, or not set the %JAVA_HOME% to the directory of the JDK. You should re-check your steps in Stage 2. Confluence won't start -

Port 8080 is in use

If you have another Tomcat running on the same machine, you must edit <INSTALL>/conf/server.xml and change both 8080 and 8005 to ports that do not conflict with your other Tomcat instance according to these instructions. Confluence won't start -

Error creating bean with name 'scheduler' You will need to adjust your system time.

Error registering bean with name 'fileSystemAttachmentDataDao'

Confluence won't start -

Document generated by Confluence on Oct 10, 2007 11:54

Page 429

If you did not use one of the recommended unzipping tools, and happened to use for instance the default Windows XP extractor, one of the classes required for starting up Confluence may not be located due to the lengthy file-path. This is due to the reason that the default Windows tool silently fails to extract files with long names. We suggest you to use other tools such as WinZIP and 7zip and redo the deployment process.

Cause: org.springframework.beans.factory.BeanDefinitionStoreException: Error registering bean with name 'fileSystemAttachmentDataDao' defined in class path resource [applicationContext.xml]: Class that bean class [com.atlassian.confluence.pages.persistence.dao.FileSystemAttachmentDataDao] depends on not found; nested exception is java.lang.NoClassDefFoundError: com/atlassian/confluence/pages/persistence/ dao/FileSystemAttachmentDataDao$FileSystemAttachmentNamingStrategy at org.springframework.beans.factory.xml.DefaultXmlBeanDefinitionParser.parseBeanDefinition(DefaultXmlBeanDefinitionP caused by: java.lang.NoClassDefFoundError: com/atlassian/confluence/pages/persistence/dao/ FileSystemAttachmentDataDao$FileSystemAttachmentNamingStrategy at java.lang.Class.forName0(Native Method) Confluence starts but

localhost:8080 times out

Check the server logs for errors. If you are running Confluence Standalone on Windows, error messages will be printed to the console window that opened when you ran startup.bat. On Unix systems, Confluence will log messages to logs/catalina.out. Confluence starts but

localhost:8080 goes to Tomcat start homepage

The CATALINA_HOME environment variable is set to another instance of Tomcat. You should run shutdown.sh, remove the CATALINA_HOME reference to the other Tomcat version, and run startup.sh again. Confluence starts but

logins fail at login screen

If you try to login with the correct username and password but are always returned to the login screen without any error messages, and you are running Zone Alarm, please check that it is not blocking the Confluence server

RELATED TOPICS

Change listen port for Confluence Standalone Adding SSL on Confluence 2.1.5a and earlier Confluence Setup Guide Configuration Guide Documentation Home

Document generated by Confluence on Oct 10, 2007 11:54

Page 430

Change listen port for Confluence Standalone
This page last changed on Jun 04, 2007 by ivan@atlassian.com.

Problem
You get errors like the following when starting Confluence Standalone, and can't access Confluence on port 8080. java.net.BindException: Address already in use: JVM_Bind:8080 This means you are running other software on Tomcat's default port 8080. This may either be another Tomcat or some other process. To find out what process is listening on that port, load a command prompt and type: netstat -an
-a : Displays all active TCP connections and the TCP and UDP ports on which the computer is listening. -n : Displays active TCP connections, however, addresses and port numbers are expressed numerically and no attempt is made to determine names.

There is also Process Explorer tool available to determine what is binding port 8080.

Solution: change Confluence listen ports
To change the ports for Confluence Standalone, open the file conf/server.xml under your Confluence installation. The first four lines of the file look like this: Default conf/server.xml
<Server port="8005" shutdown="SHUTDOWN" debug="0"> <Service name="Tomcat-Standalone"> <Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8080" minProcessors="5" maxProcessors="75" enableLookups="true" redirectPort="8443" acceptCount="10" debug="0" connectionTimeout="20000" useURIValidationHack="false"/> ...

You need to modify both the server port (8005) and the connector port (8080) to ports that are free on the machine hosting Confluence. If required, netstat can be used to identify free ports on your machine [1]. For example, the first four lines of a modified server.xml using ports 8015 and 8090 is below: Modified conf/server.xml using ports 8015 and 8090
<Server port="8015" shutdown="SHUTDOWN" debug="0"> <Service name="Tomcat-Standalone"> <Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8090" minProcessors="5" maxProcessors="75" enableLookups="true" redirectPort="8443" acceptCount="10" debug="0" connectionTimeout="20000" useURIValidationHack="false"/> ...

To access Confluence in this configuration, point your web browser to http://localhost:8090/.
NOTES

[1] For more information on netstat, see using netstat on Windows, or netstat man page (Linux). [2] JIRA Standalone also runs on port 8080 by default. If you're looking to change the port of JIRA Standalone, see Changing JIRA Standalone's port.
RELATED PAGES

Installing Confluence Standalone

Document generated by Confluence on Oct 10, 2007 11:54

Page 431

Documentation Home

Document generated by Confluence on Oct 10, 2007 11:54

Page 432

Set JAVA_HOME variable in Windows
This page last changed on Oct 08, 2007 by smaddox.

After you install the Java Development Kit in Windows, you must set the JAVA_HOME variable to the install directory. Common Problem Some users have only installed the Java Runtime Environment (JRE). You need either a Java Development Kit (JDK) or J2SE Software Development Kit (SDK). If you would like to confirm that you have the right version, you can check the Java install path. Unless you changed the path during installation, Java will be installed to a subdirectory under C: \Program Files\Java, for example C:\Program Files\Java\jdk1.5.0_02 Open C:\Program Files\Java and confirm the install path is for a JDK or SDK. JRE installs are not suitable, and have an install directory begining with jre. The numbers after the jre are not relevant. Example JREs are: jre1.3.0_02 jre1.4.0_02 SDK and JDK installs are suitable. Their install directory begins with jdk or j2sdk, the numbers after are not relevant. Example JDK and SDKs are: jdk1.5.0_02 j2sdk1.5.0_09 Any install directory starting with jdk or j2sdk is valid. If you cannot see an installed JDK or SDK, install the JDK now from the JDK download site

Stage 1. Locate Install Directory
If you already know the install path for the Java or Software Development Kit, go to Stage 2. Otherwise, find the install path by following these instructions: 1. Unless you changed the install path for the Java Developement Kit during installation, it will be in a directory under C:\Program Files\Java. Using Explorer, open the directory C:\Program Files \Java 2. Inside that path will be one or more subdirectories such as jdk1.5.0_08. If you just installed the Java Development Kit, it will be installed to the newest directory, which you can find by sorting by date. For example, it may be installed in C:\Program Files\Java\jdk1.5.0_08. This is the install path.

Stage 2. Apply Setting
Once you have identified the JDK install path: 1. 2. 3. 4. 5. 6. 7. 8. 9. Right click on the My Computer icon on your desktop and select properties Click the Advanced Tab Click the Environment Variables button Under System Variable, click New Enter the variable name as JAVA_HOME Enter the variable value as the install path for the Development Kit Click OK Click Apply Changes If you are running Confluence as a EAR/WAR rather than the Standalone, you may need to restart your application server This diagram shows setting the JAVA_HOME variable to an install path of c:/j2sdk1.4.2

Document generated by Confluence on Oct 10, 2007 11:54

Page 433

If you came here from Installing Confluence Standalone, go back and begin Stage 3.

RELATED PAGES
• Installing Confluence Standalone • Start Tomcat as a Windows Service • To set JAVA_HOME on Linux - Installing Confluence in Linux

Document generated by Confluence on Oct 10, 2007 11:54

Page 434

Installing the Confluence EAR-WAR edition
This page last changed on Oct 05, 2007 by pkamal.

The Confluence EAR-WAR edition is intended for deployment into an existing J2EE application server. It is assumed that you already know how to deploy a webapp on the application server of choice. If not, please contact your system administrator to assist you, or consider installing the Confluence Standalone edition instead.

Confluence EAR-WAR requirements
In addition to the Confluence requirements, the EAR-WAR edition requires an application server: For more information, please read the Supported Platforms FAQ. Compatible / Supported • • • • • • Apache Tomcat (4.1 and 5.5) Weblogic (8.1 SP3 and above) Resin (2.11.11 and above) JBoss Orion (2.0.2 and above) Websphere (5.1.1.3 and above)

Compatible / No Technical Support • Macromedia JRun - untested • Microsoft IIS Server - untested Incompatible • Oracle OC4J - issue • Sun Application Server - issue • GlassFish - issue Setup Notes and List of Known Issues for Application Server Configuration can be found here • If deploying as an unexploded WAR, Ant 1.3 or later is required • If deploying on an unsupported server, server-related issues cannot be covered by Atlassian technical support. Requests for assistance can be directed to the user forums instead • Confluence, the database and application server must use the same character encoding. UTF-8 is recommended • A user-contributed Fedora or RHEL/Centos Install Guide is also available for reference • Unix, Linux or Solaris users must install these X11 libraries

How to install Confluence EAR-WAR on Tomcat

Step 1 - Download and extract WAR 1. Download the Confluence WAR zip file (remember to click the Show advanced downloads link to get access to the war file) 2. Extract the downloaded zip file: • Windows users must avoid Win XP's built-in unzip as it doesn't extract all the files. Use a 3rd party zip extractor like WinZip. • Solaris users will need to use GNU tar to handle the long filenames. • Tomcat users must not unzip their Confluence install to inside the Tomcat webapps folder as this may cause Confluence to be deployed more than once. 3. It will unzip your Confluence install directory, which should contain the version number e.g. confluence-2.2.9 or confluence-2.5.0. This directory will be later referred to as the Confluence

Document generated by Confluence on Oct 10, 2007 11:54

Page 435

install directory. Inside is a confluence subdirectory, referred to later as the Confluence WAR directory. Record the absolute path to the Confluence WAR directory. Step 2 - Check for patches Review the Release Notes for your Confluence version and apply any patches listed Step 3 - Check for application server issues Known Issues for Apache Tomcat Known Issues for JBoss Known Issues for Jetty Known Issues for Resin 2.x Known Issues for Resin 3.x Known Issues for SAP Application Server Known Issues for WebLogic Known Issues for Websphere Step 3 - Configure confluence-init.properties 1. Inside the Confluence install directory, edit ...confluence/WEB-INF/classes/confluenceinit.properties in a text editor 2. Set the confluence.home property to a directory of your choosing. This is the directory that will contain all of Confluence's configuration, backup and attachment files. Step 4 - Edit Tomcat context descriptors If you using Tomcat 5.0.x or Tomcat 5.5.x: 1. Create a file called confluence.xml in your Tomcat installation's conf/Catalina/localhost directory (if you have set up a different hostname for your tomcat instance, please specify that instead of localhost) 2. Open confluence.xml and add these lines:
<Context path="/confluence" docBase="c:/applications/confluence-2.1.3/confluence" debug="0" reloadable="false"> <Logger className="org.apache.catalina.logger.FileLogger" prefix="atlassian-confluence." suffix=".log" timestamp="true"/> </Context>

3. For docBase specify the value you noted down earlier. If you are using Tomcat 4.x 1. Open conf/server.xml in a text editor 2. Add the following:
<Context path="/confluence" docBase="c:/applications/confluence-2.1.3/confluence" debug="0" reloadable="false"> <Logger className="org.apache.catalina.logger.FileLogger" prefix="atlassian-confluence." suffix=".log" timestamp="true"/> </Context>

3. For docBase specify the value you noted down earlier. Step 5 - Configure Your Application server Review any documentation associated with your webserver here. If your application server requires deploying Confluence as a EAR/WAR, follow these instructions to build the WAR file: Windows users

Document generated by Confluence on Oct 10, 2007 11:54

Page 436

1. Open the command line prompt 2. Navigate to the Confluence installed directory 3. Run the command build war Linux users 1. 2. 3. 4. 5. Open a terminal window Navigate to the Confluence installed directory Add executable mode to build.sh - chmod +x build.sh Run build.sh The WAR file is now located in the dist subfolder in your Confluence installed directory

Step 6 - Restart Server 1. Shut down, and then restart Tomcat 2. Confluence should now be accessible on http://host:port/confluence

Next Step
Setup Confluence

General Tips & Information
• • • • • • Start Confluence automatically on Windows as a Service Known Issues with Enterprise or Webhosting environments Pull down RSS Feeds or use the Repository plugin through a web proxy Set JAVA_HOME variable in Windows Setup a mail session in standalone version Where Is My ConfluenceHome Directory?

Troubleshooting
Solutions to common issues with installing Confluence. Review your logs by opening the Confluence install directory and checking the /logs/catalina.out and /logs/catalina.out files for errors described below. Click on a problem to show the solution. Confluence window

closes immediately when started An error is preventing Confluence from starting.

1. Open a command prompt. On Windows, do this by clicking on your Start menu, then click Run. In the Run box, type cmd and press OK 2. From the command prompt, go to your Confluence install directory 3. Go into the bin subdirectory 4. Run startup.bat and read the error message 5. Find the solution to that error below Confluence won't start -

java.lang.NoClassDefFoundError IntraHibernateAttachmentCopier

If you are seeing "java.lang.NoClassDefFoundError: com/atlassian/confluence/pages/persistence/dao/ hibernate/AbstractHibernateAttachmentDao$IntraHibernateAttachmentCopier", you have unzipped Confluence using a program that cannot handle long filenames. You must delete your install directory

Document generated by Confluence on Oct 10, 2007 11:54

Page 437

and go back to the point in the instructions that covers unzipping Confluence using a third-party unzip program. Confluence won't start -

Exception in thread "main" java.lang.NoClassDefFoundError: ...

If http://localhost:8080 goes to an error page when you run Confluence, go to the install directory and find the /logs/catalina.out. If this file contains a single line error starting with "Exception in thread "main" java.lang.NoClassDefFoundError", your install path may contain spaces. The solution is to rename your install directory path so that there are no spaces, then restart Confluence. Confluence won't start -

Error creating Confluence Home directory

The confluence.home variable specified in confluence-init.properties cannot be created. To fix this, edit /confluence/WEB-INF/classes/confluence-init.properties and check the path specified exists. Make sure all the directory slashes use / and that the # has been removed. If you're stuck, try using confluence.home=c:/confluence/data Confluence won't start -

JAVA_HOME environment variable is not defined correctly

You have not installed the Java Development Kit, or not set the %JAVA_HOME% to the directory of the JDK. You should re-check your steps in Stage 2. Confluence won't start -

Port 8080 is in use

If you have another Tomcat running on the same machine, you must edit <INSTALL>/conf/server.xml and change both 8080 and 8005 to ports that do not conflict with your other Tomcat instance according to these instructions. Confluence won't start -

Error creating bean with name 'scheduler' You will need to adjust your system time.

Error registering bean with name 'fileSystemAttachmentDataDao'

Confluence won't start -

If you did not use one of the recommended unzipping tools, and happened to use for instance the default Windows XP extractor, one of the classes required for starting up Confluence may not be located due to the lengthy file-path. This is due to the reason that the default Windows tool silently fails to extract files with long names. We suggest you to use other tools such as WinZIP and 7zip and redo the deployment process.

Cause: org.springframework.beans.factory.BeanDefinitionStoreException: Error registering bean with name 'fileSystemAttachmentDataDao' defined in class path resource [applicationContext.xml]: Class that bean class [com.atlassian.confluence.pages.persistence.dao.FileSystemAttachmentDataDao] depends on not found; nested exception is java.lang.NoClassDefFoundError: com/atlassian/confluence/pages/persistence/ dao/FileSystemAttachmentDataDao$FileSystemAttachmentNamingStrategy at org.springframework.beans.factory.xml.DefaultXmlBeanDefinitionParser.parseBeanDefinition(DefaultXmlBeanDefinitionP

Document generated by Confluence on Oct 10, 2007 11:54

Page 438

caused by: java.lang.NoClassDefFoundError: com/atlassian/confluence/pages/persistence/dao/ FileSystemAttachmentDataDao$FileSystemAttachmentNamingStrategy at java.lang.Class.forName0(Native Method) Confluence starts but

localhost:8080 times out

Check the server logs for errors. If you are running Confluence Standalone on Windows, error messages will be printed to the console window that opened when you ran startup.bat. On Unix systems, Confluence will log messages to logs/catalina.out. Confluence starts but

localhost:8080 goes to Tomcat start homepage

The CATALINA_HOME environment variable is set to another instance of Tomcat. You should run shutdown.sh, remove the CATALINA_HOME reference to the other Tomcat version, and run startup.sh again. Confluence starts but

logins fail at login screen

If you try to login with the correct username and password but are always returned to the login screen without any error messages, and you are running Zone Alarm, please check that it is not blocking the Confluence server

RELATED TOPICS

Confluence Cluster Installation Configuration Guide Confluence Setup Guide Confluence Documentation Home Confluence Main FAQ

Document generated by Confluence on Oct 10, 2007 11:54

Page 439

License will not validate
This page last changed on Apr 27, 2005 by vidya.

This issue has been fixed and the solution will be shipped as part of future confluence releases, beginning with confluence 1.4. In the interim, if you are experiencing this problem, see below. Some users have recently reported problems when installing Confluence regarding licensing. This problem is encountered in the first stage of the Setup Wizard, where a provided license will simply not validate.The log file resembles the below. 2005-04-24 20:56:13,240 WARN [confluence.license.decoder.LicenseDecoder] Signature did not verify properly. 2005-04-24 20:56:13,267 WARN [confluence.license.decoder.LicenseDecoder] Signature did not verify properly. 2005-04-24 20:56:13,270 FATAL [confluence.setup.actions.SetupLicenseAction] License is not valid Our own testing shows that this problem replicates under Windows XP, Service Pack 2 with with JDKs 1.4.2_08, 1.5_02 . The problem does not occur when running JDK 1.4.2_07 and below. A simple workaround is to download the file in attachment, Page.key, and place it in the WEB-INF/classes directory of your Confluence installation beneath the following path:
WEB-INF/classes/com/atlassian/confluence/page/Page.key

Here it will load correctly and the license will validate.

Document generated by Confluence on Oct 10, 2007 11:54

Page 440

Server Hardware Requirements Guide
This page last changed on Sep 17, 2007 by david.soul@atlassian.com.

Server administrators can use this guide in combination with the free Confluence trial period to evaluate their server hardware requirements. Because server load is difficult to predict, live testing is the best way to determine what hardware a Confluence instance will require in production. Peak visitors are the maximum number of browsers simultaneously making requests to access or update the Confluence server. Visitors are counted from their first page request until the connection is closed and if public access is enabled, this includes internet visitors as well as logged in users.

Minimum Hardware Requirements
On small instances, server load is primarily driven by peak visitors. 5 Concurrent Users • 1GHz+ CPU Pentium 4 or equivalent • 256MB RAM • 5GB database space 25 Concurrent Users • Dual 2.4GHz CPU Pentium Xeon or equivalent • 512MB+ RAM • 10GB database space

Example Hardware Specifications
These are example hardware specifications for non-clustered Confluence instances. It not recorded whether the RAM refers to either total server memory or memory allocated to the JVM, while blank settings indicate that the information was not provided.

Accounts 150 350 5,000 10,000 10,000 21,000

Spaces 30 100 500 350 60 950

Pages 1,000 15,000

CPUs 1 2 4

CPU (GHz) 2.6 2.8 3 3.8 3.6 3.6

RAM (Meg) 1,024 700 2,024 2,024 512 4,048

16,000 3,500

2 2 2

Server Load & Scalability
When planning server hardware requirements for your Confluence deployment, you will need to estimate the server scalability based on peak visitors, the editor to viewer ratio and total content. • The editor to viewer ratio is how many visitors are performing updates versus those only viewing content • Total content is best estimated by a count of total spaces Confluence scales best with a steady flow of visitors rather than defined peak visitor times, few editors and few spaces. Users should also take into account: • Total pages is not a major consideration for performance. For example, instances hosting 80K of pages can consume under 512 meg of memory • Always use an external database

Document generated by Confluence on Oct 10, 2007 11:54

Page 441

Maximum Reported Usages
These values are largest customer instances reported to Atlassian or used for performance testing. Clustering for load balancing, database tuning and other performance tuning is recommended for instances exceeding these values.

Most Spaces Most Internal Users Most LDAP Users Most Pages

1700 15K 100K 80K

Hard Disk Requirements
All wiki content is stored in the database, while attachments use either the database or filesystem. For example, the wiki instance you are reading now uses approximately 13GB of database space.

Private & Online Comparison
Private instances manage their users either internally or through a user repository such as LDAP, while online instances have public signup enabled and must handle the additional load of anonymous internet visitors.

Use Case

Spaces

User Editors Accounts

Editor To Viewer Ratio 9% 78%

Pages

Page Attachments CommentsDatabase Revisions Size (GB) 65,000 84,000 7,300 3,800 11,500 500 13.0 4.5

Online 140 Documentation Private Intranet 130

11,500 180

1,000 140

8,800 8,000

Related Pages
Clustering in Confluence Example Size & Hardware Specifications From Customer Survey Size Information For Atlassian's Own Confluence Instances Size Information For Atlassian's Own JIRA Instances

Document generated by Confluence on Oct 10, 2007 11:54

Page 442

Using the IBM 64bit J9 JDK
This page last changed on Sep 05, 2006 by tom@atlassian.com.

This JVM must be started with the argument: -Dsun.reflect.inflationThreshold=0 Otherwise you will see an error message like:
bucket.core.InfrastructureException: java.lang.NoClassDefFoundError: com.atlassian.confluence.spaces.Space$$EnhancerByCGLIB$$58d74b80 at com.atlassian.confluence.util.XWorkTransactionInterceptor.intercept(XWorkTransactionInterceptor.java:151) caused by: java.lang.NoClassDefFoundError: com.atlassian.confluence.spaces.Space$$EnhancerByCGLIB$ $58d74b80 at sun.reflect.GeneratedMethodAccessor311.invoke(Unknown Source)

Document generated by Confluence on Oct 10, 2007 11:54

Page 443

Confluence Release Cycle
This page last changed on May 18, 2006 by david.soul@atlassian.com.

New versions of Confluence are released frequently. Our goals are to: • Make bug-fixes available to customers sooner • Give interested customers early access to new features and API changes • Make Confluence major releases predictable

Feature Releases
We aim to release new versions of Confluence every two to three months. These releases will contain the bulk of new functionality. Feature releases are numbered by incrementing Confluence's minor version number, so the move from Confluence 2.0 to 2.1 and 2.1 to 2.2 both introduced significant new features to the product. Occasionally we may change to a whole new major version number (Confluence 2.0 was originally slated to be released as 1.5), but that is mostly done for marketing purposes, and shouldn't be considered to have any practical meaning. Feature releases may not be API-compatible with the previous release. This means that you should test RPC clients, macros and plugins before running them on a newer version of Confluence.

Bug-Fix Releases
Confluence bug-fix releases are scheduled every two to three weeks, depending on the number and urgency of the bugs that have been fixed during that particular development cycle. We aim to minimise the time between a bug being reported and a fix being available, without either us or our customers having to manage clumsy sets of manual patches. Bug-fix releases will contain mostly bug-fixes, plus the occasional minor new feature or enhancement. Enhancements will be limited, however, as the main aim of these point releases is to improve stability, and make no significant API changes. Bug-fix releases are numbered by incrementing the patch-level. So the first bug-fix release after Confluence 2.2 is 2.2.1, followed by 2.2.2. Occasionally, we will re-issue a bug-fix release because something was faulty with the original download. In that case we will create a "re-issue" release number, for example 2.1.5a or 2.2.1a. Obviously, we don't expect anyone to upgrade Confluence every two weeks, administrators should keep their own schedule, based on how much of an inconvenience is being caused by any bugs that may have been fixed since. Sometimes, however, a security issue or serious application bug will arise that we feel it is in everyone's best interests to fix as soon as possible. In such cases, we will recommend in the Release Notes that all customers upgrade to the latest version.

Development Releases
Occasionally, when possible, we will release preview "development snapshots" of the next major Confluence version. How often and when we do so depends on the particulars of the current development cycle. In situations where we are working on a number of disparate features we may be able to do a number of progressive development releases, whereas in iterations where we are making significant changes to the Confluence internals, we may not have anything suitable for public consumption until quite late in the release cycle. Development releases will be announced on the Development Releases page, and to the confluencedeveloper mailing list. The version number of a Development Release will be the version number of the next major release, suffixed with -dev. So Confluence 2.3-dr1 will be followed by 2.3-dr2, and so on until the ultimate release of the finished Confluence 2.3

Document generated by Confluence on Oct 10, 2007 11:54

Page 444

Development Releases
This page last changed on Jul 30, 2007 by smaddox.

Development Releases are interim builds of Confluence that we make available so that interested customers can try out new features, especially those features that you may have been waiting for, and don't want to wait another month for the next official release. Development Releases are Not Safe Development releases are snapshots of the ongoing Confluence development process. As such: • While we try to keep these releases stable, they have not undergone the same degree of testing as a full release. • Features in development releases may be incomplete, or may change or be removed before the next full release. No Upgrade Path Because Development releases represent work in progress, we can not provide a supported upgrade path between DRs, or from any DR to the eventual final release. Thus, any data you store in a Confluence DR may not be able to be migrated to a future Confluence release. Current Development Release Cycle • Release Notes 2.6-dr1 Previous Development Release Cycles 2.3 Development • Release Notes 2.3-DR1 • Release Notes 2.3-DR2 1.5 - 2.0 Development • • • • 1.5-DR1 was not released Release Notes 1.5-DR2 Release Notes 2.0-RC1 Release Notes 2.0-RC2

1.4 Development • • • • • • • • • Release Notes 1.4-DR1 Release Notes 1.4-DR2 Release Notes 1.4-DR3 Release Notes 1.4-DR4 1.4-DR5 was not released Release Notes 1.4-DR6 Release Notes 1.4-DR7 1.4-RC1 was not released Release Notes 1.4-RC2

1.3 Development • • • • • Release Release Release Release Release Notes Notes Notes Notes Notes 1.3-DR1 1.3-DR2 1.3-DR3 1.3-DR4 1.3-final

Document generated by Confluence on Oct 10, 2007 11:54

Page 445

Development Release Warnings
This page last changed on Nov 13, 2006 by cmiller.

Development Releases are Not Safe Development releases are snapshots of the ongoing Confluence development process. As such: • While we try to keep these releases stable, they have not undergone the same degree of testing as a full release. • Features in development releases may be incomplete, or may change or be removed before the next full release. No Upgrade Path Because Development releases represent work in progress, we can not provide a supported upgrade path between DRs, or from any DR to the eventual final release. Thus, any data you store in a Confluence DR may not be able to be migrated to a future Confluence release.

Document generated by Confluence on Oct 10, 2007 11:54

Page 446

Release Notes 1.3-DR1
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.3-DR1 is the first development release in the cycle leading up to Confluence 1.3. In it, we have rewritten the Space Summary/Space Administration pages to be more useable, adn implemented a much-requested feature: the ability to undelete pages. Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.2 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.1.2 or earlier, be sure to read the upgrade instructions in the Confluence 1.2 release notes. New Features in Confluence 1.3-DR1 Space Summary The Space Summary page has been the dumping-ground for every space-related operation and report since Confluence's early alpha releases. As such, it had become confusing to navigate and hard to find anything on. For 1.3-DR1, we have rewritten the space summary to be a suite of tabbed pages, making that whole area of Confluence easier to navigate, more self-explanatory, and much better-looking. The Trash Can When a page or blog post is deleted, it is no longer removed completely, but is placed in a space-wide trash can. The trash can be found in the Administration tab of the newly rearranged Space Summary pages. Space Administrators can choose to restore pages from the trash, or purge them so they are unrecoverable. New Emoticons Just because. Cannot resolve external resource into attachment. Bug Fixes All the bug-fixes that were part of the Confluence 1.2.2 release have also been incorporated into 1.3DR1. In addition, we've fixed one or two issues specifically for 1.3-DR1, take a look in JIRA for the full list.

Document generated by Confluence on Oct 10, 2007 11:54

Page 447

Release Notes 1.3-DR2
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.3-DR2 is the second development release in the cycle leading up to Confluence 1.3. For DR2, we have made space-level permissions a lot more fine-grained, and added a new plugin manager which should open the way to making it easier for people to write extensions to Confluence: Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.2 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.1.2 or earlier, be sure to read the upgrade instructions in the Confluence 1.2 release notes. Note: Because we have made significant changes to permissions in 1.3-DR2, you should check that your user permissions have been correctly migrated. The upgrade manager should ensure permissions remain consistent between versions, but as with anything related to security, it's best to double-check. New Features in Confluence 1.3-DR2 New Space-Level Permissions (CONF-1375, CONF-1764 and their linked issues)

We've been getting a lot of requests for more fine-grained control over who can do what in a space, so as a result, we've added a whole raft of new permissions at the space level:

Object Page Blog Post Comment Attachment Space

Permissions create/edit, remove, export create/edit, remove create, remove create, remove export, administer

Create space permission is still managed at the global level.

Document generated by Confluence on Oct 10, 2007 11:54

Page 448

The permissions editing screens have been changed a little, too, taking into consideration the feedback we received from the last DR. All editing functions are now firmly on the edit screen, and we have introduced a user-picker to avoid having to find users in a massive drop-down list. New Plugin Architecture (CONF-1877) Confluence now incorporates the plugin architecture that was written for JIRA 3.0 (which in turn was adapted from Confluence's macro management. Who said code reuse was dead?). Right now, there's not much you can do with it, but plugins pave the way to making Confluence a great deal more flexible and extensible. See: Writing Confluence Plugins New Macro Descriptor Format (CONF-1878) Macro libraries are now implemented as plugins, which means that if you have written a macro library, you will need to convert your macro-library.xml files to atlassian-plugin.xml files. See: Converting Macro Libraries to Confluence Plugins Themes (CONF-1856) It is now possible to package a colour-scheme and a set of customised decorators into a portable Confluence plugin. Just drop the theme jar into your server's classpath, restart the server and space administrators will be able to select the theme from the space administration console.

DR-2 comes with two very simple themes (look under themes/ in your Confluence directory), but we will have more (and more useful) themes available by the time 1.3.0 is released. In addition, we're hoping that users will continue to share their Confluence modifications in the Confluence Extensions Space, and that themes will help you continue to share neat things you've done with Confluence. See: [Confluence Themes] Bugs fixed for 1.3-DR2 All the bug-fixes that were part of the Confluence 1.2.3 release have also been incorporated into 1.3DR2. In addition, we've fixed a handful of issues specifically for 1.3-DR2, take a look in JIRA for the full list.

Document generated by Confluence on Oct 10, 2007 11:54

Page 449

Release Notes 1.3-DR3
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.3-DR3 is the third development release in the cycle leading up to Confluence 1.3 - and a momentous day in the history of Confluence. We've finally made it to that special point in every applications life. Confluence has evolved. 1.3-DR3 is best summed up by Jamie Zawinski's Law of Software Envelopment: Every program attempts to expand until it can read mail. Those programs which cannot so expand are replaced by ones which can. That's right - Confluence now has more content than ever before. It reads, stores and indexes email. Oh, and as a nifty little bonus - it also indexes Word documents, PDF documents, RTF documents, Excel spreadsheets, PowerPoint files, text files, source files etc... attached to your mail! Have we got your interest? How does all this magic happen you ask? Read on to pull back the curtain. Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.2 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.1.2 or earlier, be sure to read the upgrade instructions in the Confluence 1.2 release notes. Note: Because we have made significant changes to permissions in 1.3-DR2, you should check that your user permissions have been correctly migrated. The upgrade manager should ensure permissions remain consistent between versions, but as with anything related to security, it's best to double-check. New Features in Confluence 1.3-DR2 Mail Archiving (CONF-1965) Confluence is a collaboration tool. When communication happens through email instead of through Confluence, information will get lost in the depths of someone's mail folders, instead of shared with the team, archived, interlinked and indexed. While we would love to see all collaboration within a group to happen through Confluence, it's often not possible to change the way people work. So instead of finding new ways to force people to use Confluence instead of email, why not route all the relevant email into Confluence?

Document generated by Confluence on Oct 10, 2007 11:54

Page 450

It is now possible to archive email within a Confluence space. The support for mail is only just getting started in DR3, but we believe this is an incredibly useful direction for Confluence to go, and will be expanding and improving the mail integration in future releases. Confluence spaces can retrieve mail periodically from a POP mailbox (this will delete all mail from that POP account, so don't try it on an account you want to keep mail on), or space administrators can import mail directly from a standard mbox-format mail file. Once mail is imported into Confluence, it can be browsed chronologically from the Content pane of the Space Summary page, and can be searched through Confluence's search interface. In the future, we will be adding new ways to link to and between email (bringing the email closer to the other content of the wiki), proper representation of email threads, more flexible search, and much, much more. Read the Mail Archiving FAQ for more information Want to play with it now? We love to play with features right now, so here's how you can: • Testing mail search is a snap. We're indexing our own mailing list on this very space! View archives or search mail. • Testing mailing content into Confluence is also easy - well, relatively. Simply mail mailtest@atlassian.com and your email will show up here (it only polls the box once an hour, but it will show up eventually!). It will also be indexed. Improved Indexing Performance We now make much more efficient use of resources by batching updates to full-text search index. This should lead to improved performance for many tasks within Confluence, but will mean that it may take up to a minute for a change in the site to be reflected in the site's index. (CONF-2029 In addition, we have made a number of improvements to the indexing of large PDFs, including fixing some cases where a PDF might cause indexing to freeze indefinitely. (CONF-1953, CONF=1954) Library Upgrades Many of the librares Confluence is dependent on have been upgraded for this release, which should result in improved stability and performance. Bugs fixed for 1.3-DR3 We've fixed a handful of issues specifically for 1.3-DR3, take a look in JIRA for the full list.

Document generated by Confluence on Oct 10, 2007 11:54

Page 451

Release Notes 1.3-DR4
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.3-DR4 is the fourth development release in the cycle leading up to Confluence 1.3. We're on the home stretch! The final, stable 1.3 isn't far away. Confluence 1.3-DR4 includes a raft of improvements to mail archiving, a redesigned setup wizard, significant improvements to the way we back up and restore your system configuration, and a truck-load of bug fixes. Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.2 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.1.2 or earlier, be sure to read the upgrade instructions in the Confluence 1.2 release notes. Note: You will need to rebuild the search index after you upgrade for certain features (including mail threading) to work properly. New Features in Confluence 1.3-DR4 Setup Improvements Confluence's setup wizard was badly in need of an overhaul, so that's exactly what we've done. Among the improvements, we have: • Improved the ordering of steps. For example, if you are importing straight from a backup, you no longer need a redundant administrative user. • Added a quick, two-step setup process to get Confluence running straight away • Made the database setup much more robust, and much better at reporting errors • Removed those steps that weren't really necessary to get Confluence running Hopefully this will make it a lot easier to get Confluence up and running, or show off Confluence to your friends and family. Mail Archive Improvements (CONF-2050) We've been working hard to build on the basic mail-archiving features included in 1.3-DR3. Included in the new version are: Improved indexing of mail senders, message-ids and subjects Improved integration of mail with search The ability to delete mail (if you have been assigned the delete mail permission) Direct access to mail archives from the dashboard Display of mail attachments in the "view mail" page The ability to link to a single message by its internal Confluence ID ( [\$1234] will link to message 1234) • The ability to navigate forward and back through mails chronologically • Email addresses are displayed or masked in accordance with your global preferences • • • • • •

Document generated by Confluence on Oct 10, 2007 11:54

Page 452

We still have a few things to do (date based views, a calendar), but the mail archive is now very useable. Especially when you take into account... Mail Threading (CONF-2059) Of course, it's important for your mail archive to be able to represent conversation threads. How you present threads, though, is just as important. Here's how most mail-based web archives present your thread at the bottom of each message:

Not very helpful, is it. Here's how that same bottom-of-the-message view looks in Confluence:

At a glance, you can see exactly where the message sits in a conversation. Backup Improvements (CONF-1090 and CONF-2046) Confluence 1.3-DR4 contains two significant improvements to backing up and restoring the system. • You can now exclude attached files from your backups. Of course, this means you have to back up your attachment directory separately, but if you already have a good backup regime for your filesystem (and can thus restore the attached files separately), it means that your Confluence data backups will take up far less room. • We now include important parts system configuration in your backups. this means that colourschemes and plugin preferences are now saved, and fixes a large number of issues that users have filed due to the restore process not bringing the system back up in the same state as when they saved it. Library Upgrades

Document generated by Confluence on Oct 10, 2007 11:54

Page 453

We have continued the process of upgrading to the most recent stable versions of those libraries Confluence is built on, which should result in improved stability and performance. Bugs fixed for 1.3-DR4 We've also fixed a lot of bugs, as we ramp up for the stable 1.3 release. Take a look in [JIRA|http:// jira.atlassian.com/secure/IssueNavigator.jspa?reset=true&mode=hide&sorter/order=ASC&sorter/ field=priority&pid=10470&fixfor= 10933] for the full list.

Document generated by Confluence on Oct 10, 2007 11:54

Page 454

Release Notes 1.3-final
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.3-final is the stable release of Confluence 1.3. Woohoo! We made it! The full release-notes for Confluence 1.3 are located here, this page documents only the changes made since the 1.3-DR4 development release. 1.3-final contains over 100 improvements over 1.3-DR4, mostly focused around fixing bugs, polishing the interface, and making Confluence ready for a stable release. Who should upgrade? Confluence 1.3 is the new stable release of Confluence. It contains a huge raft of enhancements and fixes made since 1.2.3. If you are running Confluence (and not using Oracle, see below), you should upgrade to Confluence 1.3. If you are not running Confluence, you should install 1.3 immediately, regardless of your database. Current users of Confluence on Oracle databases users may wish to delay upgrading. Read this document for more details. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.2 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.1.2 or earlier, be sure to read the upgrade instructions in the Confluence 1.2 release notes. Note: You will need to rebuild the search index after you upgrade for certain features (including mail threading) to work properly. New Features in Confluence 1.3-final New Demonstration Content As part of the DR4 setup improvements, users were given the option to install an example space, but the demonstration content that was loaded was pretty uninspiring. For the final release, the demonstration space now contains a suite of demonstration pages, examples of what Confluence can do, and a few pictures of the Sydney Opera House. This should make it much easier to get Confluence up and running quickly. Referrer Performance Improvement We discovered (from monitoring the http://confluence.atlassian.com site) that our recording of HTTP referrers was causing some serious performance problems for public Confluence sites. Upgrading to Confluence 1.3-final should make Confluence a lot more responsive, especially under heavy load. Improved Notation Guide The notation guide has been reorganised to be more user-focused, making it easier to find the markup or macro you are looking for. It is also now possible for macro plugins to insert themselves into the notation guide. Just write your macro description as a two-column HTML table row, put it in a vm file, and include the following in your atlassian-plugin.xml file:
<resource type="velocity" name="help" location="/path/to/your/helpfile.vm"><param name="helpsection" value="tables"/></resource>

The help section can be one of: texteffects, headings, breaks, links, lists, images, tables, advanced, confluence, external or miscellaneous. If you don't include a help section, it will be put in the 'macros' section. Improved Search Indexing

Document generated by Confluence on Oct 10, 2007 11:54

Page 455

We've updated the way we index content within Confluence. A lot of searches that came up empty before will now find something. In addition, you can now set your primary language for indexing under General Configuration, so that the indexer can better optimise itself for non-English content. Also • By popular demand (it was our most highly voted-for bug), pages are now exported in alphabetical order, not in order of creation. • The Remote API can be accessed anonymously, if you wish (anonymous remote access must be turned on in the general configuration). • When previewing a page, you can continue to edit on that screen, instead of having to go back to the edit page. • The thread view on a mail page has been improved, and the full-thread view is no longer a pop-up. • You no longer need to be in the confluence-admin group to access the administration pages, you just need global administrative privileges • You can link to anything in Confluence if you know its ID in the database (currently this is how you must link to email): [$1234] • You can link to anything relative to the root of the Confluence site (useful for pointing to parts of the site that can't otherwise be linked): [///pages/editpage.action?pageId=1234] • New macros: {jiraportlet}, {note} {tip}, {information} and {warning} • A lot more... Issues Resolved for 1.3-final In all, over 130 issues were resolved between DR4 and 1.3-final. Unfortunately, merging all the versions together in JIRA means the list of precisely what went into those 130 has been lost, but if you sort this list by last-modification date, you'll get some idea... Issues Resolved for 1.3

Document generated by Confluence on Oct 10, 2007 11:54

Page 456

Release Notes 1.4-DR1
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.4-DR1 is the first development release in the cycle leading up to Confluence 1.4. On the surface, we have implemented one of Confluence's most requested features. Under the hood, there's a whole new event system to play with. Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.3 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.2.3 or earlier, be sure to read the upgrade instructions in the Confluence 1.3 release notes. Downloads All development releases are available from Development Releases on the Atlassian website. New Features in Confluence 1.4-DR1 Consult JIRA for the full list of issues resolved for 1.4-DR1 (Note, this list doesn't include all the 1.3.1 fixes that were also merged into the development release) Move Page Hierarchy When you move a page between spaces, you now have the option to include all children of that page in the move. With 13 votes, this was one of Confluence's most requested features. (Note, as of DR1, you can not both move a hierarchy of pages and rename the root page at the same time. This bug is filed as CONF-2452) Attach Multiple Files Another commonly requested feature, you can now attach multiple files to a page at once. By default, you can attach a maximum of five at a time, but this maximum is configurable. GZip Content Encoding Pages are served with GZip content encoding, which means less bandwidth consumption and faster page downloads. Events and Listeners We have implemented the beginnings of a pervasive system of events within Confluence. By the final release of 1.4, all major actions within Confluence will trigger an event. These events can be listened for, and reacted to by a new plugin module type: "listener". This will allow Confluence to be further customised, as extensions can react to anything that happens within the system. Creating an event listener plugin is insanely easy. Step one, implement this interface:
package com.atlassian.confluence.event; import com.atlassian.confluence.event.events.ConfluenceEvent;

Document generated by Confluence on Oct 10, 2007 11:54

Page 457

/** * Defines a listener for Confluence events. */ publicinterface EventListener { /** * Perform some action as a response to a Confluence event. The EventManager will * ensure that this is only called if the class of the event matches one of the * classes returned by getHandledEventClasses * * @param event some event triggered within Confluence */ void handleEvent(ConfluenceEvent event); /** * Determine which event classes this listener is interested in. * * The EventManager performs rudimentary filtering of events by their class. If * you want to receive only a subset of events passing through the system, return * an array of the Classes you wish to listen for from this method. * * For the sake of efficiency, only exact class matches are performed. Sub/superclassing * is not taken into account. * * Returning an empty array will allow you to receive every event. * * @return An array of the event classes that this event listener is interested in, * or an empty array if the listener should receive all events. Must not * returnnull. */ Class[] getHandledEventClasses(); }

Step two: Package it as a plugin module with a descriptor like this:
<listener name="My Listener" key="mylistener" class="com.example.listeners.MyListener"> <description>Listens for stuff.</description></listener>

And that's about it. We'll be adding information about the events that are being produced in Confluence over the next couple of days (We would have had them documented today, but Nick, who wrote most of them, was sick). Bugs Fixed All bugs that were fixed in Confluence 1.3.1 are also fixed in Confluence 1.4-DR1.

Document generated by Confluence on Oct 10, 2007 11:54

Page 458

Release Notes 1.4-DR2
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.4-DR2 is the second development release in the cycle leading up to Confluence 1.4. Seeing as the DR2 development fortnight straddled Christmas it's not quite as feature-laden as some previous releases, but we thought we'd give you a few new toys to play with for the New Year. Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.3 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.2.3 or earlier, be sure to read the upgrade instructions in the Confluence 1.3 release notes. Downloads All development releases are available from Development Releases on the Atlassian website. New Features in Confluence 1.4-DR2 Consult JIRA for the full list of issues resolved for 1.4-DR2 Export Page Hierarchy When you export a page to PDF or HTML, you have the option to include its children in the export.

Popup Page Picker We now have a popup that can be used to select pages for inserting links, or choosing a page's parent. The picker lets you choose from your recently visited pages, the list of pages that link to the current page, or you can perform a search within the picker itself.

Document generated by Confluence on Oct 10, 2007 11:54

Page 459

New Macros As part of the process of making Confluence more flexible, we have implemented the various functions of the Confluence dashboard and space summary pages as macros. These macros are currently disabled by default, but if you're interested in using them within regular pages, you can enable them from your global plugin configuration. This currently has no effect on the dashboard itself - but will become useful in the future when the dashboard becomes customiseable. For example, the {spaces-list} macro will reproduce the list of spaces that appears on the dashboard: Error rendering macro: java.lang.NullPointerException Known Bugs There is a known bug that occurs whenever you enable or disable a plugin in Confluence 1.4-DR2. The error will appear to be 'null', but the following will appear in the logfiles:
[ERROR] Tue Jan 04 18:01:20 CST 2005 [com.atlassian.core.util.DateUtils] java.util.MissingResourceException: Can't find resource for bundle java.util.PropertyResourceBundle, key core.dateutils.minutes

This is issue CONF-2513 and will be fixed in the next DR.

Document generated by Confluence on Oct 10, 2007 11:54

Page 460

Release Notes 1.4-DR3
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.4-DR3 is the third development release in the cycle leading up to Confluence 1.4. It is the first step in a process of making the Confluence User Interface simpler, and easier to navigate. Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.3 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.2.3 or earlier, be sure to read the upgrade instructions in the Confluence 1.3 release notes. Downloads All development releases are available from Development Releases on the Atlassian website. New Features in Confluence 1.4-DR3 User Interface Enhancements

Some of the most frequent feedback we get about Confluence is that while users like the wealth of features on offer, the interface is often overwhelmed by too much information and too many options, making Confluence difficult to navigate, and difficult to introduce to non-technical users. Confluence 1.4DR3 is the first step in an attempt to present a cleaner, more useable design for Confluence, while still providing a powerful interface for experienced users.

Document generated by Confluence on Oct 10, 2007 11:54

Page 461

1.4-DR3 is a developer release. As such, some of the changes to the interface are incomplete, and some may not make it into the final version. Please offer your feedback on DISC:1.4 UI Discussion. While the obvious way to get a look at the new interface is just to explore this site, here are a few screenshots that might help:

Confluence 1.4 Interface Changes (view as slideshow)

More Functional Edit Page Interface

Simpler Dashboard

Cleaner (and wider) page view

Newlook recently updated list for spaces

New attachment management interface

I'm also compiling a page to help people who are used to Confluence Classic, and might be a little lost in the new interface: 1.4 Interface - Where Did Everything Go? Known Bugs A page has been created in the Discussion space to gather comments, suggestions, compliments and complaints about the new interface: DISC:1.4 UI Discussion

Document generated by Confluence on Oct 10, 2007 11:54

Page 462

1.4 Interface - Where Did Everything Go?
This page last changed on May 17, 2005 by exampleuser.

If you're used to the Confluence Classic interface, the new 1.4 interface might be a little hard to navigate at first. We think that the new design is a vast improvement, but it's inevitable that people who have used the application since its release will be wondering where some of the buttons they were used to have gone... Where Did They Go... • • • • • • Blogs? Rename Page? Move Page? Create Child Page? Page Locks? Page History? Short URL? Watch Page? Remove Page?

Like it? Don't? Join the discussion.

Cannot resolve external resource into attachment. Blogs?
By incredibly popular demand, blogs have been renamed to "News" across the site. While blogs are all the rage at the moment (or, as my brother would say, very zeitgeisty), it's still far easier to explain "News" to someone familiar with blogs, than it is to explain blogs to someone who is familiar with news.

Cannot resolve external resource into attachment. Rename Page?
Rename page is no longer a separate function. Just edit the page and change the page title, and Confluence will rename all the links to the page for you.

Cannot resolve external resource into attachment. Move Page?
Move page is no longer a separate function. Just edit the page and change its space, and Confluence will move the page to the new space for you, renaming any links to the page. If the page has children, you will be given the option to move all the children as well.

Cannot resolve external resource into attachment. Create Child Page?
Whenever you select the "Add Page" link from the top of the page, your current page will be automatically inserted into the Parent Page box. We've found that this is the way most people use Confluence anyway.

Document generated by Confluence on Oct 10, 2007 11:54

Page 463

Cannot resolve external resource into attachment. Page Locks?
Page locks have been renamed "Permissions" and moved to the bottom of the edit page. We found that most people didn't understand (or couldn't find) locks, and thus didn't understand that Confluence has page-level edit security.

Cannot resolve external resource into attachment. Page History? Short URL? Incoming Links? Hot Referrers?
All this information has been moved under the "Info" tab when you view a page.

Document generated by Confluence on Oct 10, 2007 11:54

Page 464

Release Notes 1.4-DR4
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.4-DR4
Confluence 1.4-DR4 is the fourth development release in the cycle leading up to Confluence 1.4. In 1.4DR4 the user interface continues to improve, and our new wiki->HTML renderer lands, fixing a large number of bugs (but probably introducing a few more) 1.4-DR4a One of the bugs that was introduced in 1.4-DR4 caused the edit option to disappear completely from the Confluence interface for anyone who was not a global administrator. Because that issue rendered Confluence mostly unuseable, 1.4-DR4a has been released including a fix to that problem. 1.4-DR4a also includes the patch for Confluence Security Advisory 2005-02-09. We would like to remind everyonee who downloads the developer releases that they are not fully stable. Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.3 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.2.3 or earlier, be sure to read the upgrade instructions in the Confluence 1.3 release notes. Downloads All development releases are available from Development Releases on the Atlassian website.

New Features in Confluence 1.4-DR4
User Interface Enhancements The user interface of Confluence continues to improve. A big thankyou to all the users who contributed feedback on DR3. While the changes between DR3 and DR4 aren't as radical as the last release, we've been able to polish up a lot of the edges, and make Confluence even easier and more pleasant to use. We're still gathering feedback on the UI changes, add your input here: DISC:1.4 UI Discussion Mail Archives • You can now bulk-delete all mail within a space (mail deleted this way does not go to the trash, and can not be recovered later!) • Pagination on the mail archives is a bit more sane: it doesn't try to tell you about every single page of mail in the archives. • The mbox importer detects if you're trying to import something that isn't an mbox file, making you much less likely to break anything if you upload the wrong file. Nofollow Support

Document generated by Confluence on Oct 10, 2007 11:54

Page 465

As part of the effort to combat spam on wikis and blogs (Confluence being both), Google came up with some markup that will cause search-engines not to follow links. By removing the main benefit of wikispamming (increased search-engine PageRank), it's hoped that the noxious practice will stop being costeffective, and eventually die out. By default, all URLs inserted in a page (or in comments) will be given the nofollow tag. Inter-page links (i.e. Documentation Home) or shortcut links (i.e. CONF-2622) will not be tagged. If your wiki doesn't support public editing or commenting, or you just disapprove of nofollow on principle, the site administrator can turn the feature off in General Configuration. V2Renderer Over the last few releases of Confluence, it has become apparent that the engine we were using to convert wiki text to HTML was starting to cause us problems. There were a growing number of bugs that we simply couldn't fix, because the nature of the engine meant that fixing one bug would cause ten worse bugs to spring up in its place. After a few false starts, we can now introduce 'v2Renderer', which fixes quite a few of these problems already, and promises to make fixing the rest of them much easier:

Atlassian JIRA(0 issues) T Key Summary Assignee Reporter Pr Status Res Created Updated Due

Because this is the first public release of v2Renderer, it's likely that there are some situations in which the markup of pages may change. We've been pretty careful, but users who have been making heavy use of undocumented (or accidental) features of the old markup may encounter situations in which the page displays differently to before. Please, pleasereport these problems to us, so that we can fix the renderer for the final release, or perhaps provide you with a script to painlessly convert your pages to a markup that works. Renderer Bugs If you file a bug about the v2Renderer, PLEASE make sure you put it in the Wiki/XHTML component: this makes finding all the relevant bugs so much easier for me. – Charles Miller Macros There is a new macro API that we will be rolling out for 1.4. However, there's a compatibility layer in place to make sure that most 1.3 macros will continue to function properly. Most macros written for Confluence 1.3 will continue to work in 1.4-DR4. Most of our macros are running without any changes at all, and many of the ones we did migrate were changed over in order to use the capabilities of the new engine to fix bugs. We suggest that macro authors who are worried about compatibility test their macros with 1.4-DR4 and contact us as soon as possible to discuss how we can improve the compatibility layer before the final release, or help you migrate to the new API. Known Bugs The renaming of links when a page is moved or renamed is currently unreliable. This is a side-effect of the change in renderers, and will be fixed before the final version of 1.4 is released.

Document generated by Confluence on Oct 10, 2007 11:54

Page 466

Release Notes 1.4-DR6
This page last changed on Mar 06, 2007 by jnolen.

Confluence 1.4-DR6
Confluence 1.4-DR6 is the next development release in the cycle leading up to Confluence 1.4. In 1.4DR6 we: • • • • • • • introduce page-level view permissions, make Confluence radically more themeable, further improved the overall user interface and usability, add several interesting new plugin types, add file attachments to blog posts and user profile pages, let you customize Confluence logos at a space and global level, and help you keep track of all the email watches you might have set up in Confluence.

Phew! Got all that? Who should upgrade? Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Note for Oracle Users Confluence 1.4-DR6 is currently not recommended for Oracle users, as it has not passed our test-suite against the Oracle database. This will (obviously) be fixed before we release Confluence 1.4. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.3 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.2.3 or earlier, be sure to read the upgrade instructions in the Confluence 1.3 release notes. If you upgrade to Confluence 1.4-DR6 you will need to rebuild your search indexes before search will function correctly. Look for "Rebuild Search Index" on the global Administration page. Downloads All development releases are available from Development Releases on the Atlassian website.

New Features in Confluence 1.4-DR6
See also: Issues Resolved for 1.4-DR6 Page Level Permissioning A highly-requested feature, and the reason this DR took so long to get out, you can now hide pages from other users. The option for hiding pages can be found at the bottom of the page's "Edit" screen. • You can hide a page so it is only visible to yourself, or only visible to members of groups you belong to. • Once a page is hidden, all its child pages (and their children, and so on) are also hidden.

Document generated by Confluence on Oct 10, 2007 11:54

Page 467

• A new space-level permission has been introduced to determine which users are permitted to hide pages. Please note that it may be possible for users to learn the names of hidden pages, even if they can't see their content. So don't make a page called "We Hate Bob Smith" if Bob Smith has access to your wiki. Just make a page called "We hate..." and put Bob's name in the body. Improved Themes While the overwhelming reaction to the User Interface changes we have made in the 1.4-DR series has been positive, it has sparked continuing discussions on the user mailing list about various aspects of the presentation of a Confluence site. From these discussions we have determined: • Everyone wants something slightly different. • Some people want something completely different. In response, we've moved to vastly improve the level of themeability that Confluence offers. Almost all of the user interface elements have been pushed into customisable decorators, so if you don't like the tabs, you will be able to install a theme that removes them entirely! We're hoping to bring out some example themes with the 1.4 release that do just this, but for now you can read the documentation for the new decorators in the Theme Plugins documentation. Plugin Improvements To make Confluence more flexible, we're introducing more ways for advanced users to extend the system: Uploadable Plugins Confluence administrators can now upload new plugins through the administrative interface, and have them installed without restarting the server. Search Extractor Plugins Extractor plugins allow you to add custom information to Confluence's full-text index when Confluence content is saved or updated. The most obvious application for this plugin type is to allow you to index attachment formats that Confluence does not yet support, but more creative plugin authors might make use of this as a sneaky way to store and retrieve metadata about any content in the Confluence system. Documentation for Extractor plugins is coming soon. XWork Plugins XWork plugins allow you to add new XWork (Webwork 2) actions to Confluence. Advanced programmers can add entirely new behaviours to the application: take a look at the examples in XWork-WebWork Plugins, in which we've implemented a rudimentary "Google Suggest"-like live search entry box for Confluence:

Servlet Plugins Servlet plugins allow you to deploy servlets into Confluence dynamically – perfect for integrating Confluence with some legacy application that is only available as a servlet. See Servlet Plugins for an example. Attachments for Blog Posts and User Profiles You can now upload attachments to blog posts and user profiles, both frequently requested features. Users have the option to nominate one picture attached to their profile as their "profile picture", but we haven't quite decided what to do with this information yet. There is a new global permission to determine if users can attach files to their profile. This permission is not assigned by default, so you will need to explicitly give it to users if you want to enable this feature.

Document generated by Confluence on Oct 10, 2007 11:54

Page 468

Customizing Logos at a Space and Global Level Space and global administrators may now easily configure the image displayed as the Confluence logo. This can be done for each space, or at a global level, without having to actually edit a single file. Keeping track of your Email Watches A Notifications link on your profile displays a list of all currently configured email watches you might have set up on various spaces or pages. You can now delete them in one, central, place or simply visit them. Bug fixes All bugs fixes made between Confluence 1.3.2 and Confluence 1.3.5 have been merged into the developer release branch, fixing many annoying bugs including the crash on selecting "Next" in search results. See also: Issues Resolved for 1.3.4, Issues Resolved for 1.3.5.

Document generated by Confluence on Oct 10, 2007 11:54

Page 469

Issues Resolved for 1.4-DR6
This page last changed on Mar 31, 2005 by cmiller.

Issues resolved for 1.4-DR5

Atlassian JIRA(0 issues) T Key Summary Status Res

Issues resolved for 1.4-DR6

Atlassian JIRA(0 issues) T Key Summary Status Res

Document generated by Confluence on Oct 10, 2007 11:54

Page 470

Release Notes 1.4-DR7
This page last changed on May 29, 2007 by rosie@atlassian.com.

Confluence 1.4-DR7
Confluence 1.4-DR7 is the first release-candidate build of Confluence 1.4. In 1.4-DR7 we have resolved over 120 issues: mostly related to fixing bugs and polishing up the application for a stable release. We anticipate that DR7 will be the last major build before the stable 1.4 release. DR7 is not a public release. It has been built and deployed onto http://confluence.atlassian.com as part of our internal quality-control process, but we have decided that the developer time required to make this a public beta release would be better directed towards continuing the push towards a final, stable 1.4 build. Who should upgrade? Since Confluence 1.4-DR7 is not publicly available, nobody should upgrade. The upgrade note below is just for completeness, so when we come to gather all these release notes together into a single note for 1.4, we don't miss the warning. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.3 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.2.3 or earlier, be sure to read the upgrade instructions in the Confluence 1.3 release notes. When you first start Confluence 1.4-DR7 after upgrading, the server may take a few minutes to become fully functional. This is because Confluence is rearranging information in the database so that it can be looked up more efficiently. This will only be done the first time Confluence is started after upgrading.

New Features in Confluence 1.4-DR7
The changes made between DR6 and DR7 are mostly correctness and polish issues - major feature development on Confluence 1.4 has been completed. A few notable changes however are: • The space content tree is now updated dynamically, leading to much faster page-load times and much less load on the server (for large spaces, this page was turning into a reliable way to DOS Confluence). However, you must have a modern web browser with Javascript enabled for the tree to work. (A non-Javascript fallback will be included in 1.4-final - CONF-3098) • You can now customise the site's name alongside the logo • The display and navigation of page history diffs has been improved significantly • Webdav configuration has been reinstated to the same functionality as 1.3.5 • An "insert image" popup has been added to the page editing screen, that can select images from the page's attachments. There is also an Attachments tab in the "insert link" popup. Allowing file upload from these popups has not yet been implemented (CONF-3099) • Many improvements and fixes to email notifications • Marking your change as a "minor edit" will prevent email notifications being sent • The new Component plugin module adds new beans to the Spring context • You can now uninstall plugins via the web interface • The default theme has various keyboard shortcuts (see the tabs on this page) • The (outdated) Include Page Macro can now include pages from other spaces • For developers, macros can now decide whether or not they have a body • Report showing all attachments to pages in a space (check it out!) • Generally improved notifications including a much more usable "File Attached" notification • "View wiki source" link, for all those source junkies... And much much more.

Document generated by Confluence on Oct 10, 2007 11:54

Page 471

Release Notes 1.4-RC2
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.4 Release Candidate 2
1.4-RC2 is now available for download here. Confluence 1.4-RC2 is (barring some absolute disaster) the final public developer build for Confluence 1.4. It incorporates all the changes that were deployed in the private DR7 build, as well as around 60 new bug fixes and improvements. Confluence 1.4-RC2 is being released to give Confluence customers the opportunity to test the upgrade path for their existing Confluence installation. By testing your migration with this pre-release, you can ensure that any problems you may experience will be fixed before the final 1.4 release, rather than having to rely on ad-hoc patches or wait for 1.4.1. Who should upgrade? While 1.4-RC2 is still pre-release software, and we do not recommend upgrading production Confluence sites until the release of 1.4-final, we would recommend any existing Confluence customer install this release on a test server, and try to import their existing Confluence data into it. Upgrade Procedure Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.3 or higher, you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! If you are upgrading from Confluence 1.2.3 or earlier, be sure to read the upgrade instructions in the Confluence 1.3 release notes. When you first start Confluence 1.4-RC2 after upgrading, the server may take a few minutes to become fully functional. This is because Confluence is rearranging information in the database so that it can be looked up more efficiently. This will only be done the first time Confluence is started after upgrading.

New Features in Confluence 1.4-RC2
The changes made between DR7 and RC2 are mostly correctness and polish issues - major feature development on Confluence 1.4 has been completed. A few notable changes however are: You can upload attachments while editing a page – from the "Insert Link" popup The dynamic content-tree degrades gracefully on unsupported browsers Many bugs related to PDF export (and images included in PDF exports) have been fixed Ü characters in page titles no longer confuse the database Text properties set via the contentPropertyManager can now be longer than 255 characters, fixing related bugs in the {tasklist} and {excerpt} macros • The {attachments} macro can display the list of attachments inline within a page • New XML-RPC and SOAP plugin types allow you to deploy web services dynamically into Confluence • A potential connection leak that has been causing problems for Oracle users has been fixed. • • • • • And much much more.

Document generated by Confluence on Oct 10, 2007 11:54

Page 472

Release Notes 1.5-DR2
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 1.5-DR2 is the first public development release leading up to Confluence 1.5. (Confluence 1.5DR1 was an internal release only). Developer releases are a snapshot of our work in progress, allowing our customers to see what we're up to, and provide feedback

Who should upgrade?
Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. Developer releases are not suitable for running on production systems. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases. Macro Compatibility Incompatibilities exist that may cause Confluence not to start if custom macros are deployed. When upgrading to Confluence 1.5-DR2, be sure to remove any custom Macro plugins from your $confluencehome/plugins and WEB-INF/lib directories. These incompatibilities should be resolved before the final, stable release.

Upgrade Procedure
Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.4 or higher, you can find instructions here. We strongly recommend that you backup yourconfluence.homedirectory and database before upgrading! If you are upgrading from Confluence 1.3.x or earlier, be sure to read the upgrade instructions in the Confluence 1.4 release notes.

Downloads
All development releases are available from Development Releases on the Atlassian website.

New Features in Confluence 1.5-DR2
We've been pretty busy, but the four major new features you can find in 1.5-DR2 are: • • • • WYSIWYG Editing Labels for content A dynamic RSS Builder Change summaries

Consult JIRA for the full list of issues resolved for 1.5-DR2. 1.5-DR2 also incorporates all the bug-fixes that were made between TestTest. WYSIWYG Editing Browser Compatibility The Confluence WYSIWYG editor is currently only compatible with Internet Explorer 6 on Windows, plus Mozilla and Firefox across platforms. Javascript must be enabled in the browser for the editor to function. Support for Safari under Mac OS X is currently not available. To track Safari compatibility, please follow this JIRA issue: CONF-3864 The WYSIWYG editor allows for Confluence pages to be edited directly through an editing GUI embedded in the web browser, without having to remember Confluence's wiki markup. It almost goes without saying that this has been our number one most requested features, and we're glad we can finally offer it!

Document generated by Confluence on Oct 10, 2007 11:54

Page 473

Global administrators can enable WYSIWYG editing in the General Configuration screen of the site's preferences. They can also choose whether users are presented with the WYSIWYG editor by default, or whether users default to the old wiki markup text-field.

If WYSIWYG markup is enabled, but an individual user does not like the default set by the administrator, they are free to override it via a "make this my default" link that will appear on whichever editor is currently not your default. For the "feature mad" amongst us, here are some neat things you can do with the WYSIWYG editor: • Full screen view - really useful for editing large pages. Click Cannot resolve external resource into attachment. in the menu bar. • Quickly switch between WYSIWYG and Wiki markup without a page refresh • Change the size of your editing window to suit your browser. Your size preference is remembered across sessions. To change it, drag the handle in the bottom right hand corner of the editor. • Undo and redo! Labels for content Another highly requested feature was the ability to categorise content within Confluence beyond the rigid heirarchy allowed by spaces and parent-child relationships between pages. To this end we have introduced labels.

Labels are simple one-word 'tags' that can be added to any page or blog-post the user has permission to edit. Labels can be used to categorise content, bookmark it, flag it for attention, or anything else you can think of. A Tag By Any Other Name Picking a name for labels wasn't easy. Google's GMail service calls them labels, while other collaborative categorisation systems such as del.icio.us and Flickr call them tags. We decided that 'label' was a more natural description. For more information about the philosophy behind labels and tags, check out the Folksonomy page on Wikipedia Labels can be added to any page from the edit screen, as a space-separated list of words. If you are browsing the site with a modern, Javascript-enabled browser, you'll also be able to use the dynamic web UI to add labels while viewing the page through an interactive interface.

Document generated by Confluence on Oct 10, 2007 11:54

Page 474

Once a page is labeled, then clicking on the label's name allows you to browse other pages with the same label, or view related labels that commonly occur on the same pages. You can also view the space's most popular labels from the space browser, to get an idea of the most popular topics within the space.

Many other Confluence features interact with labels: they can be searched for through the search interface, the new RSS builder can filter pages by their label, and we're looking forward to building label support into Confluence's packaged macros, and even the dashboard. Personal Labels If you prepend my: to a label (for example, my:todo or my:favourite, then the label is a personal label – only visible to you. Personal labels allow you to tag content for your own purposes. You can browse your personal labels from your user profile. Any user can add their personal labels to any page, even when they don't have editing permission.

Personal Label Privacy It is possible in Confluence 1.5-DR2 to see other people's personal labels in various views through the system. This is a known issue and in the final release, personal labels will be private to the user. (sharing personal labels at the user's discretion is also planned for the future) Favourites Favourites are a special personal label: my:favourite or my:favorite. Whenever you see the Cannot resolve external resource into attachment. icon, it means you can label this content as being your favourite, and whenever you see the Cannot resolve external resource into attachment. icon, it means that the content is currently in your list of favourites. You can view your favourites from the Labels tab of your user profile, but they come in handy for... Labels and the Dashboard Labels can be used on the Dashboard to create different views of the Confluence site. The list of spaces now offers the following tabs: • My shows you spaces that you have labelled as a Favourite. You can label any space you see on the dashboard by clicking its Cannot resolve external resource into attachment. icon. • Team allows space admins to dynamically create lists of spaces on particular topics (see below. This tab only appears if there are teams that the user can see)

Document generated by Confluence on Oct 10, 2007 11:54

Page 475

• New shows any spaces that have been created in the last week (This tab only appears if there are new spaces) • All shows all the spaces in the Confluence site A "team" is a group of spaces that share a common team label. Spaces can be labeled from the Advanced tab of Browse Space.

As of Confluence 1.5-DR2, anyone can add space-level labels. This will be fixed in the final release. The Recent Changes list on the dashboard will show only content that has been changed in the spaces that are currently listed in the space view. So if you are currently viewing the 'My' tab, only updates in your favourite spaces will be shown on the dashboard. If you are logged in, Confluence will remember your most recently selected tab and team on the dashboard. Dynamic RSS Builder A third highly-requested feature. Confluence has always provided a brace of useful RSS feeds, but the problem is that for every feed we provided, users wanted half a dozen more. The obvious answer is to let users build RSS feeds based on their own chosen criteria. You can access the RSS builder from the Confluence dashboard Once in the builder, you can choose • • • • • • • Which spaces to include in the feed Which types of content should be tracked Which labels, if any, you are interested in How many items to include in the feed Whether you want a single RSS entry per page or one for each time the page is edited Whether you want an RSS 2.0 or Atom 0.3 feed Whether Confluence should require authentication to view the feed

Once you have decided what you want, Confluence will give you a URL to paste into your RSS reader. These URLs can be shared with other Confluence users, although they will only ever be allowed to see content that they have permission to view. If you have asked to authenticate, Confluence will require HTTP Basic Authentication, which is supported by most RSS readers.

We've also taken the opportunity to improve the presentation of our RSS feeds - including a lot more information in each feed so you can follow your Confluence site entirely from your newsreader.

Document generated by Confluence on Oct 10, 2007 11:54

Page 476

The Atom 1.0 draft has just been accepted as an IETF standard. Future versions of Confluence will be phasing out use of Atom 0.3 in favour of Atom 1.0 Change summaries In a very late addition (added during our recent Fedex Day 2), Confluence now has change summaries. These allow you to add a comment to each edit that will appear in change histories, allowing you to keep a more complete record of how and why a particular page has been modified.

There is also a {change-history} macro to enable you to display a page's history within its body if you so desire. Other Things to Check Out Embed Flash and Movies You can now embed Flash content or movies (Quicktime or Windows Media) into a page as easily as you can an image: just attach the Flash or movie file to the page, then include it as you would include an image (!filename.mov!). Export Pages as Word Documents You can now export pages straight into Word from the Info tab. This is extremely useful for emailing around content to non-Confluence users, printing a document or just creating a backup in Word.

Improved Search Interface Results returned from Confluence's search engine now have: • Improved contextual results, showing the most important text around where your query was matched in the page • Contextual results for any attachment: see where a search was matched even inside PDF, Word, PowerPoint or Excel documents! • Search results for attachments give you more (and clearer) information about what the attachment is, and where it's from!search-result-fragments.png|thumbnail, align=center! Improved Gallery Macro The gallery macro has been spruced up, and now has a slideshow view:

Confluence 1.5DR2 Screenshots

Document generated by Confluence on Oct 10, 2007 11:54

Page 477

(view as slideshow)

These release notes exported to Word (even on a Mac!) great for printing too.

The new RSS builder lets you construct RSS feeds of exactly the content you want.

Screenshot of the new 1.5 WYSIWYG editor.

View page label interface showing autocomplete.

Improved search showing fragments from attachments, file sizes and types.

My personal labels! Only for me!

Document generated by Confluence on Oct 10, 2007 11:54

Page 478

The new Dashboard space tabs, here showing the "jira" team tab and one favourite space.

A very basic (quite boring - sorry, it's late) example of change summaries.

Popular labels for a given space.

Alphabetically organised labels for a given space.

Also: • Additions to the Confluence Remote API including: ° Comment manipulation ° Label manipulation ° Attachment uploading and editing ° Improved user- and permissions management • Import and restore now have progress indicators • Backup and restore use significantly less memory • The embedded database has been upgraded to HSQL 1.8, which should be significantly more reliable • Collapsed breadcrumbs now expand with a single mouse click

Document generated by Confluence on Oct 10, 2007 11:54

Page 479

Known Bugs Confluence 1.5-DR2 is a preview, not a full Confluence release, and as such there are a number of known bugs included in the release (at no extra cost!). Important bugs include: • The left-navigation theme is currently broken • The "make this my default editor" link does not always appear (try switching back and forth between views) • The Info page may cause a Hibernate exception when its parent has page level permissions • The space export may be unreliable, and does not properly back up labels. • Incoming Trackback pings are not recognised • Various WYSIWYG round-trip inconsistencies

Document generated by Confluence on Oct 10, 2007 11:54

Page 480

table test
This page last changed on Oct 26, 2005 by vidya.

Document generated by Confluence on Oct 10, 2007 11:54

Page 481

Release Notes 2.0-RC1
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 2.0-RC1 is the first release candidate for Confluence 2.0 (previously known as Confluence 1.5). It resolves almost 150 issues since the 1.5-RC2 release.

Who should upgrade?
Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. Developer releases are not suitable for running on production systems. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases.

Upgrade Procedure
Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.4 or higher, you can find instructions here. We strongly recommend that you backup yourconfluence.homedirectory and database before upgrading! If you are upgrading from Confluence 1.3.x or earlier, be sure to read the upgrade instructions in the Confluence 1.4 release notes. Important Notice If, after you have upgraded Confluence, the "Recent Changes" list on the dashboard is empty, this may be because you need to re-build your site's search index. You can do this under Administration # Content Indexing # Rebuild Search Index

Downloads
All development releases are available from Development Releases on the Atlassian website.

New Features in Confluence 2.0-RC1
The 2.0-RC1 has largely concentrated on fixing bugs and polishing existing features. If you are upgrading from Confluence 1.4 or earlier, you should read the 1.5-DR2 Release Notes for a description of the major new features in Confluence 2.0. Consult JIRA for the full list of issues resolved for 2.0-RC1. Notable Features and Improvements • You can now place markup such as bold or italics within a word if you are using the WYSIWYG editor • The following characters are now permitted in page titles: ! & ( ) * ~ $ _ Pages can not, however, start with ~ or $. • The most recent change comment for a page is now included in the page's searchable text • rel="nofollow" added to links to printable versions of pages, to prevent them from being indexed by search engines • The Recent Changes list on the dashboard now correctly reflects whether you are viewing all spaces, a team, or your favourite spaces • Further improvements to the edit page UI including: ° Improved label editing ° Inline page previewing ° Hiding of lesser-used functions such as moving a page or editing page permissions • Attachment downloads now support HTTP conditional get • Space exports now include that space's labels and page-level properties • Support for labels in the SOAP and XML-RPC remote APIs has been completed • Determining if a user exists via the remote API is now supported

Document generated by Confluence on Oct 10, 2007 11:54

Page 482

Release Notes 2.0-RC2
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Confluence 2.0-RC2 is the second release candidate for Confluence 2.0 (previously known as Confluence 1.5). It resolves almost 80 issues since the 1.5-RC1 release.

Who should upgrade?
Development releases are snapshots of the ongoing Confluence development process. We make them available for customers who are willing to risk an unpolished release in order to have early access to new features. Developer releases are not suitable for running on production systems. If you want to be running the most stable and most reliable version of Confluence, you should stick with the official, numbered releases.

Upgrade Procedure
Upgrading Confluence should be pretty easy. If you are upgrading from Confluence 1.4 or higher, you can find instructions here. We strongly recommend that you backup yourconfluence.homedirectory and database before upgrading! If you are upgrading from Confluence 1.3.x or earlier, be sure to read the upgrade instructions in the Confluence 1.4 release notes. Important Notice If, after you have upgraded Confluence, the "Recent Changes" list on the dashboard is empty, this may be because you need to re-build your site's search index. You can do this under Administration # Content Indexing # Rebuild Search Index Important Notice 2 If, after you have upgraded Confluence and you find the page breadcrumbs do not show the page's parents correctly, log into your site as administrator, then visit http:// yoursite.example.com/admin/permissions/rebuild_ancestor_table.action (substituting your own site's URL, obviously) to rebuild the ancestor table (this will be fixed for the final release.

Downloads
All development releases are available from Development Releases on the Atlassian website.

New Features in Confluence 2.0-RC2
The 2.0-RC2 has largely concentrated on fixing bugs and polishing existing features. If you are upgrading from Confluence 1.4 or earlier, you should read the 1.5-DR2 Release Notes for a description of the major new features in Confluence 2.0. Consult JIRA for the full list of issues resolved for 2.0-RC2.

Atlassian JIRA(0 issues) T Key Summary Assignee Reporter Pr Status Res Created Updated Due

Document generated by Confluence on Oct 10, 2007 11:54

Page 483

Release Notes 2.3-DR1
This page last changed on Nov 13, 2006 by cmiller.

Confluence 2.3-DR1 is the first public development release leading up to Confluence 2.3. Development releases are a snapshot of our work in progress, allowing our customers to see what we're up to. Development Releases are Not Safe Development releases are snapshots of the ongoing Confluence development process. As such: • While we try to keep these releases stable, they have not undergone the same degree of testing as a full release. • Features in development releases may be incomplete, or may change or be removed before the next full release. No Upgrade Path Because Development releases represent work in progress, we can not provide a supported upgrade path between DRs, or from any DR to the eventual final release. Thus, any data you store in a Confluence DR may not be able to be migrated to a future Confluence release.

Who should upgrade?
This development release is being made available specifically for Confluence plugin developers. The changes to the Confluence API discussed below mean that many plugins will need to be updated to work with Confluence 2.3. For all production use and testing of Confluence, please use the latest official release. The bundled Tangosol library with this development release has a license which expires on August 31, 2006. This release will not operate after that date. This release should not be used for testing a clustered deployment; the clustering user interface is not yet complete.

Upgrade Procedure
Follow the normal upgrade instructions to upgrade from Confluence 2.2.x to this release. We strongly recommend that you backup your confluence-home directory and database before upgrading! If you are upgrading from Confluence 2.1.x or earlier, be sure to read the upgrade instructions in the Confluence 2.2 release notes.

Downloads
All development releases are available from Development Releases on the Atlassian website.

New features in Confluence 2.3
In short, the new features of Confluence 2.3 are: • Clustering support (not available in 2.3-DR1) • People directory • Bundled Plugin Repository Client

Architecture changes between Confluence 2.2 and 2.3-DR1
Summarised below are architectural changes that might be relevant to plugin developers. Please add a comment below if there is anything else that should be listed here.

Document generated by Confluence on Oct 10, 2007 11:54

Page 484

We've kicked the Bucket!

Most of the functionality of Confluence's biggest internal library, bucket, has been split into three new components: atlassian-config, atlassian-spring and atlassian-event. Where practical, the old interface is still available as deprecated classes and methods. However, some plugins will not compile unless modified to use the new package names. Please refer to the source code or Javadoc for details on the new interface.
Tangosol Coherence replaces EhCache

Tangosol Coherence is now the caching library used by Confluence, both in clustered and non-clustered mode. To facilitate this, some of the caching APIs have been updated. As mentioned above, the Tangosol license included with this release is specifically for testing purposes and will expire on August 31, 2006.
Bandana configuration stored in database

The Bandana Confluence configuration files previously stored in confluence-home are now stored in the database. An upgrade from a previous version will automatically move existing configuration settings to the database.

Document generated by Confluence on Oct 10, 2007 11:54

Page 485

Release Notes 2.3-DR2
This page last changed on Nov 13, 2006 by cmiller.

Confluence 2.3-DR2 is the second public development release leading up to Confluence 2.3. Development releases are a snapshot of our work in progress, allowing our customers to see what we're up to.

Who should upgrade?
Development Releases are Not Safe Development releases are snapshots of the ongoing Confluence development process. As such: • While we try to keep these releases stable, they have not undergone the same degree of testing as a full release. • Features in development releases may be incomplete, or may change or be removed before the next full release. No Upgrade Path Because Development releases represent work in progress, we can not provide a supported upgrade path between DRs, or from any DR to the eventual final release. Thus, any data you store in a Confluence DR may not be able to be migrated to a future Confluence release. This development release is being made available specifically for Confluence plugin developers. The changes to the Confluence API discussed below mean that many plugins will need to be updated to work with Confluence 2.3. For all production use and testing of Confluence, please use the latest official release. This release should not be used for testing a clustered deployment; the clustering user interface is not yet complete.

Upgrade Procedure
Follow the normal upgrade instructions to upgrade from Confluence 2.2.x to this release. We strongly recommend that you backup your confluence-home directory and database before upgrading! If you are upgrading from Confluence 2.1.x or earlier, be sure to read the upgrade instructions in the Confluence 2.2 release notes.

Downloads
All development releases are available from Development Releases on the Atlassian website.

Things to look out for
• The Tangosol Coherence jars included in this DR are now fully licensed. • The API for retrieving historical versions of content has changed.

Architecture changes between Confluence 2.3-DR1 and 2.3-DR2
Content history API changed The getPreviousVersions method of ContentEntityObject has been removed, because it was insanely inefficient as soon as a piece of content started having lots of versions. It has been replaced with the following methods on the ContentEntityManager:
ContentEntityObject getPreviousVersion(ContentEntityObject ceo); ContentEntityObject getNextVersion(ContentEntityObject ceo);

Document generated by Confluence on Oct 10, 2007 11:54

Page 486

ContentEntityObject getOtherVersion(ContentEntityObject ceo, int version); /** * Get a VersionHistorySummary for all previous versions of a ContentEntityObject, starting with the current * content. * * @param ceo the entity object to return the version history of * @return the full version history of that object, as VersionHistorySummary objects. */ List getVersionHistorySummaries(ContentEntityObject ceo);

The VersionHistorySummary class defines a limited set of Content data that is relevant to viewing version histories.

Document generated by Confluence on Oct 10, 2007 11:54

Page 487

Release Notes 2.6-dr1
This page last changed on Jul 30, 2007 by dave@atlassian.com.

Confluence 2.6-dr1 is a public development release leading up to Confluence 2.6. Development releases are a snapshot of our work in progress, allowing our customers to see what we're up to.

Who should upgrade?
Development Releases are Not Safe Development releases are snapshots of the ongoing Confluence development process. As such: • While we try to keep these releases stable, they have not undergone the same degree of testing as a full release. • Features in development releases may be incomplete, or may change or be removed before the next full release. No Upgrade Path Because Development releases represent work in progress, we can not provide a supported upgrade path between DRs, or from any DR to the eventual final release. Thus, any data you store in a Confluence DR may not be able to be migrated to a future Confluence release. This development release is being made available specifically for Confluence plugin developers to test their existing plugins against the significant style changes that have been made. For all production use and testing of Confluence, please use the latest official release.

Upgrade Procedure
Follow the normal upgrade instructions to upgrade from Confluence 2.5.x to this release. We strongly recommend that you backup your confluence-home directory and database before upgrading!

Downloads
All development releases are available from Development Releases on the Atlassian website.

Note about themes
Confluence 2.5.x themes are expected to be compatible with 2.6 without authors needing to make any change to their existing themes. This is possible because Confluence will, by default, include all Confluence 2.5.x specific styles automatically. However, if you would like to upgrade your theme to use the latest style and typography changes in Confluence 2.6, you will need to update the way you include stylesheets in your theme. Full instructions on how to do so can be found here.

Document generated by Confluence on Oct 10, 2007 11:54

Page 488

Including Cascading Stylesheets in Themes for Confluence 2.6
This page last changed on Jul 30, 2007 by dave@atlassian.com.

Firstly, you will need to disable the inclusion of Confluence 2.5.x styles. These were included by default to allow 2.5.x themes to remain compatible in Confluence version 2.6 and after. To disable 2.5.x styles, add the following to your theme's atlassian-plugin.xml:
... <theme key="aqua" i18n-name-key="com.atlassian.confluence.themes.aqua.name" name="Aqua Theme" class="com.atlassian.confluence.themes.BasicTheme"><description key="com.atlassian.confluence.themes.aqua.desc"/> ... <param name="includeClassicStyles" value="false"/> ... </theme> ...

Note the flag includeClassicStyles is set to false. You will have to set this explicitly as the default is true. Secondly, you will need to declare your custom theme style sheet in atlassian-plugin.xml like this:
... <theme key="aqua" i18n-name-key="com.atlassian.confluence.themes.aqua.name" name="Aqua Theme" class="com.atlassian.confluence.themes.BasicTheme"><description key="com.atlassian.confluence.themes.aqua.desc"/> ... <resource type="stylesheet" name="my.css" location="styles/my-css.vm"/> ... </theme> ...

Differences from Confluence 2.5.x • You no longer have to include your theme stylesheet in the main decorator using #pluginStylesheet anymore. Confluence will load your theme's stylesheet automatically provided that its the active theme • The resource is declared in the theme module instead of the layout module • You need to start your custom style sheet (say my-css.vm), by copying over the latest styles from http://yourhost/contextPath/styles/main-action.css. This step is necessary as Confluence now includes either your theme stylesheet or the default stylesheet, not both. This implies: ° you can no longer rely on the default styles being there to style parts of the Confluence you are not directly theming ° you are no longer overridding styles with your plugin style sheet. It is now the primary stylesheet ° you will need to merge any new styles in later versions of Confluence into your theme's style sheet Multiple style sheets It is possible to configure your theme to use multiple style sheets. This feature may useful if you want to break up your main style sheet into a few smaller style sheets with more defined purposes. You can declare these like so:
... <theme key="aqua" i18n-name-key="com.atlassian.confluence.themes.aqua.name" name="Aqua Theme" class="com.atlassian.confluence.themes.BasicTheme"><description key="com.atlassian.confluence.themes.aqua.desc"/> ... <resource type="stylesheet" name="my1.css" location="styles/my-css1.vm"/><resource type="stylesheet" name="my2.css" location="styles/my-css2.vm"/><resource type="stylesheet" name="my3.css" location="styles/my-css3.vm"/> ... </theme>

Document generated by Confluence on Oct 10, 2007 11:54

Page 489

...

These style sheets will be included in the order in which they are declared.

Document generated by Confluence on Oct 10, 2007 11:54

Page 490

Release Notes
This page last changed on Oct 03, 2007 by smaddox.

More information about Confluence The latest Confluence documentation contains information about all Confluence functionality, including the updates in the newest Confluence release.

Confluence 2.6
Confluence 2.6 brings many popular features which save you time and improve the your wiki's usability. Upgrading to Confluence 2.6 is free for all customers with active Confluence software maintenance as at 27th September 2007. A new theme brings a fresh, clean look and feel. This is for our customers who have asked for a friendlier interface and improved readability. We've included more social networking features, to enhance the sense of community in your wiki. For example, author photos are now shown in comments and in the 'Recent Updates' on the Dashboard. And the Social Bookmarking plugin is now shipped with Confluence, allowing you to share bookmarks with your team. Other popular new features include default content for spaces, labels on templates, the ability to backdate or rename news items (blog posts), official MySQL 5.0 support and PDF export of images. Read the full release notes.

All Release Notes
Confluence 2.6 • Confluence 2.6 Release Notes Confluence 2.5 • • • • • • • • • Release Release Release Release Release Release Release Release Release Notes Notes Notes Notes Notes Notes Notes Notes Notes 2.5.8 2.5.7 2.5.6 2.5.5 2.5.4 2.5.3 2.5.2 2.5.1 2.5 Confluence 1.4 • • • • • Release Release Release Release Release Notes Notes Notes Notes Notes 1.4.4 1.4.3 1.4.2 1.4.1 1.4

Confluence 1.3 • • • • • • Release Release Release Release Release Release Notes Notes Notes Notes Notes Notes 1.3.6 1.3.5 1.3.4 1.3.2 1.3.1 1.3

Confluence 2.4 Confluence 1.2 • • • • Release Release Release Release Notes Notes Notes Notes 2.4.5 2.4.4 2.4.3 2.4.2 • • • • Release Release Release Release Notes Notes Notes Notes 1.2.3 1.2.2 1.2.1 1.2

Confluence 2.3 Confluence 1.1 • • • • Release Release Release Release Notes Notes Notes Notes 2.3.3 2.3.2 2.3.1 2.3 • Release Notes 1.1.2 • Release Notes 1.1.1 • Release Notes 1.1

Document generated by Confluence on Oct 10, 2007 11:54

Page 491

Confluence 2.2 • • • • • • • • • • • Release Release Release Release Release Release Release Release Release Release Release Notes Notes Notes Notes Notes Notes Notes Notes Notes Notes Notes 2.2.10 2.2.9 2.2.8 2.2.7 2.2.6a 2.2.5 2.2.4 2.2.3 2.2.2 2.2.1 2.2

Confluence 1.0 • Release Notes 1.0.3 • Release Notes 1.0.1 • Release Notes 1.0

Confluence 2.1 • • • • • • Release Release Release Release Release Release Notes Notes Notes Notes Notes Notes 2.1.5 2.1.4 2.1.3 2.1.2 2.1.1 2.1

Confluence 2.0 • • • • Release Release Release Release Notes Notes Notes Notes 2.0.3 2.0.2 2.0.1 2.0

Document generated by Confluence on Oct 10, 2007 11:54

Page 492

Confluence 2.6 Release Notes
This page last changed on Oct 04, 2007 by smaddox.

The Atlassian Confluence team is delighted to present Confluence 2.6. Confluence 2.6 brings many popular features which save you time and improve the your wiki's usability. Upgrading to Confluence 2.6 is free for all customers with active Confluence software maintenance as at 27th September 2007. A new theme brings a fresh, clean look and feel. This is for our customers who have asked for a friendlier interface and improved readability. We've included more social networking features, to enhance the sense of community in your wiki. For example, author photos are now shown in comments and in the 'Recent Updates' on the Dashboard. And the Social Bookmarking plugin is now shipped with Confluence, allowing you to share bookmarks with your team. Other popular new features include default content for spaces, labels on templates, the ability to backdate or rename news items (blog posts), official MySQL 5.0 support and PDF export of images. • Many thanks for your issues and votes. They help us keep improving our products. • We've highlighted the main features of this release below. • Attached is a full list of issues resolved in 2.6. Upgrading to Confluence 2.6
°

Responding to your feedback: 5 new feature requests implemented 275 votes satisfied Highlights of this release: Fresh look for the Default theme Personalised comments and Dashboard Space description on Dashboard Labels on templates Default content for space home pages Social Bookmarking plugin now bundled with Confluence • Back-dating and renaming news items • Plus over 90 other fixes and improvements • Special thanks • • • • • •

°

°

Upgrading Confluence should be fairly straightforward. Please refer to the upgrade instructions and notes . We strongly recommend that you back up yourconfluence.homedirectory and database before upgrading! All draft pages will be destroyed during the upgrade process. Confluence administrators should warn users of the Confluence site that drafts will not survive the upgrade. If you are using any third-party plugins, please test them thoroughly before rolling 2.6 into production.

Document generated by Confluence on Oct 10, 2007 11:54

Page 493

Highlights of Confluence 2.6
Fresh look for the Default theme
• Default font now Arial instead of Verdana. • Fresh, clean look and feel - these release notes are an example of the new style. • If you prefer the original Confluence look and feel, select the Confluence Classic Theme when creating a space. • Improved layouts for email and RSS feeds, helping you to skim-read and classify information quickly.

Personalised comments and Dashboard
• In the new themes (Confluence Default and Clickr), comments now include the user's profile picture. (See screenshot above.) • 'Recently Updated' section on Dashboard includes profile picture and a summary of the change.

Space description on Dashboard
• List of spaces on the Dashboard now includes a short description of the space.

Document generated by Confluence on Oct 10, 2007 11:54

Page 494

Labels on templates
• You can include labels when adding a page template. • New pages based on the template will automatically include the labels. • Read the documentation.

Default content for space home pages
• Confluence site administrators can define default content for a space. • Home page for newly-added spaces will include the default content. • Read the documentation.

Social Bookmarking plugin now bundled with Confluence
• Use Confluence to share bookmarks with your team. • Plugin will be enabled by default. • You can create a bookmark for any space in which you have 'create page' permission. • To view your bookmarks, go to the 'Bookmarks' tab under 'Browse Space'.

Document generated by Confluence on Oct 10, 2007 11:54

Page 495

• Drag the bookmarklet from the 'Bookmarks' tab onto your browser toolbar to create bookmarks any time. • Use the bookmarks macro to display a list of bookmarks anywhere in Confluence. • Subscribe to an RSS feed for your bookmarks. • Read the documentation.

Back-dating and renaming news items
• Rename a news item at any time. • When creating a news item, you can now set the posting date to earlier than today. • Backdating is also supported by the RPC interface - useful for migrating blog posts from other systems.

Plus over 90 other fixes and improvements
• MySQL 5.0 is officially supported, when used with Confluence 2.5 and above. • Images generated by macro plugins will now export to PDF, .doc and .html formats. • For plugin developers, the Joda-time library has been upgraded from 0.98 to 1.4 in Confluence 2.6. Plugins that use the date formatting or parsing functionality of Jodatime will need to be recompiled to work with Confluence 2.6. • Administrators can configure a non-standard port for the Confluence outgoing mail server.

Document generated by Confluence on Oct 10, 2007 11:54

Page 496

The host address can now be specified as hostname:port. • Improved user migration when integrating with LDAP: If you have existing Confluence users with the same usernames as LDAP users, you can now avoid duplicate users by configuring the LDAP repository before running the migration. The migration will then ignore users who have the same username as an LDAP user. Read the documentation. • And more.

Special thanks
We'd like to thank some of our valued community members whose contributions to the open source plugin library have made this version of Confluence even stronger: • Shannon Krebs, for the BloggingRPC plugin, the Contributors plugin and the Social Bookmarking plugin. • David Peterson and Bob Swift for the Chart Plugin. • David Peterson for the IM Presence Plugin, and the Table of Contents plugin. • Dan Hardiker & Adaptavist for the Plugin Repository Client.

The Confluence 2.6 team
Development Paul Curren Tom Davies Matthew Jensen Anatoli Kazatchkov Samuel Le Berrigaud David Loeng Charles Miller Christopher Owen Agnes Ro Matt Ryall Don Willis UI Jason Taylor Stephen Russell Technical Writing Rosie Jameson Sarah Maddox Oversight & Mismanagement Mike Cannon-Brookes Scott Farquhar Soren Harner Per Fragemann

Document generated by Confluence on Oct 10, 2007 11:54

Page 497

Confluence 2.6 Upgrade Guide
This page last changed on Oct 04, 2007 by smaddox.

Confluence 2.6 brings many popular features which save you time and improve the your wiki's usability. Upgrading to Confluence 2.6 is free for all customers with active Confluence software maintenance as at 27th September 2007. A new theme brings a fresh, clean look and feel. This is for our customers who have asked for a friendlier interface and improved readability. We've included more social networking features, to enhance the sense of community in your wiki. For example, author photos are now shown in comments and in the 'Recent Updates' on the Dashboard. And the Social Bookmarking plugin is now shipped with Confluence, allowing you to share bookmarks with your team. Other popular new features include default content for spaces, labels on templates, the ability to backdate or rename news items (blog posts), official MySQL 5.0 support and PDF export of images.

Upgrade Notes
Draft Pages

All draft pages will be discarded during the upgrade process. Confluence administrators should warn users of the Confluence site that drafts will not survive the upgrade.
Plugins

If you are using any third-party plugins, please test them thoroughly before rolling 2.6 into production. For plugin developers: the Joda-time library has been upgraded from 0.98 to 1.4 in Confluence 2.6. Plugins that use the date formatting or parsing functionality of Joda-time will need to be recompiled to work with Confluence 2.6.
Custom Themes

Custom Confluence 2.5.x themes are expected to be compatible with 2.6 without authors needing to make any change to their existing themes. This is because Confluence will, by default, include all Confluence 2.5.x specific styles automatically. But if you would like to upgrade your theme to use the latest Confluence 2.6 style and typography, you will need to update the way you include stylesheets in your theme. You can read full instructions here.
Custom Page Layout

1. If a space uses a custom decorator page layout, the new Confluence 2.6 decorator is not applied. This may causes GUI oddities, such as: • On a page, the View, Edit, Info and Attachments tabs are shown as a vertical bulleted list instead of tabs. • Comments do not show properly. Fix: Apply the Default Page Layout, then re-insert the custom code. 2. In addition, if you are using pagetree navigation to form a table of contents on the left, you may find that your wiki text becomes italic after upgrading to Confluence 2.6. • Cause: To create the left-hand panel, you have probably inserted a chunk of HTML/CSS in the space's page layout. The chunk of code may use a <blockquote> element to align the body of the page and draw a blue line on its left. Confluence 2.6 stylesheets apply the italic style to blockquotes. • Fix: Use a new format for your left-hand panel. One possible example is given here. Steps in detail: 1. 2. 3. 4. 5. 6. 7. Go to the Space Admin screen and click 'Edit' to view your customised Page Layout. Copy the customised code. Cancel the edit. Click 'Reset Default' to apply the new Confluence 2.6 default page layout. If you are using the pagetree navigation panel, edit your customised code as described above. On the Space Admin screen, click 'Create Custom' to create a custom page layout. Reinsert your customised code and click 'Save'.

Document generated by Confluence on Oct 10, 2007 11:54

Page 498

Upgrade Procedure
Upgrading Confluence should be pretty easy. We strongly recommend that you backup yourconfluence.homedirectory and database before upgrading! You can get the latest version of Confluence here. If you are upgrading from Confluence 2.2.x or a later version, you can find instructions here. If you are upgrading directly from 2.1 or earlier, you should also read the 2.2 Release Notes for warnings about the 2.1 -> 2.2 upgrade.

Document generated by Confluence on Oct 10, 2007 11:54

Page 499

Issues resolved in Confluence 2.6
This page last changed on Aug 31, 2007 by smaddox.

Below is the full list of issues resolved by Confluence 2.6. You can read the release notes here.

Atlassian JIRA(165 issues) T Key CONF-1576 CONF-1580 Summary Rename news (blog posts) Allow user to specify a non-standard SMTP mail server port Backdate blog entries Links inside html quotes get listed on the "Undefined pages" page [foo] inside {noformat} appears on the "Undefined Pages" page Userlister icons absent in HTML export Order by name Status FIXED Resolved FIXED Resolved Res

CONF-1711 CONF-3050

FIXED Resolved FIXED Resolved

CONF-3355

FIXED Resolved

CONF-3373 CONF-4419 CONF-4739

FIXED Resolved FIXED Closed FIXED Resolved

CONF-4743

CONF-4755

CONF-5453

CONF-5608 CONF-5849 CONF-5954

CONF-6049

Multi-page PDF exports get confused by attachments on different pages but with identical file names. HTML space export FIXED Resolved does not use either global or space layout for index page DataIntegrityViolationException FIXED Resolved on MySQL 5.0 during Confluence configuration at the admin account creation step Space with no FIXED Resolved administration rights won't allow addition of user/group Add default label(s) FIXED Resolved to template creation PDF export does not FIXED Resolved honor image width property ConfluenceSoapServiceImpl.changeMyPassword() FIXED Resolved incorrectly delegates to SoapServiceDelegator.changeUserPassword Export of FIXED Resolved Documentation Space to PDF and XML restoration are broken

Document generated by Confluence on Oct 10, 2007 11:54

Page 500

CONF-6284

CONF-6361 CONF-6528

CONF-6544

CONF-6587 CONF-6606

CONF-6738 CONF-6829

CONF-6966 CONF-6987 CONF-7414 CONF-7529

CONF-7601

CONF-7643

CONF-7739

CONF-7857

Pages served over HTTPS that embed Flash movies display a security warning on IE Use relative font sizes for page text Images with explicit height and width of 0 are showing up in PDF exports Images exported into a PDF file are not in a high resolution Enable browser font resizing Images created by Gallery Macro are not correctly created into PDF-exports Long words fail to wrap in PDF exports Allow sales links to remain localized even if user switches language Add ability to disable/customize external link icon. Simplify Rich Text Editor localisation Officially support mySQL 5.0 Move page operation should not add space keys to links inside noformat or code blocks Images produced by macro plugins like Gliffy are not generated into .doc or .html exports Searching for pages with a certain label in ONE space returns the pages related to the label in ALL spaces (when clicking on "Next>>" link on first result page) Some content migrated from 2.0 to 2.3 fails to render (due to:- system error: java.lang.String java.lang.ClassClastException: java.langString) Authenticating LDAP users doesn't use

FIXED Resolved

FIXED Resolved FIXED Resolved

FIXED Resolved

FIXED Resolved FIXED Resolved

FIXED Closed FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 501

CONF-7864

CONF-7875

CONF-7946

CONF-7970

CONF-7985

CONF-7987

CONF-7997 CONF-7998 CONF-8133 CONF-8152

CONF-8163

CONF-8170

CONF-8249

CONF-8297

CONF-8339

CONF-8343

the userSearchFilter for its test search Remove trailing and prefacing empty character in SPACE name flowchart or graphviz macro images are not visible in HTML export space Querying Bandana Context during Restore from Backup returns null Labels that are no longer associated with any content should not be displayed Rich Text Editor Improper handling of Line Feed in {code} parts Daily notification mail contains unsubstituted term "${baseUrl} " The code issue still occours. Code macro fails to hide brackets Upgrade to Tomcat 5.5.23 in standalone Link to results in other spaces given when searching all spaces Space creation broken when running Confluence in Shared Mode and not having space groups A link within a comment breaks when the linked page is renamed Rename 'Maximum Attachments per Form' setting to "... per Upload" Attachments macro doesn't list previous versions of attachments though "old' property is set to true Image and Link editing in Rich Text is not fully translated when Foreign Language pack is applied. Poor quality of Thumbnails

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Closed

FIXED Resolved

Document generated by Confluence on Oct 10, 2007 11:54

Page 502

CONF-8348

CONF-8392 CONF-8397 CONF-8402

CONF-8407

CONF-8417 CONF-8422 CONF-8423 CONF-8434

CONF-8450

CONF-8451 CONF-8454 CONF-8459 CONF-8468

CONF-8489

CONF-8491

Confusion regarding enabling "External User Management" option in General Configuration menu when integrating with LDAP Sort favourite spaces alphabetically in search drop-down Bundle Social Bookmarking 1.0 plugin README.txt contains out of date information about support "Restore backup" does not detect invalid ZIP files, exceptions are rendered Missing plugin-info knocks Confluence over Plugin respository exception NullPointerException when editing a group from Manage Groups Exporting spaces with pages containing a ContentPermission may throw an exception On the user management page, if you click "Search" without entering results you get a java exception Duplicate javamail / mail JARs Hyperlinks containing round brackets are broken Export Layouts don't work for Spaces, only for Site Members of groups in Group Management are printed in ugly technical way Dynamic Tasklist does not work with a "-" sign in the Title of the Tasklist A small typo on the mailto link on the Administration view user profile.

FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Resolved

FIXED Resolved

FIXED Resolved FIXED Closed FIXED Closed FIXED Resolved

FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved

FIXED Resolved

FIXED Resolved

Document generated by Confluence on Oct 10, 2007 11:54

Page 503

CONF-8503

CONF-8506

CONF-8523

CONF-8533 CONF-8543 CONF-8544 CONF-8554

Upgrade joda-time dependency from version 0.98 to version 1.4 Preformatted text from the Rich Text Editor removes link properties Edit Space Permissions failure in IE7 (works in FireFox 2.0.0.3) Rich-Text-Editor failed to load for some users Junit macro broken Underscores used to work in template values but now don't Misleading errormessage when trying to edit a nonexisting users group (via direct URL-access) No warning of page currently being edited in Confluence Clustered Environment Indexing unprintable/ encrypted PDFs fails Creating a page on an not authorized space DefaultBreadcrumbsManager generates invalid HTML Exporting a Space sometimes fails, throwing a NullpointerException Improve Indexing Error Handling Improve and speed up plugin resource loading errors.jsp should return HTTP 500 Server Error instead of HTTP 200 OK when errors are present Exports should be done asynchronously, not to give the impression that Confluence has hung When 'AND' is used to search, the label 'and' is matched

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved

CONF-8573

FIXED Resolved

CONF-8580 CONF-8586 CONF-8593 CONF-8600

FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved

CONF-8608 CONF-8623 CONF-8630

FIXED Resolved FIXED Resolved FIXED Resolved

CONF-8631

FIXED Resolved

CONF-8634

FIXED Resolved

Document generated by Confluence on Oct 10, 2007 11:54

Page 504

CONF-8644

CONF-8657

CONF-8658

CONF-8665

CONF-8682 CONF-8690 CONF-8742 CONF-8746

CONF-8754 CONF-8758 CONF-8762 CONF-8767

CONF-8770

CONF-8771

CONF-8786

CONF-8787

It is not possible to globally disable mail archiving any more (Regression) Rich Text Editor broken with IE6 and French language pack In rare cases new users don't get added to the proper group and therefore can't use Confluence exporting a space to XML incorrectly includes comments, even when 'Include comments' is deselected. "Not Permitted" error when I try to use the time sheet template REGRESSION - Copy Page not permitted (extranet) Hyperlinks do not wrap Make threaded comments the default for new installations Insert Link Popup Page Icon links are incorrect New theme does not have permalink for comments Multithreaded access to HashMap, can cause infinite loop The create page templates page does not display action errors Email address exposure - email hidding option is ignored in user lookup View template bugs: Labels are not displayed, content is (wrongly) aligned to the right confluenceadministrators no longer fits into its cell in Global Permissions Clickr theme's fonts get overridden by new stylesheet in wiki content and RTE

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Closed FIXED Resolved

FIXED Closed FIXED Resolved FIXED Resolved FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

FIXED Resolved

Document generated by Confluence on Oct 10, 2007 11:54

Page 505

CONF-8791 CONF-8802

CONF-8804 CONF-8813 CONF-8814 CONF-8815

Set-up wizard theme broken New quoted typography doesn't un-italicise <em> markup Typography Fixes New theme breaks Calendar plugin completely Foldernav styles have disappeared in new stylesheet Tabnav ID appears multiple times in markup; should be a class Viewing a historical version of a page has weird note styles at the top Rich text editor 'Insert Link' button triggers pop-up blocker Modifying the title of page removes the page formatting of pages linking to it Page title length is not being validated, leading to errorpage for titles longer than 255 characters code macro looks bad in firefox on linux Comment UI (clickr theme) - blue box in the left top corner of comment editing panel Incoming Links to Blog Posts broken JavaScript error occurs when editing a page without having permission to restrict it Footer broken in Clickr theme on extranet Merge Charles' 2.5.5 branch commits into trunk 'Preview End' box doesn't join up with sides of preview box on Safari Panel macro shows last line grey on EAC XSS vulnerability: space name and key

FIXED Closed FIXED Resolved

FIXED Closed FIXED Resolved FIXED Resolved FIXED Resolved

CONF-8827

FIXED Resolved

CONF-8831

FIXED Resolved

CONF-8854

FIXED Resolved

CONF-8855

FIXED Resolved

CONF-8856 CONF-8857

WON'T FIX Resolved FIXED Resolved

CONF-8858 CONF-8869

FIXED Resolved FIXED Resolved

CONF-8904 CONF-8906 CONF-8909

FIXED Resolved FIXED Resolved FIXED Closed

CONF-8912 CONF-8917

FIXED Closed FIXED Resolved

Document generated by Confluence on Oct 10, 2007 11:54

Page 506

CONF-8944

CONF-8950 CONF-8956

CONF-8962 CONF-8971 CONF-8978 CONF-8979 CONF-8980 CONF-8986 CONF-8987 CONF-8988 CONF-8993 CONF-8994 CONF-9000 CONF-9007

CONF-9024

CONF-9054 CONF-9060

CONF-9067 CONF-9111

not validated nor escaped Profile settings are lost when using Crowd with Confluence XSS vulnerability in app/spaces/ listattachmentforspace.action stored XSS vulnerability in app/themes/ leftnavigation/ configuretheme.action Stylesheet not loading on setup Inefficient group lookups Vulnerability against DoS attack via labels Vulnerability against DoS attack at permission setting XSS vulnerability at "Edit Space Permissions" Tab spacing is wrong on Classic and Left Navigation theme Tabs are missing using the Theme Builder theme "Robert Paulsen" misspelled in notation guide Reflected XSS Vulnerability in the Feed Builder Change renewal hyperlink to use new website redirects OutOfMemoryError's during indexing Moving an attachment does not update the respective links Update professional German and French translations in Confluence NPE thrown when attempting to export space as PDF Missing text in breadcrumbs when viewing changes since last login Division by zero in SnipSnapImporter Add hints encouraging users to provide a profile picture

FIXED Closed

FIXED Resolved FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Closed FIXED Resolved FIXED Resolved

FIXED Closed

FIXED Resolved FIXED Resolved

FIXED Resolved FIXED Resolved

Document generated by Confluence on Oct 10, 2007 11:54

Page 507

CONF-9117

CONF-9124

CONF-9167

CONF-9174

CONF-9179 CONF-9180 CONF-9187 CONF-9188

CONF-9195

CONF-9201 CONF-9214 CONF-9215 CONF-9218 CONF-9231 CONF-9237 CONF-9249

Confluence API supports adding user with null password, but users will null passwords produce NullPointerException when using the osuser to atlassianuser migration utility jsp Documentation update: MySQL 5.0 is supported when used with Confluence 2.5 and above the '{code}' and '{noformat}' macros truncate long lines of code Space and global permissions show $user.fullName for LDAP users which have been deactivated Left nav theme icon missing in select theme page Can't comment in Clickr theme Note joda-time incompatibility in 2.6 release notes Remove page removal not permitted text from edit page Confluence 2.5.6 ldap configuration failing on osuser2atluser.jsp migration Redundant information in new RSS feed format News posts are always shown as having been edited Internet Explorer issues specific to 2.6 Themes can override admin layout Entering invalid page labels hides label edit section AuthenticatedUserThreadLocal does not clear on Logut Action Duplicate dependencies in WEB-INF/lib/

FIXED Resolved

FIXED Resolved

FIXED Closed

FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Closed FIXED Resolved

FIXED Resolved

FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved FIXED Resolved

Document generated by Confluence on Oct 10, 2007 11:54

Page 508

CONF-9251 CONF-9276

CONF-9289

CONF-9303

CONF-9346

CONF-9401

CONF-9434

CONF-9450

CONF-9452

CONF-9465

CONF-9475

CONF-9521 CONF-9555 CONF-9589

"Too many open FIXED Resolved files" error during index operations Recompile FIXED Closed SocialBookmarking plugin against 2.6 final Resources served FIXED Resolved from /display/* are not sent with correct cache headers Caching is not FIXED Resolved enabled by default for the hibernate repository Include parent FIXED Resolved Comment in comment notifications Weird string appears FIXED Resolved above the edit box when *editting* an existing comment Enabling Caching FIXED Resolved for Hibernate Repository causes net.sf.hibernate.LazyInitializationException error Don't put the FIXED Resolved "Cancel" button so close to the "Save" button when editing pages Accessing an FIXED Resolved invalid attachment download URL causes exception Confluence jar's FIXED Resolved pom contains unsubstituted property for artifactid Make simple FIXED Resolved modifications to default layout to allow page-by-page customization of the UI TinyMceServlet has a FIXED Closed memory leak Improve macros.vm FIXED Resolved backwards compatibility Link to an FIXED Closed attachment combined with an image renders incorrectly

Document generated by Confluence on Oct 10, 2007 11:54

Page 509

Release Notes 1.0
This page last changed on Mar 13, 2004 by cmiller.

Confluence 1.0
Ring the bells. Break out the champagne. Paint the town red. Dance naked in the streets. Or at least that's what we'll be up to tonight, because we're finally releasing Confluence 1.0! Confluence 1.0 represents the hard work and dedication of quite a few people. Obviously there's the development team: Ara, Armond, Charles, Dave, Mike and Ross, but there's also the JIRA team and the rest of the guys at Altlassian who have offered support, advice, and loud music. A huge thanks also goes out to everyone involved in the beta-testing program. Your real-world use of Confluence gave us invaluable suggestions and bug-reports, and we apologise for the times we've messed up your databases on the way. We're pretty proud of all the cool stuff we've managed to fit into Confluence already, and we're looking forward to making it even better in forthcoming versions (Remember, a license entitles you to a year of upgrades). The only sad moment for the day is that for the 1.0 release, we had to lose emoticons. The regular expression responsible for turning into a smiley-face was causing pages to take ten seconds to render. Commenting out the filter lowers the rendering time of even highly complex pages to a few hundred milliseconds. We promise, the smileys will return in a future version, faster and stronger than ever! Or if you don't mind the cost, you can re-enable them by uncommenting the emoticonFilter line in wikiSubsystemContext.xml Users of late Release Candidate builds will notice a substantial improvement in performance as a result. Contents 1. 2. 3. 4. 5. New Features Notable Bug-fixes since RC6 Outstanding Issues Upgrading from RC6 Notable Features from Previous Releases

See also: Issues Resolved for 1.0 New Features For once, we managed to resist the urge to add any new features this week, since we were busy cleaning everything up for today's release. Notable Bug-fixes • We have verified that you can now use Confluence's internal datasources with MySQL (for users of RC5 or earlier, see the upgrade section below for information on how to change to the productionready datasources) • Fixed the database transaction problems that were causing problems with user/group management, page renaming and commenting • [~user] links no longer place the context path in the link twice • Fixed a rendering regression that caused text to be spaced incorrectly within panels • The 404 error page no longer causes a NullPointerException • The recent comments RSS feed returns a valid RSS version number • The 'diff' link now works in HTML edit notification emails when Confluence is installed in a non-root context. Outstanding Issues • The Emoticon filter is currently shipped disabled, because it was causing page-load times to go through the roof CONF-963

Document generated by Confluence on Oct 10, 2007 11:54

Page 510

• You can not complete the Confluence setup process if you have external user-management enabled. Set up Confluence before setting up external user-management. CONF-950 • It is possible to make a "create page" link to a page with invalid characters in its title (which will thus fail to be created) CONF-810 • If you are using PostgreSQL, please make sure you use the JDBC3 version of the Postgres JDBC drivers. Some users have encountered problems with the JDBC2 drivers. • Links to images that are page-attachments are broken in email notifications CONF-878 • There continue to be problems with high-bit characters in pages when Confluence is deployed on Resin CONF-569 Upgrading from RC6 We haven't made any changes to the database schema, so you should just be able to install the new version of Confluence, point it at your existing confluenceHome directory, and carry on as before. I would, however, recommend making a backup before you upgrade, just in case. If you: 1. have not gone through the Confluence database setup steps since Confluence 1.0RC5 2. are running the embedded HSQL database, or are connecting to a database directly (not through an Application Server Datasource) Then you will need to add a few connection pooling properties to confluence.cfg.xml file in your confluenceHome directory. Edit the file, and insert the following somewhere in the <Properties> section: If you do not fall into the category described above, or if you find these lines are already in the file, you do not need to do this!
<property <property <property <property name="hibernate.c3p0.max_statements"><![CDATA[0]]></property> name="hibernate.c3p0.min_size"><![CDATA[0]]></property> name="hibernate.c3p0.timeout"><![CDATA[30]]></property> name="hibernate.c3p0.max_size"><![CDATA[4]]></property>

This will enable c3p0 connection-pooling, which is far more reliable than the default pooling that we were using previously. Notable Features from Previous Releases Here's a quick retrospective of some of the cool things we have added to Confluence during the beta- and RC- releases. It is by no means comprehensive, but you can follow the links to the original release notes for an idea of just how busy we've been in recent months. Confluence 1.0a2 (November 6, 2003) • Shortcut links allow you to create special URL Shortcuts to point to existing web services: i.e. CONF-195 • Undefined and Orphaned Pages reports • Revert page to previous version Confluence 1.0a3 (December 5, 2003) • Comments for pages • Links in exported PDFs are internal links if the destination page has also been exported, external links otherwise • Personal History popup keeps track of the pages you have visited • Page Information screen lists all the incoming and outgoing links on a page • Printable version of every page Confluence 1.0b1 (December 19, 2003) • Pages that have changed since your last login are highlighted in the 'recent changes' list • Pages can be organised in parent-child hierarchies, allowing for clearer organisation of pages within a space • Page renaming refactors links to the page, wherever they may appear in the site • Search works across all content in the site, including comments, space descriptions and user information

Document generated by Confluence on Oct 10, 2007 11:54

Page 511

• A new permission was added for creating comments • {color} macro for coloured text • Parameters allowed on image links Confluence 1.0b3 (January 19, 2004) • • • • • Beta2 was released a few days earlier, but we'd prefer not to talk about it. Searching works across PDF, HTML, XML and Word attachments The colour-scheme and page decorators can be configured across the site The site homepage is configurable

Emoticons • New macros: {include}, {include-html}, {rss}, {search}, {jiraissues}, {junitreport} • User profiles can be longer than 255 characters • Much better handling of anonymous contributions Confluence 1.0b4 (January 26, 2004) • • • • • • FatCow, our acceptance-testing framework was introduced to the world Confluence now supports chronologically organised content: blog posts You can now move pages between spaces, and have their links updated accordingly en – and em — dashes are supported You can link directly to attachments New macros: {blog-posts}, {anchor}, and an improved {rss} macro

Confluence 1.0rc1 (February 6, 2004) XML-RPC and SOAP APIs allow you to programmatically interact with Confluence Trackback allows Confluence to notify other sites of links, and be notified by them User notifications on page and space editing were overhauled Look and Feel configuration was enabled individually for each space Linking to space descriptions and user profile pages directly is now possible: DISC:, Mike CannonBrookes • History popup tracks more than just pages • • • • • Confluence 1.0rc2 (February 13, 2004) • Improvements to the remote API • RSS and HTML macros now use HTTP proxies if configured to Confluence 1.0rc5 (February 20, 2004) • RC3, RC4 and RC5 were released within days of each other, in a flurry of mad bug-fixing • Page templates can now be filled in in-line • If a page is moved or renamed and you go to the URL it used to inhabit, Confluence will try to direct you to its new location • Exported PDFs now incorporate the site's stylesheet Confluence 1.0rc6 (March 5, 2004) • • • • • You can prevent people signing up, for private Confluence installations You can configure Confluence to mask user email addresses User management can now be shared with JIRA Page templates can now contain drop-down menus and text areas New macro: {html}

Document generated by Confluence on Oct 10, 2007 11:54

Page 512

Demonstration Site
This page last changed on May 24, 2007 by rosie@atlassian.com.

Atlassian have set up a demonstration space on this site so that you can try out Confluence for yourself The space has been configured so that anyone can create or edit pages within it. When using it, you should keep the following in mind. • This server may not be running exactly the same version of Confluence as is available for purchase. While we try to keep the two in sync, there may be differences between the demo site and the downloadable version of Confluence. The version that the site is running can be found at the bottom of each page. • Because the space is open for anyone to edit, Atlassian can not be responsible for the content on it. Do not rely on anything you read in the test space. • The contents of the test space may be edited or deleted at any time. Periodically, Atlassian may restore the test space from backup, deleting everything that has been added to it by visitors. • For a full demonstration of Confluence, including its administrative features, you should download an evaluation instead. • If you have any questions, contact us and we'll be happy to answer them. Want to try Confluence yourself? Experiment with Confluence in our demonstration space >>

Document generated by Confluence on Oct 10, 2007 11:54

Page 513

Issues Resolved for 1.0
This page last changed on Mar 12, 2004 by cmiller.

Atlassian JIRA(36 issues) T Key CONF-797 Summary Provide documentation about shared user database (Jira +Confluence) Import from other wiki's PDF Indexing Status FIXED Closed Res

CONF-219 CONF-1060 CONF-764 CONF-936

FIXED Closed INVALID Closed FIXED Closed FIXED Closed

CONF-944 CONF-916 CONF-551 CONF-876 CONF-913

CONF-943 CONF-833 CONF-941

CONF-883

CONF-904

CONF-937 CONF-933 CONF-919 CONF-1008

Create jspwiki importer Page save and preview is slow for large pages with lots of markup Linking Images (thumbnailing / popups) Joined Numbered Bullet Points export page is unusable for large spaces Possibility to hide email addresses Blog post results in the search page don't have edit and remove icons next to them Can not delete users under Postgres rss feed cannot read a confluence feed Access Administration.action results in a Page Not Found Security Management vs Group confluenceusers java.lang.RuntimeException: Caught an Ognl exception while getting property space User to group assignments don't stick Delegating user management to JIRA causes Exception commentrss.action returning rss 0.92 Cannot add page comments

DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed

CANNOT Closed REPRODUCE CANNOT Closed REPRODUCE

DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 514

CONF-1057 CONF-897 CONF-899 CONF-931

CONF-896 CONF-1161

CONF-643

CONF-806 CONF-917 CONF-921 CONF-932 CONF-918 CONF-924

CONF-946 CONF-940

CONF-923 CONF-920

Daily backup doesn't seem to do anything [~profile] links place context name twice in link Image attributes don't work when embedded in links apostrophe followed by closing parenthesis rendered as wink emoticon Batch update row count wrong: 0 Must remove correct email adress from profile to prevent spam soap wsdl is broken ( and you need to add a remote api component ) Email report shows incorrect # of comments on a topic Tables not getting formatted correctly within the lists! Regression: Spacing within a panel. exporting table to PDF fails Sticky "Add Comment" Textfield [~username] links are wrong if Confluence is run through forwarding NPE trying to rename the space home page Page edited email does not use full URL for 'View Changes' link can't assign users to groups Paragrap spacing issues, Panel and after headings

INVALID Closed FIXED Closed FIXED Closed FIXED Closed

CANNOT Closed REPRODUCE DUPLICATE Closed

FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed WON'T FIX Closed DUPLICATE Closed

FIXED Closed FIXED Closed

FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 515

Release Notes 1.0.1
This page last changed on Sep 14, 2006 by david.soul@atlassian.com.

Confluence 1.0.1
Over the course of the last month of supporting Confluence 1.0, there are a number of patches that we have been distributing to fix specific problems our users have encountered. Confluence 1.0.1 is a maintenance release into which all these patches have been integrated. Who Should Upgrade? All the issues that were resolved for this release are listed below. We have not snuck in any other changes: what you see here in the release notes is precisely what you will get. If you find something on the list that directly affects you, or that you feel justifies the effort of an upgrade, then do so. Otherwise, feel free to stick with 1.0. Upgrade Procedure If You Have Customised osuser.xml If you have customised Confluence's user-management, for example to integrate it with LDAP or JIRA, you will have to integrate your changes to account for the caching OSUser providers we introduced in Confluence 1.0.1. See this document for more details: Confluence Caching OSUser Provider. Updated instructions for integrating with JIRA user management are here: Delegate user management to use JIRA logins Otherwise To avoid the possibility of data-loss, you should back up your ConfluenceHome directory and your database before upgrading, and perform a full backup from within the application. Changes in 1.0.1 See also Issues Resolved for 1.0.1 Direct Attachment Links In response to a loud demand from users, links to attachments using the [^attachment.jpg] syntax will download the attachment file directly, instead of linking to an anchor in the destination page. Sybase ASE Support Confluence 1.0.1 resolves the following problems that were causing Confluence not to work with Sybase ASE 12.5.1: • • • • • ORDER-BY mappings failing on Sybase (CONF-1021) Can't add users under Sybase (CONF-1022) Weird datatype error under Sybase (CONF-1024) Sybase doesn't like complicated distinct selects (404 page fails) (CONF-1025) Backup import fails under Sybase (CONF-1063)

These bug-fixes may also improve Confluence's compatibility with other untested databases. They will not, however, have any effect on Confluence's operation against PostgreSQL, MySQL or HSQL. Microsoft SQL Server Dialect in Setup Page The Microsoft SQL Server database dialect was missing from the database setup page. It has now been added to the list. Confluence has not yet been tested on Microsoft SQL Server, and the usefulness of this option is not yet guaranteed. However, since the Sybase issues above are now resolved and SQL Server belongs to the same family as Sybase, it would be well worth a try. JIRA User Provider Caching

Document generated by Confluence on Oct 10, 2007 11:54

Page 516

Users who were linking their user management to JIRA's using the supplied provider were experiencing significant performance problems as a result. 1.0.1 introduces caching to the user provider, which should speed up these installations significantly. Global Reports Visibility Under Confluence 1.0, the global "undefined pages" and "orphaned pages" reports did not properly filter out pages that the user could not see. The user could not see the content of any page they did not have access to, but they could learn of the existence of (and names of) pages and spaces they were not permitted to see. This bug is fixed in 1.0.1 Locale-Independent Dates in Backup/Restore In Confluence 1.0, dates were written into backup files using a localised representation of the month. As such, if you exported Confluence data from a server in one locale it might not import successfully into a server with a different Locale setting. Confluence 1.0.1 still recognises the 1.0 export format, but its own exports will write out dates in a locale-independent format. As noted above, this means that data exported from Confluence 1.0.1 can not be imported successfully into Confluence 1.0. Fix Browser Crash on Viewing Some Templates Previously, if you created a template containing no variables, then anyone attempting to preview or use that template would have their browser hang in an infinite Javascript loop. Confluence 1.0.1 fixes this bug. Typo Fixed on User Group Editing Page A single-character change from "privilage" to "privilege".

Document generated by Confluence on Oct 10, 2007 11:54

Page 517

Issues Resolved for 1.0.1
This page last changed on Apr 06, 2004 by cmiller.

Atlassian JIRA(16 issues) T Key CONF-1007 CONF-1065 CONF-1025 CONF-1020 CONF-1021 CONF-1043 CONF-1063 CONF-1003 CONF-1028 CONF-1114 CONF-1038 CONF-1070 CONF-1005 CONF-1055 CONF-1022 CONF-1024 Summary Ability to specify attachment link behavior Add Caching to JIRA user providers Sybase doesn't like complicated distinct selects Dates are localised on backup, lost on restore ORDER-BY mappings failing on Sybase Missing Dialect Class Name for Microsoft Sql Server Backup import fails under Sybase typo on edit user groups JavaScript runs bananas when viewing Templates The emoticons don't seem to work.... Template with no form fields can't be previewed Users without permissions can see undefined pages Script causing browser to hang "Global reports" visibility bug Can't add a user under Sybase Weird datatype error under Sybase Status FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed DUPLICATE Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed Res

Document generated by Confluence on Oct 10, 2007 11:54

Page 518

Release Notes 1.0.3
This page last changed on Jul 21, 2004 by mike@atlassian.com.

Confluence 1.0.3
Confluence 1.0.3 is another maintenance release, hopefully the last maintenance release we will need on the 1.0 branch before moving full steam ahead towards version 1.1. It fixes some bugs regarding the remote SOAP/XML-RPC API, the display of the 404 error page under Postgresql, and the display of the site's stylesheet under certain versions of Internet Explorer. The Confluence development team are now working hard on 1.1, which will contain significant improvements and new features. Remember, a Confluence license entitles you to a year of upgrades, so if you buy 1.0.3 today, you'll be able to upgrade to 1.1 for no extra charge when the time comes. See also: Issues Resolved for 1.0.3 Who should upgrade? Confluence users should be running at least Confluence 1.0.2. Versions prior to 1.0.2 contain a bug that will cause their licenses to expire a month after the build date listed in the page footer, regardless of the true expiry date of the license. Versions 1.0.2 and later do not contain this bug. (Note: In the absence of this bug, only trial licenses ever expire. Purchased licenses for Confluence do not expire.) All the issues that were resolved for this release are listed below. We have not snuck in any other changes: what you see here in the release notes is precisely what you will get. If you find something on the list that directly affects you, or that you feel justifies the effort of an upgrade, then do so. Otherwise, feel free to stick with 1.0.2 Upgrade Procedure Confluence 1.0.3 contains no database or configuration file changes, so you should just be able to unpack it on top of your existing Confluence installation: 1. Shut down the Confluence server 2. Back up confluence/WEB-INF/classes/confluence-init.properties, and if you have customised it, confluence/WEB-INF/classes/osuser.xml 3. Unpack Confluence 1.0.3 in the same location as your existing Confluence installation 4. Restore the two files you backed up in step 1 to the 1.0.3 installation. 5. Start Confluence To avoid the possibility of data-loss, you should back up your ConfluenceHome directory and your database before upgrading, and perform a full backup from within the application. Changes in 1.0.3 Global RSS Feed Fixes The global RSS feeds found on the Dashboard page were not being generated correctly: an extra ')' was being added to the end of links. This has been fixed in 1.0.3 Page Not Found Fix for Postgresql Users running Confluence against a Postgresql database were encountering a system error whenever someone attempted to visit a page that did not exist. This has been fixed. Remote API Fixes Several outstanding issues with the remote API that were holding back the [TimTam|] client have been fixed. In addition a getVersion method has been added to allow client authors to determine which version of Confluence a server is running, and adjust their features to match. The full description of Confluence's remote API is here: Remote API Specification • The WSDL file now respects the server's configured base URL, so SOAP can be used on servers that are behind a proxy.

Document generated by Confluence on Oct 10, 2007 11:54

Page 519

• getPermissions now recognises when a user is in the confluence-administrators super-user group. • storePage handles re-parenting a page correctly • storePage will now allow a page to be renamed (all links to the page are automatically redirected) Other Fixes • You can now comment on a blog post when the title contains non-US-ASCII characters • The bug that was causing some versions of Internet Explorer 6 to not display the site's stylesheet has been fixed

Document generated by Confluence on Oct 10, 2007 11:54

Page 520

Issues Resolved for 1.0.3
This page last changed on Apr 30, 2004 by cmiller.

Atlassian JIRA(14 issues) T Key CONF-1123 CONF-1100 CONF-1101 CONF-1091 CONF-974 CONF-1140 Summary Add getVersion to remote api 404 page dies under Postgresql Global RSS feed links have extra ) storePage does not handle re-parenting correctly Store Page fails when page is renamed. Remote API permissions not respecting "superuser" group Can not comment on blog posts which title contain special characters SOAP Service broken on confluence.at Some versions of IE6 can't see the stylesheet SOAP interface not using Base URL Cannot Delete User from Group confluenceadminstrators Permissions check for commenting fails Page not found blows up with oracle dialect Some SQL Exception raise randamly Status FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed Res

CONF-1068

FIXED Closed

CONF-1088 CONF-1186 CONF-1166 CONF-1083

FIXED Closed FIXED Closed FIXED Closed WON'T FIX Closed

CONF-1200 CONF-982 CONF-1118

FIXED Closed FIXED Closed DUPLICATE Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 521

Release Notes 1.0a2
This page last changed on Jan 19, 2004 by cmiller.

Confluence 1.0a2
Confluence 1.0a2 was released November 6, 2003.

New Features
• Shortcut links (CONF-195 & CONF-247) - shortcut links enable you to easily make links to any 'web service' from within the syntax of a Confluence page. Simply specify your shortcut and the URL to link to (eg "google", "http://www.google.com/search?q=$1") to add your own links. You could use this to link directly to JIRA installations, Google, intranets, searches or anything that has a 'URI' based interface. • Revert page to a previous version (CONF-32) - revert to a previous version of any given page from the list of previous versions. • Forgot password function (CONF-88) - retrieve your password if you happen to have forgotten it • Report: undefined pages (CONF-197) - list of all pages which are linked to from other pages, but not defined. • Report: orphaned pages (CONF-198) - shows all the pages which are never linked to (ie have content but no way to get to them). • Interstitial help page after creating a space (CONF-251) • 'Notify me', and HTML/text email preferences, with HTML email content • Links to non-exported pages are now maintained in exported PDFs (the links point back to the online Confluence installation) • Custom Radeox macros can now be used within Confluence - this enables you to write your own macros to produce custom content • XML import/export of a single space (CONF-199) - useful for porting spaces between installations • XML import/export of a single page (CONF-200) - useful for creating pages automatically, or sync'ing pages between installations. • Many other minor fixes, improvements and performance tweaks

Document generated by Confluence on Oct 10, 2007 11:54

Page 522

Release Notes 1.0a3
This page last changed on Jan 19, 2004 by cmiller.

Confluence 1.0a3
Confluence 1.0a3 was released December 5 2003

New Features
• • • • • • • • • • • • • • • • Completely rearchitected around the spring framework Page comments (CONF-235) - users can now attach comments to a page. Email notification for new comments. Supports non-ASCII characters in page names (CONF-297) Improved handling of internal and external links in exported PDFs Editing popup to help with inserting links (internal and external) into pages (CONF-129) Personal history (CONF-196) - a popup window containing your recently visited pages. Page information screen (CONF-270) lists all the incoming and outgoing links for a page, and all attachments User profile UI has been enhanced (CONF-172) Dashboard and Space summary pages have had a big UI overhaul) Brief help on Wiki notation now available on create and edit pages. (CONF-295) Improved available help on various pages. Enhanced mail-server administration. All pages have a printable version accessible from the icon at the top-right of the page (CONF-338) HTML and text email notifications have been greatly improved and are now much more useful. Links in HTML emails work seamlessly with online Confluence version. Many other minor fixes, improvements and performance tweaks

Document generated by Confluence on Oct 10, 2007 11:54

Page 523

Release Notes 1.0b1
This page last changed on Jan 19, 2004 by cmiller.

Confluence 1.0b1
Confluence 1.0b1 was released 19th December 2003. That's right - we finally got it out the door! cheers from around the room erupt as developers across in the Atlassian offices crack open a beer.

New Features
• It's soooo much faster as we've implemented caching at multiple levels - trust me, it now flies in development. Here's hoping it flies for you too. (For those with a development bent, turn on profiling via the URL to see abeautiful profiling stack trace on stdout) • The last login date is now tracked, pages and spaces changed since your last login are highlighted in green (as these are presumably pages you want to view), you can see a diff of the currently viewed page against the date you last logged in and there are various related reports of spaces/ pages changed since your last login. • Parent/child page hierarchies have been implemented. You can specify the parent for any pages and the ancestry is reflected in the breadcrumbs list. The full hierarchy is shown (including the current page's position) on the Page Information screen, and there is a related macro to show the children in various different types of trees (see the Notation Guide for details) • Search has been completely overhauled - search now works across pages, comments and space descriptions and the results now display descriptions with highlighted search terms (this is really cool!) • Page renaming and link refactoring now works across comments, space descriptions and pages neat! • The Notation Guide has been significantly improved with more useful examples, a list of the available macros and a tabbed interface. Also the edit/create pages now have a 'quick notation guide' to the most commonly used operations • There is a new 'Create Comment' permission - so that you can make spaces which are publicly viewable/commentable, but not editable. • The UI of the 'create link' and 'external link' links within a rendered page have been improved with subtle icons • Page comments now have a sexy icon of their own, and can be shown/hidden at will. You can also permalink to any given comment and comments are fully indexed. • Undefined and orphaned pages reports have been tightened significantly so that they now report truly undefined/orphaned pages • You can create a list of URLs ignored from external referrers - this is useful where your server is known by multiple IP / domain name combinations, or you want to ignore all internal referrers (Admin / General configuration) • {color} macro to colour blocks of text • Logging in to Confluence now takes you to your intended destination, not the Dashboard • There is an option to choose whether the default link for a space goes to the space homepage or the space summary (people internally and externally seem to be divided about which it should go to - so you can choose for yourselves) • You can now edit and add SMTP servers through the web interface • The administration interface has been completely overhauled and tightened • Added a Mail Queue administration page • Added a View System Information page • Added a pretty error page, and the ability to submit but reports (including exports) directly to us • The permissions viewing and editing pages have been greatly simplified and improved across the application • Confluence now has a licensing system, so you will need a license key to evaluate (these can be generated online as with JIRA). • Image embedding can now include parameters (such as height, width, alignment etc) - see the Notation Guide for details. • https:// links are now treated just like ftp:// and http:// external links • Various rendering bugs have been fixed. • Many other minor fixes, improvements and performance tweaks

Document generated by Confluence on Oct 10, 2007 11:54

Page 524

Release Notes 1.0b2
This page last changed on Jan 19, 2004 by cmiller.

I see dead pages! Confluence 1.0b2 was released on Friday January 16, 2004 with a major bug in its search indexing that caused it to index pages that no longer existed. It was replaced by 1.0b3 the next Monday. See also: Release Notes 1.0b3 and Issues Resolved for 1.0b3

Document generated by Confluence on Oct 10, 2007 11:54

Page 525

Feature List
This page last changed on May 24, 2007 by rosie@atlassian.com.

The features listed on this page refer to Confluence version 1.0 beta1. Content Management • Content is organised into discrete spaces in which users can create and edit pages. • Easy-to-learn, easy-to-read but powerful notation for designing pages and linking between them, based on the popular textile markup. • Arbitrary files can be attached to pages. • Comments can be left on pages. • Page templating allows rapid creation of boiler-plate pages. • Pages can be organised into hierarchies. Update Tracking • • • • Each page has a full change history, accessible as coloured diffs highlighting each change made. Simple Reports which pages have been updated since you last logged in. Email subscription informs you of pages that have been added or updated, or comments left. RSS feeds available for new and updated pages across the site, or in individual spaces.

Searching • Full-text searching of all content, including pages, comments and space descriptions Site Management • • • • • Smart page-renaming updates links across the entire site, even in comments or space descriptions. Pages or spaces can be imported from plain text files, or exported to PDF or HTML. Simple backup and restore to XML files. Automatic daily backup feature. Reports of "orphaned" pages that exist but are not linked to, and of links that point to pages that do not yet exist.

User Management and Security • Flexible security, from a public site, to a personal space. • User- and group-based permissions. • Separate viewing, commenting, editing and administration permissions for each space. Deployment and Compatibility • Available on a wide variety of platforms, either as a stand-alone server, or as a web-archive deployable into a compatible Java application server. • Compatible with a large number of databases • See Requirements for more information Support • Confluence is under full-time development, with licensees entitled to a year of free updates. • Atlassian's Legendary Service.

Document generated by Confluence on Oct 10, 2007 11:54

Page 526

Release Notes 1.0b3
This page last changed on May 29, 2007 by rosie@atlassian.com.

Confluence 1.0b3
1.0b3 was released on January 19th, 2004. It replaces the short-lived 1.0b2 release, after 1.0b2 managed to escape into the wild with a bug in the search index that made it see pages that weren't there any more. Since 1.0b2 only existed for one weekend, the release-notes for both versions have been folded into a single document. This is a massive release. Over 90 issues (new features, improvements and bug-fixes) were resolved between beta-1 and beta-3, with even more improvements made below the issue-tracking radar.

Contents
1. 2. 3. 4. 5. New Features New Macros Improvements Notable Bug-fixes Outstanding Issues

See also: Issues Resolved for 1.0b3

New Features
Search Attachments Attachments are now indexed for searching just like any other content in the Confluence space. Alongside text, HTML and XML attachments, Confluence will also index Word, RTF and PDF documents. Configurable Look and Feel The site administrators can now customise the colour-scheme of the Confluence installation. More advanced configuration can be done by editing the site's templates through a web interface, changing the appearance of the whole site. See Customising Confluence for examples and information. Site Homepage The site administrator can now set the site homepage for users who have not logged in: choosing from either the dashboard (the default behaviour in beta1 and before), or any of the Space homepages within the site. Users who have logged in can choose their own site homepage in their user profile. RSS Feed for New Comments You can subscribe to all new comments added to a space using an RSS newsreader. (The link to the RSS feed can be found on the Space Summary page) Emoticons

New Macros
• {include} – include the contents of one Confluence page within another (see (outdated) Include Page Macro for more details) • {include-html} – include the contents of an HTML document within a Confluence page (turned off by default. See Enabling the html-include Macro for more information) • {rss} – include an external RSS feed (see (outdated) RSS Feed Macro for details and example)

Document generated by Confluence on Oct 10, 2007 11:54

Page 527

• {search} – include the results of a Confluence search (see (outdated) Search Macro for details and example) • {jiraissues} – integrate Jira issue reports with your Confluence site (see (outdated) JIRA Issues Macro for details and example) • {junitreport} – include JUnit test result data (see (outdated) JUnit Report Macro for details and example)

Improvements
• • • • • • • • • • • • Users' login names and full names are indexed for searching Users' profiles may now be longer than 255 characters, and are also indexed for searching Usernames are no longer case-sensitive Anonymous contributions are clearly labeled Users are warned if they are editing or commenting without having logged in Notification emails now link to the appropriate "diff" page, so you can quickly see what has changed Page diffs now highlight precisely what changed within each line: very useful when just one or two words change in a long paragraph Lists of child pages and links are sorted alphabetically Long lists of pages or search results are paginated Shortcut links can be given different link text in the same way as other links (e.g. [Search for Confluence on Google|confluence@google]) Incoming links and "hot referrers" are listed in the sidebar of the page view Child pages are listed below the page contents in the page view

Notable Bug-fixes
• You no longer get the old page (or don't see the comment) immediately after editing or commenting on a page CONF-453 • Persistent login cookies no longer conflict with a JIRA installation on the same server CONF-440 • Persistent login cookies no longer fail for users with certain characters in their username CONF-387 • Notification emails no longer send out garbage for anonymous changes. CONF-421 • Users who are not logged in no longer see strange table titles CONF-422 • And many more....

Outstanding Issues
• You should restart Confluence immediately after finishing the initial setup steps, to avoid data loss CONF-493 • New-lines may not be drawn if the next line starts with whitespace CONF-475 • Emoticons are rendered inside {noformat} blocks CONF-502 • If you put a {children} macro after an {include} macro, it will list the children of the included page. CONF-504

Document generated by Confluence on Oct 10, 2007 11:54

Page 528

Issues Resolved for 1.0b3
This page last changed on Jan 19, 2004 by cmiller.

Atlassian JIRA(3 issues) T Key CONF-497 CONF-495 CONF-496 Summary Search includes old versions of pages Problem with incoming links Problem with rename Status FIXED Closed FIXED Closed FIXED Closed Res

Issues resolved for 1.0b2
1.0b3 was a quick bug-fix release for 1.0b2, so here are the issues resolved in 1.0b2:

Atlassian JIRA(81 issues) T Key CONF-304 CONF-425 CONF-410 CONF-429 CONF-438 CONF-483 CONF-307 CONF-437 CONF-456 CONF-418 CONF-407 CONF-173 CONF-420 CONF-417 CONF-290 CONF-449 CONF-412 Summary Sitemesh/Velocity Integration Upgrade to CVS HEAD of XWork / WebWork 2 Update confluence features list Upgrade SiteMesh and use Velocity decorators JUnit XML displaying macro ! {include:page} macro Ability to search attachments External RSS macro! Global colourscheme configuration Better handling of anonymous contributions RSS feed for recently added comments Remote editable space decorators Set "Site Homepage" One-click bug submission Configurable Look & Feel Macro for fetching/ importing JIRA issues Make usernames and user full names searchable Status FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed Res

Document generated by Confluence on Oct 10, 2007 11:54

Page 529

CONF-458 CONF-462 CONF-394 CONF-431 CONF-443 CONF-457 CONF-401

JIRA macro column selection Documentation for decorator editing Update links from other spaces when renaming pages Per word diffing Shortcuts should allow "my link name" like other links do Put nice colourpicker on colour customisation screen Parent child relationships should be thought about more Child pages invisible by default Add diff link to "page edited" email Make diffs highlight changes within a line. Fix user profile so it can hold > 255 chars Add emoticons to confluence Pagination for long lists (search is the first!) Include user in "Recently Updated Pages" Move "incoming links" back to the page Upgrade to the Spring SessionInView filter Warn user if they're commenting/editing anonymously Improve the JUNIT macro Page templates should be editable on the web interface and saved in exports Escaped characters don't work as they should BackupJob does not have a Hibernate session Mistyped link syntax gets rendered weirdly ampersand in links breaks them "Display Default Decorator" shows

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-371 CONF-413 CONF-415 CONF-397 CONF-477 CONF-471 CONF-388 CONF-387 CONF-373 CONF-419 CONF-454 CONF-482

FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-408 CONF-450 CONF-392 CONF-446 CONF-467

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 530

CONF-424 CONF-488 CONF-414

CONF-453

CONF-421

CONF-452 CONF-406 CONF-433 CONF-468 CONF-393 CONF-411 CONF-485 CONF-479 CONF-472 CONF-404

CONF-447 CONF-441 CONF-440 CONF-494

edited template, not default {children} macro barfs on removed child page Too much white space generated? Replace all webwork.urlEncode with generalUtil.urlEncode "Add Page" permission checking is not consistent when logging in as anonymous NPE when sending notifcations for anonymous user activity Permissions check for /signup.action always fails Could not parse : Dec 19, 2003 : java.text.ParseException No security checking in FileServerServlet! Link extraction should exclude {code} contents (*boldme* does not work. Cancel button not working on Add Comment Dialog Incoming links from space descriptions buggy Errors invisible on "rename page" form adding a comment does not display it right away Undefined pages report misrenders when link source is a comment Error automatically creating pages with illegal names "my link name" links in tables don't work right Confluence Login cookies conflict with JIRA Export from data originating in beta1 may be unimportable in beta2

FIXED Closed FIXED Closed FIXED Closed

FIXED Closed

FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Resolved FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 531

CONF-435 CONF-463 CONF-481 CONF-383 CONF-442 CONF-466

Macros still run inside {noformat} block Path admin page still thinks it's a setup step Newly added comment doesn't appear when posted Export space fails line breaks (\\) don't work {color} macro messed up by surrounding {{monospace}} markup Space descriptions can't contain links in their space Setting a homepage makes dashboard inaccessible. Usernames (while logging in or setting up a new account) shouldn't be considered as case sensitive Logging in annonymously & the UI display keys! Apostrophe doubleencoded inside {code} block HTML emails contain #emailUserLink (mike) Editing personal information in user profile stops working Exception when diffing added line Can not use LDAPCredentialsProvider i18n text inside a webwork 2 component do not display (only their keys do) for anonymous users Email password doesn't seem to work ' is converted into &#8217 Should not be able to add ANYONE group to ADMINISTRATE Conlfuence/Space permissions

FIXED Closed FIXED Closed DUPLICATE Closed WON'T FIX Closed FIXED Closed FIXED Closed

CONF-486 CONF-451 CONF-405

FIXED Closed FIXED Closed FIXED Closed

CONF-409 CONF-470 CONF-487 CONF-476 CONF-432 CONF-354 CONF-422

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed WON'T FIX Closed DUPLICATE Closed

CONF-439 CONF-459 CONF-423

FIXED Closed CANNOT Closed REPRODUCE FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 532

CONF-384 CONF-464

Login cookie appears to be broken on confluence.atlassian.com:8080 Standalone tomcat version is not working!

FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 533

Release Notes 1.0b4
This page last changed on Jul 02, 2004 by jnolen.

Confluence 1.0b4
To belatedly ring in the Year of the Code-Monkey, it's time for Confluence 1.0 beta 4. We've had some great feedback on the last few betas, thanks to everyone for submitting bugs, and contributing to the forums and discussion space. Contents 1. 2. 3. 4. 5. 6. FatCow New Features New Macros Improvements Notable Bug-fixes Outstanding Issues

See also: Issues Resolved for 1.0b4 Atlassian FatCow Along with 1.0b4, we're also releasing FatCow: Functional Acceptance Testing for the Confluence Wiki. Styled after Ward Cunningham's FIT and Bob Martin's Fitnesse, FatCow allows you to define web-based acceptance tests in wiki notation, and then run them from inside Confluence. Here's a tutorial showing how to write a quick FatCow test suite that makes sure Confluence shows up on Google. FatCow is Open Source, and also serves as example code for anyone who wants to extend Confluence by writing their own macros (something that we'll be looking to make easier in future releases). New Features Blog Posts Each space can now host a "blog" of pages that are organised by date, rather than just by title. This is pretty useful if you want to attach some kind of updating news to a space. The "create blog post" button can be found on the right-hand toolbar. Blogging support is pretty basic right now: you can create posts, and you can include the most recent posts in a page using the {blog-posts} macro. Rest assured, we'll be piling on the features in the next few releases. Move Pages Between Spaces A much requested feature, our newest refactoring lets you move pages cleanly from one space to another. We're using this already to maintain a private space where we stage documentation waiting to be transferred to the main documentation space. Configurable Site Description You can now change the text in the site description that appears on the user's dashboard: somewhere to put welcome messages or MOTDs. And, of course, it understands Confluence markup. #includePage("Page") Velocimacro For the decorator-editors, you can use this render the contents of a page anywhere inside a decorator. The page has to be in the space that the user is looking at, and if the page does not exist, nothing will be rendered. New Macros • {blog-posts} displays the most recent blog posts for a space. • {rss} macro now has maxEntries and titleBar parameters.

Document generated by Confluence on Oct 10, 2007 11:54

Page 534

• {anchor} macro allows you to create named anchors in a page (link to them with [SPACE:page#anchor]) Improvements • • • • • You can now draw en – and em — dashes. mailto: links are now drawn as just the email address, like so user@example.com the {search} macro now excludes the page it was included in from the search results you can also link to attachments using #-anchors [SPACE:page#attachment.pdf] you are given the opportunity to pick a template when creating a page from a link, and any entered page title survives picking a page template

Notable Bug-fixes • Spurious error message about editing a stale version of a page have been squashed. • No longer crashes when you add a user to certain groups. • Some database queries have been rewritten to work around the fact that MySQL doesn't understand sub-selects. • Diffs more reliably highlight changed words • Several minor rendering problems to do with deeply nested lists have been fixed. • and many more... Outstanding Issues • You should restart Confluence immediately after finishing the initial setup steps, to avoid data loss CONF-493 • New-lines may not be drawn if the next line starts with whitespace CONF-475 • Emoticons are rendered inside {noformat} blocks CONF-502

Document generated by Confluence on Oct 10, 2007 11:54

Page 535

Issues Resolved for 1.0b4
This page last changed on Jan 27, 2004 by jnolen.

Atlassian JIRA(39 issues) T Key CONF-460 CONF-501 CONF-291 CONF-192 CONF-509 CONF-234 CONF-531 CONF-534 CONF-554 CONF-544 CONF-555 CONF-513 Summary FIT macros and integration &mdash; and &ndash; filters Ability to move a pages between spaces Ability to link to attachments Site description Blog posts Add Max Entries parameter to rss macro Search macro should exclude page it's included on Support emdash like Textile add a titleBar=true| false option to rss macro mailto links should look better Form rules on 'Create Admin Account' during setup! Preview & Confirm is always telling me the page is outdated Back button "rollbacks" changes when previewing a page Internal anchor links have the external link icon HTML export is broken jiraissues macro does not display due column Cannot add user to additional groups Edit Page Conflicts is buggy - often seems to detect conflicts which aren't there Lists only work to 4 levels {include} macro confuses {children} macro. Status FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed Res

CONF-543 CONF-517

FIXED Closed WON'T FIX Closed

CONF-505 CONF-537 CONF-528 CONF-516 CONF-524

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-519 CONF-504 CONF-510

FIXED Closed FIXED Closed FIXED

Document generated by Confluence on Oct 10, 2007 11:54

Page 536

CONF-523 CONF-515 CONF-474 CONF-535 CONF-529

CONF-547 CONF-526 CONF-507 CONF-445 CONF-567 CONF-508

CONF-518 CONF-546 CONF-512 CONF-566

CONF-522

CONF-444

'Browse Pages' does not show the recently modified pages (in green)... Single word diff rendering is buggy Home link on summary page goes to... summary. Don't get the chance to fill out variables Removing a page gives exception on MySQL template variables with an underscore in the name don't highlight properly MySQL doesn't support sub-selects Moving page doesn't break parent/child relationships SnipSnap import does not add users to confluence-users JDBC error accessing undefined pages on mysql Home link should take users to the home page Space description links don't take you to the space description Deeper item in list can't be bold Hot Referrers includes editing links Confluence doesn't like it when I re-add a deleted child page Previewing multiple times while editing confuses the versioning system Page-Space relation is corrupted after latest upgrade (blog related table modifications) JDBC error accessing orphaned pages on mysql

Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed WON'T FIX Closed FIXED Closed DUPLICATE Closed

FIXED Closed

FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 537

Release Notes 1.0rc1
This page last changed on Jul 21, 2004 by mike@atlassian.com.

Confluence 1.0rc1
It's Friday again, and that means it's time for us to release Murray; Confluence 1.0 Release Candidate 1. RC1 marks the start of the feature-freeze as we plunge headfirst towards a stable 1.0 release. From now until 1.0-final we will be concentrating on fixing up the remaining bugs and polishing the interface. We are hoping that we won't need to send out a second release candidate, but we can't really make any promises until we've had a chance to go through the inevitable deluge of new issues that will follow this release. Of course, this means that there are features you want to see in Confluence that won't make it into 1.0final. Keep those ideas and suggestions coming. Confluence isn't going to stop at 1.0 – we just had to draw a line somewhere or we'd end up perpetually in beta. We have no plans to slow down development after the first major release. Your Confluence licence includes a year of upgrades, and if you think Confluence is way cool now, it's just going to get better. As always, before upgrading an existing Confluence installation, be sure to back up your data. As you can see below, we've been busy the last two weeks. A hard-earned thirst needs a good cold beer. Contents 1. 2. 3. 4. 5. 6. New Features New Macros Improvements Notable Bug-fixes Outstanding Issues Database Changes from Beta4

See also: DOC:Issues Resolved for 1.0rc1 New Features Remote API Cannot resolve external resource into attachment. Confluence can now be browsed and edited remotely via SOAP or XML-RPC. There are more details of the XML-RPC API here, while the SOAP WSDL can be downloaded from $your_confluence_root$/rpc/soap/ confluenceservice-v1.wsdl. Throwing together a GUI client for Confluence is now prettyeasy, so feel free to embed Confluence support into your favourite editor, web browser or IDE. Blogging Enhancements The sketchy blogging support from Beta4 has been upgraded and overhauled. Enhancements include: The look and feel of blog pages has been greatly improved A "recent blog posts" list available from the Space Summary page Daily and monthly views for blog posts Blog posts can now be edited and deleted You can now link to blog posts using the internal link syntax. Blog posts are addressed by their posting-date and title, like so: [SPACEKEY:/2004/01/03/Blog Post Title] • You can link to the daily views, too: [SPACEKEY:/2004/01/03/] • RSS feeds are available for new blog posts, both globally (from the dashboard), and for each space (from the space summary page) • • • • • Also, anonymous users are no longer allowed to post blog entries. We couldn't really think of a use-case where anonymous blog-posts would be wanted, but if you can, let us know! Configurable User Notification

Document generated by Confluence on Oct 10, 2007 11:54

Page 538

With any knowledge-sharing application, it's important to keep informed as to what has changed. One way to do this is by subscribing to any of the RSS feeds offered by Confluence. Another is to have Confluence email you directly whenever there has been a change. Up 'til now, users have had to make do with the ad-hoc regular-expression based notifications that were put in for developers. WIth RC1, we now have a more fine-grained and user-friendly way to choose how you find out about changes to the site. 1. Each day, Confluence can email you a summary of any changes that have been made to the site in the past 24 hours. You can activate this feature in your user preferences. 2. You can subscribe to "watch" a page from the option in the right-hand operations menu. Whenever the page is modified, commented on, or a new attachment is added, you will receive an email. When you no longer want to watch the page, you can click the icon again to unsubscribe. 3. You can subscribe to watch an entire space from the option on the space summary page. This subscribes you to all pages in that space, and also notifies you when new pages are created. Each user can now also choose whether or not they will be notified of changes they make themselves. Trackbacks While Confluence has always tracked links between pages within the Confluence site, it now has a way to track links to and from external sites: the Trackback API. In this way, a Confluence page can be informed when another site has mentioned it, and inform other sites that it has linked to them. We have implemented the Trackback and Trackback auto-discovery APIs across pages and blog-posts. Trackback is a widely implemented API that allows web pages to notify each other of links. You can enable (or disable) trackbacks from the Confluence general administration page. When Trackbacks are enabled, each Page and Blog Post within Confluence is set up to receive trackback pings, and contains the auto-discovery code to allow clients to automatically find out how to send those pings. Trackbacks that are received are listed in the right-hand sidebar of the page. Also when Trackbacks are enabled, Confluence will perform auto-discovery on each outgoing link from a page to see if the destination is equipped to receive trackbacks, and send its own trackback ping. Look forward to future versions of Confluence making very interesting use of this feature. Per-Space Look and Feel The template-- and colour-scheme editing features that were available on a global basis in previous versions of Confluence can now be configured separately for each space, allowing you to apply a different look and feel to the various spaces within your Confluence site. New Macros • {panel} macro allows you to draw a shaded box containing some content Improvements • Import and Export should now be much faster, and use significantly less memory • The user browser now has a search function, to make it possible to manage large numbers of users effectively • Incoming links are no longer displayed on a page if the user is unable to view the page being linked from • The {anchor}, {blog-posts}, {index} and {quote} macros are now documented properly. • You can escape smileys by putting a backslash before their last character, to cause them not to be rendered as images :) • You can now link to peoples' user profile pages with [~username] (e.g. Charles Miller) • You can now link to space homepages with [SPACEKEY:] (e.g. TEST:) • mailto: links have a nifty icon: user@example.com • The History popup now tracks your visits to blog posts, space summaries and user profile pages • Recent changes listings on the dashboard, user profile and space summary pages now includes changes to all content, not just pages. • New Emoticons! (well, icons really)

Document generated by Confluence on Oct 10, 2007 11:54

Page 539

(y)

(n)

(i)

(/)

(x)

(!)

Notable Bug-fixes • Added HTML headers to detect and prevent RSS, HTML-Include and FatCow macros from being made to loop in on themselves. CONF-525 • The {anchor} macro, and [DOCPRIV:null] links now work as advertised. CONF-616, CONF-605 • Fixed a divide-by-zero error in page diffs CONF-584 • Included javax.transaction libraries with release, to allow the WAR to run under Tomcat 5 CONF-613 • And many more rendering and stability fixes... Outstanding Issues • Still some problems with character encoding in page titles CONF-569 • HTML include macro interacts badly with other Radeox filters CONF-549 Database Changes from Beta4 New Tables TRACKBACK and NOTIFICATION tables were introduced. These tables should be generated automatically when you first start RC1. New column in the EXTRNLINKS table • alter table EXTRNLINKS add column CONTENTTYPE varchar(255); Constraint Change on LINKS Table The "not null" constraint was removed from the DESTPAGETITLE column of the LINKS table. Consult your database documentation on how to alter your database for this change. For example: • MySQL 3.23: alter table LINKS modify DESTPAGETITLE VARCHAR(255); • PostgreSQL 7.3.2 alter table LINKS alter DESTPAGETITLE drop not null;

Document generated by Confluence on Oct 10, 2007 11:54

Page 540

Issues Resolved for 1.0rc1
This page last changed on Feb 06, 2004 by cmiller.

Atlassian JIRA(63 issues) T Key CONF-579 CONF-540 CONF-559 CONF-280 CONF-545 CONF-581 CONF-591 CONF-615 CONF-541 CONF-538 CONF-465 CONF-542 CONF-580 CONF-626 CONF-553 CONF-561 CONF-617 CONF-583 CONF-568 CONF-601 Summary Daily Notification Report Recent Blog Posts RSS feed Add Trackback support Implement VP Wiki API create a panel macro Notify me for this page Remote XML-RPC API Create SOAP API Blog Post Daily View Internal links to blog-posts Per-space colour schemes Blog Post Monthly View Notify me for this space Recent Blog Posts page Link directly to user profile Space specific decorators History popup now tracks viewing user info pages Do not notify user of his own actions documentation for {anchor} macro missing I18n for execution threads that aren't triggered by web requests "New file attached" notification email nice icon for mailto: links Remove blurb from {jiraissues} header. Improve user browser Display of comment section remembered by page Edit/delete blog posts Status FIXED Closed FIXED Closed FIXED Closed WON'T FIX Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Resolved FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed Res

CONF-562 CONF-558 CONF-506 CONF-557 CONF-578 CONF-539 CONF-600

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED

Document generated by Confluence on Oct 10, 2007 11:54

Page 541

CONF-576 CONF-625

CONF-502 CONF-564 CONF-624

CONF-610 CONF-563 CONF-588 CONF-572 CONF-570 CONF-612 CONF-3286 CONF-622 CONF-621 CONF-525 CONF-582 CONF-573 CONF-552 CONF-475 CONF-609 CONF-623

listpages.action should show a page count Blog page L&F needs to be more blog like "Recent Changes" lists should include chages to all content types Need a way to escape smileys Error deleting template Prevent trackback autodiscovery from downloading just anything Pages with a parent are, by definition, not orphaned Incoming links displayed for pages you can't see Links in noformat macro broken ImportExportException Moving page doesn't update internal links Bug on "Moving Page" CLONE -New line disappears Errors with new links Stack trace editing issue RSS macro can loop on itself exception when removing page Insert Link is broken search macro output is not updated New line disappears Deny blog posting for anonymous users children Hierarchy macro fails if page is assigned to heirarchy later Can not setup with hsqdl Can't edit personal profile Links in PDF export broken (contain www.atlassiannull.com/ blah) Templates feature doesnt seem to work in B3 When renaming a page name

Closed FIXED Closed FIXED Closed

FIXED Resolved CANNOT Closed REPRODUCE FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed CANNOT Closed REPRODUCE FIXED Closed FIXED Closed FIXED Closed CANNOT Closed REPRODUCE FIXED Closed FIXED Closed WON'T FIX Closed FIXED Closed FIXED Closed

CONF-618 CONF-620 CONF-571

FIXED Closed FIXED Closed FIXED Closed

CONF-597 CONF-590

DUPLICATE Closed CANNOT Closed REPRODUCE

Document generated by Confluence on Oct 10, 2007 11:54

Page 542

CONF-585 CONF-616 CONF-536 CONF-613 CONF-584 CONF-574 CONF-605 CONF-592 CONF-628 CONF-602

truncalates first letter of new link faulty rendering of anchor links Links containing &#xxxx; entities are malformed Renaming backup files is dangerous javax.transaction not included in lib jars page diff results in ArithmeticException missing velocity file for blog post preview Page anchors showing in links Changing parent page doesn't work Can not choose custom backup path No notification email is sent!

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 543

Release Notes 1.0rc2
This page last changed on Feb 14, 2004 by cmiller.

Confluence 1.0rc2
After a week of frantic bug-fixing, we have released Confluence 1.0 Release Candidate 2. Thanks everyone for reporting all the bugs they found in RC1. While we really hope you'll keep reporting anything you find that doesn't work, we're also hoping that there's a lot less to report now. We have released RC2 because it's a lot more stable than RC1. We know a lot of you are already using Confluence in some kind of production capacity, and we don't want to keep you waiting for the important fixes that we put in this week. Since we're in the middle of a feature freeze, there obviously aren't any new major features in this release, but there are a number of incremental improvements, and a lot of fixes. But first, a... WARNING If you are upgrading from Confluence 1.0rc1, do not perform a backup of your data from within Confluence. There was a serious bug with RC1 that caused user permissions to be corrupted during data exports. There have been no database changes between RC1 and RC2, so you should simply be able to run RC2 against your existing data without performing a backup/restore. If you wish to back your data up safely before the upgrade, you will need to do so manually: shut down Confluence, make a copy of your Confluence home directory (as defined in confluenceinit.properties, and if you are storing your data in something other than HSQL, use your database's native backup procedure. Contents 1. Improvements 2. Other Bug-fixes 3. Outstanding Issues See also: Issues Resolved for 1.0rc2 Improvements • Remote XML-RPC and SOAP APIs now have a getPermissions() method • {noformat} macro accepts a title parameter • Page view and create links are no longer displayed if the user does not have permission to view or create the destination page. • When you create a page from viewing a previous page, you are given another chance to make that page the new page's parent. • RSS and HTML include macros use HTML proxies if they are defined using the standard Java http.proxyHost and http.proxyPort system properties. • Default session timeout is now 60 minutes • Improvements to user browser and user profile page UI • Shortcut link definitions are now backed up and restored Notable Bug-fixes Stability We've done a lot of work tracking down the source of any exception and page error that has been reported to us, and fixing their causes. We've also made one or two improvements to the error reporting page, but we're hoping you won't see it nearly as often (if at all) any more. Page Templates

Document generated by Confluence on Oct 10, 2007 11:54

Page 544

The creation, editing and deletion of page templates should now be a lot more reliable and provide a smoother user experience. Also You no longer have to restart Confluence after its initial setup CONF-493 Performing a full data export no longer corrupts users' group membership data. CONF-645 You can now link to profiles of users with an @ symbol in their usernames CONF-639 Trying to create a page with illegal characters in its name no longer loses your page content on some browsers. CONF-713 • Trackback pings are now sent for URLs that are not surrounded by square brackets CONF-708 • And, of course, many more... • • • • Outstanding Issues The two major areas we still need to work on are the PDF export and the use of non-ASCII characters in pages (especially page titles). Handling of both are much better than they were a week ago, but there's still some work to do before they're completely reliable.

Document generated by Confluence on Oct 10, 2007 11:54

Page 545

Issues Resolved for 1.0rc2
This page last changed on Feb 14, 2004 by cmiller.

Atlassian JIRA(74 issues) T Key CONF-589 CONF-255 CONF-532 Summary Way to prevent a http URL from being rendered as a link Please please please. Support external (LDAP) groups. Add title parameter to noformat macro ( and you can rename it at the same time to 'block' ) Pages that have more than one version have different icon Up default session timeout to 60 minutes Make doubleencoding smarter Fix user browser UI anchor links to local page anchors classed as incoming link Improve user profile UI Javascript 'Make previous page into parent' link Create a page from a sub page should implicit include the parent page in the Create Page Dialogue Move "new blog post" away from "add child page" Edit my profile page help information is inconsistent RSS and HTML include macros should use proxies if defined User friendly options for exporting a space Remote APIs need a getPermissions() method Link icons don't show up in PDFs emoticons path is wrong Status FIXED Closed WON'T FIX Closed FIXED Closed Res

CONF-642

FIXED Closed

CONF-668 CONF-654 CONF-640 CONF-636

FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-641 CONF-670 CONF-700

FIXED Closed FIXED Closed FIXED Closed

CONF-646 CONF-697 CONF-714

FIXED Closed FIXED Closed FIXED Closed

CONF-596 CONF-666 CONF-627 CONF-656

DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 546

CONF-631 CONF-689 CONF-690 CONF-708

CONF-659 CONF-662 CONF-703

CONF-704 CONF-706

CONF-673 CONF-684 CONF-701

CONF-687

CONF-484

CONF-655

CONF-716 CONF-679 CONF-657 CONF-683 CONF-702

SOAP service can't get started .... pdf export of page containing ndash (--) fails italic text effect in link text broken External links that are not bracketed "[ ]" are not pinged for trackbacks Snipsnap Import Fails. Login required to browse spaces Unable to create template of same name, after deleting origional Template stops working once you've edited it once Recent updates lists gets page modifier wrong if anonymously edited. isUserWatchingSpace throws null pointer sometimes Clicking on Previous Version -> Version gives NPE Export page to PDF, click on generated link for page that doesn't exists...generates a NPE Comments to blog posts that appear on the dashboard recently updated list are broken Some links in the documentation site are "create new page" links Upload attachment without specifying file should have nicer error SQL error removing user on Postgres Blog RSS DTD gives 404 Various crashes with space-less links in user profiles PDF export fails on {children} macro Export to PDF doesn't render all text correctly

FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed WON'T FIX Closed CANNOT Closed REPRODUCE FIXED Closed FIXED Closed

FIXED Closed FIXED Closed DUPLICATE Closed

FIXED Closed

FIXED Closed

FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 547

CONF-688 CONF-349 CONF-698

CONF-639 CONF-647 CONF-619 CONF-633 CONF-675

CONF-493 CONF-674 CONF-648

CONF-685 CONF-651

CONF-360 CONF-695 CONF-699

CONF-677 CONF-705

CONF-696

CONF-681

SOAP service has $Proxy name Create page from template Anonymous users cannot access the RSS feeds. Throws a NPE [~username] link fails when username contains @ Templates feature doesnt seem to work in RC1 Upgrade from B3 to B4 gives InfrastructureException Can't restore the extranet data locally When running confluence under a non-default context, exporting PDF breaks Confluence not fully set up until first restart Notifications not updated when a page is deleted Unable to set the name of a page using templates once a template is selected Attempting to export a non-perfect page as PDF breaks Viewing previos version diff "to previous" throws NullPointerExceptions Edit Profile corrupts user record Inconsistencies in remote soap api Renaming page and only changing the case gives error message Exporting a page as PDF with macros results in "null" When creating a document with the template Java error occurs Wrong type of date returned incall to getPage and getPageHistory Rename problems (CONF-496) persist

FIXED Closed FIXED Closed DUPLICATE Closed

FIXED Closed FIXED Closed WON'T FIX Closed WON'T FIX Closed DUPLICATE Closed

FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed

DUPLICATE Closed FIXED Closed FIXED Closed

FIXED Closed CANNOT Closed REPRODUCE FIXED Closed

FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 548

CONF-686

CONF-667 CONF-645 CONF-669 CONF-635

CONF-672 CONF-644 CONF-691 CONF-713

in pages made with previous versions Servlet context added for export causing problem with mod_jk admin login doesn't work in Safari groups disappearing for users Exception clicking "New Blogs" link Can not view the users which have their username start with capital ! NPE with GlobalRSSFeed Cannot backup data Can't delete page templates that have been edited Creating a page with bad characters in the title loses page content Panel, first list item not recognized, and not closing on multiple list items ClassCastException in BackupJob Exporting entire space gives ImportExportException "Create Page" link displayed even when user can't create a page Shortcut/Interwiki links are not backed up and restored! NPE in Global "spaces report" RSS feeds throw NullPointerExceptions

FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-658

FIXED Closed

CONF-632 CONF-678 CONF-649

FIXED Closed FIXED Closed FIXED Closed

CONF-634 CONF-711 CONF-652

FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 549

Release Notes 1.0rc5
This page last changed on Sep 19, 2004 by timcolson.

Confluence 1.0rc5
It's time to release Confluence 1.0rc5 into the wild: it's the fourth Release Candidate since last Friday, and we're definitely getting close here. The last two release-candidates did not have their own releasenotes, so these notes will also include things that were fixed for those versions. Contents 1. 2. 3. 4. 5. New Features New Macros Improvements Notable Bug-fixes Outstanding Issues

See also: Issues Resolved for 1.0rc5 New Features In keeping with our promise to not add any features during the Release Candidate process, we have been very restrained, and only added two new features Template Preview Page templates have been given an overhaul: when filling in your template variables, you are presented with a template of the rendered page, with input fields where the variables will be inserted. If you have the same variable used in several places, the form will take care of keeping them all in synch.

Page Redirection

Document generated by Confluence on Oct 10, 2007 11:54

Page 550

When you rename or move a page, the page's old URL will attempt to give users some clue as to where they should be looking: checking which pages have had this name in the past, or redirecting users to pages in another space with the same name.

New Macros • {weblogs} is a synonym for {blog-posts} Improvements • The user signup screen has a more friendly UI • Exported PDFs now incorporate the site's stylesheet, and thus look a lot better. • Confluence now has a useful "404" error page that gives the user some suggestions of how to find what they were looking for. • An Administrators page, linked from the footer of each page, lists those users in the "confluenceadmin" group. (If you don't want your address to be made public on this page, create an administrative group with some other name) • The error you receive when you exceed your licensed user limit is more informative, and no longer directs users to email Atlassian. • The SnipSnap importer converts SnipSnap blog posts to Confluence blog posts. • Several methods added to the XML-RPC and SOAP APIs for managing users and spaces. (See DISC:Conf Remote API Additions) • The Daily Report email is more informative and more readable • Page comments and Parent/child relationships are maintained during HTML and PDF exports • news: and nntp: URL schemes are now recognised in bracketed links Notable Bug-fixes Since RC2 • • • • Links between pages now work when you have a context path other than / (oops!) The daily report email is no longer sent every minute (oops!) You can no longer download attachments without being logged in (OOPS!) Search results no longer highlight words that were terms in previous searches

Since RC3 • Page redirects now work properly under Orion 2.0.2 Since RC4 • Removing a user no longer causes their notifications to hang around and crash things • Removing a blog post works, too • Many fixes to PDF rendering and exporting

Document generated by Confluence on Oct 10, 2007 11:54

Page 551

Many fixes to handling of Latin character set (See outstanding issues below) Invalid macros now give a more informative error than "no group 3" The 404 error page no longer requires you to log in to view it Macros that generate HTML (page include, HTML include, JIRA, RSS, FatCow) bypass the remainder of the page processing, and so should have far fewer formatting errors now. • User browser filter remembers your search across pages • • • • Plus, of course, innumerable fixed to annoying crashing bugs across all three releases. Outstanding Issues Latin Characters under Resin We've tested creating pages with non-ASCII titles and content across several different browsers and several different operating systems, and they seem to be working reliably now... except on Resin. This will be quite noticeable since confluence.atlassian.com itself is running under Resin, but we have so far been unable to come up with a solution that works on this application server. For users who need this functionality, we suggest running under Tomcat. • On MySQL, the "orphaned pages" report may include the space's homepage CONF-766 • Combining block macros with lists is dangerous CONF-756 • Under some circumstances, paragraph tags will not be closed CONF-746

Document generated by Confluence on Oct 10, 2007 11:54

Page 552

Issues Resolved for 1.0rc5
This page last changed on Feb 20, 2004 by mike@atlassian.com.

Atlassian JIRA(35 issues) T Key CONF-775 Summary Add user management methods to remote API for administrators Allow news: and nntp: URL schemes in [links] Forced newline // should give <br clear="all"/> Improve the UI of the signup screen Make daily email a bit more readable Renaming a page should leave behind an HTTP redirect create a ConfluenceException and throw when we have a user correcatble error The parent/child relationships are not reflected in HTML exports! PDF Export Bookmark browser doesn't reflex parent/child page relationship space scoped templates not showing up on Browse Templates page NPE on 500 error response that contains no exception under Orion Moving page edits space descriptions? User browser filter not maintained in session Daily Email not picking up all of the changes in a day Error message for an unknown macro is misleading content-by-user macro broken Status FIXED Closed Res

CONF-787 CONF-788 CONF-750 CONF-773 CONF-499 CONF-755

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-723

FIXED Closed

CONF-719

FIXED Closed

CONF-763

FIXED Closed

CONF-781

FIXED Closed

CONF-751 CONF-739 CONF-774 CONF-760 CONF-758 CONF-777

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 553

CONF-754 CONF-729

CONF-710

CONF-745

CONF-768

CONF-757 CONF-676

CONF-744

CONF-779 CONF-782 CONF-772

CONF-752 CONF-771

CONF-769 CONF-767 CONF-761 CONF-556

Remote API does not incidate space comment or admin perms weblog macro broken in rc3 after a snipsnap import renderContent generates bad html for images from blog macro & for attached images Can not export a page (as PDF) while there are two anchors with the same name! Panel, extra white space at top and extra extra when included Logging in occasionally redirects user straight to the fourohfour page :) PDF's show question marks instead of bulletin points Exporting as a PDF, document with list items generates garbage in PDF Exporting a page as PDF with {fatcontroller} breaks Removing a user doesn't remove notifications Page doesn't get listed instantly putting in bogus URL doesnt show 404, later 404 looks unwell ImmutableException when trying to reset password NPE on "recently updated pages report" on dashboard Getting a lot of these traces running RC4 under tomcat 4.1.27 html export zip appears empty as XP compressed folder Watch this Space didn't work Import fails if export is from different database

FIXED Closed FIXED Closed

FIXED Closed

FIXED Closed

FIXED Closed

DUPLICATE Closed FIXED Closed

FIXED Closed

FIXED Closed CANNOT Closed REPRODUCE FIXED Closed

CANNOT Closed REPRODUCE FIXED Closed

WON'T FIX Closed WON'T FIX Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 554

CONF-770

NPE in space look and feel action

FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 555

Release Notes 1.0rc6
This page last changed on May 23, 2006 by david.soul@atlassian.com.

Confluence 1.0rc6
Confluence 1.0rc6 fixes more bugs. Lots of them. There aren't many new and interesting features to report, although we have implemented the much-requested ability to mask email addresses and prevent public signup. Mostly, we've been toiling away fixing the lots of little problems that are getting in the way of us calling Confluence truly worthy of the 1.0 label. Contents 1. 2. 3. 4. 5. New Features New Macros Improvements Notable Bug-fixes Outstanding Issues

See also: Issues Resolved for 1.0rc6 New Features Private Confluence Configuration In private mode, the only way to add users to Confluence is through the administrative interface: users can not sign up on their own. This way, you can prevent random passers-by from signing on to your Confluence installation. The site administrator can configure this in the general administration settings. Email Address Privacy Another much-requested feature, the site administrator has three options for email-address privacy: • Public: just like pre-rc6, users 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. • Private: only site administrators can see users' email addresses. Administrators should be aware that even in private mode, anyone in the confluence-admin group will still be listed (with their email address) on the administrators page, although their addresses will be masked. Share User Management with JIRA For sites with both a Confluence and a JIRA installation, Confluence can be set up to delegate its usermanagement to JIRA. You can find detailed instructions here. Template Field Types Templates now support drop-down menus and text-input areas. @variablename|textarea(5,10)@ will give you a 5 x 10 text-area called 'variablename'. @variablename|list(one,two,three,four)@ will give you a drop-down list called 'variablename', with options one, two, three and four.

Document generated by Confluence on Oct 10, 2007 11:54

Page 556

New Macros • The {html} will allow you to insert arbitrary HTML code into a page. This macro is turned off by default, as it is a security-risk on public systems. We only recommend you enable it on private or intranet-based Confluence installations where you trust your users not to write malicious HTML code. Here's a trivial example of its use:
\{html\} <p>This HTML is <b>inserted</b> into the page</p> \{html\}

• The {junitreport} macro has an option: "reportdetails=failuresonly" that will cause it to only show details of tests that have failed. For example: {junitreport:directory=file:///var/tests| reportdetail=failuresonly} Improvements • • • • Users are now taken to their preferred homepage rather than the dashboard after logging in Text-fields in a template are disabled during preview and viewing Orphaned and Undefined page reports are now paginated Macros such as {code} or {noformat} are now made part of a list if they are placed adjacent to them

Notable Bug-fixes • • • • • • User->Group relationships should no longer disappear during manual or scheduled backups Search results no longer allow people to see content they might not be allowed to see Comments should no longer appear out of order on a page Moving a page between spaces no longer breaks #anchor links Many rendering fixes, some subtle, some not so Many stability fixes, especially regarding import and export

Outstanding Issues Random MySQL Disconnections If you are running Confluence against MySQL using Confluence's built-in datasource, the connection with the database server may be lost after long periods of inactivity. We are pretty sure we have a fix for this, but since the bug takes several hours to manifest, we were not able to test the fix before the release of rc6.

Document generated by Confluence on Oct 10, 2007 11:54

Page 557

The good news is that if we are right, it will only require a quick edit of your configuration file to implement the fix. Further announcements will be made both on confluence.atlassian.com, and the confluence-user mailing-list. In the meantime, the workaround is to not use Confluence's built-in datasource, but to configure Confluence to use your application-server's JNDI datasources instead. Instructions for doing this with Tomcat can be found here, and if you need more help, don't hesitate to contact us at confluencesupport@atlassian.com. Latin Characters under Resin We've tested creating pages with non-ASCII titles and content across several different browsers and several different operating systems, and they seem to be working reliably now... except on Resin. This will be quite noticeable since confluence.atlassian.com itself is running under Resin, but we have so far been unable to come up with a solution that works on this application server. For users who need this functionality, we suggest running under Tomcat. Also.. • On MySQL, the "orphaned pages" report may include the space's homepage CONF-766 • You can create a link to a page with an illegal title: prompting the user to create a page that can not exist CONF-810 • Trackbacks are not sent for shortcut links CONF-888

Document generated by Confluence on Oct 10, 2007 11:54

Page 558

Issues Resolved for 1.0rc6
This page last changed on Mar 05, 2004 by cmiller.

Atlassian JIRA(52 issues) T Key CONF-786 CONF-849 CONF-792 CONF-813 CONF-868 CONF-815 CONF-808 Summary Document running JIRA and Confluence on one standalone Delegate confluence user management to JIRA Private setup Mask/hide email preference Inline HTML Macro Disable textfields in template on viewing and preview Undefined and Orphanned pages are not getting paginated! Wording on signup page Have Junit report show failures only Some final really quick UI fixes? It would be nice to be able to break up a list over several lines Allow Template variables to have types Users should be taken to their specified home page after successful login Lists, and noformat blocks combination not working Templates barf on anchors with no context Change notification email links do not use full server path Browse pages does not show newly added pages until a page is deleted list items with russian symbols break list MySQL disconnects if configured for direct connection {noformat} renders spurious semicolon Status FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed Res

CONF-812 CONF-837 CONF-903 CONF-905

FIXED Closed FIXED Closed WON'T FIX Closed FIXED Closed

CONF-789 CONF-906

FIXED Closed FIXED Closed

CONF-756 CONF-912 CONF-855 CONF-882

FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-872 CONF-909 CONF-846

FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 559

CONF-804 CONF-860 CONF-828 CONF-869 CONF-902 CONF-839 CONF-549 CONF-874 CONF-854 CONF-881 CONF-908

CONF-891 CONF-894 CONF-821

Daily Email says all edits are by Anonymous Date / Time display in 12 hour format, without AM/PM Search results include restricted spaces Crash on viewing own profile Blog post macro recursion problem Group bases permissions doesn't works properly html-include macro broken Auto backup is not working ParseException when trying to use rss / jiraissues macro User/group relations vanish Input area to enter info in user profile is very small when using IE 6.0 Comments appearing out-oforder RSS feeds {blog-posts} macro gives weird black/ grey/black/grey stripes Licensing error appears on 'enter licence' screen Jira issues macro doesn't render correct title if it includes html tag Need to restart tomcat if confluence unused for a while Image attributes allow malicious javascript Inline images get garbled when exporting to PDF Blank Space on Enclosed {panel} Inter-page links in exported PDF wrong HTML Paragraph not closed if starts with number colon Remove space fails with a SQL Integrity Contraint Violation

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed CANNOT Closed REPRODUCE WON'T FIX Closed FIXED Closed FIXED Closed

FIXED Closed CANNOT Closed REPRODUCE FIXED Closed

CONF-829 CONF-826

FIXED Closed FIXED Closed

CONF-873 CONF-910 CONF-863 CONF-857 CONF-798 CONF-746 CONF-870

DUPLICATE Closed FIXED Closed WON'T FIX Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 560

CONF-682 CONF-836 CONF-871 CONF-841 CONF-820

CONF-915 CONF-790 CONF-838 CONF-875

Single letter phrase notation doesn't work Primary key conflicts after an import faulty rendering of sequenced text effects Moving page between space borks #anchor links hibernate lazy instantiation problem on getRecentlyUpdatedContent() in ViewSpaceAction Bold not working inside a subnumbered Bullet {noformat} inside bullets Template of email notifications for 'text' format doesn't exist. Unexpected end of input stream

FIXED Closed FIXED Closed FIXED Closed FIXED Closed CANNOT Closed REPRODUCE

FIXED Closed DUPLICATE Closed FIXED Closed DUPLICATE Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 561

Release Notes 1.1
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

Nymboida, Nym to his friends, is Confluence 1.1. He wants to be your friend. Confluence 1.1 is the first major update to Confluence. It's faster, more reliable, and packed with new features. Thanks to our policy of a year's free upgrades, any current Confluence customer will be able to upgrade to 1.1 at no cost. Current customers, or new users who wish to try out Confluence for 30 days can download either the standalone or WAR distributions from the Atlassian website: http://www.atlassian.com/software/ confluence

Upgrading from 1.0.3a
Upgrading Confluence should be pretty easy: you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! • Users who have enabled external user-management by customising their osuser.xml file will need to read this document also. • Users who have used MySQL or Postgresql with Confluence 1.0 should read this document which explains how to get rid of any extraneous triggers or indexes that might have been created.

Contents
1. 2. 3. 4. 5. New Features New Macros Improvements Notable Bug-fixes Outstanding Issues

See also: Issues Resolved for 1.1

New Features
Macro Management The biggest Nymboida new feature from an end user point of view is going to be the rewritten macro support. Management - You can now enable and disable macros from this convenient (and very attractive) console. Macros are now grouped into libraries to make the management and creation of related macros simpler. Libraries can be installed, activated or deactivated as a single entity. Cannot resolve external resource into attachment. User Macros - We've also had a lot of requests from users for simple formatting macros: people who wanted their code snippets or notes to be formated in a certain way. Confluence 1.1 contains a simple way for administrators to create new macros from within the application without a restart: defining a template that the macro will apply to its arguments or content. User macros are very handy for providing consistent formatting and layouts across your pages. Cannot resolve external resource into attachment. Custom Macros - Installation of new macro libraries is a breeze: simply drop the library .jar file inside the web application, restart Confluence, and your new macros will appear in the management console. Confluence 1.1 also includes a custom macro toolkit (with Task List example shown below) to help users build their own complex macros easily using Java. Cannot resolve external resource into attachment. More information: • [DOC:Macro Management] - a guide to the Macro Management console

Document generated by Confluence on Oct 10, 2007 11:54

Page 562

• DOC:User Macros - how to write User Macros • [DOC:Custom Java Macros] - a guide (and worked example) for writing and distributing your own Java macros for Confluence Attachments: versioning, comments and WebDAV support Versioning - The number one feature request for Confluence 1.0 was versioned attachments. You ask, we deliver! Confluence can now have multiple versions of the same file attached to a page. It will keep a history of different versions of attachments, expandable dynamically. Comments - Each attachment can now be accompanied with a comment describing why it is there, what it's about or the reason for it being attached. This is useful for tracking the differences between attachment versions, as well as for informing users as to why they should be interested in a particular file. Cannot resolve external resource into attachment. WebDAV - You can configure Confluence to store attachments in an external WebDAV server. This allows companies with an existing WebDAV infrastructure to give users alternative ways of accessing attachments and attaching files to Confluence pages. Improvements to Page and Space Exports • Exporting pages and spaces to PDF should be a great deal more reliable now. Whereas in Confluence 1.0, the export was likely to fail if the pages contained questionable markup, we now dynamically clean up each page before we export it. • You can choose whether or not page comments are exported. Often you want to exclude comments if you want to send out a PDF of a page or publish a space as a website. • The templates used to publish pages and spaces to HTML can be customised on a global and perspace basis. This makes it easy to publish a static website from the contents of a Confluence space: customise your templates, choose which pages to export, and voila. Customise Display of Blog Posts The templates used to display blog posts (both individually and in lists) can be edited either globally, or on a per-space basis, in the same way as the site's main decorators are editable. Also, the interface for editing templates has improved and will continue to do so in future releases. Page Locking If you want to prevent another user from editing, deleting or renaming a page, you can now lock it. You may want to do this because certain pages in an otherwise public space (for example, front pages, disclaimers or copyright notices) must remain un-edited, or just because you're working on the page and don't want anyone else to interfere just yet. Locking a page restricts editing to a single user (yourself), or members of a particular group. Anyone with the space administrative permission can override or delete a lock. Oracle and Weblogic Support We have made a concerted attack on the various issues that were making Confluence unreliable on Oracle and Weblogic, and we're pleased to report that both have been running just fine in testing. Most importantly, the bug that was preventing pages being saved to Oracle when they were over 4Kb in length has been fixed. For details of what precisely was fixed, see: • The Weblogic support super-issue in JIRA • The Oracle support super-issue in JIRA

Document generated by Confluence on Oct 10, 2007 11:54

Page 563

Search Powerpoint and Excel Attachments Confluence already searches across attached Word, PDF and RTF documents, XML, HTML and any plain text file. This search support has now been expanded in Nymboida to include searching and indexing of all text within Microsoft Powerpoint presentations and Excel spreadsheets. In addition, the new attachment comments are also searchable. TinyURL Every page has a unique, short URL displayed at the top of its Page Information page. This makes it easier to send colleague's the URLs for pages with long titles via email, instant message or IRC.

New and Improved Macros
New • {excerpt} allows you to mark a portion of the page as its "excerpt". This has no effect on the page itself, but other macros (such as {blog-posts} and {children}) can use the excerpt as a short summary of the content of the page. • {excerpt-include} includes one page's excerpt in another page. Improved • {code} macro supports coloured highlighting for several more languages: JavaScript, ActionScript, XML and SQL. • {code} macro can have its title and border customised in the same way as the {panel} macro • {blog-posts} takes an optional time parameter to indicate how far back it should look for blog posts. For example, {blog-posts:time=7d} will show all blog-posts within the last seven days • {blog-posts} takes an optional content parameter to change the way the blog-posts are displayed. content=excerpts displays excerpts instead of the full content of the blog entry (using the {excerpt} macro if available, otherwise extracting the first few hundred characters of the post). content=titles displays the entries as a list of titles. • {children} takes an optional excerpts=true parameter: if any of the children have an excerpt available, the first line will be displayed in the list.

Improvements
Improvements to the Markup Engine Many improvements have been made to the Confluence markup parser, fixing niggling inconsistencies, and allowing many more combinations of effects. If you want to produce something like the following, you can:

Name Some code

Value
publicstatic void main(String[] args) { System.out.println("Hello World"); }

A list

• • • •

Item Item Item Item

1 2 3 4

A panel I like cheese

Document generated by Confluence on Oct 10, 2007 11:54

Page 564

• • • •

Brie Camembert Gruyere Cheddar

You can also center an image using !image.gif|align=center! Improvements to Linking • You can specify a link title (which appears in the mouse-over tooltip) by adding another section to the link: [Link Body Text|Page Name|Link Title] • [//foo/bar/baz.html] will create a relative URL link to /foo/bar/baz.html on the same server as Confluence is running • file: URL links work • UNC-style links: [\\SERVER\share\directory\file.doc] will create a file:// link to the file on an external share Note: Some web browsers (specifically Mozilla) consider file: URLs to be a security hazard, and do not follow them. And a whole lot more... Here's the quick fire version of some of the other improvements we've made in this release: • You can resize the recent changes lists on the dashboard and space summary pages. This change is persisted in your user preferences. • UI state (whether comments or attachments are open, size of recent changes lists) persists between sessions for registered users. • The maximum attachment size can be configured from the General Configuration administration page. • Going to http://yoursite.example.com/display now brings up a list of spaces instead of an error page. • The display of the space summary page is significantly faster. • Newly created users don't show up on the dashboard recent changes list unless they edit their profiles. • The word "Confluence" has been moved to the end of page titles instead of the beginning, making them easier to distinguish in tabs and bookmarks. • There are more ways to navigate to the "recent blog posts" page for a space. • Removing a user is significantly faster. • Headings in pages are automatically turned into anchors with the same name. • Creating a space now creates an index page as well as a home-page.

Notable Bug-fixes
It's hard to know where to start. We've fixed a lot of bugs across the whole application. If you want to know what's been fixed, you're probably best off looking for yourself. Two areas, however, have been improved enough to deserve special mention. • PDF Export - as mentioned above, we've made the PDF export much, much more reliable than it once was. Where before a page or space may have confused the PDF converter into not working, it should now be able to handle any markup you throw up at it. • International characters - Many issues related to the use of non-ASCII characters in page titles, links, page contents and RSS feeds have been resolved since Confluence 1.0. Our users in nonEnglish-speaking countries should find Confluence a much more pleasant and seamless experience now than they may have before.

Document generated by Confluence on Oct 10, 2007 11:54

Page 565

Issues Resolved for 1.1
This page last changed on Jun 09, 2004 by cmiller.

Atlassian JIRA(208 issues) T Key CONF-1067 Summary Documentation for Confluence Integration with Active Directory Rev atlassianconfluence-extras to 1.1 in project.xml Document 1.1 macro packaging and creation Mark 1.0 as a Released Version in jira.atlassian.com Merge 1.0.x branch changes into HEAD Document how to use LDAP authentication in Jira Upgrade FatCow to be shipped as a 1.1 macro library Attachment Improvements Test PDF export! Weblogic Support Syntax Highlighting for Java Script and Action Script creating links within tables Customise HTML export templates per-space Ability to put a description next to an attachment and rename Attachment versioning Get Blog posts via XML-RPC? Lock Pages and/or sub pages Choose whether comments get exported or not Center/middle alignment on images - how? Resize "recent changes" list in dashboard and space summary page Excerpt macro Status FIXED Closed Res

CONF-956 CONF-1255 CONF-978 CONF-1132 CONF-935 CONF-1254 CONF-1235 CONF-1258 CONF-1230 CONF-893 CONF-1081 CONF-1151 CONF-614

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed CANNOT Closed REPRODUCE DUPLICATE Closed FIXED Closed

CONF-527 CONF-1712 CONF-660 CONF-1150 CONF-1218 CONF-1220

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-1263 CONF-430

FIXED Closed FIXED

Document generated by Confluence on Oct 10, 2007 11:54

Page 566

CONF-1307 CONF-608 CONF-1184 CONF-834 CONF-1213 CONF-794 CONF-1211 CONF-802 CONF-968 CONF-1178 CONF-1262 CONF-1308 CONF-1183 CONF-952 CONF-1141 CONF-867

Template for exporting space / page Add comments to a Blog Customise look and feel of blog posts Weblogic support longer list of page updates Support UNC path linking syntax Configurable permissions for Recent Changes Enhance blog-posts macro to expire old blog posts from view WebDAV access to attachments Custom Defined Macro's Macro Enable / Disable switches Blog titles macro Build custom macro builder toolkit Oracle Support Tiny URL support for Pages Confusing page titles Ask if you want to overwrite if attaching file with same name as existing attachment Wiki markup guide doesn't describe named links Headings should automatically generate anchors Rename templates Syntax Highlighting for XML {code} macro Hide "add comments" text box on print preview Have the || table markup allow multi line cells add title parameter to links ( hrefs ) Make /display and / display/ aliases for / listspaces.action Improve links Timestamps on attachments

Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed WON'T FIX Closed

CONF-1032 CONF-712 CONF-692 CONF-892 CONF-1047 CONF-1035 CONF-606 CONF-1086 CONF-402 CONF-907

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 567

CONF-929 CONF-1192

CONF-1303 CONF-1127 CONF-827 CONF-1286 CONF-1257 CONF-1226

CONF-879 CONF-845 CONF-1154 CONF-1015 CONF-1208

CONF-1185

CONF-1051 CONF-694 CONF-1267 CONF-1187

CONF-1275

CONF-1266 CONF-1288

White Space above a h1. header Fix any possible wiki redering/exporting flaws caused by invalid HTML, by applying JTidy Trim length of outgoing links so they don't overflow Remember UI state across sessions Border around comments Make Excel spreadsheets searchable Index attachment comment Change number of entries in Dashboard:"Recently Updated" Customisable Maximum Attachment Size Creating a space should create an index page Allow linking to files on shared network drives Remote renderContent() method bugs Add ability to start a numbered list at a specific starting value Only "view page" links should go by page title, rest by page ID Need icon to decorate attachment links Blog Management missing in API Make blog display use inline decorators Improve error message for trying to remove yourself from admin group Dashboard recent updates lists irrelevant personal information entities Add more links to the recent blog posts page Make PowerPoint presentations searchable

FIXED Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed WON'T FIX Closed

FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed

FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 568

CONF-1274 CONF-1250

CONF-1224 CONF-962 CONF-1064 CONF-1144 CONF-1232 CONF-884 CONF-1108 CONF-1259 CONF-1256 CONF-1122 CONF-2078 CONF-945

Allow user macros to be deleted Edit page and edit blog post links should use page id rather than page title Allow caption to be specified in {code} macro Recent updates list for space is very slow Rewrite wiki -> link transformation code Removing a user is very slow State attachment file name on "delete attachment" dialog Shortcuts pages needs minor reworking how to create relative site hrefs? Buttons at top and bottom Add brief descriptions for all existing macros User can import pages from arbitrary directories Add tiny URL support Unrecognised macro {Weblog} created on start page by snipsnap import Improper link processing when CamelCase link style is turned on PDF export does not maintain spaces between links Emoticon filter kills page-rendering performance parent page info lost after choosing a template Page(link) creation process & the invalid characters in page title! Mixed # and * items do not render correctly Viewing profile of a user with no blog posts logs an NPE Unable to link to URL's with single

FIXED Closed DUPLICATE Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed

CONF-926

FIXED Closed

CONF-793 CONF-963 CONF-1044 CONF-810

FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed

CONF-1039 CONF-1058 CONF-1036

FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 569

CONF-1071 CONF-1042 CONF-1084 CONF-1102 CONF-816 CONF-1103

CONF-1001 CONF-997 CONF-1098 CONF-1066 CONF-1142 CONF-1128 CONF-1169 CONF-1097 CONF-1165 CONF-1124 CONF-1125 CONF-859 CONF-1149 CONF-1157 CONF-992 CONF-1182 CONF-1190 CONF-1175

quote's as they are escaped Text -format email notifications are HTML-formatted Export to PDF throws following exception Disabled users still get updates email Deactivated users show up in manage users Exporting page with {children:all=true} breaks PDF export Deactivated users should not show up in the add permissions page PDF export removes newlines in {noformat} panel macro display incorrect border Possible to add page names in the errors? {children:depth=2} can generate a "create page" link Can't generate hrefs to IRC Titled links to attachments display filename instead {include} macro fails with quotes unescaped ampersands kill PDF export PDF export throws exception MethodInvocationException thrown during space export ImportExportException during space PDF export Lists not functioning inside of a Table No easy way to insert literal \\ noformat inside tables {html-include} not being process before a table is outputted back ticks cause line breaks in lists Export to PDF dies due to ampersand Write XML with spetial symbols: &, <, >, etc

FIXED Closed FIXED Closed FIXED Closed FIXED Closed CANNOT Closed REPRODUCE FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed DUPLICATE Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 570

CONF-1194 CONF-1094 CONF-1013 CONF-1030 CONF-1301 CONF-1317 CONF-778 CONF-970 CONF-1323 CONF-1229 CONF-995 CONF-1242 CONF-1236

List items ending with a tab misrender UTF-8 characters (russians at least) breaks the table High unicode characters not displaying properly code macro is totally screwed up when exported as PDF Create-this-page links aren't being stored rss not well formed error New remote API methods are not documented Unable to export to PDF on Linux server VM Error when the page title contains Chinese words Link names not showing up for attachments Export cleanup JIRA issue macro fails on certain URL Chinese characters garbled under Resin and Tomcat due to sitemesh bug File name with non us characters Trackbacks seem to be being added multiple times KeyFactory provider still hardcoded to "SUN" Regression: Next/ Prev entry blog links still displayed on first/last blog New installation on Oracle 9i, errors in log Create links pass potential parents between spaces RSS feed has a ) in link Deploy to weblogic as a war causes load resrouce to fail Creating a child page with a template loses parent information

FIXED Closed FIXED Closed INVALID Closed FIXED Closed INVALID Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed

CONF-976 CONF-842 CONF-1199 CONF-1139

FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-1027 CONF-1244 CONF-981 CONF-949 CONF-911

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 571

CONF-1313 CONF-1289 CONF-1079 CONF-1188 CONF-1037 CONF-1050

CONF-964 CONF-1243 CONF-942 CONF-959

CONF-1277

CONF-1283 CONF-780 CONF-1247 CONF-795

CONF-1201

CONF-1012 CONF-1270 CONF-1174 CONF-979

Another strange problem editing pages getActiveUsers loads property set for Every Single USer korean language title link problem Apache XML-RPC library blows up on high-bit chars Errors with database - can not save in Oracle Changing server path does not change path in internal links subsequent ampersands not rendered as entities Need a safe way to make "Create" links for high-bit pages os_propertyentry table getting out of sync with os_user Search results on user with no personal info results in visible velocity crap Create page with template may have problems if parent page has non-ASCII title Renaming attachments screen is incorrect Confirming user deactivation takes forever? Confluence Crash on selecting Profile Signing up creates user profile page with Anonymous editor NPE when clicking on the previous versions link when viewing v.1 of a page NPE in Page template wizard Form templates don't work any more Shouldn't need to escape things inside {code} Snipsnap Import Fails

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed CANNOT Closed REPRODUCE

FIXED Closed

FIXED Closed FIXED Closed FIXED Closed WON'T FIX Closed

CANNOT Closed REPRODUCE

CANNOT Closed REPRODUCE FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 572

CONF-1173 CONF-1180 CONF-1181 CONF-1059 CONF-975 CONF-1268

CONF-1191 CONF-1152 CONF-898 CONF-951 CONF-1048 CONF-1056

CONF-1168 CONF-877 CONF-1204 CONF-1216 CONF-971 CONF-818 CONF-1078 CONF-1167 CONF-1117 CONF-1046 CONF-1709 CONF-1148 CONF-1219

Setup steps don't check any more Cannot delete page with accent in title Parse exception in jiraissues Nested lists break PDF export (smart quotes) Linking and non-us characters Can not rename page when it has links from a user profile Export to XML dies due to ampersand Duplicate pages with same name Cannot create pages with () in title page names ending is space are not properly linked List items, panels and code:xml conflict Attachments with irregular characters (commons, pounds, spaces) fail to download NullPointerException in LinkManager when renaming page Email search is casesensitive Multiple indexes in same DB column Export space problem Stream type cannot be used in batching Hibernate lazy instantiation problem (in Oracle) RSS Feed Error Backups created on Windows can't restore on Unix. Restore from Backup Zip file cannot over 20+M bytes.. Missing text keys New Links resolve to different project Some page-related views fail on a renamed page Confluence: The title you have entered contains invalid

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

DUPLICATE Closed CANNOT Closed REPRODUCE FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 573

CONF-1306 CONF-569 CONF-1319

CONF-1300 CONF-1011 CONF-1018

CONF-1278 CONF-1316 CONF-1310 CONF-1233

CONF-1116 CONF-1170 CONF-1325 CONF-927 CONF-1089 CONF-993 CONF-1074 CONF-822 CONF-1197 CONF-1126

CONF-1320

characters (...) (question mark) IE browser bug on 'page does not exist' page cannot use latin characters in page title Save of blog comment breaks when preview is done first. Watch this page without being logged-in Export to PDF stack trace Wiki outgoing links are incorrectly reported (false positive) Tables containing form fields are messed up not permitted to view previous versions of page Cannot remove page with problematic titles FileNotFoundException for defaultformatting.properties on weblogic restart Potential Race condition Log4j.properties not being recognized in weblogic Wrong URL in daily summary Blogging Varies in Output depending on Link Results of getPermissions are inccorect Lose Parent page when selecting a template Can not setup the embedded database! Error adding child pages on Oracle New line code (\\) around images not working in 1.0.3 ImportExportException caused by ClassCastException when doing Export Space as XML Error drawing panel

FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 574

CONF-1312

CONF-1280 CONF-1010 CONF-1284

CONF-888

Problem linking to an attachment whose name contains a special character Search macro results are borked Space-level custom printable decorator broken Link in format [my link name| pagename^attachment.ext] shows attachment.ext Trackbacks are not sent for shortcut links

FIXED Closed

FIXED Closed FIXED Closed FIXED Closed

FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 575

Release Notes 1.1.1
This page last changed on Jun 21, 2004 by jnolen.

Confluence 1.1.1 is a maintenance release that fixes some bugs regarding attachments, page links and notifications. Remember, a Confluence license entitles you to a year of upgrades, and this upgrade along with future updates will be free of charge. Who should upgrade? This release mainly fixes the bugs discovered in our recent 1.1 release. The major issues resolved are listed below, or you can see the full list here. As some of the issues resolved have a significant impact on the user experience of Confluence, we recommend that anyone currently running 1.1 upgrade to 1.1.1. Upgrade Procedure 1. Shut down the Confluence server 2. Back up confluence/WEB-INF/classes/confluence-init.properties, and if you have customised it, confluence/WEB-INF/classes/osuser.xml 3. Unpack Confluence 1.1.1 in the same location as your existing Confluence installation 4. Restore the two files you backed up in step 1 to the 1.1.1 installation. 5. Start Confluence To avoid the possibility of data-loss, you should back up your ConfluenceHome directory and your database before upgrading, and perform a full backup from within the application. Changes in 1.1.1 Attachment fixes • Attachment versioning introduced a new table in Confluence that had a column whose name conflicted with some databases like Sybase • Links to older version of attachments could not be accessed if the webapp was deployed with a context path • Attaching files that contained '+' and '&' symbols caused certain pages in Confluence to break These have been fixed in 1.1.1. Notification fixes Users opting to receive html formatted email received emails with the correct subject but no content. In addition, the "View Changes" link in the daily change email was broken. These are now fixed. Email Server fixes An upgrade to an email component used in Confluence in 1.1, caused an error to be displayed when users attempted to modify their email server settings. An upgrade has been added in 1.1.1 that will fix this problem to save users from having to perform the fix manually. Export to PDF fix Spaces labelled with names containing an '&' symbol could not be exported to PDF. This has been fixed. Wiki Notation fix The notation for a horizontal ruler was changed to five dashes (up from 4) in 1.1. This stopped the ruler from showing. This has been changed back in 1.1.1.

Document generated by Confluence on Oct 10, 2007 11:54

Page 576

Issues Resolved for 1.1.1
This page last changed on Jun 18, 2004 by jnolen.

Atlassian JIRA(25 issues) T Key CONF-1391 CONF-1384 CONF-1358 Summary Old versions of pages appear when you reindex Redirect sometimes faster than previous txn commit "VERSION" is a reserved word in a lot of databases (Attachment table Confluence 1.1 Installation wizard step 7 System Error Restore exception: Bad SQL grammar [null] in task 'HibernateAccessor' ClobStringType requires active transaction sync exception Problem afer Upgrade from 1.0.3 to 1.1 WAR release has wrong readme.txt etc Url containing CamelCase words are not parsed properly Mail Queued problem .sh files in the standalone release aren't executable URL for the nontip version of an attachment is incorrect Notifications are missing content Crash at creating new group SEVERE Ognl exception in server logs Wrong interaction between include and children macros Restore just spins when file access is denied and attachment directories cannot be restored Status FIXED Closed FIXED Closed FIXED Closed Res

CONF-1344 CONF-1342

FIXED Closed FIXED Closed

CONF-1341

FIXED Closed

CONF-1386 CONF-1343 CONF-1340

FIXED Closed FIXED Closed FIXED Closed

CONF-1510 CONF-1388 CONF-1387

FIXED Closed FIXED Closed DUPLICATE Closed

CONF-1382 CONF-1380 CONF-1377 CONF-1365 CONF-1362

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-1361

FIXED

Document generated by Confluence on Oct 10, 2007 11:54

Page 577

CONF-1357 CONF-1356 CONF-1352

CONF-1349 CONF-1346

CONF-1345 CONF-1335

Using Ampersand (&) in Space names breaks PDF export Incorrect title is passed when page is created from the link Reset Default Colour Scheme Attachments with plus sign in file name cause an NPE when loaded Links to attachments includes the ^ symbol No such setting:webwork.ui.templateDir - When confluence is root web app Moving page with linked attachment horizontal ruler notation broken

Closed FIXED Closed FIXED Closed FIXED Closed

FIXED Closed FIXED Closed

FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 578

Release Notes 1.1.2
This page last changed on Jun 30, 2006 by david.soul@atlassian.com.

This fixes an upgrade problem in 1.1.1 where users attemtping to upgrade from 1.0.x directly to 1.1.1 encountered an "Upgrade Failed" error. Therefore, if you are still using a version older than 1.1, and am planning to upgrade, please upgrade to 1.1.2 to avoid this problem. If you have already upgraded to 1.1.1 from 1.0.3a and cannot start Confluence due to the upgrade error, simply download 1.1.2 and upgrade to it. This should fix the problem. If you have already upgraded successfully to 1.1.1 from 1.1 then you may safely ignore this upgrade.

Useful tips when upgrading from 1.0.3a
Upgrading Confluence should be pretty easy: you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! • Users who have enabled external user-management by customising their osuser.xml file will need to read this document also. • Users who have used MySQL or Postgresql with Confluence 1.0 should read this document which explains how to get rid of any extraneous triggers or indexes that might have been created.

Document generated by Confluence on Oct 10, 2007 11:54

Page 579

Release Notes 1.2
This page last changed on Jun 18, 2007 by rosie@atlassian.com.

Atlassian is proud to present Confluence 1.2, otherwise known as Swan, to the world. Existing customers who wish to upgrade, or new users who wish to try out Confluence for 30 days can download either the standalone or WAR distributions from the Atlassian website: http://www.atlassian.com/software/ confluence Swan is the second major update to Confluence, and once again all existing customers can upgrade for free, thanks to the provision for one year of free upgrades in your license. You will find that Swan contains significant new features in the areas of user management, search and space browsing, as well as the usual raft of enhancements, bug fixes and things we just couldn't resist throwing in at the last minute. In all, 109 issues were resolved between 1.1.2 and 1.2. You can see the full list here: DOC:Issues Resolved for 1.2 Looking towards the future, we are going to attempt to increase the frequency of releases. While having one release every three months makes for impressively long release notes, it also means that customers are often left waiting longer than might be necessary for important enhancements or bug-fixes.

Upgrading from 1.1.2
Upgrading Confluence should be pretty easy: you can find instructions here. We strongly recommend that you backup your confluence.home directory and database before upgrading! You will need to reindex your site after upgrading to enable some of the new site search features. You can do this from the "Rebuild Search Index" link on the Administration Console. Site administrators upgrading from 1.1.2 or earlier should take particular note of the changes to global and space permissions. Confluence should automatically upgrade old permissions to the new scheme when upgrading from or importing data from earlier versions, but it is a good idea to check that your spaces are still secure and accessible after the upgrade, just in case.

Upgrading from 1.0.3a
Users upgrading directly from 1.0.3a should also read the Nymboida Release Notes for caveats regarding the 1.0 -> 1.1 upgrade.

Contents
1. New Features 2. Improvements 3. Notable Bug-fixes See also: DOC:Issues Resolved for 1.1

New Features
Page List Views

The old "list pages" screen has been enhanced, almost to the point of being unrecogniseable. In its place, we now offer three ways to browse the contents of a space. The Alphabetical View looks like the "list pages" screen from 1.1 and earlier, but it has been enhanced to allow you to find pages quickly by the first letter of their title.

Document generated by Confluence on Oct 10, 2007 11:54

Page 580

The Directory View presents the contents of a space as a tree, allowing you to drill down the hierarchy of parent and child pages (You will need Javascript turned on to use this view). The Search View presents Swan's enhanced search interface, already focused on the space you are looking at. Image Thumbnails and Thumbnail Galleries

You can now display a thumbnail of any image attached to a page. Clicking on the thumbnail will pop up a window containing the full-sized image. For example, the nice picture of the waterfall from my holiday in California was generated by the following wiki-markup.
!waterfall.jpg|align=right thumbnail!

In addition, the {gallery} macro will create a thumbnail gallery of all the images that are attached to the page the macro is included in. You can see an example of this macro in action here: Thumbnail and Gallery Example. The maximum sizes for thumbnails are configured in the General Configuration section of the Administrative Console. Threaded Comments Bowing to public demand, we have added the ability to arrange comments by thread: users may respond to a particular comment, and the comments will be arranged in accordance with who responded to what. The default is still for comments to be presented as a flat list, but you can enable comment-threading in the General Configuration section of the Administrative Console.

Document generated by Confluence on Oct 10, 2007 11:54

Page 581

Improvements
Enhanced Search

The site-search functionality of Confluence has been enhanced, both subtly behind the scenes, and quite obviously in front of them. Behind the scenes, we now index more information such as attachment comments and filenames. We have improved the indexing of Powerpoint presentations so that more text is extracted from the Powerpoint file. We have also tweaked the ranking algorithms behind the search so that you are more likely to find the page (space, comment, blog post, attachment, user...) you are looking for. More obviously, we have given the user a lot more control over searching with an intuitive user interface that allows you to limit searches by space, type of content, or date last modified, and to group search results by type and space. The {search} macro has also been updated to take advantage of the new search features (the options are described more fully in the notation guide linked from Confluence's edit page):
{search:query=Confluence|maxLimit=5|spacekey=DISC|type=page}

Document generated by Confluence on Oct 10, 2007 11:54

Page 582

New Permissions Interface

Two of the biggest issues users have been having with permissions in Confluence were: • The interface for setting permissions was confusing. • It was hard to keep sites that allowed anonymous access below the workgroup license 25-user limit, especially if they used external user management. Both of these issues have been fixed in Swan, but it has involved a slight change in the way permissions are checked. This should not be a problem for new Confluence users: the new system is easier to use than the old,. However, if you are upgrading from 1.1.2 or earlier, you should read this document to see what's different. And a whole lot more... Here's the quick fire version of some of the other improvements we've made in this release: • The "double-click to edit" feature has been removed. • Blog views now come with a monthly calendar showing nearby posts • Macro libraries can now include images, or any other content the macro needs to serve over the web: look out for new example code in the [macro documentation] soon. • Users can set their profile page to be their site homepage • You can delete all referrer links that match your exclusion list (in General Configuration), to rid the site of referrer spam • The site's administrative, search and editing pages are served with robots exclusion meta tags so that only the site's main content will be indexed by well-behaved search engines • Restoring backups should be significantly faster for installations with many users • Administrators can choose to restore backups from the filesystem instead of uploading them (important if your backup is quite large) • Confluence now serves files with a proper Content-Length header, so browsers can display the download accurately • CSS stylesheets are hidden in emails so they don't mess up Lotus Notes • Export and backup filenames use a neater yyyymmdd date format

Notable Bug-fixes
• Exports created on Windows can now be imported on Unix-like operating systems without having to fix the path separators • Hyphens in page headings or anchors will no longer render strangely • Restoring a backup during setup now properly generates the search indexes • Page "short links" now respect the configured site URL, regardless of which URL the user is accessing the site from • Strange Powerpoint files no longer choke the indexer • Users with Admin privileges can now see the link to the Administration Console without being in the 'confluence-administrators' superuser group • Space administrators can modify space templates without having global administrator privileges. • User macros are now lower-cased by default • It is now possible to change the case of a page title by renaming the page

Document generated by Confluence on Oct 10, 2007 11:54

Page 583

Issues Resolved for 1.2
This page last changed on Aug 23, 2004 by cmiller.

Atlassian JIRA(117 issues) T Key CONF-1264 CONF-1393 CONF-1442 Summary BOB: Run functional tests against Weblogic Upgrade libraries Use atlassian core's thread appender instead of confluence's Allow import/restore from server local filesystem Inline image attachment as thumbnail Gallery Page Macro Calendar for blog posts "View in hierarchy" link from a page Option to scope searching Improve threaded comments L&F Improve Administration Setup Paths page Add "Hide Comments" link when comments are shown Incorrect number of licensed users displayed Revisit UI for adding permissions Email template fix for Lotus Notes 6.5 Change backup filenames to 2004-06-29 format Zipped exports created on a Windows Confluence instance are not platformindependent Put NOINDEX NOARCHIVE tags on adminstrative and search actions Warn if adding a space permission to user without USECONFLUENCE permission Status FIXED Closed FIXED Closed FIXED Closed Res

CONF-1130 CONF-784 CONF-785 CONF-765 CONF-1539 CONF-1497 CONF-1695 CONF-1668 CONF-1490

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed FIXED Closed

CONF-1529 CONF-817 CONF-1676 CONF-1477 CONF-1658

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed

CONF-1163

FIXED Closed

CONF-665

FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 584

CONF-1239 CONF-1408 CONF-1487 CONF-1359 CONF-1196 CONF-1588 CONF-961 CONF-1376 CONF-809 CONF-480 CONF-1260 CONF-1447 CONF-886 CONF-1491 CONF-985 CONF-957 CONF-1564

Ability to clear Referrers Restoration process take a long time updating indexes Alphabetical, Directory and Search views for page listing Improve search Add App Specific Exceptions to Remote API FileServerServlet doesn't serve file sizes Add "my profile" to the list of a user's available homepages Allow macro libraries to include webserved resources Scope-base searches (on-site and via {search} macro)! Alphabet links in paged search results / page links DHTML spaces control Index attachment names Hierarchy view as proper treeview Double-click to edit page feature unintuitive Threaded Comments

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed DUPLICATE Closed FIXED Closed FIXED Closed

CONF-1682 CONF-1692 CONF-1617 CONF-1486 CONF-1524 CONF-1392 CONF-1501 CONF-1423

Quick Search should notice if you've typed in a page title ClobStringType FIXED Closed requires active transaction synchronization Space keys are FIXED Closed alphanumeric, not ASCII Update Page fails in DUPLICATE Closed MailNotificationQueueItem.createFromTemplateFile Couldn't restore FIXED Closed directory from backup error i18n title shows up FIXED Closed as hashes when exporting to PDF Hyphen in Blog text FIXED Closed causes corruption. Import on initial FIXED Closed setup doesn't index Rebuilding Search FIXED Closed Index take forever View mail servers FIXED Closed doesn't show From

Document generated by Confluence on Oct 10, 2007 11:54

Page 585

CONF-1612 CONF-1508 CONF-1292 CONF-1536 CONF-1548 CONF-1419 CONF-1659 CONF-1045

CONF-1666 CONF-1426 CONF-1471 CONF-1696 CONF-1701 CONF-1430 CONF-1690 CONF-1121 CONF-1684 CONF-1582 CONF-1440 CONF-1454 CONF-1407 CONF-1441

address, but Edit operation does. Brackets "()" break rendering of headings Very long headings render bad anchor tag Mail queue not updated with queued notification items template.not.found i8n message missing User History page with velocity bug? Dates in a heading are not rendered correctly Anchor links don't work in exported PDF's Exports performed on Windows may have \ as path separator in zip Deleting a group should delete that group's permissions Please remove the double-click-startsediting feature Broken links in 'Confluence Notation Guide' Must-fixes for search Gallery macro prints $thumb.attachment.comment under all thumbnails Children macro choking on dashes in page names Bad URL for "edit space homepage" in space created screen Changing a word in a page shows wrong diff Attachment search fails when limited by space Links not rendered correctly using Remote render Confluence still doesn't clean the temp directory h3 element rendering junk Headers with Certain Characters Special Caracters in headers do not render properly

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed WON'T FIX Closed FIXED Closed FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 586

CONF-1599 CONF-1630

CONF-1519 CONF-1550

CONF-1515

CONF-1691 CONF-1533 CONF-1681

CONF-1326 CONF-1249 CONF-1574 CONF-1593 CONF-1417

CONF-1205

CONF-1710 CONF-1492 CONF-1403 CONF-1439 CONF-1431 CONF-1615 CONF-1432 CONF-1369

Children macro FIXED Closed chokes on minus characters View space FIXED Closed permission description wrongly says that a user can edit a page page anchor links FIXED Closed break Page Information: CANNOT Closed Incorrect Short URL REPRODUCE if webapp context is not "/" Special german FIXED Closed characters (ä ö ü) not being exported to PDF properly $generalUtil.formatDateTime($page.lastModificationDage) FIXED Closed showing up all over the place PowerPoint search FIXED Closed not working (example included) Only confluence FIXED Closed admins can add and modify templates (space or global) Can't change mail FIXED Closed format of daily summary messages. Zip file creation FIXED Closed problems Using % in page title FIXED Closed causes error java.lang.ClassNotFoundException: FIXED Closed weblogic.jdbc.extensions.WLConnection jiraissues macro CANNOT Closed ignores the first REPRODUCE entry in the colums parameter Search results FIXED Closed for velocity get truncated on wiki.opensymphony.com Upgrade failed: Can't FIXED Closed call commit when autocommit=true "short link" not FIXED Closed respecting site URL Date formats of FIXED Closed jiraissues macro TXT daily summary DUPLICATE Closed generate raw HTML Error commenting RESOLVED LOCALLY Closed Blog user suddenly FIXED Closed gets system error messages InfrastructureException RESOLVED LOCALLY Closed after update Error when export FIXED Closed page as PDF

Document generated by Confluence on Oct 10, 2007 11:54

Page 587

CONF-1480 CONF-1420

CONF-1579 CONF-1418 CONF-1428 CONF-1445 CONF-1252

CONF-1663 CONF-1645

URL returned from search is incorrect for attachements Bulleted list items from JSPWiki not converted when no space after * Exception when attaching a file Spaces in File links not preserved on Wiki Export cannot set page with unicode characters in title as parent page Icons don't get exported in PDFs (Confluence Changes in the last 24 hours) has incorrect link to edit profile A small error in the {excerptinclude} macro is documented with the wrong syntax Display of paragraphs in comment blocks not consistent Random PermissionCheckDispatcher crashes when viewing pages User Macros with upper-case characters ignored Administrate tab only shows if user is in confluenceadmininstrators Importing into Swan seems to wipe space permissions Export space (html) fails, if attached image missing Use of quotes in page name brings issues with it java.lang.IllegalAccessError on PDF Export rename page bug "Restore Page" restores entire confluence? Non-administrator users can perfrom some admin tasks Empty error queue message incorrect Wrong number of licensed users

FIXED Closed FIXED Closed

FIXED Closed FIXED Closed FIXED Closed FIXED Resolved FIXED Closed

FIXED Closed FIXED Closed

CONF-1468

FIXED Closed

CONF-1350

FIXED Closed

CONF-1512 CONF-1650

FIXED Closed FIXED Closed

CONF-1673 CONF-1269 CONF-1146 CONF-1677 CONF-1452 CONF-1549 CONF-1507 CONF-1404 CONF-1499

FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed FIXED Closed DUPLICATE Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 588

CONF-1228

CONF-1662 CONF-1443

CONF-1459 CONF-1535

CONF-1699 CONF-1401

reported when anonymous access enabled Granting "anyone" use permission breaks with JIRA user management NPE in Mail notification On doubleclick inside Add Comment editor new page is loaded and comment is lost Special characters in "search" result in various problems Nullpointer exception on updating a page that is being watched by a new user Entering "*" as search string causes error. Wrong document tree in exported PDF files

DUPLICATE Closed

DUPLICATE Closed FIXED Closed

WON'T FIX Closed FIXED Closed

FIXED Closed FIXED Closed

Document generated by Confluence on Oct 10, 2007 11:54

Page 589

Permissions Changes in 1.2
This page last changed on Aug 23, 2004 by cmiller.

For Swan, changes were made to the way Confluence manages and checks permissions. This document is a guide for anyone migrating from Confluence 1.1.2 or earlier describing why the changes were made, and what this means to existing Confluence installations.

Why Change?
There were two goals behind changing permissions in Confluence: 1. Fix a significant problem whereby users with external user management enabled could not also enable Confluence anonymous access without blowing out their 25-user workgroup license. 2. Make the user interface for assigning and viewing permissions easier to use and understand.

What Changed?
"Anyone" User Removed In Confluence 1.1.3, there was an "Anyone" user, who represented anyone using the system, whether logged in or not. This user was the source of the licensing problem, and no longer exists in Confluence 1.2 Anonymous Permissions Added Confluence 1.2 has explicit permissions for anonymous users. These permissions are only granted to users who are not logged in. There is nothing stopping an administrator granting some permission to anonymous users, but not granting it to logged-in users. This results in the slightly bizarre possibility that a user might be able to do more before logging in than they can after. Luckily, this is a pretty easy situation for administrators to avoid. Enabling anonymous access has no effect on Confluence's user count for licensing purposes. Guard Permissions Added The roles of the "Use Co