Professional Documents
Culture Documents
4
Confluence 6.4 documentation 2
Contents
Confluence Server documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Get started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Tutorial: Navigate Confluence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
The space directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
The space sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Complete your mission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Tutorial: Space ace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Create a project space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Create your personal space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Create the team's PR space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Delete and archive spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Create a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Create a Space From a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Space Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Navigate Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Space Permissions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Assign Space Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Make a Space Public . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Give Access to Unlicensed Users from JIRA Service Desk . . . . . . . . . . . . . . . . . . . . 34
Organize your Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Set up a Space Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Use Labels to Categorize Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Customize your Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configure the Sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Edit a Space's Color Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Apply a Theme to a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Documentation theme migration FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Customize Space Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Archive a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Delete a Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Export Content to Word, PDF, HTML and XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Customize Exports to PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Advanced PDF Export Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Create a PDF in Another Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Pages and blogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Create and Edit Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Blog Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
The Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Symbols, Emoticons and Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Collaborative editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Move and Reorder Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Copy a Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Delete or Restore a Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Add, Remove and Search for Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Display Pages with Label Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Drafts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Concurrent Editing and Merging Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Page Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Anchors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Add, Assign, and View Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Autocomplete for links, files, macros and mentions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 3
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 4
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 5
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 6
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 7
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 8
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 9
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 10
Get started
Kick start your Confluence journey with our navigation and space tutorials.
View guide
Get started
Welcome to the Confluence getting started documentation. In this section, you'll find tutorials and other
information that'll be useful for evaluating Confluence, and getting to know it when you're starting out.
Teams in Space
For each tutorial in this section, we'll use a fictional organization known as 'Teams in Space'. Their mission is to:
"Perform flight research and technology integration to revolutionize aviation and pioneer aerospace
technology. Also, land the first humans on Mars by 2020."
You're an astronaut in the 'See Space EZ' team, which is working on the upcoming colonization of Mars.
Go ahead dive into the tutorials, and let us show you around Confluence and some of its handy features.
Tutorial: Navigate Confluence
The dashboard
The space directory
The space sidebar
Keyboard shortcuts
Complete your mission
Tutorial: Space ace
Create a project space
Create your personal space
Create the team's PR space
Delete and archive spaces
Teams in Space
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 11
In this tutorial,you'll be working with some new Teams in Space recruits. Let's get to know them.
Now that you've met your team, let's take a look at your mission.
Mission brief
Your mission commander has thrown you a curveball: this week you'll be training new recruits at Teams in
Space HQ on your collaboration tool Confluence. You just need to know the basics, so we'll go through the
main things you need to know to complete your mission.
Your mission is broken up into the following components:
Get to know the dashboard
Find your way in the space directory
Master the space sidebar
Impress everyone with keyboard shortcuts
Those new recruits will be here tomorrow; we better get started!
Let's go!
The dashboard
1. The dashboard
2. The space directory
3. The space sidebar
4. Keyboard shortcuts
5. Complete your
mission
The dashboard is the hub of your Confluence site, providing you with access to information and updates that
are important to you. It's also the first thing your new recruits will see, so you need to make a good
impression on this one.
You can get to the dashboard from anywhere in Confluence by choosing the site logo at the left of the
Confluence header.
The dashboard has a collapsible sidebar that helps you get around:
Discover
Watch the action unfold in real time with All updates or check out pages with lots of likes and activity
in the Popular feed.
My Work
Get lightning fast access to your recently created and edited pages in Recently worked on, get back
to that page you stumbled across yesterday in Recently viewed, and have mission critical pages on
speed dial under Saved for later.
My Spaces
This is where you can keep links to the spaces that you hop in and out of several times a day.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 12
If you're a Confluence admin you can give the dashboard some personality by adding useful announcements,
links, or a photo from your last mission (or office party). The whole right hand column is ready and waiting for
you to customize.
Pro tips
You can choose to set any page as your personal home page
You can always get to the dashboard at https://yoursite.com/wiki/dashboard.ac
tion
Your Confluence admin can customize the global dashboard that all users see
Next
1. The dashboard
2. The space directory
3. The space sidebar
4. Keyboard shortcuts
5. Complete your
mission
The space directory won't let you look up ET in the intergalactic phone book, but it will let you see and filter
all the spaces in your Confluence site. Spaces are places to collect pages with a common theme you can
create as many spaces as you like and you can find them all in the space directory.
Here are some tasks to get you comfortable using the space directory:
1. Visit the space directory To get to the space directory, choose Spaces > Space directory in the
Confluence header.
2. Choose the spaces you'll use the most No doubt there'll be a space or two that you'll use on a
regular basis. Click the star to the right of a space to make it appear under My Spaces on the
dashboard.
3. Choose space categories Once you're there, you'll see a list of all the spaces in your Confluence
site. Choose the 'My Spaces' category on the left to see only the spaces you marked with a star. Then
choose all spaces again.
4. Filter the list of spaces Type part of a space name in the Filter field at the top right. That'll quickly
narrow down the list of spaces if there are a lot of them.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 13
You can also categorize spaces with labels you create yourself. We're not going to cover that here,
but, if you'd like to know more, you can check out Use Labels to Categorize Spaces.
Understanding and using the space directory will make it much easier to find pages and blog posts that are
relevant to you.
You're ready to impress those new recruits with your knowledge of Confluence's space directory; now it's
time to sneak a peek at the space sidebar.
Next
1. The dashboard
2. The space directory
3. The space sidebar
4. Keyboard shortcuts
5. Complete your
mission
The sidebar is a feature of every Confluence space; it's where you'll find the page tree (a hierarchical list of
pages in the space), customizable space shortcuts, and a link to the space's blog.
The See Space EZ team will find their meeting notes, decisions, requirements, and other pages in the
sidebar. Basically any page you create in the space will appear in the sidebar by default.
When you use certain page templates, like meeting notes, Confluence will automatically add an
index page to your space shortcuts. The index page is just a place where you can view all pages of
the same type meeting notes in this example in one place.
The space's blog is great for announcements and what's new-type updates.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 14
You can expand or collapse the sidebar using the left square bracket ( [ ) on your keyboard, or by dragging it
with your mouse.
There are lots of things you can change in the sidebar, but we'll stick to the basics just enough to train your
new recruits.
You need to be a space admin to complete this task. Take a look, but feel free to skip it if you're not
an admin of any space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 15
Next
Keyboard shortcuts
1. The dashboard
2. The space directory
3. The space sidebar
4. Keyboard shortcuts
5. Complete your
mission
Give a person some space food, and they'll eat for a day; teach a person to rehydrate their own space food,
and they're set for the whole mission. Or something like that. Keyboard shortcuts fall into this basket. We
could give you a list here, but then you'd need to keep referring to this page. The best way to go is to show
you how to find the list of keyboard shortcuts within Confluence.
Your recruits also need to work fast, so you'll need to pass this wisdom on to them.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 16
You can turn the 'General' keyboard shortcuts off when you visit the General tab in the keyboard
shortcuts dialog.
Take some time to open the dialog and take a look at the shortcuts, and maybe find some you'll use a lot.
Then, start practising!
Next, we'll wrap up this mission and give you some ideas about where to head from here.
Next
1. The dashboard
2. The space directory
3. The space sidebar
4. Keyboard shortcuts
5. Complete your
mission
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 17
Well done, astronaut, you've acquitted yourself admirably. I'm sure those new recruits will be mightily
impressed with your knowledge of Confluence.
In this tutorial, we've:
Explored the anatomy of the dashboard
Navigated using the space directory and favorited a space
Taken a look at and customized the space sidebar
Found a handy list of keyboard shortcuts to help you work faster
Just look at your team's adoring faces...
If you'd like to take things to the next level, check out our tutorial on becoming a space ace.
Teams in Space
In this tutorial you're a new recruit on the Teams in Space crew, but, even though you're new, you'll be given
a lot of responsibility. You need the power to go with it.
Mission brief
You're in charge of organizing information and resources for the planned mission to Mars. There's going to
be plenty of important information, and it must be readily available to the people who need it. Some
information, though, will be sensitive, and may be 'for your eyes only.' You'll use the power and flexibility of
Confluence spaces to organize information, and make sure it's visible to the right people.
Your mission is broken up into the following components:
Create a space to house all of the important information related to the mission
Create your own space to keep yourself organized
Create a public relations space, where you'll introduce your team the world
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 18
What's a space?
Well, being an astronaut, I hope you know what space is, but what's a Confluence space all about? It's really
just a place to put related things, like information pages and files. But spaces also give you a place to
collaborate with groups of people, whether that's your team, people working on a common project, or the
whole world.
Every space has its own permissions, allowing you to grant access and other privileges to the right people.
They also have a blog, so you can post important messages and updates to whoever can see the space. You
can have as many Confluence spaces as you like, and you can archive or delete spaces when you no longer
need them.
Enough about that; let's begin.
Start the mission!
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 19
Your 'Mars colony' space is ready for your team to add pages to. If you want to find it again, choose Spaces i
n the Confluence header, and select it from the list; to add a page to it, navigate to the space and hit Create i
n the header.
Now it's on to your personal space; a place where you can work in peace, and be sure that no one's looking
over your shoulder.
Next
1. Choose your profile picture at the right side of the Confluence header
2. Select Add Personal Space...
3. Hit Create
You've now got a space that you can call your own. But we still need to lock it down to make sure it's
only visible to you.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 20
4. Choose Space tools > Permissions from the bottom of the siderbar
5. Hit Edit Permissions (enter your password if prompted)
You should see the confluence-users group listed under Groups. To the left of the list of
permissions is the View permission, which determines whether everyone in that group can see your
space.
6. Uncheck View and hit Save all at the bottom of the page
You're now the only one that can view this space. Feel free to try anything in this space, and store super
secret stuff here.
Next
In order to allow anonymous access to your Confluence site, a site admin needs to grant anonymous
users the 'Use Confluence' permission. Don't worry if you can't do that, or if it's not done; it's just
something to note if you're opening up your Confluence site for real.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 21
Each space you create also has its own blog, so your social media team will be able to create posts in this
space and speak directly to all those adoring fans. But none of those fans can see this space. Yet.
It's time to let the world in by changing the permissions on this space.
1. Choose Space tools > Permissions from the bottom of the sidebar
2. Scroll down until you see Anonymous, then hit Edit Permissions
3. Tick the View permission for anonymous users and hit Save all
That's it. You can now share the space's URL, which will be
http(s)://<your_confluence_site>/display/MarsPR. Visitors to that space don't need to log in, or have a license
for Confluence.
Next
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 22
If you need to clean up old spaces (or destroy the evidence of a failed mission!), you can either archive or delete
a space. Archiving just means it won't show up in the regular search, whereas deleting is obviously a lot more
permanent.
To archive a space:
1. Choose Space tools > Overview from the bottom of the sidebar
2. Click Edit Space Details
3. Change the Status from 'Current' to 'Archived' and hit Save
To delete a space:
1. Choose Space tools > Overview from the bottom of the sidebar
2. Select the Delete Space tab
What next?
If you'd like to know more about spaces and the permissions that govern them, check out Spaces and Permissio
ns and restrictions in the Confluence documentation.
Teams in Space HQ, signing off.
Spaces
What is a space? On this page:
What is a space?
Spaces are Confluence's way of organizing content
How do I use a space?
into meaningful categories. Think of it like having
different folders into which you can put your work. Related pages:
Create a Space
Spaces come in two main varieties: Space Permissions Overview
Navigate Spaces
Site spaces These spaces are found in the
Organize your Space
Space Directory and are the areas where
Customize your Space
you create content and collaborate with
Archive a Space
others. They are sometimes called global
Export Content to Word, PDF,
spaces.
HTML and XML
Personal spaces Every Confluence user
Delete a Space
can set up a personal space which they can
keep private or make public so others can
view and edit. Personal spaces are listed in
the People Directory and found under your
personal profile.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 23
Team spaces Give each team (QA, HR, Engineering, Support, ...) their own space so they can
focus and make their information easier for everyone to find.
Project spaces Put all the information related to your project in one place. This allows everyone to
work together in Confluence instead of emailing back and forth.
Personal space Store everything you're working on individually, keep your to-do lists, and polish
any content before you move it into another shared space.
Want more ideas for using spaces? Check out our kickass guides on how to:
Use Confluence as a Knowledge Base
Develop Technical Documentation in Confluence
Use Confluence as your Intranet
Use Confluence for Software Teams
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 24
Create a Space
There's no limit to the number of Spaces you can create on Confluence. You
can choose to set up a space for each team, project, or a mix of both On this page:
depending on your needs. Create a
Each space in Confluence functions autonomously, which means that each personal
space: space
Create a
Has its own homepage, blog, pages, comments, files, and RSS site space
feeds. Space
Can be customized with different color schemes, logo and sidebar. permission
Has its own set of permissions, as set by the space admin. s
Linking
For example, an IT team can create one overarching space with all their roa
related
dmaps, details of sub-teams, and a list of all the people and roles within that
spaces
team. They could then create a new space for each sub-team, such as
Tips
Quality Assurance, Developers, and Documentation, with guidelines, long
term plans, and knowledge articles within them. Each project that these Related pages:
teams work on could also have its own space, which could be linked to the
team spaces using labels. Spaces
Space
Keys
Create a personal space Create a
Space
Your personal space is always owned by you, and you can use it to store From a
your individual work, keep track of tasks, blog about what you've been Template
working on, or just use it to polish your pages before you move them into a
site space.
1. Choose your profile picture at top right of the screen, then choose Add Personal Space..
2. Choose Create.
You can change the permissions for your space at any time to determine who can and can't access the
content. So if you want it to be a private sanctuary, that's no problem.
To create a personal space you need the 'Personal Space' global permission.
You can create a site space for any team or project that would benefit from having a place where people can
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 25
work together and store related files. You can create these as blank spaces, or use templates, called space
blueprints , to help you create Team spaces, Knowledge Bases spaces, or Documentation spaces quickly
and easily.
1. Hit Spaces > Create space in the header.
2. Pick a type of space.
3. Enter the required details and create your space.
Choose your space key carefully as you can't change this later.
Each space you create will automatically have a home page that you can customize to display relevant
information for people viewing the space. If you use a space blueprint when creating a space, it will
customize your home page for you.
To create a site space you need the 'Create Space' global permission.
Space permissions
Each space is created with a set of default permissions. The user who created a site space is automatically
granted 'space admin' permissions for that space, which means that they can then grant permissions to other
users and groups. See Space Permissions Overview for more information.
System Administrators can edit the permissions of spaces in their Confluence site at any time.
You can link related spaces together using labels. This will create categories in the space directory for each
label, grouping all spaces with that label together.
You can also add a space description to make it easier for visitors to find the right space within each
category.
To help navigate between related spaces, you can use the Spaces List Macro on a page and filter by
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 26
category. This will let you insert a list of all the other spaces in a certain category into your space. You
can use this, for example, to keep a list in your team space of all the project spaces your team is
working on.
If you want to link to only certain pages of related content, rather than whole spaces, you can use the
Content Report Table Macro. You can use this, for example, in a space that functions as a workplace
directory, to create a list of all the team pages with everyone's roles and contact details across your
organization.
Tips
If your needs change, or your spaces grow too big, it's easy to copy or move content from one space
to another.
If the content or purpose of your space changes, you can update the space name, logo, colors and de
scription to reflect those changes.
If you no longer need a space, such as when a project has been completed, you can archive it, which
makes it less visible but retains the content on your site so that you can still refer back to it later.
You can find blueprints for creating a team space, knowledge base space,
documentation space, or software project space.
Your Confluence administrator can customize or disable your blueprint
templates. See Create a Template and Administering Site Templates for
more information on templates.
Types of Blueprints
Team space
A great building block if you are using Confluence as an intranet or to manage teams. Team spaces highlight
the members of the team, and grants permissions to those users accordingly.
This space blueprint uses search and page labels to make content easier to find, right from the space
homepage. It also contains two page blueprints for creating how-to and troubleshooting articles. The
templates used in these page blueprints are completely customizable. The Knowledge Base space blueprint
also Use JIRA applications and Confluence together.
Documentation space
This space blueprint displays the full page tree in the sidebar and hides other sidebar features including
blogs and shared links. The homepage uses search and page labels to make content easy to find. Add the
'featured' label to any page you want to highlight on the homepage. This space does not include any page
blueprints but you can create and promote templates for your documentation authors to use.
This space is designed to help you organize your software project. The purpose-built space home page lets
you view and edit your roadmap, see team members, and Use JIRA applications and Confluence
together#JIRA Software. Create pages in this space for requirements, meeting notes, decisions, retros, and
more.
The software project space blueprint will only appear if you have linked Confluence to your JIRA Software
instance.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 27
Check out our guides for some more tips on how to:
Use Confluence as a Knowledge Base
Develop Technical Documentation in Confluence
Use Confluence as your Intranet
Confluence for Software Teams
Space Keys
Each Confluence space has a space key, which is a short, unique identifier
that forms part of the URL for that space. Related pages:
Create a
Space
Create a
Space
From a
Template
When you create a site space, Confluence will suggest a space key or you can enter your own key to make it
more memorable.
For example, you might give your marketing team's space a key of MARKETING. You can then navigate
directly to the space using a URL like this - http://<yoursite>/display/marketing
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 28
You can't change the space key after you create your space, so choose your space key carefully!
Navigate Spaces
How is content arranged in spaces? On this page:
How is
Think of a space as the container that holds all the important stuff a team, content
group, or project needs to work. These are autonomous that means that arranged
each space has its own pages, blogs, files, comments and RSS feeds. in spaces?
Each space is automatically created with a homepage - the first page you'll View all
see when you navigate to the space. You can edit your homepage and your spaces in
sidebar to help people navigate their way around your space. Confluenc
e
Spaces can't be nested you can't have a space within a space but you
can Use Labels to Categorize Spaces. Spaces with the same label will Related pages:
appear together in the the space directory and in the recent activity area of Organize
the dashboard. your
Space
Watch
Pages,
Spaces
and Blogs
Pages and
blogs
Search
Inside the space, you can nest your pages, and you can create as many levels of hierarchy as you need.
Each space also has its own blog, which lets you share news and make announcements. Blog posts are a
great way to keep people involved in what's going on in your team or project.
You can set different levels of access for each space, and the pages and blogs within it, using Space
Permissions Overview.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 29
The space directory choose Spaces > Space directory in the Confluence header for a list of all
the site and personal spaces you have permission to see. Filter the list of spaces by selecting from the
categories on the left of the space directory.
The dashboard you can make your most useful spaces appear under My spaces on the
dashboard. Choose the star icon in the space sidebar or space directory to add a space to My spaces
.
The spaces menu in the header also displays a list of your recently viewed spaces, allowing you to quickly
navigate to the things you view most often.
The Spaces List Macro allows you to display a list of spaces on a Confluence page, and lets you filter them
by category.
This page is about Space Permissions. Confluence also lets you set Page Restrictions.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 30
Permissions Summary
Permission Applies to
View This lets a user view all the content in your space.
Add This lets a user add and edit pages, blogs, comments and attachments.
Restrict This lets a user restrict others from viewing or editing a page.
Delete own This lets a user delete any pages, blogs and attachments they originally created
(regardless of whether other users have subsequently edited the content).
Delete This can be used to let a user delete pages, comments, attachments and mail items.
Export This lets a user export the whole space. This is different to page exports - anyone who can
view a page can also export it.
Admin This lets a user administer the space, including the ability to pass on admin permissions to
other users.
Confluence administrators aren't necessarily space administrators. In order for them to be a space admin,
they must belong to a group which has space admin and view permission for the space, or their username
must be specifically granted space admin and view permission for the space. People with the System
Administrator global permission can choose to grant themselves space admin permissions for any space.
Space permissions are additive. If a user is granted permissions as an individual or as a member of one or
more groups, Confluence will combine these permissions together.
Here's an example...
Sasha is a member of the confluence-users group and the developers group. The confluence-u
sers group has 'export' permission, but does not have 'restrict' permission. The developers group has
'restrict' permission but does not have 'export' permission.
By being a member of these two groups, Sasha can restrict and export content. The permissions do not
conflict, they combine to determine what Sasha is allowed to do in this space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 31
Licensed Users - this is where you grant permissions to groups and individual users.
Anonymous Access - this is where you grant permissions to users who are not logged in (essentially
making the space public)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 32
To add a new user or group to the permissions list, search for either a group or user in their respective
sections and choose Add. The group or user will appear in the list of groups; select the specific permissions
you'd like to apply then choose Save all. You can bulk assign or revoke permissions by selecting Select All
or Deselect All.
There is no way to change permissions for multiple spaces at once. Permissions are managed on a space
by space basis. However, your Confluence Administrator is able to set default space permissions, which will
apply to any new spaces.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 33
To remove a user or group from the space permissions list, deselect all the checkboxes for that user or group
and save the changes. The user or group won't appear in the list once you save.
If you're a Confluence Administrator and a space admin accidentally denies all admin access to a space, so
that nobody has access to administer that space any more, you are able to recover those permissions for
them.
In order to make a space public, your administrator must first turn on the global permission for
anonymous access.
This permission doesn't automatically grant anonymous users permission to see any of the content
on your site, but it does need to be turned on to give space admins the option of granting anonymous
users access to their space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 34
You can't grant space administration or page restriction rights to anonymous users.
If your Confluence administrator turns off anonymous access to your site, users who are not logged in will
no longer be able to see any spaces. However, all logged in users (regardless of their group membership)
will be able to see all spaces that have granted space permissions to anonymous users.
Auditing considerations
There are some additional things to be aware of if you grant the Add page permission to anonymous users.
You won't be alerted, when closing the editor or publishing a page, if the only unpublished changes on the
page were made by anonymous users. This means a logged in user may inadvertently publish changes they
were not aware had been made to the page.
The changes themselves are visible in the page, but the usual warning dialog will not appear if the only
people to have made changes were not logged in.
If there are unpublished changes from both logged in users and anonymous users, the warning dialog will
appear, but only the logged in users will be listed in the dialog. Changes made by all users (including
anonymous) will be included if you view the changes from that dialog.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 35
This permission overrides all existing space permissions, so any logged in Confluence user will also be
able to see the space (regardless of their group membership).
You can edit this permission at any time to revoke access to a space, but it can only be re-enabled from JIRA
Service Desk.
Active users who don't hold a Confluence license have very limited access to Confluence. They can view
pages, but can't like, comment, edit, view the dashboard, use the space directory, see user profiles or search
your full site.
See Use JIRA applications and Confluence together for more information about JIRA Service Desk
integration.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 36
over time, create it as a blog post. Your blog displays as an infinite scroll, so it surfaces the latest
news and visitors just need to scroll down if they're interested in older content.
If you're creating content that you want to last, and possibly evolve over time, then create it as a page.
Pages nest, so every page can have its own child pages, which lets you organize your content into
categories and subcategories.
Using Labels
Labels are keywords or tags that you can add to pages, blog posts, and attachments.
Define your own labels and use them to categorize, identify, or bookmark content in Confluence. For
example, if you assign the label 'accounting' to all accounts -related pages on your site, you'll then be
able to:
a. Browse all pages with that label in a single space or across the site.
b. Display a list of pages with that label.
c. Search based on that label .
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 37
Use the Content by Label Macro to create a table of contents for your space that is organized by label
categories.
Labels aren't exclusive, so you can have as many labels as you want on a page. The page will then
appear under each of those categories. See Use Labels to Categorize Spaces for more information.
Let your collaborators know about what parent pages to create their child pages under, so no content
gets lost or misplaced.
Decide on standard labels to add to pages, blogs, and attachments so all content gets neatly
categorized.
Add a link to this in the Space Shortcuts section of the sidebar so that it's easy to find.
Blueprints are templates that come with formatting, macros and sample content. You can customize these
Blueprints for each space. Everything created from a Blueprint will have it's own index in the sidebar, so for
example if you use the Meeting Notes Blueprint , you can select 'Meeting Notes' in the sidebar to see a list of
all the meeting notes in your space.
Make things simpler for other contributors by using the Create from Template Macro . The Create from
Template Macro lets you put a button on a page that links to a specific template of your choice. When the
button is clicked, the macro opens the editor, ready to add a new page, and adds content to that page based
on the given template.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 38
Create your own templates for any content that you want formatted the same way every time. For example, if
you have to create a regular report tracking the same criteria, create a template with headings, variable
dates, tables, and spaces for any graphics, so that each time all you have to do is input the new data instead
of creating the whole report from scratch.
My Spaces
Add any spaces that you want to be able to navigate to easily to your list of 'My Spaces'. This list can be
found under your dashboard and in the Space Directory, and you can also use the Spaces List Macro to
display it on a page or blog.
To add a space to your list of 'My Spaces', either navigate to that space or find it under the Space Directory,
and select the star icon next to the Space Name. To remove it from the list, just select the star icon again.
If you only want links to certain pages or blogs rather than a whole space, you can choose Save for laterand
these will appear on your dashboard and under your profile. You can use the Favorite Pages Macro to
display a list of all of everything you've saved for later.
If you want to keep track of all the changes made to a page, blog, or space, you can also watch them.
Watching any content means that you will receive email notifications for all edits, deletions, attachments or
comments made to that content.
To watch a page, navigate to the page you want to watch, then choose Watch > Watch page , or if
you want to watch the whole space, select Watch all content in this space .
To watch a blog, navigate to that blog and choose Watch this blog .
To stop watching something, deselect the relevant tick box.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 39
You can also manage watchers for your own space. This is useful when, for example, you're creating a new
project, and want the team members on that project to stay notified of its progress. Go to any page in that
space and choose Watch > Manage Watchers, then add or delete any names under 'Watching this space'.
@mentions
Use @mentions for any work where you need someone else's input or want to assign someone a task.
Mentioning someone works like a tag; they'll immediately receive a notification that they've been mentioned,
and can click through to that page or blog. If you mention someone when creating a task, it'll assign that task
to them and they'll also be able to find it under their profile.
You can use this in place of emails if you want someone to look something over, add in additional
information, or approve anything, simply put that work on Confluence and assign it to them as a task. They'll
be able to make any changes or comments within Confluence and let you know when they're done by
mentioning you back.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 40
Add a search box so that it's easy to find content within your space
The Livesearch Macro allows you to add a search box to a Confluence page, and you can set it to only
find content within your space.
Keep everyone updated about the latest changes within your space
If it's important for your visitors to know about the latest changes to your space, you can use the Rece
ntly Updated Macro to display a list of the most recently updated content. You can set the space
parameter to show this for just your space, or, if you have related spaces, to show the most recently
updated content across all of those spaces as well.
Team Spaces:
Introduce the team: The User Profile Macro displays a short summary of a given Confluence user's
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 41
Knowledge Base:
Have external content that you need on your page? Embed online videos, slideshows, photo
streams, and more, directly into your page with the Widget Connector Macro.
Put your own multimedia content onto the page: The Multimedia Macro embeds attached video,
animation, and other multimedia files on a Confluence page.
Create an index of all your content: The Page Index Macro creates a hyperlinked alphabetical index
of all page titles within the current space.
Planning/Project:
Keep track of everyone's tasks: Use the Task Report Macro to display a list of tasks on a page.
Filter the tasks by space, page, user, label, created date and more.
Is your project on track? The Status Macro displays a colored lozenge (a rounded box) that is useful
for reporting project status. You can choose the color of the lozenge and the text that appears inside
the lozenge.
Let everyone see where you're going: The Roadmap Planner Macro creates simple, visual timelines
that are useful for planning projects, software releases and much more.
Using Macros
Whether you're using your personal space as a sandbox to draft and test content, a portfolio to show off what
you're working on, a home base to navigate to your content in other spaces, or something completely
different, these are some macros that should help you use your space more effectively.
Use the Favorite Pages Macro to create a list on your home page of all the pages you've saved for
later, so you can easily navigate back to any of them.
Use the Content by User Macro to keep track of all the current pages, comments and spaces you've
created so you can find everything you've been working on in one place.
Use the Task Report Macro to keep track of all tasks assigned to you, and tick them off as you finish
them.
Use the Recently Updated Dashboard Macro to keep track of all the content across your Confluence
site that you're interested in - the Dashboard lets you choose which spaces, users, blogs, pages or files
you would like to keep updated about.
If at any point you decide that you would like another page within your space to be your home page, you can
easily change this from the Edit Space Details tab.
To edit a space's details:
1. Go to the space and choose Space tools > Overview from the bottom of the sidebar.
2. Choose Edit Space Details.
3. Enter the page you want use in the Home page field then choose Save.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 42
You can change the home page, name and description of your space, but you are not able to change the
space key.
Categorize a space
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 43
Help make it easier to find the right space within a category by adding a description to your space:
1. Go to the space and choose Space tools > Overview from the bottom of the sidebar.
2. Choose Edit Space Details.
3. Under the Description field, type a short description to tell visitors what your space is
about, then choose Save.
To see what spaces are in a category, choose Spaces > Space directory in the Confluence header, then
select one of the categories from the list.
Head to My Spaces in the Space Directory to see all your favorite spaces. When viewing a space,
you can choose the star icon next to the space title in the sidebar to add it to My Spaces so that it's
easier to find later.
1. Go to the space and choose Space tools > Overview from the bottom of the sidebar
2. Choose Edit next to Space Categories.
3. Under Space Categories, choose the x icon next to each category that you want to remove.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 44
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 45
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 46
Choose the icons to show or hide pages, blogs, shortcuts or navigation options.
For example, if you want your space to be used primarily as a blog you can hide the 'Pages' link.
Add--ons such asTeam Calendars for Confluence Server may add other links in this section of the
sidebar and you can also show or hide these.
Choose Add link to add a shortcut link to the sidebar. This could be a link to an important page for
your team, or to an external site.
Drag links to reorder them within each section (you can't move a link from one section to another).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 47
Choose Child pages to see the current page and its children in the sidebar.
Choose Page tree to see the page tree for the entire space, expanded to the current page.
You can also choose to completely hide the navigation display options and instead add the pages you
want to visible as shortcut links. Alternatively, you can remove the sidebar navigation altogether and
use a Page Tree Macro or Children Display Macro on your homepage for navigation instead.
You can further customize a sidebar using wiki markup to add custom content.
To add custom content to your sidebar:
1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar.
2. Choose Sidebar, Header and Footer.
3. Enter your custom content in the Sidebar field.
The sidebar, header and footer fields all use wiki markup, check our guide to wiki markup for help, or check
out some common customizations below.
Add a search field to your sidebar...
To add a search field to the sidebar add the following wiki markup for a search macro in the Sidebar field.
For the Livesearch Macro macro:
{livesearch}
{pagetreesearch}
Add your own page tree to replace the default page tree...
To hide the default page tree and add your own, with additional parameters:
1. Add the wiki markup for the Page Tree Macro in the Sidebar field.
The following example includes parameters to expand the top three levels of the page tree by
default and include an Expand All and Collapse All link above the tree.
{pagetree:root=Page Name|startDepth=3|expandCollapseAll=true}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 48
Customizable Elements
The color scheme allows you to edit the colors of UI elements including the top bar, tabs and backgrounds.
Some UI elements below are for specific themes, and color changes may not take effect for other themes.
Top Bar - the top navigation bar background
Top Bar Text - the text on the top navigation bar
Header Button Background - buttons on the top navigation bar (e.g. Create button)
Header Button Text - the text on buttons on the top navigation bar
Top Bar Menu Selected Background - background color of top navigation bar menu items when
selected (e.g. spaces)
Top Bar Menu Selected Text - text color of top navigation bar menu items when selected
Top Bar Menu Item Text - text on top navigation bar drop down menus (e.g. help or cog)
Menu Item Selected Background - highlight color on top navigation bar drop down menu items
Menu Item Selected Text - text color on highlighted top navigation bar drop down menu items
Search Field Background - the background color of the search field on the header
Search Field Text - the color of the text in the search field on the header
Page Menu Selected Background - the background color of the drop down page menu when
selected
Page Menu Item Text - the text of the menu items in the drop down page menu
Heading Text - all heading tags throughout the space
Space Name Text - the text of the current space name located above the page title
Links - all links throughout the space
Borders and Dividers - table borders and dividing lines
Tab Navigation Background - the background color of the tab navigation
Tab Navigation Text - the text of the tab navigation when highlighted
Tab Navigation Background Highlight - the background color of the tab navigation when
highlighted
Tab Navigation Text Highlight - the text of the tab navigation elements when highlighted
Screenshot: Editing the color scheme
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 49
Handy Hint
If you mess things up, just choose Reset then try again.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 50
When a new space is created, whichever theme is applied to the whole site will be applied by default to the
new space. This is the global look and feel, and any changes made globally will flow through to all spaces
that inherit the global look and feel.
If a space has its own theme applied, or if changes have been made to customize the look and feel of the
space, it will no longer inherit changes from the global look and feel.
If you want to go back to inheriting the global look and feel choose Global look and feel from the Themes p
age.
As previously announced, the documentation theme is not available in Confluence 6.0. We know you'll have a lot
of specific questions, so we've created this FAQ to help you prepare for upgrading to Confluence 6.0.
If you have further questions, you can ask them at the bottom of the page and we'll do our best to provide an
answer.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 51
Here's an example of the documentation theme, and default theme with the same custom content side by side:
The easiest way to check whether your space is using the documentation theme is to look for a Browse menu in
the header, near the Create button. (If you're using the default theme already, you'll see a Space Tools menu at
the bottom of the sidebar instead.)
How can I check if the documentation theme is being used anywhere in my site?
There's no simple way to see a list of spaces using the Documentation theme in Confluence itself, however if
you have a very large site, your Confluence Administrator can use the following query to get a list of spaces
directly from the database.
SELECT *
FROM BANDANA B, SPACES S
WHERE B.BANDANAKEY='atlassian.confluence.theme.settings'
AND S.SPACEKEY=B.BANDANACONTEXT
AND B.BANDANAVALUE LIKE ('%documentation%')
ORDER BY S.SPACENAME;
This query will only find spaces that are explicitly using the documentation theme. It doesn't include spaces
using the global look and feel (these spaces automatically change when you change the Site Theme, you wont
need to change the theme space by space).
During the upgrade we'll automatically turn on the default theme for any spaces that currently use the
documentation theme. If you've customized the documentation theme (by adding wiki markup to the sidebar,
header or footer) we'll take this wiki markup and drop it into the sidebar, header and footer in the default theme.
The default theme adds some new sections to the sidebar, such as links to pages, blogs and space shortcuts.
You can choose to hide these - head to Space Tools > Configure Sidebar and use the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 52
Will my space break after the upgrade?
This depends on the amount of customization you have. In most cases your space sidebar may look a little
different but the changes shouldn't be dramatic.
If you've used CSS to change the appearance of your space (either in the space stylesheet or by using the
Adaptavist Content Formatting macros like {style} and {div} in the sidebar, header, or footer of the
documentation theme), you may need to make a few changes to some class names in your CSS to get your
space looking right. For example, if you specified #splitter-sidebar in the doc theme, you'll need to use .
acs-side-bar for the default theme.
If you have customized default theme layouts through the Confluence UI, you may find that your space looks
strange or broken when the default theme is re-applied to spaces previously using the documentation theme.
If you experience problems, you'll need to reset the broken layouts.
http://<yoursite>/spaces/choosetheme.action?key=YOURSPACEKEY
2. In the space administration options go to Layouts (if available) or use the following link, replacing YO
URSPACEKEY with the space key for the space.
http://<yoursite>/spaces/listdecorators.action?key=YOURSPACEKEY
3. Choose Reset Default next to any template that have been customized.
4. Return to the Themes page and try applying the default theme again.
Layouts can also be customized for the entire site - head to
> General Configuration > Layouts if you need to reset the layout for the entire site.
Remove customized layouts in the database...
If you're unable to reset the layouts via the Confluence UI, you can remove the affected layouts directly in the
database. Be sure to take a full database backup before you try this.
First, use the following query to identify customized layouts:
Select *
FROM DECORATOR
ORDER BY SPACEKEY
Then, you can selectively remove records for spaces that are affected.
Can I add custom content to the sidebar, header and footer globally?
Yes. Head to
> General Configuration > Sidebar, Header and Footer. All spaces that use the global look and feel will
inherit your custom content. Any custom content added to the sidebar, header and footer in a particular space
will override any custom content added globally.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 53
Yes! If a macro worked correctly in the documentation theme it'll work in the default theme too.
You can add custom content to the sidebar, header and footer in each space individually ( Space Tools > Look
and Feel > Sidebar, Header and Footer) or globally (
How do I turn off the Pages and Blogs shortcuts at the top of the sidebar?
No. You can add custom content to the sidebar globally, but showing and hiding sections of the sidebar, setting
space logos, and adding shortcut links are done on a space by space basis.
I want to see the page tree, not child pages. how do I do this?
Head to Space Tools > Configure Sidebar and select Page Tree in the navigation options. The default for all
new spaces is Page Tree.
Instead of choosing between Space Operations and Space Administration, the documentation theme has a
single Space Tools menu that lets you jump right to Permissions, Content Tools, Look and Feel, or Integrations.
Browse > Pages Pages on the sidebar or Space Tools > Reorder pages
Browse > Labels Click a label on any page, then use the
Browse > Space Operations > Space Space Tools > Overview
Details
Browse > Space Operations > Orphaned Space Tools > Content Tools > Orphaned Pages
Pages
Browse > Space Operations > Undefined Space Tools > Content Tools > Undefined Pages
Pages
Browse > Space Operations > Attachments Space Tools > Content Tools > Attachments
Browse > Space Operations > PDF, HTML, Space Tools > Content Tools > Export
XML Export
Browse > Space Operations > RSS Feeds Space Tools > Content Tools > RSS Feeds
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 54
Browse > Space Operations > Watch this Pages > Watch this space (or use the Watch button on any
space page)
Browse > Space Operations > Watch this Blogs > Watch this blog (or use the Watch button on any
blog blog post)
Browse > Space Admin > Space Details Space Tools > Overview
Browse > Space Admin > Space Space Tools > Overview
Categories
Browse > Space Admin > Templates Space Tools > Content Tools > Templates
Browse > Space Admin > Delete Space Space Tools > Overview > Delete Space
Browse > Space Admin > Trash Space Tools > Content Tools > Trash
Browse > Space Admin > Permissions Space Tools > Permissions
Browse > Space Admin > Restricted Pages Space Tools > Permissions > Restricted Pages
Browse > Space Admin > Application links Space Tools > Integrations > Application Links
Browse > Space Admin > Themes Space Tools > Look and Feel > Themes
Browse > Space Admin > Color Scheme Space Tools > Look and Feel > Color Scheme
Browse > Space Admin > PDF Layout Space Tools > Look and Feel > PDF Layout
Browse > Space Admin > PDF Stylesheet Space Tools > Look and Feel > PDF Stylesheet
Browse > Space Admin > Change Space Space Tools > Configure Sidebar then choose the edit icon
Logo on the space logo
Browse > Space Admin > HipChat Space Tools > Integrations > HipChat
Integration
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 55
Yes. Our main focus when adding this feature was to help people move from the documentation theme to the
default theme with a minimum of effort. Keeping these fields as wiki markup means that your existing
customizations can be pasted straight in.
You can upload any image to use as your space logo, but you can't change how it appears in the sidebar (it's
always round and always at the top).
Yes! If you want to have complete control over how the page tree appears in your sidebar you can hide the built
in page tree, and then add a Page Tree macro {pagetree} in the sidebar custom content.
Page titles do not wrap in the sidebar of the default theme (regardless of whether you're using the built in page
tree or have added a {{pagetree}} macro as custom content). There's no way to change this.
You can change the order of some items in the sidebar, such as the shortcuts, but the order of the sections
themselves can't be changed. Anything that has a
No, the space jump macro was provided by the documentation theme and will not be available once the
documentation theme is removed. If you've used this macro on a page or in the header or footer of a space, it
will show the following error after the upgrade unknown macro: {spacejump}.
To find out whether the Space Jump macro is used on any pages in your site, enter macroName:spacejump int
o the search bar. All pages containing the macro will be returned (it won't search the sidebar, header or footer
unfortunately).
The default theme does not list child pages below the sidebar, but you can achieve a similar result by adding a C
hildren Display macro to the footer.
No, that is one of the features we removed with the documentation theme.
One workaround is to add a Livesearch macro to the sidebar or space homepage. Use @self in the spaces
parameter to restrict the search to the current space.
The default theme does not have an option to view all pages in your space alphabetically.
What will happen if I import a space that uses the documentation theme?
You should have no problems importing the space, but it will have the default theme applied and any wiki
markup customization in the theme will not be automatically migrated to the default theme. Before exporting the
space you should copy the wiki markup contents of the sidebar, header, and footer fields and keep it so that you
can add it back in manually after you've successfully imported your space.
Customize Space Layouts
You can modify Confluence's look and feel by
editing the layout files. This page tells you how to
customize the layout files for a space. You'll need
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 56
If you modify the look and feel of Confluence by following these instructions, you'll need to update
your customizations when you upgrade Confluence. The more dramatic the customizations are, the
harder it'll be to reapply your changes when upgrading. Please take this into account before
proceeding with any customizations.
For more information on updating your customizations, please refer to Upgrading Customized Site
and Space Layouts .
Confluence is built on top of the Open Source SiteMesh library, a web-page layout system that provides a
consistent look and feel across a site. SiteMesh works through 'decorators' that define a page's layout and
structure.
To edit the layout of Confluence, you will need to modify these decorator files. A decorator file is a .vmd file
and is written in a very simple programming language called Velocity. Learn more about Velocity. Once you
become familiar with Velocity, you can edit the decorator files to personalize the appearance of Confluence.
The decorator files in Confluence are grouped into the following categories:
Site layouts: These are used to define the controls that surround each page in the site. For example,
if you want to make changes to the header and the footer, you will need to modify these layouts.
Content layouts: These control the appearance of content such as pages and blog posts. They do
not change the way the pages themselves are displayed, but they allow you to alter the way the
surrounding comments or attachments are shown.
Export layouts: These control the appearance of spaces and pages when they are exported to
HTML. If you are using Confluence to generate a static website, for example, you will need to modify
these layouts.
Learn more about using decorators.
To edit a decorator file:
1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
2. Choose Layout (Layout is displayed only if you are a Confluence system administrator.)
You'll see a list of the layouts for the space
3. Click Create Custom to edit the default vmd file
This will open up the vmd file in edit mode. If you only want to view the vmd file, click View Default.
4. Make any changes and click Update
Screenshot : Edit Layouts Example
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 57
Archive a Space
Archiving a space is useful when you have content that is no longer On this page:
relevant, but you still want the option of accessing it at a later date. Archived
spaces are less visible, but still available on your site. Archiving a space is Archive a
easy to undo - you can make a space current again at any time. space
The effect
of
Archive a space archiving a
space
1. Go to the space and choose Space tools > Overview from the Change a
bottom of the sidebar space from
2. Choose Edit Space Details. archived to
3. Select Archived in the Status dropdown menu. current
4. Choose Save.
Related pages:
Delete a
Space
Export
Content to
Word,
PDF,
HTML and
XML
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 58
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 59
Delete a Space
Deleting a space permanently removes the space and all of its contents,
including any calendars and questions linked to that space. Only someone Related pages:
with space admin permissions can delete that space. Archive a
Deleting a space is permanent it does not go to the trash and cannot Space
be undone. Export
Content to
If you're unsure about deleting a space, create an XML export of the space Word,
as a backup before proceeding. You can then restore the space from the PDF,
XML export file if you need to. HTML and
XML
To delete a space:
1. Go to the space and choose Space Tools > Overview from the
bottom of the sidebar.
2. Choose Delete Space.
3. Choose OK.
Members of the confluence-administrators group can also delete spaces, including personal
spaces.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 60
To use the space export functionality, you need the 'Export Space' On this page:
permission. See the guide to space permissions.
Export
single
Export single pages to PDF pages to
PDF
If you need to send content to people who don't have access to Confluence, Export
you can export a single page or blog post as a PDF. single
pages to
If you've got permission to view the page in Confluence, you'll be able to
Word
export it in this way; go to the page and choose Tools > Export to PDF.
Export to
Only published content is exported. This means you can create PDF exports HTML,
even while people are still working on the page. XML, or
PDF
When you export a single page to PDF, the PDF stylesheet customizations Customizin
are applied, but any PDF layout customizations are not. To make your PDF g the
layout customizations apply to a single page exported to PDF, you'll need to appearanc
use the 'multiple page' method described below to export the single page. e of PDF
See Customize Exports to PDF. exports
Related pages:
Customize
Exports to
PDF
You can also choose to export single pages to a .doc file that can be opened in Microsoft Word.
If you've got permission to view the page in Confluence, you'll be able to export it in this way; go to the page
and choose Tools > Export to Word.
Only published content is exported. This means you can create Word exports even while people are still
working on the page.
Note that due to the format of this file, it can only be opened in Microsoft Word and is not compatible with
other applications such as Open Office, Libre Office or Google Docs.
If you want to export a space or selected pages in a space to HTML, XML, or PDF, Confluence can
create a zipped archive of the HTML or XML files, or a single, downloadable PDF file.
PDF export is useful you're producing a printable user manual from your documentation space for example.
The HTML export can be used to convert your site content to a static website, and finally the XML export can
be used to import your space content into another Confluence space (running the same or later version of
Confluence).
To export pages to HTML, XML, or PDF:
1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Export
3. Select either HTML, XML, or PDF, then choose Next
4. Select either a normal or custom export for HTML or PDF, or a Full or Custom XML export:
Normal Export (HTML and PDF) to produce an HTML file containing all the pages that you
have permission to view.
Full Export (XML) to produce an XML file containing all the pages in the space, including
those that you do not have permission to view.
Custom Export if you want to export selected pages only, or if you want to exclude
comments from the export.
5. Choose Export
When the export process has finished, you can download the zipped archive or PDF.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 61
You can add a title page, table of contents, and customized headers and footers to the PDF output. For more
advanced customizations, you can apply Cascading Style Sheet (CSS) modifications. These customizations
are specific to each space, and you need the 'Space Administrator' permission to apply these customizations.
For more information, see Customize Exports to PDF.
To export a PDF containing international text, see Create a PDF in Another Language
Confluence's PDF export feature is designed to handle a wide variety of content, but on rare
occasions the PDF Export process may fail due to an unrecognized customization. If that happens, the
PDF export screen will indicate the title of the page in which the problem occurred, to help you
diagnose the cause of the failure.
In the zip file, page attachments are placed in individual folders with names in the following format:
...\download\attachments\xxxxxx
where 'xxxxxx' is the page ID of the page containing the attachments.
To customize the HTML output, you'll need to modify the file confluence-x.y.z-jar/com/atlas
sian/confluence/pages/Page.htmlexport.vm. To learn how to repackage this file, see How to
Edit Files in Confluence JAR Files
You can only import a space into the same or later Confluence version. You can't import a space
into an earlier version.
If you're doing the export for backup purposes, consider another means of backup. See Production
Backup Strategy.
If you are running Confluence behind Apache HTTP Server and are facing timeout errors, please
consider creating the export directly from Tomcat, instead of going through Apache. This will speed up
the process and prevent timeouts.
See Restoring a Space for notes on restrictions when importing a space into Confluence Server.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 62
You can add your own HTML to customize the title page, page headers and page footers in the PDF output.
1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar You'll
need Space Admin permissions to do this.
2. Choose PDF Layout.
3. Choose Edit.
You can customize the HTML that is generated for the following areas when the space is exported to PDF:
PDF Space Export Title Page title page.
PDF Space Export Header page headers.
PDF Space Export Footer page footers.
Enter your customizations into each text box as required. The PDF layout section accepts HTML code. You
can include inline CSS in the HTML too.
You can adjust the appearance of the PDF pages by customizing the CSS in the PDF Stylesheet screen.
To get started, download the default CSS rules for the PDF stylesheet - confluencedefaultpdf.css.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 63
Any rule defined in this file can be customized and added to the PDF Export Stylesheet section. Your
customizations override any default CSS rule. If no customizations are defined, the default CSS rules will be
applied.
By default, the export does not include a title page, headers or footers. You can define these in the PDF
layout.
To customize the PDF Stylesheet:
1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar You'll
need Space Admin permissions to do this.
2. Choose PDF Stylesheet.
3. Choose Edit.
4. Enter your customizations.
The PDF Export Stylesheet field accepts Cascading Style Sheets (CSS) rules. The 'PDF Export Stylesheet'
page shows the current (e.g. customized) contents of your PDF stylesheet.
Example Customizations
This section provides examples of typical customizations that you can add. See also Advanced PDF
Customizations.
Page Size
The default page size is based on the location of your Confluence server. For example, if this server is
located in the US then the default paper size of your PDF export will be US Letter (8.5 inches wide by 11
inches long). If the server is located in Australia, the default paper size will be A4 (210 mm wide by 297 mm
long). More information about paper sizes can be found on Wikipedia.
To modify the page size to A4, edit the PDF Stylesheet to add a size property to the CSS@page rule, like
this:
To change the page orientation of your PDF document, simply reverse the order of the values declared in the
@page rule's size property. The first and second values of this property represent the width and height of
the page, respectively.
For example, to generate PDF space exports in A4-sized landscape orientation, your @page rule might look
like this:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 64
Page Margins
To set all margins to 15 mm, with a paper size of A4, edit the CSS @page rule in the PDF Stylesheet, like
this:
To set margins to provide a gutter for binding a printed document, use the :left and :right pseudo-class
es, as follows:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 65
Note the use of the :first pseudo-class in the example above to define distinct margins for a cover or title
page.
Page Breaks
By default, Confluence pages are exported without page breaks, so that shorter pages will appear on the
same PDF page.
To make each Confluence page appear on a separate page in the PDF file, add the following rule in the PDF
Stylesheet:
Title Page
You can add a title page to your PDF document by adding HTML to the Title Page section of the PDF Layout
screen. The following example creates the title page and adds a title:
Use CSS rules in the PDF Stylesheet to control the appearance of the title page and the title text:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 66
.fsTitle
{
font-size: 42px;
font-weight: bold;
margin: 72px 0 4px 0;
text-align:center;
}
In the example above, the title page includes an image called 'titlepage.png', centred in the middle of the
page. The "590719" in the src attribute is the ID number of the page to which the image is attached.
Table of Contents
By default, a table of contents will be generated after the title page, or at the beginning of the PDF document
if no title page is defined in the PDF Layout. To see the default CSS rules applied to the table of contents,
download the default CSS rules (confluencedefaultpdf.css) and examine the specific rules with toc in their
name.
To make changes to the appearance of the table of contents, define CSS rules in the PDF Stylesheet.
To prevent the table of contents from being generated in your PDF document, add the div.toc-macro rule
to the PDF Stylesheet and set its display property to none:
The leader character is used to link a heading in the table of contents with its page number. By default, the
leader character is the '.' (dot) character. Leader values of dotted, solid and space are allowed. You can
also use a string, for example leader(". . . ").
To change the leader character to a solid line, modify the leader() value on the content property of the
CSS rule as follows:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 67
You can add headers and footers to your PDF pages using the 'Header' and 'Footer' sections of the PDF Layout
screen. By default, headers and footers only apply to a space export and not to exports of single pages
(however, see Advanced PDF Export Customizations ). The following example adds a simple copyright notice.
Page Numbering
To add page numbering, you need to combine customized HTML in the PDF Layout with customized CSS in the
PDF Stylesheet.
1. PDF Layout HTML: In the Footer section (or the Header section), use an empty span element with a
unique ID, for example pageNum, to act as a place holder for the page number.
2. PDF Stylesheet CSS: Create the following CSS selector rule for the empty span:
In order to break long words or words that are not separated by whitespace, add a selector to the PDF
stylesheet containing the word-wrap property with a value of break-word:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 68
General Formatting
You can use the stylesheet to customize the output of just about anything else that will influence the look and
feel of the final document. This includes fonts, tables, line spacing, macros, etc. The export engine works
directly from the HTML output produced by Confluence. Therefore, the first step in customizing something is
to find a selector for the HTML element produced by Confluence or the Confluence macro. Then add a CSS
rule to the PDF stylesheet. Your customization will appear in the PDF export.
Notes
Demotion of heading elements: h1, h2, and so on. Due to the hierarchical manner in which a space
is exported, Confluence will modify the heading elements to generate a uniform appearance for the
entire space export. This means that headings will be demoted. This will affect the application of
custom PDF Stylesheets. It is possible to calculate the amount by which a heading will be demoted in
order to have the correct CSS styling applied. A heading will be demoted by the value of its depth in
the export tree. A page at the first level will be demoted by 1 (all <h1> elements will become <h2> ele
ments, and so on). A page at the second level will be demoted by 2, and so on.
Atlassian support for PDF customization is limited. We support the mechanism for customizing the
PDF layout with HTML and CSS, and we will help if the mechanism is broken or does not work as we
say it should in our published examples. But, since custom HTML and CSS offer potentially limitless
possibilities, Atlassian will not support issues that are caused by or related to PDF customizations.
Single page exports don't support adding HTML headers and footers via the PDF Layout page, but you can
use CSS rules in the PDF Stylesheet page (Space tools > Look and Feel > PDF Stylesheet) to produce
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 69
For example, the following rules add a document title at the centre of the header and a page number at the
centre of the footer:
Notes:
The font-family and font-size properties ensure that the header and footer text is rendered in
the same default font style used for the body text, based on the default CSS rules.
It is not possible to use this method to insert images (stored as attachments within your Confluence
instance) into the headers and footers of single page exports.
To insert an image into the header or footer, add HTML to the Header or Footer section of the PDF Layout
screen.
The following example uses an HTML img element with src attribute to add an image to the left of the
header. The src attribute refers to an image attached to a Confluence page. The image element is usually
placed within a div element container.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 70
In the example above, the header includes an image called 'header-image.png'. The "12346" in the src attrib
ute is the ID number of the page to which the image is attached.
Follow these instructions to include an image on your page:
1. Attach the image to a Confluence page.
2. View the list of attachments on that page, then right-click the image and copy its location.
3. Paste the link into the appropriate src="" attribute in your PDF Stylesheet, as shown above.
4. Edit the image URL so that it is relative, by removing the first part of the URL before /download/....
Notes:
This example uses an inline CSS property margin-top in the style attribute to force the image
away from the top of the page by 10mm. This comes in handy when your header image is large
enough to touch or spill over the top of the page.
Likewise, for footers, you can use the margin-bottom:XXmm property to force an image away from
the bottom of the page by 'XX' mm.
Very large images can spill over into the body of a page or alter the position of text or other elements
used within a header or footer. In such situations, it is recommended that you reduce the size of the
image and then attach it to your Confluence page again. If you prefer to keep the image size and want
to move the content lower instead, you can do so by configuring the margin-top properties in the @p
age CSS rule.
By default, a header or footer image is aligned to the left-hand side of the page. However, you can
align this image to the centre or right-hand side of a page by adding either the text-align:center
or text-align:right properties to your style attribute. For example, to align the header image to
the right-hand side of the page, your style attribute would look similar to this: style="margin-top
:10mm; text-align:right".
By default, Confluence provides Times New Roman, Helvetica or Courier fonts for use in PDF exports. You
can use your own fonts for PDF exports by declaring them in a @font-face CSS rule in your PDF
Stylesheet.
The following CSS rule example shows how to declare the Consolas font and apply it to some elements for
your PDF export:
The font path specified in the CSS must be the path to the font on the Confluence server.
When you export an arbitrary set of pages from Confluence, you may like to have a corresponding title added
to the cover (or title) page automatically. This can be done (in a somewhat irregular way) by using the top
level item from the default table of contents as the title. This method relies on having the exported pages
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 71
structured as sub-pages of the top-level page. In other words, the pages to be exported should consist of a
page (at the top-level) and all of its child pages. The result is that the title that appears on the cover page
changes depending on the top-level page that is used for the export.
The CSS below moves, and styles, the top-level TOC item for use as the title on the cover page, and turns
off the leader and page number normally associated with this item in the TOC.
This section describes a way to hide text from your PDF export. In other words, you can have text on the
Confluence page that will not appear in the PDF export.
There are three steps:
1. Follow the instructions to define the NoPrint user macro.
2. Use the NoPrint macro to mark some text on a Confluence page.
3. Add the following CSS to your PDF stylesheet to make the PDF export recognize the NoPrint macro:
Indexing
To obtain an index at the end of the exported PDF file, consider using the Scroll Wiki PDF Exporter plugin tha
t is produced by K15t Software GmbH.
Notes
If styling is not working as expected, it is useful to look at the intermediary HTML source to which the CSS is
applied. This intermediary HTML is created whenever you create an HTML export that contains multiple
pages, and is stored in the temp directory in Confluence's home directory. For example:
/temp/htmlexport-20110308-154047-1/export-intermediate-154047-2.html
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 72
1.
C:\WINDOWS\Fonts
/usr/share/fonts
Microsoft True Type core fonts such as Verdana can be downloaded from this page: http://coref
onts.sourceforge.net/
2. Copy the font file into a temporary folder, for example a folder on your desktop.
3. Choose the cog icon
Notes
The only font files supported are true type fonts and true type collections. The accepted file extensions
are *.ttf and *.ttc.
Confluence can only store one font file at any one time. Please create a collection to install more than
one *.ttf files.
We recommend that you use Unicode font Verdana for correct character encoding and exporting to
PDF.
If the font file size is bigger than your current attachment size limit, you will not be able to upload it.
Please increase the attachment size limit temporarily and re-upload again. An improvement of the
CONFSERVER-24706
error messaging is tracked at RESOLVED
To make use of an installed font in your PDF Export style sheet (CSS) refer to it by the font-family
ConfluenceInstalledFont.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 73
If you want to quickly create a blank page, hit the Create button in the header; if you want to create a
page from a template, hit the Create from template button.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 74
1. Select space: choose the space where you'll create the content.
2. Page templates: create a page from a template or create other types of content.
3. Parent page: your page will be a child of this page.
Once you decide on a blank page or blueprint, you'll be taken straight into the Confluence editor. The editor
is where you'll name or rename your page, add the content, and format it to look great. When you've added
some content, choose Preview to take a peek at what your finished page will look like, and Publish when
you're ready to make it appear in the space.
After you save you'll see the page in 'view' mode. You can re-enter the editor any time by choosing Edit or
pressing E on your keyboard.
1. Confluence header: create blank pages, pages from templates and visit spaces or your profile.
2. Space sidebar: access pages, blogs and administer the space.
3. Page tools: edit or share the page, watch it to get updates and perform more actions.
Another useful way to create a page is to use the Create from Template Macro. This macro allows
you to choose a page template, and adds a button to the page allowing one-click page creation. If
you want others to create pages using this template, this is a great option.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 75
Edit together
Need input from your team members? Multiple people can edit your page at the same time.
Hit the Invite button in the editor and either grab the link, or enter some people or groups to invite by email (t
hey need the appropriate Confluence and space permissions of course).
See Collaborative editing for all the ins and outs.
Collaborate or restrict
Once you've created a page, you can decide if you want to keep it private, using restrictions, or collaborate
on it with others using @mentions, sharing, and comments.
You can also organize pages in a hierarchy, with child and/or parent pages for closely related content. When
you navigate to a Confluence page and choose the Create button in the header, the page you're creating will
by default be a child of the page you're viewing. Have as many child pages and levels in the hierarchy as you
need to, and move pages if you want to change their location.
If you want to view all pages in a Confluence space, choose Pages in the sidebar.
Each time you create a page, you're creating it in a space. Spaces are containers used to contain
pages with related content, so you can set them up for each team in your organization, for projects, a
combination of both, or for any reason you want to group pages together. See Spaces for more
information.
If you rename a page, Confluence will automatically update all relative links to the page, except in
some macros. Links from external sites will be broken, unless they use the permanent URL. See Wor
king with Links for more information.
Notes
You may experience problems saving extremely large pages. Confluence can accept approximately 5mb of
content (not including attached files) which is roughly equivalent to 800,000 words. If you do experience
errors that indicate the page is too large to save, you should break up the page into several smaller pages.
Blog Posts
Blog posts are an easy way to share announcements, journal entries, status
reports, or any other timely information. Others can join in by commenting
on and/or liking your blog post and, if you get enough of either, your post
might make it to the popular feed on the dashboard!
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 76
Each space in Confluence, including your personal space, has it's own blog. On this page:
To view a space's blog, go to a space and choose Blog in the sidebar. You'll Create a
see a list of the latest blog posts, and you can click through to earlier posts blog post
via the navigation area in the sidebar. Move a
blog post
Restrict a
Create a blog post blog post
Delete a
You can follow the same process to create a blog post as when you create a
blog post
Confluence page.
Export a
1. Navigate to the space where you want to create your blog post blog post
2. Choose Create in the Confluence header and select Blog post
Related pages:
3. Add your content and choose Publish
Subscribe
You can create blog posts from the Dashboard, but you'll need to make sure
to RSS
you choose the space it's going to appear in in the create dialog.
Feeds
within
Confluenc
e
Blog Posts
Macro
Collaborati
on
Export
Content to
Word,
PDF,
HTML and
XML
Blog posts can be attractive and engaging in the same way a page can be, so go ahead and add images,
YouTube clips (preferably of cats), and tables to your post to really grab your audience.
To create a blog post, you need the 'Add Blog' permission. See Space Permissions.
If you create a blog post in the wrong space, or want to reorganize your spaces, you can move an individual
blog post to another space.
To move a blog post, go to the post and choose
You can restrict a blog post so that it is only available to specific users or groups. Blog post restrictions work
in the same way as page restrictions.
To restrict a blog post prior to publishing it, choose the Unrestricted button in the footer and apply your
restrictions. To restrict a blog post after publishing, choose
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 77
notification.
As a blog post has no parent, restrictions aren't inherited.
> Delete. Deleting a blog post follows the same rules as deleting a page.
You can export individual blog posts to PDF. This is useful, for example, if you want to email an internal blog
post to people outside your organization.
See Export Content to Word, PDF, HTML and XML for more information on exporting blog pages to PDF.
The Editor
The Confluence editor is what you'll use to create and edit Confluence
pages, blog posts, and comments. You can enter content as you would in a
Word document, apply formatting, and embed other content and files on the
page.
Note: To edit a page, you need the 'Add Pages' permission for the space.
See space permissions. Someone may also apply page restrictions that
prevent you from editing the page.
You'll be taken to the editor whenever you create a new page or blog post,
or add a comment. To edit an existing page or blog post, choose Edit at the
top of a page or press E on your keyboard.
Confluence automatically saves drafts of your page as you work. If another
user begins editing the same page as you, Confluence will display a
message and will try to merge the changes when you save your page. To
see changes between different versions of the page, look at the history of
the page.
The editor
The editor allows you to enter or change the title of your page; insert content
including text, images, and links; and format your content using the toolbar.
If you're renaming your page, there are some things you should take into
account.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 78
On this page:
Edit a
page or
blog post
The editor
Editor
toolbar
Restriction
s, labels,
and
notification
s
Things to
help you
work faster
Find and
replace
text
Invite
people to
edit with
you
Record
change
comments
and notify
watchers
Related pages:
Tables
Page
Layouts,
Columns
and
Sections
Display
Files and
Images
Links
Symbols,
Emoticons
and
Special
Characters
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 79
Editor toolbar
The editor toolbar is where you format your page layout and text, and add links, tables, images, attachments
and macros. You can also perform a find and replace, or get help using the editor by choosing the help icon
.
Screenshot: The editor toolbar
When editing a page, you may want to set restrictions on who can view or edit the page, or add labels to the
page to make it easily searchable.
Once you're ready to save, you can enter change comments to let others know what you've changed, and, if
you like, send an email notification to anyone watching the page.
Auto-formatting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 80
You can type Confluence wiki markup directly into the editor to have Confluence auto-format your text as you
type. To learn more, choose help icon
When you paste certain URLs into Confluence, the editor will analyze what you're pasting and automatically
convert it into something that will display well in Confluence. Examples include:
YouTube videos
JIRA issue queries
Google Maps
Confluence pages, blog posts, comments, user statuses, user profiles.
Shared screenshot links from Skitch
And more.
You can drag files, like images, multimedia, Office files and PDFs, from your computer and drop them directly
into the editor. The contents of the file will be embedded into the page or blog post.
In the editor panel, you can drag an image or a macro from one location to another on the page. Hover your
cursor over the image or the macro placeholder and your cursor changes to a drag-and-drop icon
Keyboard shortcuts
Click the
icon on the toolbar, or use the keyboard shortcut Ctrl+F (Windows) or Cmd+F (Mac OS).
Search matches are highlighted in yellow. You can step through the results one by one, replace the matching
text strings one by one, or replace all matching strings at once. Find and replace works only within the
current page.
Speed up your draft and review cycles and get input from the right people by inviting them to edit the page
with you. The page does not need to be published.
Hit the
button in the editor and either grab the link, or add people, groups or email addresses to invite, just like shari
ng a page.
Sharing or inviting someone to edit a page or blog post does not automatically grant any permissions - they
will still need the appropriate Confluence permissions to access Confluence and view or edit the page.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 81
Up to 12 people can edit the same page at the same time (your administrator can change this limit).
When you finish editing a page, you can add a comment to let others know what you changed. Type a short
message in the change comments field in the footer. The comment will be visible in the page history.
If you want to send a notification to people watching the page, select Notify watchers. The change comment
will be included in the notification email.
The Notify watchers checkbox remembers your last selection for each page, so if you choose not to notify
people, the checkbox will be deselected for you next time you edit that page.
Insert emoticons
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 82
:) :( :P :D ;)
To undo the conversion of a character combination into an emoticon, press Ctrl+Z (Windows) or Cmd+Z (Ma
c).
To prevent Confluence from converting text to emoticons automatically, disable 'Autoformatting' in your user
profile. See Edit Your User Settings.
Collaborative editing
Collaborative editing takes teamwork to the On this page:
next level by letting you and your team work together
in real time on software requirements, meeting Drafts and unpublished changes
notes, retros, and any other Confluence page. See Things you should know
who's editing the page with you, and see changes as
they happen. Hit
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 83
1. Invite more people: see who is editing the page and invite others to edit with you.
2. See what they're doing: watch others edit the page in real time.
What is a draft?
A draft is a page that has never been published before. Draft pages have a lozenge that says draft, and are
only visible to their author, and to anyone that author shares their draft with. Nobody else will be able to see
your draft, as it is only accessible from the Recently worked on list of each of the people who've contributed
to it.
A page with unpublished changes is a page that has been published, and has then had edits made to it, but
which has not yet been republished. Anyone who has unpublished edits will see the page in their Recently
worked on list, with a lozenge saying unpublished changes. People who haven't contributed to the
unpublished changes won't see this lozenge.
Those unpublished changes, however, are visible in the editor, and anyone can access them by editing that
page. Therefore, if you have unpublished changes and do not want someone else making additional changes
before they can be published, you might want to temporarily restrict editing on that page (leaving the
published version of the page visible).
We dont yet have the same auditing capabilities with collaborative editing. All page changes are currently
attributed to the person that publishes the page, rather than the person who made each specific change.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 84
Were saving all the time in collaborative editing, but we dont save versions in a draft. When restoring an
earlier page version, you can only roll back to published versions (the page draft is deleted when you restore
a previous version)
Collaborative editing introduces a new type of draft, a shared draft. Previously, when you edited a page but
didn't save it, Confluence would create a draft that was only visible to you (a personal draft). Now,
Confluence creates a shared draft whenever anyone edits a page. All page editors work on this same shared
draft, and it exists until someone publishes the page.
When you publish a shared draft, you're publishing all the changes you have made and changes made by
others. Publishing creates a version in the page history.
If you discard a shared draft, you're discarding all changes, including changes made by others. Because
shared drafts aren't versioned, there's no way to get a discarded draft back.
Any existing personal drafts are still available, but are no longer editable. If you edit a page, you'll see the
shared draft of the page, not your personal draft (if one exists).
If you need to get content out of your previous personal drafts head to Profile > Drafts, locate your page and
copy the contents.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 85
The page along with any attachments, comments, and child pages is moved to your chosen location.
Confluence will automatically adjust all links to the moved pages, to point to the page(s) in its new location.
When completing the New parent page field, you need to select the page suggested by
Confluence's autocomplete. Typing or pasting the page name (or using your browser's autocomplete)
won't work.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 86
You can change the location of a page within its space, and reorder pages in the hierarchy. This allows you
to:
Move a single page, or a family of pages, to a different parent within the space.
Reorder pages that are children of the same parent.
All links to the page are maintained. When you move a parent page, the entire hierarchy of child pages will
move too.
To move or reorder a page:
1. Go to the space and choose Space tools > Reorder pages from the bottom of the sidebar
2. Expand the branches to locate the page you want to move.
3. Drag the page to a new position in the tree.
Alternatively, you can choose to order a group of child pages alphabetically by choosing the Sort
Alphabetically (A-Z) icon. The Sort Alphabetically (A-Z) icon only appears next to the parent page if the
page family is currently sorted manually.
If you change your mind, you can use the Undo Sorting icon to revert back to the previous manual page
order. This option is only available immediately after sorting the page, while you're still on the Reorder
Pages tab, and haven't performed any other action.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 87
Copy a Page
If you need to duplicate the contents of a page, the easiest way is to copy On this page:
the page. You can copy pages into the same space or to a different space.
Copy
When you copy pages into the same space, you'll need to rename them, as pages
two pages with the same name can't live in the same space. We give you Copy the
some handy tools to help rename your pages during the copy process. contents of
an entire
You need the 'Create Page' permission to copy pages. See space
space
permissions for more information.
Related pages:
Copy pages
Create and
To copy a single page: Edit Pages
Move and
1. Go to the page and choose
Reorder
Pages
> Copy.
2. Choose a Location for the new page.
3. Hit Copy.
Confluence will open the copy of the page in the editor and name it 'Copy of [original page title]'. You can
then rename the page and work in the editor like any ordinary page.
To copy a page and all its child pages:
1. Go to the page and choose
> Copy.
2. Choose a Location for the new pages.
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 88
Here's some more info on what's included when you copy a page.
Attached files and Yes Optional - if you choose not to include attachments, you may see
images 'unknown-attachment' errors on the copied pages.
Comments No No
Restrictions No Optional - you may not be able to change this option if you don't have
appropriate 'Restrict' space permissions.
Watchers No No
History No No
Child pages with - Yes - if you have permission to see the child pages.
view restrictions
No - if you do not have permission to see the child pages.
Your space permissions and any existing page restrictions have an impact on what you can copy:
To copy pages you need the 'Create' page permission in the destination space.
To copy pages with restrictions in tact, you need the 'Restrict' page permission in the destination
space.
When copying a page and its child pages, you also have a choice to copy over any existing page restrictions.
This is useful if you need to maintain the current view or edit restrictions. If you don't have 'Restrict' page
permission in the destination space, you won't be able to choose this option.
Confluence does not provide an option to copy a space, however if your space has less than 1000 pages,
you can use copy page to copy all the pages in an existing space to a new space.
To copy the contents of a space to a new space:
1. Create a new space.
2. Go the homepage of the space you want to copy, and choose
> Copy.
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 89
That's it. You can now delete the homepage that was automatically added when you created the space.
Note that this is a new space, and no space settings (permissions, color schemes, templates etc) will be
copied. See these instructions on copying a space for some other workarounds.
When deleting a page that has child pages you have the option to delete the
entire page hierarchy.
To delete a page hierarchy:
1. Navigate to the parent page and choose
> Delete.
2. Choose Also delete child pages then hit Next.
3. We'll warn you of any issues, such as incoming links that will break.
Choose Delete to proceed.
The pages will be sent to the trash, where they can be restored by a space
admin.
Any pages that are restricted (that you are not allowed to see or delete) will
not be deleted and will move up to the nearest parent page.
Space admins can delete specific versions from the page history. This is useful if you need to prevent older
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 90
versions of a page being restored in future. Deleting a page version is permanent and cannot be undone.
To delete a specific version of a page:
1. Go to the page and choose
If you're a space admin you can restore deleted pages back into a space. This is useful if someone
accidentally deletes a page and needs to get it back.
To restore a deleted page:
1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Trash.
3. Choose
If you're a space admin you can permanently delete a page (and all its attached files) by purging it from the
trash. Once purged, the page and all its versions and attached files will be gone for good.
To purge deleted pages:
1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Trash.
3. Choose
> Purge next to a specific page or you can Purge all to completley empty the trash.
Any user with permission to edit a page can add labels to it. Any existing
labels appear at the bottom-right of the page, below the page content.
To add a label to a page or blog post:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 91
On this page:
Label a
page or
blog post
Label an
attachment
The
Labeled
content
page
Search by
label
Search for
labeled
pages
using a
URL
Remove
labels
Related pages:
Use Labels
to
Categorize
Spaces
Display
Pages with
Label
Macros
1. Go to the page
choose the
edit icon
If you're editing or creating a page, and you want to add labels, choose the label icon
Label an attachment
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
1.
Confluence 6.4 documentation 92
> Attachments
Go to the space and choose Space tools > Content Tools from the bottom of the sidebar,
then choose Attachments
You'll see a list of attachments, with any existing labels listed in the Labels column.
2. Choose the edit icon
beside the list of labels and type in a new label (existing labels are suggested as you type)
3. Choose Add
You can also add labels in a list of attachments displayed by the Attachments macro, by choosing the edit
icon
If you're viewing a page or post that has labels or displays the Attachments macro, you can choose any label
to go to the Labeled content page for the space. Choose Popular Labels or All Labels from the cog at the
top-right to view the most-used labels or all labels in the space or choose See content from all spaces fr
om the cog to view labeled content from all spaces in your Confluence site.
Screenshot: The Labeled content page
The Popular Labels option displays a word cloud, where the bigger a label is displayed, the more popular it
is. Choose any label to view content tagged with that label.
You can also navigate to the labels view for a space by entering the following URL (replace SPACEKEY with
the space's key):
<your.Confluence.site>/labels/listlabels-alphaview.action?key=SPACEKE
Y
Search by label
You can use the ' labelText: ' prefix to search specifically for content that has a specific label. For
example, if you're looking for pages with the label 'chocolate', type labelText:chocolate into the search
field in the Confluence header. For more examples of searching by label, see Confluence Search Syntax.
Entering a URL with an appended label or labels is another way to search for pages with particular labels.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 93
In your browser's address bar, enter the following URL and press enter: http://<your.Confluence.sit
e>/label/foo+bar
The Labeled content page will load, showing search results for pages with the both labels, 'foo' and 'bar'.
Replace 'foo' and 'bar' with the label(s) you want to search for, and separate multiple labels with a + symbol.
Remove labels
When viewing page, blog post, or attachment labels, an x appears alongside each label. Choose the x to
remove the label.
If you have deleted pages that contain a label, you may need to purge the deleted pages from the
space's trash to ensure that the label disappears too.
Here are some other macros that use labels, and can help you categorize and display your content.
The Navigation Map macro renders the list of pages associated with a specified label as a navigation map.
The Related Labels macro lists labels commonly associated with the current page's labels.
The Content by Label macro displays a list of content marked with specified labels.
The Content Report Table macro displays a set of pages and blog posts in tabular format, based on the
specified labels.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 94
The Labels List macro lists all labels of a space, grouped alphabetically.
The Recently Used Labels macro lists labels most recently used in a specified scope - global (site), space, or
personal.
The Popular Labels macro displays popular labels in a list or in a heatmap (also called a cloud).
Drafts
A draft is a page you've never published. Unpublis On this page:
hed changes are edits that you've made to a
published page, without republishing them. Find drafts and unpublished
changes
Confluence autosaves your drafts and unpublished Resume editing a draft
changes as you work, so if you get interrupted and Resume editing a page with
close your tab or navigate away, your content lives unpublished changes
on for you to resume editing when you're ready. Delete a draft
If you're creating or editing, but don't want to publish
your changes yet, hit Close at the bottom-right of the
editor. This will save those changes in the editor
without publishing, and you can return to them at
any point. Closing the editor will land you back on
the published version of the page, or, if you're
working on a draft, on your Recently worked on list.
Drafts and pages with unpublished changes appear in Recently worked on in the dashboard. You can
easily differentiate between these as they'll have a 'draft' or 'unpublished changes' lozenge next to their titles.
The 'unpublished changes' lozenge is only visible to people who have contributed to the draft or unpublished
changes, so you don't have to worry about it distracting your viewers.
You can find your drafts under Recently worked on or by heading to your profile and clicking on Drafts (only
drafts that you created show in your profile). Clicking on a draft will drop you straight into the editor so you
can keep editing and/or publish.
If you didn't enter a page title, the draft will be called ' Untitled'.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 95
If you've been editing a page that's already been published, you can find the page again either through the
page tree or under your Recently worked on. The 'Unpublished changes' lozenge makes them easy to spot.
Edit the page to see the unpublished changes and keep editing, then, when you're ready, hit Publish.
Delete a draft
Only the person who originally created a draft can delete it. To delete a draft, head to your profile picture at
top right of the screen and choose Drafts. Choose Discard next to the draft you want to delete.
Because drafts have never been published, you'll be deleting the entire page or blog post. Discarded drafts
are not sent to the trash.
Drafts in Confluence are shared, meaning other people can work on them with you. If you delete a
draft that other people have worked on, you're deleting their changes too.
Sometimes, another user may edit the same page as you're editing, at the
same time you do. When this happens, Confluence will do its best to ensure
nobody's changes are lost.
How will I know if someone else is editing the same page as I am?
If another user is editing the same page as you, Confluence will display a
message above your edit screen letting you know who the other user is and
when the last edit was made.
Screenshot: Concurrent editing notification
What happens if two of us are editing the same page and the other user saves before I do?
If someone else has saved the page before you, when you click Save, Confluence will check if there are any
conflicts between your changes and theirs. If there are no conflicting changes, Confluence will merge the
changes.
If there are conflicts, Confluence will display them for you and give you the option to:
Continue editing - Continue to edit the page; useful if you want to manually merge the changes.
Overwrite - Replace the other person's edits with yours (their edits will not be included in the latest
version).
Cancel - Discard your changes and exit the editor, keeping the other person's edits.
Example Scenario
For example, Alice and Bob both edit the same page at the same time.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 96
If Alice clicks save before Bob, Bob is now effectively editing an out-of-date version of the page. When Bob
clicks save, Confluence will examine his changes to see if any overlap with Alice's. If the changes don't
overlap (i.e. Alice and Bob edited different parts of the page), Bob's changes will be merged with Alice's
automatically.
If Bob's changes overlap with Alice's, Confluence will display an error message to Bob showing where Alice
has changed the page, and giving Bob the options to overwrite Alice's changes with his own, to re-edit the
document to incorporate Alice's work, or to cancel his own changes entirely, maintaining Alice's changes.
Page Restrictions
Page restrictions allow you to control who can view
and/or edit individual pages in a space. So, if you're On this page:
working on a page that shouldn't be viewed by just Restrict a page or blog post
anybody, it's easy to lock it down to the people who Remove restrictions from a page
need to know. You can add restrictions for Request and grant access to a
individuals or for Confluence groups. restricted page
View all restricted pages in a
To add or remove page restrictions, you'll need to space
have permissions to edit the page and 'Restrict' or Notes
'Admin' permission in the space.
In this example, some users and groups can view only, others can also edit, plus there are inherited
restrictions that might impact who can view the page.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 97
1. Speed it up: apply the same restriction to multiple people and groups.
2. Watch out: restrictions on other pages can affect this one.
3. Be specific: choose exactly what each group or person can do.
Who is 'everyone'?
When we say "everyone can view this page" everyone means all the people who can view the page by
default. There's two things that can affect who can view a page - the space permissions, and view restrictions
on any parent pages that are being inherited.
Restrictions don't override a person's space permission. For example, if you say a person 'can view' in the
restrictions dialog and they don't have 'view' permissions for the space, they won't be able to see the page.
View restrictions are inherited, which means a restriction applied to one page will cascade down to any child
pages. Edit restrictions are not inherited, which means pages need to be restricted individually.
The restrictions dialog will tell you when there are inherited restrictions that might affect who can view your
page.
Here's the basics:
If you restrict viewing to a person or group, only they will be able to see that page and all its child
pages (unless there are further restrictions on the child pages).
If you restrict editing to a person or group, they'll be able to see and edit that page, plus see its child
pages.
Parent pages (higher up in the page hierarchy) can have their own view restrictions that may prevent
people from viewing your page.
If the person you've listed as a viewer or editor can't see the page, check to make sure:
they have View space permission for that space, or
there's no view restriction on a page higher up the page hierarchy that prevents them seeing any
children of that page.
The restrictions icon at the top of the page gives you a clue that the page has restrictions:
Viewing this page is not restricted. Everyone can see this page (but editing may be restricted).
The page is restricted. Click the icon to see the list of who can view and edit this page.
The page is inheriting restrictions from another page. Click the icon then choose Inherited
Restrictions to see a list of pages this page is inheriting restrictions from.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 98
Removing restrictions is easy. Choose No restrictions to remove all restrictions, or click Remove next to
each person or group in the list if you want to change who can view or edit the page.
If you navigate to a page that you're not able to view or edit because it has page restrictions applied (for
example from a link or page URL) you may be able to request access to the page.
To request access to a restricted page:
1. On the restricted page choose Request access.
2. Wait for an email confirming that access has been granted.
If the request access message doesn't appear, you're not able to request access for that particular page.
This usually is because the page has inherited view restrictions from a parent page, or you may not have
adequate space permissions.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 99
You need space admin permissions to view the list of restricted pages in a space.
To view restricted pages:
1. Go to the space and choose Space tools > Permissions from the bottom of the sidebar
2. Choose Restricted Pages.
Screenshot: Restricted pages in a space
Notes
Links
You can create links to pages, blog posts, anchors, attachments, external
websites, JIRA issues and more. Links can be text or images, and can be
added in many different ways.
Links to pages within your Confluence site are relative, which means that
you can move pages and rename pages without breaking links.
This page explains the most common ways to create links.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 100
3. Select a page, blog post or attachment, or enter an external URL (see On this page:
below for how to link to particular types of content) Insert a
4. Enter or modify the link text (this is the text that will appear on the text link
page. If this field is left blank, the page name or URL will be used as Insert an
the link text.) image link
5. Choose Insert Modify a
link
Alternatively you can type [ followed by the page or attachment name. Autoc
Remove a
omplete will suggest matching items for you.
link
Link to
specific
types of
content
Link to
Confluenc
e pages
from other
websites
Link to a
comment
Using
shortcut
Links
Trackback
Related pages:
Anchors
Inserting
JIRA
Issues
The Editor
You can also paste a URL directly onto your page. Confluence will automatically create the link, and if the
URL is for a page in the current site, the page name will be set as the link text.
Modify a link
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 101
Remove a link
Confluence supports many methods for creating links. Some of the common ones are listed here.
Link to a page Choose Link > Search then enter part of the page name.
Choose Link > Recently viewed and select a page from the list.
Type [ and enter part of the page name then select the page from the list.
Paste the URL of the page onto your page (Confluence will automatically create the
link).
Link to a page in Choose Link > Search enter part of the page name and select All Spaces from the
another space drop down.
Choose Link > Advanced then enter the space key followed by the page name spa
cekey:mypage.
Type [ and enter part of the page name then select the page from the list.
(you can hover over each suggestion to see which space the page is from).
Link to a blog post Choose Link > Search and enter part of the blog post name.
Type [ and enter part of the blog post name then select the blog post from the list.
Link to an Choose Link > Attachment then upload or select an attachment from the list.
attachment or
image on this page Type [ and enter part of the attachment file name then select the attachment from
the list.
Link to an Choose Link > Search and enter part of the attachment name.
attachment on
another page Type [ and enter part of the attachment file name then select the attachment from
the list
(you can hover over each suggestion to see which space the page is from).
Link to a website Choose Link > Web Link then enter the website URL.
Type or paste the URL onto the page (Confluence will automatically create the link).
Link to an email Choose Link > Web Link then enter the email address.
address
Type or paste the email address onto the page (Confluence will automatically create
a 'mailto:' link).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 102
Link to an anchor Choose Link > Advanced then enter the anchor name in one of the formats below.
on a page
For an anchor on this page: #anchor name.
Link to a heading Choose Link > Advanced then enter the heading in one of the formats below.
on a page Heading text is case sensitive and must be entered without spaces.
For a heading on this page: #MyHeading.
Be aware that these links will break if you edit the heading text. Consider using the
Table of Contents macro or an Anchor instead.
Link to a comment Go to the comment, right click the Date at the bottom of the comment and copy the
on a page link. Paste the link directly onto your page or choose Link > Web Link and paste in
the URL.
Type [$ then enter the Comment ID ('12345' in this example): [$12345]
Link to an Choose Link > Advanced then enter the new page name (a page will be created on
undefined page click).
(a page that does
not exist yet) Type [ then enter the new page name then choose Insert link to create page .
See Undefined Page Links for more information on undefined pages.
Link to a personal Choose Link > Search then enter the user's name and select their personal space
space or user homepage or their profile from the list.
profile
Type [ then enter the user's name and select their personal space homepage or
their profile from the list.
Link to a JIRA issue Paste the JIRA issue URL - Confluence will automatically create a JIRA Issue
(where Confluence macro.
is connected to
JIRA)
The best way to link to a Confluence page from outside Confluence, for example from another site or in an
email, is to use the share link which is a permanent URL. This ensures that the link to the page is not broken
if the page name changes.
To access the permanent URL for a page:
1. View the page you wish to link to.
2. Choose Share.
3. Copy the Share link.
You do not need to use the share link to link to pages within your Confluence site. Confluence automatically
updates links when you rename or move a page to another space.
If you want to link to specific content such as anchors, headings or comments you need to use the following
link syntax. Note that there are no spaces in the page name, anchor name or heading text.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 103
In the examples below, the anchor name is 'InsertLinkAnchor' and the heading text is 'Insert a link'.
Link to http://myconfluence.com/display/spacekey/pagename#pagename-anchorname
an
anchor Example from this page:
(from an https://confluence.atlassian.com/display/DOC/Working+with+Links#WorkingwithLinks-
external
website)
Link to a http://myconfluence.com/display/spacekey/pagename#pagename-headingtext
heading
(from an Example from this page:
external https://confluence.atlassian.com/display/DOC/Working+with+Links#WorkingwithLinks-
website)
Link to a http://myconfluence.com/display/spacekey/pagename?focusedCommentId=commentid#comm
comment
(from an Example from this page:
external https://confluence.atlassian.com/display/DOC/Working+with+Links?focusedCommentId=
website)
Some things to note when linking to anchors from a website or email message:
The page name is repeated in the URL, after the # sign. The second occurrence of the page name is
concatenated into a single word, with all spaces removed.
There is a single dash (hyphen) between the concatenated page name and the anchor name.
The anchor name in the full URL is concatenated into a single word, with all spaces removed.
The anchor name is case sensitive. You must use the same pattern of upper and lower case letters as
you used when creating the Anchor.
Link to a comment
You can add a link to a comment by using the comment URL (a permanent link), or by using wiki markup to
link to the Comment ID.
To find out the comment URL and comment ID:
1. Go to the comment you wish to link to
2. Choose the Date at the bottom of the comment and examine the URL
The number after 'comment-' is the Comment ID. An example is shown here.
https://confluence.atlassian.com/display/DOC/Working+with+Links?focus
edCommentId=368640803#comment-368640803
You can use wiki markup directly in the editor to link to a comment. Enter [$ followed by the Comment ID, for
example [$12345] where '12345' is the Comment ID.
If you have configured shortcut links on your Confluence site, then you can link to an external site using a
shortcut link that looks like this:CONF-17025@jira.
Our Confluence site (where this documentation is housed) is configured to allow shortcut links to our JIRA
site, using the shortcut @jira. So the shortcut link CONF-17025@jira produces this link.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 104
2. Modify or enter link text (this is the text that will appear on the page)
3. Choose Insert
You can also type '[' and choose Insert Web Link > Advanced to enter a shortcut link.
See Configuring Shortcut Links for more details.
Trackback
Trackback enables two sites can stay informed each time one site refers to the other using trackback 'pings'.
In Confluence, Trackback can be enabled by a site administrator in the Administration Console. 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 see who has sent a Trackback ping to a Confluence page:
1. Go to the page
2. Choose Tools > Page Information
Any Trackback pings the page has received will be listed under the page's Incoming Links.
Confluence incoming trackback pings only work with referenced pages that are public (anonymously
viewable).
Anchors
On this page:
You can use anchors to enable linking to specific locations on a page, and
they can be especially useful for allowing your readers to navigate to Step 1:
specific parts of a long document. Anchors are invisible to the reader when Create the
the page is displayed. anchor
Step 2:
There are two steps to using an anchor:
Create a
Step 1: Create the anchor link to the
anchor
Step 2: Create a link to the anchor Notes
Related pages:
Step 1: Create the anchor
Links
Add the Anchor Macro to mark the location you want to link to:
1. Do either of the following in the Confluence editor:
Choose Insert > Other Macros, then find and select the
Anchor macro
Type { and the beginning of the macro name, then select the
Anchor macro
2. Enter the Anchor Name (For example, 'bottom' or 'important
information')
3. Choose Insert
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 105
Anchor None This is the anchor name that you will use when creating the link.
Name
The anchor name can include spaces. Confluence will remove the spaces
automatically when building a URL that points to this anchor.
The anchor name is case sensitive. You must use the same pattern of upper
and lower case letters when creating the link as you used when creating the
Anchor macro.
4. Enter or modify the Link Text (this is the text that will appear on the page. If this field is left blank, the
page name or URL will be used as the link text)
5. Choose Save
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 106
http://myconfluence.com/display/spacekey/pagename#pagename-anchorname http://myconfluence.com/
http://myconfluence.com/
Notes
Table of contents on a page: Consider using the Table of Contents Macro to generate a list of links
pointing to the headings on the page. The list of links will appear on the page, and will be
automatically updated each time someone changes the wording of a heading.
Linking to headings: You can link directly to the headings of a page. See Links. However, if
someone changes the wording of a heading, those direct links will be broken. Use the Anchor macro
to ensure a lasting link within the body of a page.
Site welcome message: If you are adding an anchor to a page that you are using in the site welcome
message, you can only link to that anchor from another page. Internal links within that page will not
work.
Templates: When you are previewing a template, a link to an anchor is displayed as a 'broken' link.
However, when you create a page using the template the resulting page will have the correct link.
Tables
Confluence tables allow you to present important information and discuss it On this page:
with your team. Use familiar table formatting options resizing columns, Insert a
coloring cells, rows and columns, and sorting the table by clicking the table
column headers to view the information the way you like it. Edit your
table
Shortcut
Insert a table keys
Sort the
To create a table:
table in
1. Hit the Table button in the toolbar view mode
2. Click a cell in the drop-down to set the number of columns and rows Sticky
in your table table
headers in
view mode
Screenshot: Insert a table with 3 rows and 3 columns Related pages:
Page
Layouts,
Columns
and
Sections
The Editor
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 107
To resize table columns, just click and drag the column's border. To make other changes to your table, click
inside it to reveal the table toolbar.
Here's a summary of the table tools:
Rows
Insert rows before or after the current row
Delete the current row
Cut, copy and paste the current row
Mark a row as a header row (shaded with bold text)
Columns
Insert columns before or after the current column
Delete the current column
Cut, copy and paste the current column
Mark a column as a header column (shaded with bold text)
Cells
Merge selected cells
Split selected cells
Change cell color
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 108
Table
Delete table
Add a numbering column to automatically number each row
Shortcut keys
Ctrl+Shift+c Copy the current table row, or the selected rows. Cmd+Shift+c
Ctrl+Shift+v Paste the table rows from your clipboard, placing them above the Cmd+Shift+v
current row.
Ctrl+Shift+x Cut the current table row, or the selected rows. Cmd+Shift+x
Alt+Up Arrow Add a row above the current row. Alt+Up Arrow
When viewing a table on a page, you can sort it by clicking the sort icons in the header row.
Screenshot: A colorful, sortable table
In some instances table header rows will stick to the top when you're viewing a page, making those really lon
g tables easier to read. There are a few exceptions, though. Table headers aren't sticky when your table:
Is inside a page layout, inside another table, or inside a macro.
Has no header row or there are cells in the top row that aren't marked as headers.
Has a header column, instead of a header row, and scrolls horizontally.
Contains another table, that has its own header row.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 109
Keep track of the things that need to get done with tasks. With the ability to On this page:
give each task an assignee and due date, and plenty of ways to see your Add a task
tasks, you can make sure nothing slips through the cracks. View tasks
Notes
Add a task
You can add tasks on any page in Confluence. For example, you might add
tasks under action items on a meeting notes page, or in a project planning p
age anywhere you need a lightweight task management solution.
To create a task:
1. In the editor, choose the Task list
View tasks
There are a number of ways to keep track of tasks assigned to you, or tasks you've created for others.
On a page
The simplest way to see a task is on the page it was originally created on. It's easy to see if a task is
complete, who it's assigned to, and when it's due. If a task is nearing or passed its due date, the color of the
date will change (red for overdue, orange for due in the next 7 days).
In your profile
The tasks page in your profile gives you a place to see all the tasks relevant to you. Easily keep track of the
status of tasks assigned to you, and tasks you've created and assigned to others.
To view the tasks page, go to Profile > Tasks. Use the filters to show tasks that were assigned to you or
created by you in the last 6 months, and toggle between complete or incomplete tasks.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 110
If you need to see more than just your last 6 months of tasks, use a Task Report.
In a Task Report
If you're looking for a more custom view of tasks, the Task Report blueprint is a great way to track tasks
assigned to a specific team or project.
To create a task report:
1. Choose Create > Task Report
2. Select the type of report:
Assigned to my team for tasks assigned to particular people.
In my project for tasks that appear in a specific space or page.
Custom for a wide range of filtering options, including by date or page label.
3. Follow the prompts to create the report.
This blueprint uses the Task Report Macro. You can also choose to use this macro on an existing page, for
example, on a project or team space homepage.
Notes
The date picker can be triggered by typing // or by typing a date in the format dd/mm/yyyy or
dd-mm-yyyy. Typing other date formats in the editor won't trigger the date picker.
Personal Tasks (created in the Workbox in older versions of Confluence) don't appear in the Tasks
view or Task Report. To migrate any incomplete personal tasks, go to Workbox > Personal Tasks an
d follow the prompts.
The wiki markup based Tasklist Macro has been removed from the macro browser. If you have a
Tasklist macro on a page it will continue to work, but you will be unable to add new Tasklists using this
macro.
Summary of autocomplete
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 111
Type '[', or press Ctrl+Shift+K, to see a list of suggested pages or other locations to link to from your page.
You can link to pages, user profiles, images, documents and other file attachments.
To autocomplete a link:
1. Edit the page.
2. Click where you want to insert a link and do one of the following:
Type '[' and then the first few characters of the page title, user's name, image name or file
name.
Type the first few characters of the page title, user's name, image name or file name (or select
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 112
You can use the autocomplete as a fast way of embedding images, videos, audio files and documents into
your page. Type an exclamation mark or press Ctrl+Shift+M to see a list of suggested images, multimedia
files and documents to display on your page. You can use autocomplete to embed the following file types:
Images any format that Confluence supports.
Videos, audio files and all multimedia formats that Confluence supports.
Office documents supported by the Confluence Office Connector: Word, Excel and PowerPoint.
PDF files.
Autocomplete works most efficiently for files that are already attached to the Confluence page.
To embed an image, video, audio file or document:
1. Edit the page.
2. Click where you want to insert the image, video, audio file or document and do one of the following:
Type '!' and then the first few characters of the image, file or document name.
Type the first few characters of the name of the image, file or document (or select relevant text)
and then press Ctrl+Shift+M.
3. Choose the relevant file from the list of suggestions.
If the item you need is not in the list, either:
Choose Open Image Browser to find images and documents using the image browser, or
Choose Insert Other Media to embed videos, audio and other multimedia files using the macro
browser. Insert the 'Multimedia' macro to display your multimedia file.
Screenshot: Autocomplete for an image or document
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 113
You can use autocomplete to automatically notify another Confluence user that you have mentioned them in
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 114
a page, blog post, or comment. Type '@' and part of the person's name, to see a list of suggested users.
Note: Use the person's full name. Autocomplete will recognize users' full names only, not their usernames.
Canceling autocomplete
The autocomplete starts automatically when you press the trigger characters. You may want to close the
autocomplete menu or escape from autocomplete once it has started.
There are a few different ways to stop the autocomplete once it has started:
Press the escape key, 'Esc', on your keyboard.
Click somewhere else in the editor panel.
Press an arrow key to move out of the autocomplete area.
For the link autocomplete only: enter a right-hand square bracket, like this: ]
You can turn off the triggering of autocomplete by the '[' and '!' characters. This will prevent the autocomplete
from starting automatically when you press one of the trigger characters. You can also turn it back on again.
Notes:
This setting does not affect the keyboard shortcuts for autocomplete (Ctrl+Shift+K and Ctrl+Shift+M).
Even if the trigger characters are disabled, you can still use the keyboard shortcuts for autocomplete.
This setting affects only you. Other people using Confluence can enable or disable the setting on their
user profiles independently.
Note that autocomplete is enabled by default.
To enable or disable the autocomplete trigger characters:
1. Choose your profile picture at top right of the screen, then choose Settings
2. Choose Editor under 'Your Settings' in the left-hand panel.
3. Choose Edit.
4. Either:
Disable autocompletion by selecting Disable Autocomplete.
Enable autocompletion by clearing Disable Autocomplete.
5. Choose Submit.
Screenshot: User settings for the editor
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 115
Ignoring autocomplete
You can add macros, links and images by wiki markup alone. Type the macro, including its parameters and
the closing curly bracket. Add a link, such as an anchor link, and end it with a square bracket. Insert an
image or other embedded object, enclosed between exclamation marks. As soon as you close the macro,
link, or embedded image, Confluence will convert it to rich text format and add it to the page.
For more information about mouse-free macros, links and images, choose Help
Screenshot: Editor view of a page showing three sections with different column configurations.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation
1. 116
Column width The width of the columns are fixed. If you need more than three columns, or columns
of a specific width, you should use the Section and Column macros described below.
Very wide tables The width of each column is set to a percentage of the page width. The icons in
the drop-down menu indicate the relative widths for each layout. In most cases, Confluence will adapt
the width of the columns to fit the width of the page. If a column includes an item that's too wide for it,
you'll see a horizontal scroll bar when viewing the page.
You can use the Section and Column macros to add a set of columns to the page. The Section macro
defines an area that will contain the columns. You can have as many sections as you like. Within each
section, you can have as many columns as you like.
The Section and Column macros are useful if you want to define a specific percentage or pixel width for each
column.
To add a section and some columns to a page:
1. In the Confluence editor, choose Insert > Other Macros
2. Find the Section macro, select it and insert it onto the page
3. Choose Insert > Other Macros again
4. Find and insert the Column macro
5. Add your content to the column
Insert as many columns as you like within the section.
You should always have at least one column macro within a section macro. Using a section macro
without any column macros can negatively affect page loading time.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 117
When you see the page in view mode, the above layout is displayed like this:
Content for column 1 goes here
Content for column 2 goes here
Macro parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Show Border false Select this option to draw a border around the section and columns.
Note: Without a Column macro , the border will not be displayed correctly.
Column 100% of the page width, divided Specify the width of the column, in pixels (for example,
Width equally by the number of columns 400px) or as a percentage of the available width (for
in the section. example, 50%).
All content within your section must be enclosed within a Column macro, otherwise the section layout
will not work as expected.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 118
People. Add a Profile Picture Macro to show a picture of a Confluence user, or a User Profile Macro to show
a summary of the person's profile as well as their avatar.
Multimedia. You can display movies, animations and videos, and embed audio files on your Confluence
page. For example, Confluence supports Adobe Flash, MP3, MP4, and various other movie formats. See Em
bedding Multimedia Content.
Social video and image sharing. The Widget macro displays live content from social sites such as YouTub
e and other video sharing sites, and Flickr for shared photographs. See the guide to the Widget Connector
Macro.
The Chart Macro offers a variety of graphs and charts that you can use to illustrate statistics and other
numerical data.
Illustration: A 3-dimensional bar chart produced by the Chart macro
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 119
Display PDF files in Confluence too, also with the View File Macro.
Use the Widget Connector Macro to show slide decks hosted on SlideShare and other online
presentation sites.
Many project teams and customers also use JIRA applications such as JIRA Software or JIRA Service Desk.
Rather than copying and pasting issues onto your Confluence page, you can display it directly from the
source, thus ensuring that the information shown in Confluence is always up to date.
Link to a feature request in your issue tracker, or display a list of fixed issues useful for release notes and
project planning. See the JIRA Issues Macro.
A number of Confluence add-ons provide sophisticated tools for creating diagrams and mockups.
For example:
Balsamiq Mockups for Confluence
Creately for Confluence
Gliffy Confluence Plugin
Graphviz Plugin for Confluence
Lucidchart for Confluence
Search the Atlassian Marketplace for more add-ons.
Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's
information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our
guidelines on add-on support.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 120
You can build up a custom layout by using the page layout tool to add sections and columns to your page.
See the detailed guidelines to Page Layouts, Columns and Sections.
Do you need to display tabular data, which your readers can sort when viewing the page? See Tables.
Use other macros to highlight and format sections of your page:
Panel
Info, Tip, Note, and Warning
Code block
Noformat
People share information on various social sites. You can make Confluence a focal point where people
collect their shared information and see what is happening in the areas that matter to them.
Use the Widget Connector macro:
Show a live stream of tweets from a Twitter user, or tweets matching a Twitter search.
Display a video from YouTube or other online movie sites.
Share photographs from Flickr.
See what else the Widget Connector macro can do.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 121
Page Templates
When you add a new page, you don't have to start from scratch. Instead,
you can base your new page on a template a Confluence page with
predefined content. Some templates are provided by blueprints or add-ons,
and you can even create your own templates.
Some examples of useful templates are:
The meeting notes template will help you and your team collaborate
on notes and follow-up tasks
The requirements template allows you to capture your
software/hardware product requirements, and create related JIRA
issues from the page
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 122
On this page:
Global
templates
and space
templates
Create a
template
Use a
template
Templates
provided
by
blueprints
Promote
templates
in the
Create
dialog
System
templates
Related pages:
Create a
Template
Administeri
ng Site
Templates
Importing
Templates
Create a
Page from
a Template
Create a template
You can write your template using the Confluence editor. You can also add special variables to the page, if
you want to include fields that the author will complete when adding the page. See Create a Template for
more information.
Use a template
Page templates are used only when adding a page. It is not possible to apply a template to an
already-existing page. Once a page has been added using a template, the template is no longer linked to the
page. All further editing is performed as if the template was never used. Some plugins provide enhanced
template functionality. You can search the Atlassian Marketplace for template add-ons. See Create a Page
from a Template for more information.
A blueprint is a page template with added functionality to help you create, manage and organize content in
Confluence, and there's a collection of predefined ones that ship with Confluence. You can also download
additional blueprints from the Atlassian Marketplace. You can customize the blueprint templates to suit your
individual needs, disable particular blueprints or even develop your own blueprints.
If you're a space administrator, you can choose to promote specific templates and blueprints in the Create
dialog. Promoting items can help ensure consistency in a space by encouraging users to create particular
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 123
System templates
Confluence also provides 'system templates' containing content like the site welcome message and default
space content. See Administering Site Templates.
Create a Template
In Confluence, there are two categories of page templates:
Space templates: These page templates are available in a specific
space only. If you have space administrator permission, you can
define templates via the space administration screen.
Global templates: These page templates are available in every
space on your site. If you have Confluence Administrator permission,
you can define global templates via the Confluence Administration
Console.
Add a template
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 124
On this page:
Add a
template
The
template
editor
Tem
plat
e
vari
able
s
Lab
els
Ima
ges
and
othe
r
atta
chm
ents
Instr
ucti
onal
text
Add a
description
to your
template
Edit or
delete a
template
Notes
Related pages:
Create a
Page from
a Template
Page
Templates
Add,
Remove
and
Search for
Labels
Macros
The Editor
Check out the article How to document releases and share release notes to see how helpful creating
templates in Confluence can be.
When you create or edit a template, you'll be using the editor in much the same way as when you edit a
page or blog post. In addition you can add variables, which will produce a form for data collection when
anyone adds a page based on the template.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 125
Screenshot: The template editor with an image, table, text, and variables
Screenshot: The form displayed when you create a page based on the template
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 126
Template variables
When you add variables to your template, they will act as form fields. When you create a page based on a
template, you'll see a text entry box for each field. Enter data into each field, and it'll be added to the page.
You can add the same variable more than once in the same template, which is useful if you need the same
information in more than one place on the page.
To insert a variable into a template:
1. Choose Template > New Variable from the editor toolbar (or choose an existing variable to add it to
the page)
2. Enter a name for the variable
3. Press Enter (by default this will create a single-line text input field)
To change the variable type, click the variable placeholder and the variable's property panel will appear.
Choose one of the variable types: Text, Multi-line Text, or List.
You can change the number of lines and width in characters of a Multi-line Text field. If you choose List,
enter each of the items in your list, separated by commas.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 127
Hint: Type $ and the variable name, then press Enter to add a new variable or to select an existing variable
from a list of suggestions. The suggestions dialog shows variables already defined in this template.
Labels
If you'd like all pages created using this template to have one or more labels, choose the labels icon
You can't upload an image or other file into a template directly. First you'll need to upload the file to a page in
your site, then in your template, choose Insert > Files > Search on other pages to embed the file or image.
Instructional text
Instructional text is placeholder content in a template, and is only visible while you're editing the page. Use it
to give guidance to whoever is creating a page from the template.
To insert instructional text:
1. Choose Template > Instructional Text in the toolbar
2. Type in your instructional text (for example, Insert an image of the interface here.)
Instructional text appears in italics with a shaded background, to distinguish it from normal paragraph text.
You can also change the placeholder type from Text to either:
User mention Opens the user mention dialog.
JIRA Macro Opens a dialog that allows you to create a new JIRA issue, or search for one or more
JIRA issues to include on the page.
The template description displays in the 'Create' dialog, and is useful for explaining the purpose of your
template to other users.
To add a description to a template:
Go to the space or global templates page (as described above)
Choose the Edit icon in the 'Description' column
Enter your description and choose Save
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 128
If you need to change anything about your template, or want to delete it, navigate to either your space or
global template (as described above) and choose either Edit or Delete.
Notes
Page templates are used only when adding a page. It is not possible to apply a template to an
already-existing page. Once a page has been added using a template, the template is no longer linked
to the page. All further editing is performed as if the template was never used. Some plugins provide
enhanced template functionality. You can search the Atlassian Marketplace for template add-ons.
When you use a Table of Contents macro in a template, you'll see an error when you preview the
template, but the Table of Contents macro works on the pages that people create from the template.
The editor for templates is available only in Confluence 4.3 and later. Please refer to the earlier
documentation for a description of the wiki markup editor templates.
Confluence also provides 'system templates' containing content like the site welcome message and
default space content. See Administering Site Templates.
If the template author included variables in the template, Confluence will display a form prompting you to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 129
supply values for the variables when you add the page.
Notes
Page templates are used only when adding a page. It is not possible to apply a template to an
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 130
already-existing page. Once a page has been added using a template, the template is no longer linked to the
page. All further editing is performed as if the template was never used. Some plugins provide enhanced
template functionality. You can search the Atlassian Marketplace for template add-ons.
Blueprints
What's a blueprint? On this page:
What's a
A blueprint is a set of page templates with added functionality to help you blueprint?
create, manage and organize content in Confluence more easily. Create
Create meeting notes, shared file lists and requirements documentation out content
of the box, and Customize the blueprint templates to suit your individual using a
needs. You can even develop your own blueprints. blueprint
Customize
blueprint
Create content using a blueprint templates
Promote
1. Choose Create from template blueprints
in the
Create
in the Confluence header dialog
2. Select a blueprint from the create dialog Add more
3. Hit Create blueprints
Disable a
The editor will open, and, depending on the blueprint selected, a prompt to blueprint
enter information or the page will appear. You can now follow the Full list of
instructions built in to the blueprint to add content. blueprints
Related pages:
Page
Templates
Request
Add-ons
The first time a blueprint is used in a space, Confluence creates an index page and adds a shortcut to your
sidebar (if you're using the default theme). The index displays a list of pages made with the blueprint, and
information selected information from your blueprint pages. For example, the meeting notes index displays a
list of all meeting notes pages in the space, who created them, and when they were last modified. Here's the
index page for the Meeting Notes blueprint:
1. Easy to find: notes from all your meetings are listed here.
2. Start a new meeting: create a new meeting notes page here.
Blueprints are made up of templates that can be customized for an individual space or the whole site. This
means you can adapt the content of the blueprint pages to suit your specific needs. For example, you might
update the Meeting Notes blueprint templates to include a heading for apologies.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 131
If you have space administrator permissions, you can customize blueprint templates for the spaces you are
an administrator of. You must be a Confluence Administrator to customize blueprint templates for a whole
site. See Administering Site Templates for more information.
To customize a blueprint template for a space:
1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Edit beside the blueprint template you wish to edit
3. Make your changes to the template and choose Save
Editing a blueprint template is very similar to editing a page template, except:
Be careful not to remove any macros that the blueprint page or index page may use to store and
display information
You can't remove a blueprint template or change the template name
To reset a blueprint template back to the default:
1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Reset to default beside the blueprint template you wish to reset
See Working With Templates and Administering Site Templates for more information on templates.
As with user created space and site templates, editing a blueprint template will not change existing pages,
but any new blueprint pages will be based on the updated template.
If you're a space administrator, you can choose to promote specific templates and blueprints in the Create
dialog. Promoting items can help ensure consistency in a space by encouraging users to create particular
types of content, instead of blank pages.
The promoted templates or blueprints will appear at the top, with all other content types, including Blank
Page and Blog Post collapsed under them. To view the other types of content available choose the Show
more link.
You can find more blueprints for Confluence in the Atlassian Marketplace. Blueprints are managed using
add-ons (also known as plugins).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 132
See Request Add-ons for information on how you can search for new blueprint add-ons and send a request
to your System Administrator.
If you are a System Administrator, see Managing Add-ons or Plugins for information on how to install new
blueprint add-ons.
You can also develop your own blueprints. See our developer documentation on Writing a Blueprint.
Disable a blueprint
You may want to disable particular blueprints. For example, you may not want to see the Product
Requirements blueprint in the create dialog in an HR or Social space. If you are a Confluence Administrator
you can also disable particular page and space blueprints for the whole site.
To disable a blueprint in a space:
Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
Choose Disable next to the blueprint you wish to disable in that space
You can re-enable the blueprint at any time.
To disable a blueprint across a whole site:
Choose the cog icon
, then choose General Configuration under Confluence Administration (You need Confluence
Administrator permissions to do this)
Choose Global Templates and Blueprints
Choose Disable next to the page or space blueprint you wish to disable
The blueprint will not appear in the 'Create' or 'Create Space' dialogs.
Decisions Blueprint
The Decisions blueprint helps you make decisions and record the outcomes
with your team.
The first time you use the Decisions blueprint in a space, Confluence will
create an index page and add a shortcut on your space sidebar (if you're
using the default theme). The index acts as your Decision Register and lists
all the decisions in that space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 133
If you want to quickly create a blank page, hit the Create button in Related pages:
the header; if you want to create a page from a template, hit the Cre
ate from template button. Blueprints
File List
Blueprint
Meeting
Notes
Blueprint
1. Create blank page
Product
2. Create from template
Requireme
nts
To create a decision page: Blueprint
1. Choose Create from template
Once you save your first decision page, Confluence will create a decision register page for the space you're
in, and add a shortcut to it in the space's sidebar. The decision register and lists all the decisions in that
space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 134
For an example of the Decisions Blueprint, and some other great page elements, check out: How to
make better decisions as a development team.
You can customize the templates that are used by the Decisions blueprint - see Customizing the blueprint
templates. For example, you might choose to edit the decisions index page in a space to change the
columns displayed by the Page Properties Report macro.
You can also edit the page template to add headings or instructional text to the background section, or even
add rows to the Page Properties macro. For example, a row for the date the decision was made.
See Instructional text to find out more about using instructional text in templates.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 135
1. Space shortcut: a quick way to find all of your file lists in this space.
2. Create a new list: create more file lists in this space.
3. Current file lists: see all the file lists in this space.
You can customize the templates that are used by the File List blueprint - see Customizing blueprint
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 136
templates.
The File List blueprint template uses the attachments macro. You can customize the macro to change the
sort order or hide features such as version history and the upload attachment fields.
You can also edit the Content Report Table macro used on the Index page to specify the number of pages
you want to display.
If you want to quickly create a blank page, hit the Create button in the header; if you want to create a
page from a template, hit the Create from template button.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 137
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 138
You can customize the templates that are used by the Meeting Notes blueprint see Customizing the
blueprint templates.
You might choose to edit the headings or add additional headings, or change the instructional text that
prompts users to enter information to suit your context. To find out more about using instructional text in a
template, see Instructional text.
You can also edit the Content Report Table macro used on the Index page to specify the number of pages
you want to display.
If you want to quickly create a blank page, hit the Create button in the header; if you want to create a
page from a template, hit the Create from template button.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 139
As no two products or projects are alike, you can customize the templates that are used by the Product
Requirements blueprint - see Customizing the blueprint templates.
You might choose to edit the index page in a space to change the columns to be displayed by the Page
Properties Report macro.
You might choose to edit the page template to:
edit the headings or add additional headings
change the instructional text that prompts users to enter information to suit your context
add or remove rows within the Page Properties macro.
See Instructional text to find out more about using instructional text in templates.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 140
with your team. You can use Shared Links to share and collaborate on web Related pages:
content, or to create a centralized repository of useful links.
Blueprints
The first time you use the Shared Links blueprint in a space, Confluence will Decisions
create an index page and add a shortcut on your space sidebar (if you're Blueprint
using the default theme). The index lists all the shared links in that space. File List
Blueprint
If you want to quickly create a blank page, hit the Create button in Meeting
the header; if you want to create a page from a template, hit the Cre Notes
ate from template button. Blueprint
Product
Requireme
nts
Blueprint
1. Create blank page
2. Create from template
To make sharing links even faster, you can add a Share on Confluence button to your browser's
toolbar. Click this button and the webpage you're currently viewing will be added as a shared link!
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 141
To use the JIRA Report Blueprint your Confluence and JIRA application
(such as JIRA Software) must be connected via Application Links .
2.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 142
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 143
The Status Report displays the progress of a JIRA project and fix version in pie charts by status, priority,
component and issue type. The Status Report uses the JIRA Chart macro, and is dynamic.
To create a status report:
1. Choose Create from template
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 144
You can customize the templates used by this blueprint. The Change Log uses the Snapshot JIRA Report
Template (for static list of issues) and the Dynamic JIRA Report Template, and the Status Report uses the
Status Report Template. See Customizing the blueprint templates. Variables represent the JIRA Issues
and JIRA Chart Macros. While these can't be edited, they can be moved around the page or deleted if you
don't want every chart to be included.
You can also choose to edit the page template to modify the format of the page, change some headings, or
modify the instructional text. To See Instructional text to find out more about using instructional text in
templates.
Retrospective Blueprint
Retrospective pages help you track team successes and opportunities after Related pages:
projects or at the end of a sprint. Use this blueprint to document what went
well, what needed improvement, and assign actions for the future. Blueprints
File List
The first time you create a retrospective page in a space, Confluence will Blueprint
automatically create an 'index' page, which will list all retrospectives in the Meeting
space, and add a shortcut to it in the space sidebar. Notes
Blueprint
If you want to quickly create a blank page, hit the Create button in the header; if you want to create a
page from a template, hit the Create from template button.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 145
Check out how the retrospectives blueprint can be used in the article Create sprint retrospective and
demo pages (like a BOSS).
Every team conducts retrospective meetings differently, so you can customize the Retrospective blueprint
template to match your team's culture and practices. You can:
Edit headings and pre-populated text
Add instructional text to capture specific information
Add additional sections and content
See Customize blueprint templates for instructions.
If you want to quickly create a blank page, hit the Create button in
the header; if you want to create a page from a template, hit the Cre
ate from template button.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 146
Related pages:
Blueprints
Troublesho
1. Create blank page oting
2. Create from template Article
Blueprint
Create
Technical
and
Onboardin
g
Document
ation
Use
Confluenc
e as a
Knowledge
Base
Once you save your page, Confluence will create an index page and add a shortcut to your space sidebar.
The index lists all the How-To Article pages in that space, and displays a summary of the information on each
page (such as creator and modified).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 147
You can customize the templates used by the How-To Article blueprint - see Customizing the blueprint
templates. For example, you might choose to edit the How-to index page in a space to change the columns
displayed by the Page Properties Report macro.
You can also edit the page template to add headings or instructional text to the background section, or even
add rows to the Page Properties macro. For example, a row for the date the How-To Article was created.
See Instructional text to find out more about using instructional text in templates.
If you want to quickly create a blank page, hit the Create button in the header; if you want to create a
page from a template, hit the Create from template button.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 148
Once you save your page, Confluence will create an index page and add a shortcut on your space sidebar.
The index lists all the Troubleshooting Article pages in the space, and displays a summary of the information
on each page (such as creator and modified).
You can customize the templates used by the Troubleshooting Article blueprint - see Customizing the
blueprint templates. For example, you might choose to edit the decisions index page in a space to change
the columns displayed by the Page Properties Report macro.
You can also edit the page template to add headings or instructional text to the background section, or even
add rows to the Page Properties macro. For example, a row for the date the Troubleshooting Article was
created.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 149
See Instructional text to find out more about using instructional text in templates.
You can also edit the Content Report Table macro used on the Index page to specify the number of pages
you want to display.
Using a combination of templates and macros you can make a wide range of reports for managing anything from
customer interviews, product requirements to IT service catalogs and more. In this tutorial we'll guide you
through the process of creating a blueprint-style report.
In this example, we'll create a multi-team status report. Here's the scenario we'll use for this tutorial.
The Design, Development and QA teams working on the Blue Sky Project need to produce a short
status update page each week, containing the focus area for the week, contact person, risks and
overall status for each team. They like the way the Product Requirements blueprint works and want
to be able to manage their status updates in a similar way.
What do each of the players want out of this report?
Project Lead Wants an at-a-glance report that shows only the status for each team.
Team Leads Want a summary report, including the focus areas and risk, just for their team.
All team members Want it to be easy to create the new page each week.
Management Team Want to see all the details for a week on one page, and don't want to
have to look at a different page for each team.
With this scenario in mind, this tutorial will guide you through how to:
1. Create a status update template containing a separate page properties macro for each team's section of
the report.
2. Create a high level status report, showing just the status of all teams.
3. Create a summary report for each team.
4. Create your first status update page.
You'll need Space Administrator permissions to complete some of the steps in this tutorial.
First we'll create a page template and add the Page Properties macros.
1. Go to Space Admin > Content Tools > Templates
2. Choose Create Template
3. Give the template a name (in this example the template will be called 'Status Update')
4. Add the skeleton of your status report to the page
5. Choose the label icon
at the top of the page to add a label to the template (in this example, we'll add the label: 'status-update')
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 150
Now we'll add a Page Properties macro to record the status of the Design team.
6. Choose Insert > Other Macros > Page Properties to add the Page Properties macro to the page
7. In the macro body create a two column table and remove the heading row
8. In the left column enter the column headings for your report (these are known as metadata 'keys')
In this example we'll add 'Design Focus', 'Design Status', 'Design Contact' and 'Design Risks').
9. In the right column, leave the cells blank, or enter some instructional text to prompt your users (Choose T
emplate > Instructional Text)
We've also added a status macro.
10. Edit the Page Properties macro and enter a Page Properties ID for this macro (in this example we'll use
'status-update-design'. This will allow us to report on the status of just the Design team later on)
Repeat this process for the Development and QA teams, remembering to specify a different ID for each
macro (we used 'status-update-dev' and 'status-update-qa').
11. Finally, add any other headings, instructional text or content to your template and Save.
You can enter a Description for your template - this appears in the Create dialog.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 151
Part 2: Create a report showing the high level status of each team
Next we'll create an index page, just like you see in many blueprints.
1. In your space create a new blank page (this will be our 'Status Report - all teams' page, showing just the
status of each team)
2. Choose Insert > Other Macros > Page Properties Report to add the Page Properties Report macro to
the page
3. Enter the Label to report on (in this example, it'll be the 'status-update' label we added to the template
page)
4. Leave the Display options > Page Properties ID field blank (we want to report on all the macros on the
page)
5. In the Columns to Show field, list the 'keys' from each macro that you want to include in the report (in
this example, we only want to show the values of 'Design Status', 'Dev Status', 'QA Status')
6. Choose Save to add the macro to the page
Screenshot: The page properties report macro on the 'Status Report - all teams' page
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 152
Now we'll add a button to the page to allow team leads to easily create new status update pages from the
template we created earlier.
7. Choose Insert > Other Macros > Create from Template to add the Create from Template macro to the
page
8. Enter the text for the button (in this example we'll call the button 'New Status Update Page')
9. Select the template from the Template Name drop down (in this example our template was called 'Status
Update')
10. Specify the title of any pages to be created (This is a great way to keep your titles consistent. In this
example we'll call the page 'Status update week ending @currentDate', which will append the current date
when the page is created, as in the meeting notes blueprint)
11. Choose Insert
12. Add any other content, links or images to the page and Save
13. Choose Space Tools > Configure Sidebar > Add Link to add a shortcut to the page on the sidebar
Now we'll create some index pages that show a more detailed summary for each team, starting with the Design
team.
1. Create a new blank page this will be the 'Design Status Report' index page, showing just information for
that team.
2. Choose Insert > Other Macros > Page Properties Report to add the Page Properties Report macro to
the page
3. Enter the Label (the page label is once again 'status-update', the label we added to the template)
4. Expand the Display options and enter the Page Properties ID that was specified in the Page Properties
macro in the template (in this example it was 'status-update-design') this allows us to report on just
information in that macro.
5. Leave all of the other fields blank (we want to show all columns from this Page Properties macro)
6. Choose Save to add the macro to the page
Screenshot: The page properties report macro on the 'Design Status Report' index page
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 153
7. Add any other content, links or images to the page and Save
8. Choose Space Tools > Configure Sidebar > Add Link to add a shortcut to the page on the sidebar
9. Create a new page and repeat this process for each team
Remember to specify a different Page Properties ID each time (in this example 'status-report-dev' and
'status-report-qa').
If your Design, Dev and QA teams have their own team spaces, this summary report could even be created in
their team spaces. Just be sure to specify the space where the Status Updates pages are created in the Restric
t to spaces field, to make sure the macro can find the pages to report on.
in the Confluence header, then select Status Update, or use the Create a new status update button to make
your first status update page. Just like a blueprint, but 100% made by you.
Here's how our finished pages look.
Screenshot: Team Leads and the management team still have a single page for the weekly status update
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 154
Screenshot: The Project Lead can see the status of each team, each week, at a glance in the All Teams status
report.
Screenshot: Each team can see their focus, risks and status at a glance in their status report.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 155
Remember, these concepts don't just apply to status updates you can use them for any purpose at all.
The Office Connector allows you to create pages by importing Word documents. The document content is
copied onto one or more Confluence pages. See Import a Word Document into Confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 156
Import options
There are a number of options when importing a Word document that control how pages are created,
whether the import should overwrite existing pages in the space, and how it should handle page name
conflicts.
Option Description
Root This is the title of the page that will be created or updated by the import.
page
title
Where Controls whether the document is imported into the current page (the page you were viewing
to when you selected Tools > Import) or created as a new page. Choose from
import
Import as a new page in the current space - a new page will be created as a child of the
space home page.
Replace <page name> - content will be imported into the current page. The title of this
page will change to the title you specified in the Root page title field.
Delete existing children of <pagename> - any existing children of the current page will
be removed when the content of the page is replaced.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 157
Title Controls how page name conflicts (a page with the same title already exists in the space) are
conflicts handled.
Rename imported pages if page name already exists - new pages get a new name (a
number added to the end of the page title). Existing pages will be unchanged.
Replace existing pages with imported pages of the same title - overwrite the content of
existing pages. The change will be shown in the Page History for the page.
Remove existing pages with the same title as imported pages - remove original pages
and then create new pages. The change is not shown in the Page History for the page.
Split by If the document contains Word heading styles you can choose to create multiple pages based
heading on the heading. Options are:
Don't split - creates a single page.
Level Headings - creates multiple pages in a hierarchy based on the heading levels in the
document.
A preview of the pages that will be created appears under Document Outline.
Screenshot: Import Word options for a document that contains multiple heading levels.
Orphaned Pages
An orphaned page is a page without any incoming links and is located at Related pages:
what's called the 'root of the space', meaning it sits alongside the space's
home page. This means that, unless you know the page exists, you're not Undefined
likely to come across it during the natural course of navigation. Page Links
Create and
There may be a legitimate reason you want to have a page at the root of a Edit Pages
space. For example, you may be effectively hiding it in the navigation. If you
don't want orphaned pages though, you can easily view all orphaned pages
in a space so you can tidily delete the pages or reorganize them so they're
no longer orphaned.
To view the orphaned pages in a space:
1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Orphaned Pages.
While in the orphaned pages view, you can do any of the following:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 158
Delete an orphaned page by choosing the 'trash can' icon next to the page name.
Edit a page by choosing the 'pencil' icon next to the page name.
Give an orphaned page a parent see Move and Reorder Pages.
Screenshot: Managing orphaned pages
The Undefined Pages view shows you all undefined pages in your space.
The undefined page links are badged with a
icon to remind you that those pages are yet to be created.
To view a list of the undefined links in a space:
1. Go to the space and choose Space tools > Content Tools from the bottom of the sidebar
2. Choose Undefined Pages.
You can choose the link for an undefined page to create the page and add content to it.
Links to pages that are in the trash are not considered undefined links, and will not appear in this list.
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 159
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 160
Hover over each avatar to see the names of people who contributed changes in that version. It is not
possible to view the individual changes made by each person in a single page version.
When you select a previous version of the page, you'll see a header like this at the top of the page:
If you want to send this page version to someone, copy and paste the URL from your browser. The link
will look something like this: http://confluence.atlassian.com/pages/viewpage.action?pageI
d=12345.
When you're viewing a specific version of the page, the following functions are available:
Function Description
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 161
Compare with Compare the differences between the version of the page you are viewing and the
Current current version.
Restore this Roll back the content of the page to the previous version that you are viewing.
Version
<< Previous and Ne View the previous or next version of the page.
xt >>
All page history is retained; restoring an older version creates a copy of that version. For example, if you
restore version 39, Confluence will create a copy of version 39 and the copy will become the new, current
version.
If the page has an unpublished draft, the content of the draft will be lost when you restore a previous version.
We'll warn you if there is an unpublished draft.
Choose Delete next to a version in the page history, to remove that version.
Using the page history view or the page information view, you can see the recent changes made to a page.
To view recent changes made to a page:
1. Choose
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 162
When you view a page comparison, all large sections of unchanged text are hidden and reduced to an
ellipsis (. . .).
You can view page changes between versions which are adjacent to your current page comparison view.
Click the link containing:
<< to view the page comparison with the earlier adjacent version
>> to view the page comparison with the more recent adjacent version
For example, if your page comparison view is between v. 30 and v. 34 of a page, you can view changes
between:
v. 29 and v. 30 by clicking << Changes from 29 to 30
v. 34 and v. 35 by clicking Changes from 34 to 35 >>
Confluence Markup
This section describes two types of markup found in Confluence:
Related pages:
Confluence storage format. Confluence stores the content of pages
and blog posts in an XHTML-based format. Advanced users can view Macros
the storage format of a page and even edit it, provided their The Editor
Confluence site is configured to allow that.
Wiki markup. Confluence allows data entry via a shorthand code
called wiki markup. Some parts of the Confluence administration
interface also accept wiki markup for defining content. For a
description of the wiki markup syntax, see Confluence Wiki Markup.
Wiki markup code examples for macros can be found in the documentation
for each macro.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 163
> View Source, you'll see the format used within the editor panel,
not the storage format of the page.
Macros
Storage format and wiki markup examples have been included in the documentation for each macro.
Headings
Format type In In Confluence 4.0 and later What you will get
Confluence
3.5 and
earlier
Heading 3 h3.
Heading 3 <h3>Heading
3</h3>
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 164
Headings 4 to
6 are also
available and
follow the
same pattern
Text effects
strong/bold *strong*
<strong>strong text</strong>
emphasis _emphasis_
<em>Italics Text</em>
strikethrough -strikethrough-
<span style="text-decoration:
line-through;">strikethrough</span>
underline +underline+
<u>underline</u>
superscript ^superscript^
<sup>superscript</sup>
subscript ~subscript~
<sub>subscript</sub>
monospace {{monospaced}}
<code>monospaced</code>
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 165
preformatted n/a
<pre>preformatted text</pre>
block
quote
{quote}
small n/a
<small>small text</small>
big n/a
<big>big text</big>
center-align n/a
<p style="text-align:
center;">centered text</p>
right-align n/a
<p style="text-align: right;">right
aligned text</p>
Text breaks
Format In Confluence 3.5 and earlier In Confluence 4.0 and later What you
type will get
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 166
Paragraph
2
Horizontal ----
rule <hr />
symbol ---
—
symbol --
–
Lists
Unordered * Round
list bullet <ul>
round list item
bullets <li>round bullet list item</li>
</ul>
Ordered # Ordered 1.
list list item <ol>
(numbered
list) <li>numbered list item</li>
</ol>
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 167
Links
Link to an [Link to an
attachment attachment^atlassian_logo.gif] <ac:link>
<ri:attachment ri:filename="atlassi
<ac:plain-text-link-body>
<![CDATA[Link to a Confluence Atta
</ac:plain-text-link-body>
</ac:link>
Link to an [Atlassian|http://www.atlassian.com/]
external <a href="http://www.atlassian.com">
site
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 168
All links received from the editor will be stored as plain text by default, unless they are detected to contain the
limited set of mark up that we allow in link bodies. Here are some examples of markup we support in link
bodies.
The markup tags permitted within the <ac:link-body> are <b>, <strong>, <em>, <i>, <code>, <tt>, <sub>,
<sup>, <br> and <span>.
Images
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 169
Attached !atlassian_logo.gif!
image
External !http://confluence.atlassian.com/images/logo/confluence_48_trans.png!
image
Supported image attributes (some of these attributes mirror the equivalent HTML 4 IMG element):
Name Description
Tables
Format In Confluence 3.5 and In Confluence 4.0 and later What you will get
type earlier
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 170
<tr>
Two N/A
column, <table> Table Table
three Heading Heading
rows, <tbody> Cell 1 Cell 2
2nd
and <tr> Merged Normal
third Cell Cell 1
with <th>Table Heading Cell
merged Normal
1</th> Cell 2
cells in
first row
<th>Table Heading Cell
2</th>
</tr>
<tr>
<td rowspan="2">Merged
Cell</td>
<tr>
<td colspan="1">Normal
Cell 2</td>
</tr>
</tbody>
</table>
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 171
Page layouts
Confluence supports page layouts directly, as an alternative to macro-based layouts (using, for example, the
section and column macros). This section documents the storage format XML created when these layouts
are used in a page.
Notes:
Page layouts were originally introduced in Confluence 4.2, and are not available in earlier versions of
Confluence. If you are using Confluence 4.2 - 5.1 you should refer to the documentation for your
version of Confluence:
Confluence Storage Format (Confluence 4.2)
Confluence Storage Format (Confluence 4.3)
Confluence Storage Format (Confluence 5.0)
Confluence Storage Format (Confluence 5.1)
Pages with a layout created in the old format will be converted to 5.2 format.
Confluence 5.2 provides more flexible layouts with a more concise storage format.
ac:layout Indicates that the page has a layout. It should be the top level None
element in the page.
ac:layout-section Represents a row in the layout. It must be directly within the ac:la ac:type
yout tag. The type of the section indicates the appropriate number
of cells and their relative widths.
ac:layout-cell Represents a column in a layout. It must be directly within the ac:l None
ayout-section tag. There should be an appropriate number of
cells within the layout-section to match the ac:type.
The following example shows one of the more complicated layouts from the old format built in the new. The
word {content} indicates where further XHTML or Confluence storage format block content would be
entered, such as <p> or <table> tags.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 172
<ac:layout>
<ac:layout-section ac:type="single">
<ac:layout-cell>
{content}
</ac:layout-cell>
</ac:layout-section>
<ac:layout-section ac:type="three_with_sidebars">
<ac:layout-cell>
{content}
</ac:layout-cell>
<ac:layout-cell>
{content}
</ac:layout-cell>
<ac:layout-cell>
{content}
</ac:layout-cell>
</ac:layout-section>
<ac:layout-section ac:type="single">
<ac:layout-cell>
{content}
</ac:layout-cell>
</ac:layout-section>
</ac:layout>
Emoticons
Format In Confluence 3.5 and In Confluence 4.0 and later What you
type earlier will get
Emoticons :)
<ac:emoticon
ac:name="smile" />
:(
<ac:emoticon ac:name="sad"
/>
:P
<ac:emoticon
ac:name="cheeky" />
:D
<ac:emoticon
ac:name="laugh" />
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 173
;)
<ac:emoticon
ac:name="wink" />
(y)
<ac:emoticon
ac:name="thumbs-up" />
(n)
<ac:emoticon
ac:name="thumbs-down" />
(i)
<ac:emoticon
ac:name="information" />
(/)
<ac:emoticon
ac:name="tick" />
(x)
<ac:emoticon
ac:name="cross" />
(!)
<ac:emoticon
ac:name="warning" />
Resource identifiers
Resource identifiers are used to describe "links" or "references" to resources in the storage format. Examples
of resources include pages, blog posts, comments, shortcuts, images and so forth.
Page
<ri:page ri:space-key="FOO" ri:content-title="Test
Page"/>
Notes:
ri:space-key: (optional) denotes the space key. This can be omitted to create a
relative reference.
ri:content-title: (required) denotes the title of the page.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 174
Blog Post
<ri:blog-post ri:space-key="FOO" ri:content-title="First
Post" ri:posting-day="2012/01/30" />
Notes:
ri:space-key: (optional) denotes the space key. This can be omitted to create a
relative reference.
ri:content-title: (required) denotes the title of the page.
ri:posting-day: (required) denotes the posting day. The format is YYYY/MM/DD.
Attachment
<ri:attachment ri:filename>
... resource identifier for the container of the
attachment ...
</ri:attachment>
Notes:
ri:filename: (required) denotes the name of the attachment.
the body of the ri:attachment element should be a resource identifier denoting the
container of the attachment. This can be omitted to create a relative attachment
reference (similar to [foo.png] in wiki markup).
Examples:
URL
<ri:url ri:value="http://example.org/sample.gif"/>
Notes:
ri:value: (required) denotes the actual URL value.
Shortcut
<ri:shortcut ri:key="jira" ri:parameter="ABC-123">
Notes:
ri:key: (required) represents the key of the Confluence shortcut.
ri:parameter: (required) represents the parameter to pass into the Confluence
shortcut.
The example above is equivalent to [ABC-123@jira] in wiki markup.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 175
User
<ri:user ri:userkey="2c9680f7405147ee0140514c26120003"/>
Notes:
ri:userkey: (required) denotes the unique identifier of the user.
Space
<ri:space ri:space-key="TST"/>
Notes:
ri:space-key: (required) denotes the key of the space.
Content
Entity <ri:content-entity ri:content-id="123"/>
Notes:
ri:content-id: (required) denotes the id of the content.
Template variables
The XML export produces the following code for the template:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 176
<at:declarations>
<at:string at:name="MyText" />
<at:textarea at:columns="100" at:name="MyMulti" at:rows="5" />
<at:list at:name="MyList">
<at:option at:value="Apples" />
<at:option at:value="Pears" />
<at:option at:value="Peaches" />
</at:list>
</at:declarations>
<p>End of page.</p>
Instructional Text
Instructional text allows you to include information on how to fill out a template for an end-user (the person
using creating a page from the template). Instructional text will:
automatically clear all instructional text as the user types in a specific text block, and
automatically trigger a @mention prompt for user selection (for 'mention' type instructional text).
Screenshot: Example of instructional text.
<ul>
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 177
Yes. You can type wiki markup directly into the editor, and Confluence will convert it as you type. (You
cannot edit the wiki markup after conversion.) See it in action in this video:
Confluence supports inserting content in markdown. This is often used in ReadMe files. See Markdown
syntax guide for some examples of markdown syntax.
To insert markdown in the editor:
1. Choose Insert > Markup
2. Select Markdown
3. Type or paste your text - the preview will show you how it will appear on your page
4. Choose Insert.
As with wiki markup, Confluence will convert your markdown to the rich text editor format. You will not be
able to edit your content using markdown.
Headings
To format a line as a heading, type "hn." at the start of your line, where n can be a number from 1 to 6.
h1. Biggest
Biggest heading
heading
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 178
Lists
Wiki markup allows you to create bulleted or numbered lists, and is flexible enough to allow a combination of
the two list types.
If you need to separate the text within lists using line breaks, make sure you do so using a double slash
(//). Empty lines may disrupt the list.
Simple lists
Use the hyphen (-) to create simple lists with square bullets. Make sure there's a space between the hyphen
and your text.
some
- some bullet
- bullet points
-
points
Bulleted lists
Use the asterisk (*) to create bullets. For each subsequent level, add an extra asterisk.
Make sure there is a space between the asterisk and your text.
some
* some bullet
* bullet indented
** indented bullets
** bullets points
* points
Numbered lists
1. a
# a 2. numbered
# numbered 3. list
# list
A second level of hashes will produce a sub-list, such as the alphabetical sub-list shown below.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 179
1. Here's a sentence.
# Here's a sentence. a. This is a sub-list point.
## This is a sub-list point. b. And a second sub-list point.
## And a second sub-list point. 2. Here's another sentence.
# Here's another sentence.
1. Here's a sentence.
# Here's a sentence. a. This is a sub-list point.
## This is a sub-list point. i. Third list level.
### Third list level. ii. Another point at the third
### Another point at the third level.
level. b. And a second sub-list point.
## And a second sub-list point. 2. Here's another sentence.
# Here's another sentence.
Note: In numbered lists as described above, the format of the 'number' displayed at each list level may be
different, depending upon your browser and the style sheets installed on your Confluence instance. So in
some cases, you may see letters (A, B, C, etc; or a, b, c, etc) or Roman numerals (i, ii, iii, etc) at different list
levels.
Mixed lists
1. Here
# Here is
#* is an
#* an 2. example
# example of
#* of a
#* a 3. mixed
# mixed 4. list
# list
Tables
Table Type 1
Allows you to create a simple table with an optional header row. Once you've added this type of table, you
can set the width of the columns using the table controls in the toolbar.
Use double bars for a table heading row.
What you need to type:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 180
Table Type 2
This method uses section and column macros to create the table, and allows you to specify the width of the
columns in the markup.
What you need to type
{section:border=true}
{column:width=30%}
Text for this column goes here. This is the smaller column with a
width of only 30%.
{column}
{column:width=70%}
Text for this column goes here. This is the larger column with a
width of 70%.
{column}
{section}
Advanced Formatting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 181
To add color and other formatting to your tables, you can use the Panel Macro within columns.
More table-formatting options may be available if your Confluence administrator has installed additional macr
os.
Lists
Here's an example of how to embed lists in a table:
What you need to type
Heading 1 Heading 2
Item 1 1. Item 1
Item 2 2. Item 2
Item 3 3. Item 3
Text Effects
*strong* strong
_emphasis_ emphasis
_italics_ italics
Hint: To italicize parts of a word, add braces (curly
brackets) around the underscore. For example,
Thing{_}x_
??citation?? citation
-deleted- deleted
+inserted+ inserted
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 182
{{monospaced}} monospaced
bq. Here's how you make a Here's how you make a paragraph appear
paragraph appear as a block as a block quotation.
quotation.
Text Breaks
Paragraph Break
In wiki markup, a paragraph is a continuous line of text ending in two carriage returns. This is equivalent to a
continuous line of text followed by a blank line.
When rendered into HTML, the result is a line of text wrapped in a set of <p></p> tags.
Line Break
Confluence provides two options for forcing a line break within a paragraph of text:
Implicitly, by entering a single carriage return at its end.
Explicitly, by entering two consecutive backslashes: \\
When rendered into HTML, the result is a paragraph of text that is split into separate lines by <br> tags,
wherever a forced line break appears.
For most purposes, explicit line breaks are not required because a single carriage return is enough.
The examples below show how to use explicit line breaks.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 183
If you wish to use multiple consecutive line breaks, each should be separated by a space character. For
example, use this for two consecutive line breaks:
\\ \\
Horizontal Rule
To create a horizontal line across the width of your page or content block, type four dashes (like this: ----) at
the beginning of a line, then press Enter or space.
Make sure that the dashes are on a separate line from the rest of the text.
Links
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 184
Note that Confluence treats headings as anchors, so you can link to headings using this pattern:
[spacekey:pagename#headingname], where headingname is case-sensitive and must be entered without
spaces.
For each of these link forms:
You can prepend a link alias, so that alternate text is displayed on the page. Example: [link
alias|pagetitle#anchor]
You can append a link tip, which appears as a tooltip. Example: [pagetitle#anchor|link tip]
Images
!http://www.host.com/image.gif! An image from a remote source is displayed on the page. Uses a fully
qualified URL.
!image.jpg|thumbnail! The image is displayed as a thumbnail on the page (only works with
images that are attached to the page). Users can click on the thumbnail
to see the full-sized image. Thumbnails must be enabled by the site
administrator for this to work.
!image.gif|align=right, For any image, you can specify attributes of the HTML image tag as a
vspace=4! comma separated list of name=value pairs.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 185
bordercolor Use with the 'border' tag. Specify colors by name or hex value.
hspace Specifies the amount of whitespace to be inserted to the left and right of the image (in
pixels).
vspace Specifies the amount of whitespace to be inserted above and below the image (in pixels).
width Specifies the width of the image (in pixels). This will override the natural width of the image.
height Specifies the height of the image (in pixels). This will override the natural height of the
image.
title Specifies alternate text for the image, which is displayed when the pointer hovers over the
image.
alt Specifies alternate text for the image. This text is retrievable via search, and contributes to
accessibility of the page for text-only viewing.
Page Layouts
Macros
Storage format and wiki markup examples have been included in the documentation for each macro.
Files
Share your team's PDFs, Office documents, images, and more in one place
by uploading your files to Confluence. Automatic versioning, instant On this page:
previews, permissions, and full-text search, means shared network drives Using Files
can be a thing of the past for your team. Permission
When you upload a file it is attached to the current page or blog post. This is s
why files are often referred to as attachments in Confluence. Related pages:
You can attach anything from project plans and design mockups to video Configurin
and audio files. You and your colleagues can also collaborate by commentin g
g on files displayed on Confluence pages. Attachmen
t Size
Using Files Configurin
g your
Upload Files Attachmen
Display Files and Images t Storage
Manage Files
Share and Comment on Files
Edit Office Files
Permissions
The 'Add Attachment' and 'Delete Attachment' permissions are used to control who can upload and delete
attachments in a space.
Users with 'Add Page' or 'Add Blog' permissions can insert existing attachments to their pages, but not
upload new attachments unless they also have the 'Add Attachment' permission.
There is no permission that controls downloading attachments. See our knowledge base article about disabli
ng the download of attachments if you need to do this.
Upload Files
When you upload a file, such as an image or
document, it will be attached to the current page.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 186
On this page:
You can then choose to display the file on the page
as a link, an image or embed it in the page (using a Upload a file
macro). Accepted file types and size
File versions
To upload a file you'll need the 'Add Attachments'
Notes
space permission.
Related pages:
Upload a file Files
Configuring Attachment Size
There are many ways to attach a file to a page. Display Files and Images
Manage Files
In the editor you can:
Drag the file directly onto the page.
Go to Insert > Files and images and upload
a file.
When viewing a page you can:
Drag the file directly onto the page.
Go to
Confluence allows you to attach most file types, but you cannot attach a folder of files (including folders
created by applications like Keynote - you'll need to export your presentation to zip or other format).
Although just about any file type can be attached to a page, not all file types can be displayed on or
embedded in a page. See Display Files and Images to find out more.
The maximum file size you can upload to Confluence is set by your system administrator. By default it is
10mb, but your administrator may have increased or reduced this limit.
File versions
If you upload a file with the same name as an existing attachment on the same page, Confluence will
overwrite the existing attachment. Version history is kept for all attachments. See Manage Files to find out
more.
Any changes you make to the source file will not affect the copy that was uploaded to Confluence. To update
the Confluence copy, you need to upload the new version of the file.
Notes
We recommend you don't use special characters in page or attachment names, as the page or
attachment may not be found by Confluence search, and may cause some Confluence functions to behave
unexpectedly.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 187
You can display a file that's attached to a different page of the same Confluence site, if you know the name of
the file.
To display an image attached to a different page:
1. Go to Insert > Files and choose the Search on other pages.
2. Enter the name of the file.
3. Choose whether to search the current space or All Spaces and choose Search.
4. Select the file from the search results and choose Insert.
You can display an image from a remote web page on your Confluence page, without needing to attach it to
your page. You need to know the URL for the image, not for the web page it appears on. This is only
available for image files, not other types of files (like documents).
To display an image from a web page:
1. While editing the page, position the cursor where you want to place the image.
2. Choose Insert > Files and choose Images from the web.
3. Enter a URL for the image. (example: http://atlassian.wpengine.netdna-cdn.com/wp-content/uploads/A
tlassianBushRegeneration-12January2012-083-trunc.jpg
4. Choose Preview to check that the URL and image are correct.
5. Choose Insert.
If you delete a file or image in the editor, the attached file will not be deleted. Go to
Seeing an 'unknown attachment' placeholder on your page? This means that the attached file has been
deleted from the page (or another page).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 188
Preview a file
Click an image, file thumbnail or link when viewing a page to launch the preview.
The preview includes images from the web that are displayed on the page and files that are attached to the
page (even if they are not currently displayed on the page).
In the preview you can:
Download the image file.
Upload a new version of the file (attached files only).
Comment on the file.
Zoom in, out or fit the image to the width of your browser.
Browse like a slideshow using the next and back buttons.
See other files attached to the page and select a thumbnail to preview that file.
Switch to a full screen presentation mode.
Many file types can be previewed, including Office files, PDFs and many image types.
1. See more files: see other files also attached to this page.
2. Manage this file: download the file, upload a new version or share with your team.
3. Add a comment: drag the pin to comment on the file.
Inserting a file in a page is a great way to make useful documents, spreadsheets, presentations and other
files available to your team.
As with all file types, you can choose to insert the file as a link, or as a thumbnail. The thumbnail shows a
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 189
Image files
When editing the page, select an image to show the image properties panel. The panel allows you to set the
display size, add a border and effects and link the image to other pages.
Displaying image effects can be resource intensive. Confluence limits the threads that are dedicated to
displaying image effects so that it does not impact your whole instance. If a thread is not available,
Confluence will display the image without the effect.
The following knowledge base article provides information if you need to adjust the number of threads - Imag
e effects are not displayed in Confluence 5.5 or later.
Multimedia files
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 190
The file preview also supports MP3 audio and MP4 video files. It uses HTML5 to play attached audio and
video files. This means the file types people can play in the preview depends on the audio and video formats
their browser supports.
You can also display a wider range of multimedia files (video, audio and animation) using the Multimedia
Macro.
Display online video (such as YouTube or Vimeo videos) using the Widget Connector Macro.
There are several ways you can display a list of files on a page. You can:
Use the Attachments Macro to show files attached to the current page.
Use the Space Attachments Macro to show all files in a space.
Use the Gallery Macro to show thumbnails of images attached to a page.
You can also use the File List blueprint for uploading, viewing and managing lists of files.
Manage Files
Files are attached to Confluence pages. See Upload On this page:
Files to find out about attaching files to pages.
Download attached files
Once attached you can download, delete and edit Delete an attached file
these files, for example if you need to upload a new Upload a new version of an
version of the file, or change the page it is attached attached file
to. Move a file to another page
Edit properties of an attached file
View all attached files in a space
Download attached files
Any user with permission to view a page can also Related pages:
download any files attached to that page.
Files
To download an individual file: Display Files and Images
Click the Download button in the file preview,
or
Go to
> Attachments
and then right click on the file name and save
the link.
To download all files attached to a page as a zip
file:
1. Go to
> Attachments
2. Click Download All.
There's no option to download all attachments in a
space.
You'll need the 'Delete Attachment' space permission to delete an attached file.
To delete all versions of an attached file:
1. Go to the page that contains the attachment.
2. Go to
> Attachments
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 191
> Attachments
2. Click the expand arrow next to the attachment name to see the list of attachment versions
3. Choose Delete next to the version you want to delete.
Deleted file versions are not recoverable from the trash.
Screenshot: Attachments and attachment versions
There are two ways up upload a new version of an attached file. You can:
Upload a file with the same file name to the page.
Use the Upload a new version
button in the file preview to upload a file with a different name (for images and PDFs only).
To view attachment versions:
Go to
> Attachments
Click the expand arrow next to the attachment name.
All earlier versions of the file will appear.
You can't revert to an earlier version of the file, but you can choose to remove earlier versions if you have
Space Administrator permissions.
You'll need the 'Add Page', 'Add Attachment' and 'Remove Attachment' space permissions to move an
attached file to another page.
To change the page that a file is attached to:
Go to
> Attachments
Choose Properties next to the attachment you want to move.
Enter the name of the page you want to move the attachment to (for example My Destination
Page).
Choose Save.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 192
If you want to move the file to a page in another space, add the space key before the page name (for
example DOC:My Destination Page).
You'll need the 'Add Attachment' permission in the space to edit the file properties.
To edit the properties of an attached file:
Go to
> Attachments
Click Properties beside the attachment you want to edit.
You can:
change the file name
add a comment (used in the version list and also by the Snapshot image effect)
change the MIME type
move the attachment to another page
add a label.
Changing the MIME type may cause your file to display incorrectly.
There are two ways you can view all files in a space. You can:
Use the Space Attachments macro to display the list of files on a page.
Go to the space and choose Space tools > Content Tools from the bottom of the sidebar Then
choose Attachments.
You can use the filters to only show files with a particular label or file extension.
Screenshot: Space attachments macro
Share a file
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 193
Do you have lots of files on a page and want to get a team member's input On this page:
on just one of them? You can share the file with them directly.
Share a
It works just like sharing a page: file
Comment
1. Click the thumbnail or link to preview the file
on a file
2. Choose the Share button
Edit a file
3. Enter an email address, user name or group name, add your
message and send Related pages:
Your team members will get an email with your message and a link to view Files
the file. Display
Files and
Images
Comment
on pages
and blog
posts
Share notifications are only sent by email, they won't appear in the workbox
Comment on a file
Whether it's an image like a mockup of the new marketing campaign that needs feedback a PDF, a
presentation, or any other file you can preview in Confluence, you can drop a pin anywhere on the preview
and add your comment to start a conversation.
To comment on a file:
1. Click the thumbnail or link to preview the file
2. Drag the pin icon from the bottom of the preview and drop it where you want to comment
3. Add your comment and Save
Pinned comments work just like inline comments on pages. You can use @mentions and links, and drop as
many pins as you need on any part of the file. You can even add simple macros such as the code macro
using wiki markup autocomplete. Anyone with permission to add comments to the page can add and reply to
comments on a file.
When you preview a file, you'll see pins for any existing comments. Select a pin to view the comment.
Once the conversation is finished, you can resolve the comment to hide it (and any replies) from view. If you
need to see resolved comments again, you can reopen them. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 194
You can't comment on files that are hosted on a web server and added to Confluence using their
URL, or on files that can't be viewed in the preview (such as videos, zip files, and some other file
types).
Edit a file
Need to go beyond commenting on files? You can even edit some files right from the Confluence page. See
Edit Office Files to find out about supported file types and applications.
> Attachments
2.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 195
Troubleshooting
Check out the Office Connector Prerequisites for the combinations of browsers, operating systems and office
applications that are supported. Here's some common issues:
Using Chrome? You can't edit Office documents as Chrome does not support WebDAV clients . See
CONFSERVER-23322
OPEN
Using Firefox? You'll need to install the WebDAV add-on. See Installing the Firefox Add-On for the
Office Connector.
Using Internet Explorer? You can only edit documents in Microsoft Office. OpenOffice is not
supported.
Using Linux? You can only edit documents in OpenOffice. Microsoft Office is not supported. See
CONFSERVER-17250
OPEN .
CONFSERVER-25594
Using Mac OS X? You can't currently edit documents. See RESOLVED .
Special characters in the filename? Edit in Office does not work for files with special characters (like
CONFSERVER-22403
' # @ ) in the filename. See OPEN .
Not seeing the Office Connector options? Your system administrator may have disabled all or part
of the Office Connector.
See Configuring the Office Connector .
You can find more troubleshooting info in the Office Connector Limitations and Known Issues knowledge
base article.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 196
Confluence can import the content from Microsoft Word 97-2013 documents ( .doc and .docx ).
The Office Connector allows you to edit Office files that are attached to pages.
You'll need to use a browser, operating system and application (either Microsoft Office or OpenOffice) as
described in the compatibility matrix below.
Here's a few common issues:
Using Chrome? You can't edit Office documents as Chrome does not support WebDAV clients . See
CONFSERVER-23322
OPEN
Using Firefox? You'll need to install the WebDAV add-on. See Installing the Firefox Add-On for the
Office Connector.
Using Internet Explorer? You can only edit documents in Microsoft Office. OpenOffice is not
supported.
Using Linux? You can only edit documents in OpenOffice. Microsoft Office is not supported. See
CONFSERVER-17250
OPEN .
CONFSERVER-25594
Using Mac OS X? You can't currently edit documents. See RESOLVED .
Special characters in the filename? Edit in Office does not work for files with special characters (like
CONFSERVER-22403
' # @ ) in the filename. See OPEN .
Not seeing the Office Connector options? Your system administrator may have disabled all or part
of the Office Connector.
See Configuring the Office Connector .
Configuration matrix
You need one of the following software combinations to edit Office files from your Confluence page.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 197
Note: The only known supported Office editor for Linux is OpenOffice. But in theory it should work with any
WebDAV-aware application.
If you experience problems editing documents using the Office Connector (using an application, operating
system and browser combination above) please raise an issue and tell us as much as you can about your
operating system, application version, document version (if its different to the version of Office / Open Office
you're using to open the document) and browser.
Troubleshooting
The first time you try to edit an attached Office document in Firefox you'll be prompted to install a WebDAV
add-on for your browser. Without this add-on you can't edit Office documents from Firefox.
1. Choose Edit in Office or Edit Document next to the document you wish to edit.
You'll see a prompt to download the add-on.
2. Choose OK.
Your browser will ask you to confirm that you want to allow the add-on.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
2. 6.4 documentation
Confluence 198
3. Choose Allow.
An installation dialog like the one below will appear.
After installing the add-on you need to configure it, to tell the add-on which desktop applications to launch for
each file type.
Configuring the add-on is slightly different in each operating system.
In most cases the add-on will automatically configure itself, based on information from the system
registry. The first time you edit a new file type, the add-on will look up the default editor for that file type and
make that the permanent setting.
If you want to override the registry settings, or the automatic configuration is not working, you can configure
the Firefox add-on manually.
1. In Firefox locate the WebDAV Launcher add-on and choose Options.
The WebDAV Launcher Options dialog, like the one below, will appear.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 199
2. Enter a file extension in the File Extension field. Do not include the leading period in the extension
name.
For example, to associate the 'doc' file extension with Microsoft Word 2003 you would type doc in the
File Extension field.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 200
The configuration procedure is similar to Windows, as shown above. Note that there is no 'Auto' button in
Mac OS X.
CONFSERVER-25594
You can't currently edit documents in Mac OS X. See RESOLVED .
The only known supported Office editor for Linux is OpenOffice (see Office Connector Prerequisites).
There is no automatic configuration on Linux. You will need to associate each file type with your Office editor
in Firefox. Note that there is no 'Auto' button in Linux.
The configuration procedure is similar to Windows. For both Ubuntu and OpenSUSE, the configuration will
look something like this:
Security Risks
Please be aware that there are security risks in installing this add-on to Firefox. Internet Explorer is
exposed to the same risks, because it can directly open Office documents.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 201
There are known flaws in the Office file formats and Microsoft Office that an attacker can exploit to
gain control of your machine. Microsoft has fixed the known exploits in the latest Service Packs for all
Microsoft Office versions, but new exploits may arise at any time. Be sure that you trust the source of
a document before opening it.
The add-on reduces the risk by supporting:
Same origin policy - the add-on can only open documents from the same host that initiated the
action.
Digital signature - the add-on is digitally signed. When you install the add-on please verify that it is
signed by Atlassian.
Prompt the user for confirmation - You will always be warned before a file is opened. Please read
these warnings carefully before opening a file. The warning tells you the complete URL of the file
as well as the complete application path of the application opening the file.
Description: Adds the ability to launch a WebDAV URL directly in a WebDAV-aware client.
Compatible with: All versions of Firefox, up to and including the latest stable version.
Confluence Mobile
On this page:
This page is about Confluence mobile web. If you're a Confluence
Cloud customer, head over to our Cloud documentation to find out The
about the Confluence Cloud app for iOS and Android. dashboard
the first
thing you
When you access Confluence on a mobile device, you'll see a version of
see
Confluence which is optimized for mobile viewing. Confluence chooses the
Searching
mobile or desktop interface based on your device, but you can still switch to
for content
the desktop site on your mobile by choosing menu
and people
Viewing
then choosing Switch to desktop version. pages,
blog posts
You can also swap from the desktop view to the mobile view if you're on a
and
mobile device, by choosing Switch to Confluence Mobile at the top of the
comments
page.
Viewing
On your supported mobile device, you can: people's
profiles
View the Confluence dashboard, pages, blog posts, and user profiles. Following
Add or reply to a comment on a page or blog post. up on
Like a page, blog post or comment. notification
Watch a page or blog post. s
See your notifications and tasks. Viewing
You can't add or edit pages or blog posts, or edit existing comments, using tasks
the mobile interface. More
things you
may need
to know
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 202
to open the menu panel on the left of the page. Then type text or a person's name in the Search box. The
mobile interface offers the quick navigation search, which returns matches on page title only. (See Search.)
To use the full search, switch to desktop mode.
Tap a link on the dashboard or on any other page. Confluence will display the linked page, blog post or
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 203
comment.
You can:
View the content, tap a link to move to another page, and interact with the page using the standard
functionality supported by mobile browsers.
Like or unlike a page, blog post or comment.
Watch or stop watching a page or blog post.
Add or reply to a comment.
Search for a person's name, then view that person's user profile. Tap the options to phone, SMS or email a
colleague directly from your mobile device.
Following up on notifications
You can view and respond to your notifications on your phone or other mobile device. Tap the menu icon
to open the menu panel on the left of the page. Choose Notifications, and tap a notification to see its
details. You can reply, watch or like via the inline actions. Tap Open to open the page or blog post in a new
page. For full details, see Workbox Notifications.
Viewing tasks
You can view and manage your tasks on your phone or other mobile device too. Tap the menu icon
to open the menu panel on the left of the page. Choose Tasks then tap a task to see its details.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 204
Confluence macros are not yet fully supported in Confluence mobile. If you view a page that contains an
unsupported macro, you will see a message inviting you to click through to the desktop version of the page.
Screenshot: Macro not rendered in Confluence mobile
The mobile functionality is provided by a system add-on called the 'Confluence Mobile Plugin'. To remove the
functionality from your site, you can disable the plugin.
In Confluence versions 5.9 and above, disabling the Confluence Mobile Plugin will also disable the
Workbox - Host Plugin plugin. This issue is being tracked at
CONFSERVER-40782 - Disabling the Confluence Mobile Plugin also disables the Workbox - Host Plugin in
Confluence 5.9.X OPEN
The Confluence iOS app is available for Confluence Cloud sites only. It cannot be used with Confluence
Server.
You can access Confluence Server on any device using a browser. Confluence will detect your device's size
and switch to the mobile web version when necessary.
See Supported Platforms for supported mobile browsers.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 205
Macros
Using macros helps you to expand the capabilities of your Confluence
pages, allowing you to add extra functionality or include dynamic content. On this page:
For example, use the Attachments macro to list files attached to a page, or Add a
use the Widget Connector macro to include things like a YouTube video or Macro to
Twitter feed. your Page
Confluenc
e macros
Add a Macro to your Page Creating
your own
macros
Including Macros with the Macro Browser
Getting
more
To add a macro to a page:
macros
1. In the Confluence editor, choose Insert > Other Macros from The
2. Find and select the required macro Marketplac
e
Speeding up macro entry with autocomplete: Type { and the beginning of Macro
the macro name, to see a list of suggested macros. Details are in Autocompl usage
ete for links, files, macros and mentions. statistics
To edit an existing macro: Click the macro placeholder and choose Edit. A
macro dialog window will open, where you can edit the parameters of the
macro.
Macro Parameters
Many macros have optional parameters you can use to control the macro's output.
With the Attachments Macro, for instance, you have two optional parameters allowing you to:
Specify the file formats of the attachments displayed
Choose whether or not you want old versions of the attachments displayed
Macro Placeholders
Macro placeholders are displayed in the editor where you have added a macro to the page.
When editing a page, you can:
Double-click a macro placeholder (or click the placeholder and choose Edit) to open the macro dialog
window and edit the macro's parameters
Select a macro placeholder to cut, copy and paste the macro
Confluence macros
Below is a list of the macros currently bundled with Confluence. Click a macro name for details of the usage,
including optional parameters and examples.
Activity Stream Macro
Anchor Macro
Attachments Macro
Blog Posts Macro
Change-History Macro
Chart Macro
Cheese Macro
Children Display Macro
Code Block Macro
Column Macro
Content by Label Macro
Content by User Macro
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 206
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 207
Users with System Administrator permissions can create user macros - see Writing User Macros.
If you want to create something more complex, you can develop your own plugin - see Writing Confluence
Plugins.
You can find a wide range of Atlassian and third party macros at The Marketplace. These are distributed as
add-ons and can be installed by a Confluence Administrator.
Confluence administrators can check how often each macro is used in your site.
To see how often a macro is used, go to
> General Configuration > Macro Usage. This lists how often each macro is used in current spaces but
doesn't include any macros used on pages in archived spaces or macros provided by disabled add-ons.
Anchor Macro
Allows you to link to a specific part of a page. For more information on using anchors see Anchors.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: anchor
{anchor:here}
Attachments Macro
The Attachments macro displays a list of files attached to a page.
It also allows users (with appropriate permissions) to:
upload a file to the page, directly from the list
edit attachment properties and labels
delete an attached file (this deletes all versions of the file)
preview image attachments
edit attached Office and PDF documents using the Office Connector.
download all files attached to the page.
Note: you can use the macro parameters to turn off previews if you have very large attachments.
Screenshot: The Attachments macro, showing details of an attachment
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 208
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Filename all A comma-separated list of regular expressions, used to filter the attachments by
Patterns file name. Note that the parameter values must be regular expressions. For
(patterns) example:
To match a file suffix of 'jpg', use .*jpg (not *.jpg).
To match file names ending in 'jpg' or 'png', use .*jpg,.*png
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 209
Attachment (none) A list of labels, used to filter the attachments to display. If you wish to enter more
Labels than one label, separate the labels with commas. Confluence will show only
(labels) attachments that have all the labels specified. (The match is an AND, not an
OR.) For information on labeling the attachments, see Add, Remove and Search
for Labels.
Include Old false A value of true will include previous attachment versions in the list.
Attachment
Versions
(old)
Sort By date The sort order for attachments. Note that people viewing the page can change
(sortBy) the sort order by clicking the column headings. Valid values are:
date sorts by updated date in reverse chronological order (newest first)
size sorts largest to smallest
name sorts alphabetically
created date - sorts by creation date in reverse chronological order (newest
first)
Sort Order ascending Used in combination with the Sort By parameter, to sort the attachments in
(sortOrder ascending or descending order.
)
Allow true If selected, the list of attachments will include options allowing users to browse
Upload for, and attach, new files.
(upload)
Page Title (none) Used to display attachments from another page. If you do not enter a page title,
(page) the macro will display the files attached to the current page.
Show true Used to display a preview of the attached file. If true, preview will be visible when
Previews the list item is expanded.
(preview)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: attachments
{attachments:old=false|patterns=.*png,.*jpg|sortby=name|page=My page
about
chocolate|sortorder=descending|labels=chocolate,cookies|upload=false|pre
view=false}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 210
Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of
suggested macros. Details are in Autocomplete for links, files, macros and mentions.
To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open,
where you can edit the parameters of the macro.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Time No no limit Specify how far back in time Confluence should look for the blog posts
Frame to be displayed.
(time)
Available values:
m Minutes
h Hours, so '12h' displays blog posts created in the last twelve
hours.
d Days, so '7d' displays blog posts created in the last seven
days.
w Weeks
Restrict to No None Filter the results by label. The macro will display only the blog posts
these which are tagged with the label(s) you specify here.
Labels
(label) You can specify one or more label values, separated by a comma or a
space.
To exclude content which matches a given label, put a minus sign
(-) immediately in front of that label value. For example: If you
specify a label value of -badpage you will get only content which is
not labeled with 'badpage'.
To indicate that the results must match a given label value, put a
plus sign (+) immediately in front of that label value. For example: If
you specify a label value of +superpage,+goodpage you will get
only content which has at least two labels, being 'superpage' and
'goodpage'.
Restrict to No None Filter the results by author. The macro will display only the blog posts
these Aut which are written by the author(s) you specify here.
hors
(author)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 211
Restrict to No @self, i.e. This parameter allows you to filter content by space. The macro will
these the space display only the pages which belong to the space(s) you specify here.
Spaces which
(spaces) contains You can specify one or more space keys, separated by a comma or a
the page space.
on which
the macro To exclude content in a specific space, put a minus sign (-)
is coded immediately in front of that space key. For example: If you specify a
space key of -BADSPACE you will get only content which is not in
the BADSPACE.
To indicate that the results must come from a specific space, put a
plus sign (+) immediately in front of that space key. For example: If
you specify a space key of +GOODSPACE you will get only content
in GOODSPACE. (Note that this is not particularly useful, because
each content item belongs to one space only. If you put a plus sign
next to one space key and list other space keys too, the other
space keys will be ignored.)
Special values:
@self The current space.
@personal All personal spaces.
@global All site spaces.
@favorite The spaces you have marked as favorite.
@favourite The same as @favorite above.
@all All spaces in your Confluence site.
* The same as @all above.
When specifying a personal space, remember to use the tilde (~) sign
in front of the username, such as ~jbloggs or ~jbloggs@example.
com.
Maximum No 15 Specify the maximum number of results to be displayed. Note that the
Number of results are sorted first, and then the maximum parameter is applied.
Blog
Posts
(max)
Sort By No creation Specify how the results should be sorted. If this parameter is not
(sort) specified, the sort order defaults to descending order (newest first)
based on the creation date.
Values:
title Sort alphabetically by title.
creation Sort by the date on which the content was added.
modified Sort by the date on which the content was last
updated.
Reverse No false Select to change the sort from descending to ascending order (oldest
Sort first). Use this parameter in conjunction with the Sort By parameter.
(reverse This parameter is ignored if the Sort By parameter is not specified.
)
In storage format and wikimarkup a value of true changes the sort
order.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: blog-posts
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 212
{blog-posts:content=titles|spaces=@self,ds|author=jsmith|time=4w|reverse
=true|sort=creation|max=10|label=chocolate,cookies}
Change-History Macro
The Change-History macro shows the history of updates made to a page: version number, author, date and
comment. It displays the information inline.
Screenshot: The Change-History macro in Confluence
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: change-history
{change-history}
Chart Macro
The Chart macro allows you to display a chart based
on tabular data. When you add the macro to a page,
you:
supply the data to be charted by the macro as
a table in the placeholder of the macro.
edit the macro parameters in the Macro
Browser to configure the format of the chart.
Screenshot 1: A table of data in the Chart macro
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 213
Parameters
Chart Type Parameters | Display Control Parameters | Title and Label Parameters | Data Specification
Parameters | Color Parameters | Axis Parameters | Pie Chart Parameters | Attachment Parameters
These parameters determine the type of chart to display and the way the chart looks.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 214
Type pie The type of chart to display. XY charts have numerical x- and y-axes.
The x values may optionally be time-based (see the Time Series para
meter).
Standard pie, bar, line, area
XY Plots xyArea, xyBar, xyLine, xyStep, xyStepArea, scatter,
timeSeries
Other gantt
Show true Applies to line charts. Shapes are shown at each data point.
shapes
Opacity 75 percent for A percentage value between 0 (transparent) and 100 (opaque) that
3D charts determines how opaque the foreground areas and bars are.
50 percent for
non-stacked
area charts
100 percent for
all other charts
Display false Sets whether to display the rendered body of the macro (usually the data
rendered tables). By default, the chart data table isn't rendered.
data
before the data are displayed before the chart.
after the data are displayed after the chart.
Image format png The image format to be used for the chart.
png
jpg
Chart Subtitle none A subtitle for the chart, using a smaller font than for Title.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 215
The data for the chart is taken from tables found when the macro body is rendered. These options control
how this data is interpreted. By default, numeric and date values are interpreted according to the Confluence
global default language (locale) formats. If conversion fails, other languages defined in Confluence will be
tried. Additional conversion options can be specified using the parameters below.
Tables all first Comma separated list of table ids and/or table numbers (starting at 1)
level tables contained within the body of the macro that will be used as the data for the
chart. If data tables are embedded in other tables, then table selection will be
required. This occurs when more complex formatting is done (for example
using section and column macros).
Columns all columns Comma separated list of column labels and/or column titles and/or column
numbers for tables used for chart data. This applies to all tables processed.
Columns are enumerated starting at 1. Column label is the text for the column
in the header row. Column title is the (html) title attribute for the column in the
header row.
Time false true the x values in an XY plot will be treated as time series data
Series and so will be converted according to date formats.
Date Confluence For time series data, the date format allows for additional customization of the
format language conversion of data to date values. If a Date format is specified, it will be the
defined first format used to interpret date values. Specify a format that matches the
date time series data. See simple date format.
formats
Time Day The time period for time series data. Defines the granularity of how the data is
Period interpreted. Valid values are: Millisecond, Second, Minute, Hour, Day, Wee
k, Month, Quarter, Year.
Language none Use in combination with the Country parameter to form a locale.
These additional number and date formats will be used for data conversion
before the default languages.
Valid values are 2 character ISO 639-1 alpha-2 codes.
Country none Use in combination with the Language parameter to form a locale. Valid
values are 2 character ISO 3166 codes.
Forgive true true the macro tries to convert numeric and date values that do not
totally match any of the default or user-specified formats.
false enforce strict data format. Data format errors will cause the
chart to not be produced.
Color Parameters
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 216
Axis Parameters
Depending on the chart type, the range and domain axis may be customized. These values are automatically
generated based on the data but can be overridden by specifying one or more more of these parameters.
Domain none Only applies to XY plots. Domain axis lower bound. For a date axis, this value
Axis must be expressed in the date format specified by the Date format parameter.
Lower
Bound
Domain none Only applies to XY plots. Domain axis upper bound. For a date axis, this value
Axis must be expressed in the date format specified by the Date format parameter.
Upper
Bound
Domain none Only applies to XY plots. Domain axis units between axis tick marks. For a date
Axis Tick axis, this value represents a count of the units specified in the Time Period param
Unit eter. The Time Period unit can be overridden by specifying a trailing character: y
(years), M (months), d (days), h (hours), m (minutes), s (seconds), u
(milliseconds).
Domain none Only applies to XY plots. The angle for the domain axis label, in degrees.
Axis
Label
Angle
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 217
Pie Section Show only the pie Format for how pie section labels are displayed. The format uses a
Label section key value string with special replacement variables:
%0% is replaced by the pie section key.
%1% is replaced by the pie section numeric value.
%2% is replaced by the pie section percent value.
Example 1: "%0% = %1%" would display something like
"Independent = 20"
Example 2: "%0% (%2%)" would display something like
"Independent (20%)"
Pie Section No exploded Comma separated list of pie keys that are to be shown exploded.
Explode sections Note: requires jFreeChart version 1.0.3 or higher.
Attachment Parameters
These are advanced options that can be used for chart versioning, to enable automation and to improve
performance. Use these options carefully! Normally, the chart image is regenerated each time the page is
displayed. These options allow for the generated image to be saved as an attachment and have subsequent
access re-use the attachment. This can be useful especially when combined with the Cache Pluginto
improve performance. Depending on the options chosen, chart images can be versioned for historical
purposes.
Attachment none The name and location with which the chart image will be saved as an
attachment. The user must be authorized to add attachments to the page
specified.
^attachmentName.png the chart is saved as an attachment to the
current page.
page^attachmentName.png the chart is saved as an attachment to the
page name provided.
space:page^attachmentName.png the chart is saved as an attachment
to the page name provided in the space indicated.
Attachment new Defines the the versioning mechanism for saved charts.
Version
new creates new version of the attachment.
replace replaces all previous versions of the chart. To replace an
existing attachment, the user must be authorized to remove attachments
for the page specified.
keep only saves a new attachment if an existing export of the same
name does not exist. An existing attachment will not be changed or
updated.
Thumbnail false true the chart image attachment will be shown as a thumbnail.
Chart Type Parameters | Display Control Parameters | Title and Label Parameters | Data Specification
Parameters | Color Parameters | Axis Parameters | Pie Chart Parameters | Attachment Parameters
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 218
Examples
Pie Chart
Type pie
Fish Type 2011
Chart Title Fish Sold
2011 Herring 9,500
Bar Chart
Type bar
Fish 2010 2011
Chart Title Fish Type
Sold
Herring 9,500 8,300
Show true
Legend Salmon 2,900 4,200
3D Bar Chart
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 219
Type bar
2009 2010 2011
Show in true
3D Revenue 12.4 31.8 41.1
Show true
Legend
Type Time
Series Month Revenue Month Expenses
XY Line Chart
Type xyLine
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 220
Show true 12 14 23
Legend Revenue 41.1 31.8 12.4
XY Area Chart
Type xyArea
12 14 23
Show true
Legend Revenue 41.1 31.8 12.4
Area Charts
Example 1
Type area
Satisfaction 2009 2010 2011
Show true
Legend Very 20 23 34
satisfied
Width 300
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 221
Opacity 50 Dissatisfied 25 26 25
Very 15 17 18
dissatisfied
Example 2
Type area
Satisfaction 2009 2010 2011
Show true
Legend Very 12 23 31
satisfied
Width 300
Satisfied 1 34 36
Height 300
Dissatisfied 4 6 22
Stacked true
Values Very 2 7 12
dissatisfied
Gantt Chart
Type gantt
Plan Start End Status
Width 300
Stage 1 6/25/2013 7/10/2013 30%
Height 200
Stage 2 7/13/2013 11/28/2013 40%
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 222
Columns ,,1,2,3,4
Stage 3 12/1/2013 12/25/2013
Date MM/dd/yyyy
format
Actual Start End Status
You must include the two leading commas in the column parameter (for example ,,1,2,3,4) for the
chart to be created correctly.
Code examples
This example is useful when you want to add a macro outside the editor, for example as custom content in
the sidebar, header or footer of a space.
Macro name: chart
Macro body: Accepts rich text, consisting of tables that hold the chart's data.
This macro recognizes a large number of parameters, listed here by type.
See all parameters...
These parameters determine the type of chart to display and how the chart looks.
Available values:
Standard charts - pie, bar, line, area
XY plots xyArea, xyBar, xyLine, xyStep,
xyStepArea, scatter, timeSeries
Other charts gantt
orientation No vertical The display orientation. Applies to area, bar and line
charts.
Available values:
vertical y-axis is vertical
horizontal x-axis is vertical
showShapes No true Applies to line charts. Shapes are shown at each data
point.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 223
legend No false Determines whether to show a legend (key) for the chart.
The data for the chart is taken from tables found in the macro body. The parameters below control how
this data is interpreted. By default, numeric and date values are interpreted according to the Confluence
global default language (locale) formats. If conversion fails, other languages defined in Confluence will be
tried. You can specify additional conversion options using the parameters below.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 224
tables No All first level You can supply a comma-separated list of table IDs
tables and/or table numbers (starting at 1) contained within
the body of the macro that will be used as the data
for the chart. If data tables are embedded in other
tables, then table selection will be required. This
occurs when more complex formatting is done (for
example using section and column macros).
dateFormat No Confluence For time series data, the date format allows for
language additional customization of the conversion of data to
defined date date values. If a dateFormat is specified, it will be
formats the first format used to interpret date values. Specify
a format that matches the time series data. See simp
le date format.
timePeriod No day The time period for time series data. Defines the
granularity of how the data is interpreted.
Available values: millisecond, second,
minute, hour, day, week, month,
quarter, year
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 225
Depending on the chart type, the range and domain axis may be customized. These values are
automatically generated based on the data but can be overridden by specifying one or more more of
these parameters.
domainAxisLabelAngle No (None) Only applies to XY plots. The angle for the domain
axis label, in degrees.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 226
pieSectionLabel No Show only the Formatof pie section labels. The format uses a
pie section string with special replacement variables:
key value %0% is replaced by the pie section key.
%1% is replaced by the pie section numeric
value.
%2% is replaced by the pie section percent
value.
Example 1: To display something like
'Independent = 20':
%0% = %1%
%0% (%2%)
These are advanced options that can be used for chart versioning, to enable automation and to improve
performance. Use these options carefully! Normally, the chart image is regenerated each time the page is
displayed. These options allow for the generated image to be saved as an attachment and have
subsequent access to re-use the attachment. This can be useful especially when combined with the
Cache plugin to improve performance. Depending on the options chosen, chart images can be versioned
for historical purposes.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 227
attachment No (None) The name and location where the chart image will be
saved as an attachment. The user must be authorized
to add attachments to the page specified.
Available syntax for this parameter:
^attachmentName.png the chart is saved as
an attachment to the current page.
page name^attachmentName.png the chart
is saved as an attachment to the page name
provided.
name^attachmentName.png the chart is
saved as an attachment to the page name provided
in the space indicated.
attachmentVersion No new Defines the the versioning mechanism for saved charts.
Available values:
new creates new version of the attachment.
replace replaces all previous versions of the
chart. To replace an existing attachment, the user
must be authorized to remove attachments for the
page specified.
keep only saves a new attachment if an existing
export of the same name does not exist. An existing
attachment will not be changed or updated.
Below is a simple example of a pie chart. See more examples in Wiki Markup Examples for Chart Macro.
{chart:type=pie|title=Fish Sold}
|| Fish Type || 2004 || 2005 ||
|| Herring | 9,500 | 8,300 |
|| Salmon | 2,900 | 4,200 |
|| Tuna | 1,500 | 1,500 |
{chart}
This page is an extension of the documentation for the Chart Macro. This page contains additional examples for
the Chart macro.
Pie chart
Wiki markup
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 228
{chart:type=pie|title=Fish Sold}
|| Fish Type || 2004 || 2005 ||
|| Herring | 9,500 | 8,300 |
|| Salmon | 2,900 | 4,200 |
|| Tuna | 1,500 | 1,500 |
{chart}
Resulting chart
Bar chart
Wiki markup
{chart:type=bar|title=Fish Sold}
|| Fish Type || 2004 || 2005 ||
|| Herring | 9,500 | 8,300 |
|| Salmon | 2,900 | 4,200 |
|| Tuna | 1,500 | 1,500 |
{chart}
Resulting chart
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 229
Wiki markup
{chart:type=timeSeries|dateFormat=MM/yyyy|timePeriod=Month|
dataOrientation=vertical|rangeAxisLowerBound=0|domainaxisrotateticklabel
=true}
|| Month || Revenue ||
| 1/2005 | 31.8 |
| 2/2005 | 41.8 |
| 3/2005 | 51.3 |
| 4/2005 | 33.8 |
| 5/2005 | 27.6 |
| 6/2005 | 49.8 |
| 7/2005 | 51.8 |
| 8/2005 | 77.3 |
| 9/2005 | 73.8 |
| 10/2005 | 97.6 |
| 11/2005 | 101.2 |
| 12/2005 | 113.7 |
|| Month || Expenses ||
| 1/2005 | 41.1 |
| 2/2005 | 43.8 |
| 3/2005 | 45.3 |
| 4/2005 | 45.0 |
| 5/2005 | 44.6 |
| 6/2005 | 43.8 |
| 7/2005 | 51.8 |
| 8/2005 | 52.3 |
| 9/2005 | 53.8 |
| 10/2005 | 55.6 |
| 11/2005 | 61.2 |
| 12/2005 | 63.7 |
{chart}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 230
Resulting chart
XY line chart
Wiki markup
{chart:type=xyline}
|| || 12 || 14 || 23 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
Resulting chart
XY bar chart
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 231
Wiki markup
{chart:type=xybar|opacity=60}
|| || 2005 || 2006 || 2007 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
Resulting chart
XY area chart
Wiki markup
{chart:type=xyarea}
|| || 12 || 14 || 23 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
Resulting chart
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 232
Area chart
{chart:type=area|dataDisplay=true|legend=true|width=300|height=300|opaci
ty=50}
|| Satisfaction || 2002 || 2003 || 2004 ||
| Very satisfied | 20 | 23 | 34 |
| Satisfied | 40 | 34 | 23 |
| Disatisfied | 25 | 26 | 25 |
| Very disatisfied | 15 | 17 | 18 |
{chart}
Very satisfied 20 23 34
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 233
Satisfied 40 34 23
Disatisfied 25 26 25
Very disatisfied 15 17 18
{chart:type=area|dataDisplay=true|legend=true|width=300|height=300|stack
ed=true}
|| Satisfaction || 2002 || 2003 || 2004 ||
| Very satisfied | 12 | 23 | 31 |
| Satisfied | 1 | 34 | 36 |
| Disatisfied | 4 | 6 | 22 |
| Very disatisfied | 2 | 7 | 12 |
{chart}
Very satisfied 12 23 31
Satisfied 1 34 36
Disatisfied 4 6 22
Very disatisfied 2 7 12
Cheese Macro
The Cheese macro simply displays the words "I like cheese!" You can use this macro to test the Confluence
macro functionality.
To add the Cheese macro to a page:
1. In the Confluence editor, choose Insert > Other Macros
2. Find and select the required macro
Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of
suggested macros. Details are in Autocomplete for links, files, macros and mentions.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 234
To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open,
where you can edit the parameters of the macro.
Note: There are no parameters for this macro.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: cheese
{cheese}
Example
This list of child pages is generated by a Children Display macro on this page:
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 235
Show false Choose whether to display all the parent page's descendants.
Descendants
(all) If true shows the complete tree of pages underneath the parent page,
regardless of Depth of Descendants
Parent Page current Specify the page to display children for, from either the current space or
(page) a different space. Enter:
'/' to list the top-level pages of the current space, i.e. those
without parents.
'pagename' to list the children of the specified page.
'spacekey:' to list the top-level pages of the specified space.
'spacekey:pagename' to list the children of the specified page
in the specified space.
Number of none Restrict the number of child pages that are displayed at the top level.
Children
(first)
Depth of none Enter a number to specify the depth of descendants to display. For
Descendants example, if the value is 2, the macro will display 2 levels of child pages.
(depth)
This setting has no effect of Show Descendants is enabled.
Include none Allows you to include a short excerpt under each page in the list. Choose
Excerpts between:
(excerpt)
None - no excerpt will be displayed
Simple - displays the first line of text contained in an Excerpt macro
any of the returned pages. If there is not an Excerpt macro on the
page, nothing will be shown.
Rich content - displays the contents of an Excerpt macro, or if there
is not an Excerpt macro on the page, the first part of the page
content, including formatted text, images and some macros.
Reverse Sort false Use with the Sort Children By parameter. When set, the sort order
(reverse) changes from ascending to descending.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: children
{children:reverse=true|sort=creation|style=h4|page=Home|excerpt=none|fir
st=99|depth=2|all=true}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 236
The Code Block macro allows you to display source code in your page with syntax highlighting, like the one
below:
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 237
Syntax java Specifies the language (or environment) for syntax highlighting. The default
highlighting language is Java but you can choose from one of the following
(language) languages/environments:
ActionScript
AppleScript
Bash
C#
C++
CSS
ColdFusion
Delphi
Diff
Erlang
Groovy
HTML and XML
Java
Java FX
JavaScript
Plain Text
PowerShell
Python
Ruby
SQL
Sass
Scala
Visual Basic
Title none Adds a title to the code block. If specified, the title will be displayed in a header
row at the top of the code block.
Collapsible false If selected, the code macro's content will be collapsed upon visiting or refreshing
(collapse) the Confluence page. Clicking the expand source link allows you to view this
content. If false, the code macro's content is always displayed in full.
Show line false If selected, line numbers will be shown to the left of the lines of code.
numbers
(linenumbers
)
First line 1 When Show line numbers is selected, this value defines the number of the first
number line of code.
(firstline)
Theme Default Specifies the color scheme used for displaying your code block. Many of these
themes are based on the default color schemes of popular integrated
development environments (IDEs). The default theme is Confluence (also
known as Default), which is typically black and colored text on a blank
background. However, you can also choose from one of the following other
popular themes:
DJango
Emacs
FadeToGrey
Midnight
RDark
Eclipse
Confluence
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 238
You can configure the Code Block macro to use a specific language and theme by default and also upload new
lanuages. You need Confluence Administrator permissions to change the default theme and language and Sy
stem Administrator permissions to upload new languages.
To set the default appearance of code blocks in your site:
1. Choose the cog icon
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: code
{code:title=This is my
title|theme=FadeToGrey|linenumbers=true|language=java|firstline=0001|col
lapse=true}
This is my code
{code}
Column Macro
Used with the Section macro to define columns on a page. See Working with page layouts and columns and
sections.
Parameters
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 239
width No 100% of the page width, The width of the column. Can be specified either in
divided equally by the pixels (for example, 400px) or as a percentage of
number of columns in the the available page width (for example, 50%).
section.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: column
{column:width=100px}
This is the content of *column 1*.
{column}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 240
CQL filters
CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in some
macros and the Confluence search. Confluence search and CQL-powered macros allow you to add filters to
build up a search query, adding as many filters as you need to narrow down the search results.
Use the Add a filter link to add more filters to your query.
For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a second
Label field to the macro, and put 'label-b' in the second one, like this:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 241
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to add
that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.
You can use the following CQL filters to build your query:
Label* Include pages, blog posts or attachments with these labels. OR (multiple values in the
same filter)
AND (multiple Label filters)
With Include pages that are children of this page. OR (multiple values in the
ancestor same filter)
This allows you to restrict the macro to a single page tree.
Contributor** Include pages or blog posts that were created or edited by OR (multiple values in the
these people. same filter)
Mentioning Include pages and blog posts that @mention these people. OR (multiple values in the
user same filter)
With parent Include only direct children of this page (further sub-pages EQUALS (one page only)
won't be included)
Including Include items that contain this text. CONTAINS (single word or
text** phrase)
With title Include items that contain this text in the title. CONTAINS (single word or
phrase)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 242
Sort by Modified Sort the list by title, the date it was created, or the date it was last modified. If you
don't select an option, CQL default ordering by relevancy is used.
Reverse sort False Sort the list descending instead of ascending (Z - A, earliest - latest)
Maximum 15 Limit the number of items to include in the list. This can be any value up to 500
number of pages.
pages
Show labels True Show or hide the labels applied to each item
for each
page
Show space True Show or hide the space name for each item
name for
each page
Display False Allows you to include a short excerpt under each page in the list. Choose
excerpts between:
None - no excerpt will be displayed.
Simple - displays the first line of text contained in an Excerpt macro any of the
returned pages. If there is not an Excerpt macro on the page, nothing will be
shown.
Rich content - displays the contents of an Excerpt macro, or if there is not an
Excerpt macro on the page, the first part of the page content, as formatted
text, including images and some macros.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 243
Username yes none The Confluence username for a person who has created content.
(name) Parameter is unnamed in wikimarkup.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: content-by-user
{content-by-user:jsmith}
A working example
Below is a working example of the Content Report Table macro, displaying content with the label 'LDAP'.
Connecting to LDAP or JIRA applications or Other Services Nick Faiz about an hour
via SSL ago
User Management Limitations and Recommendations Sarah Maddox Feb 01, 2017
[Atlassian]
Configuring an SSL Connection to Active Directory Sarah Maddox Nov 08, 2016
[Atlassian]
Synchronizing Data from External Directories Sarah Maddox May 27, 2016
[Atlassian]
Connecting to an Internal Directory with LDAP Authentication Sarah Maddox May 27, 2016
[Atlassian]
Requesting Support for External User Management Matt Ryall Oct 07, 2015
Diagrams of Possible Configurations for User Management Sarah Maddox Oct 07, 2015
[Atlassian]
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 244
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Label(s) Yes None This parameter is required. Specify one or more labels, separated by a
(labels) comma. The macro will display the content tagged with any of the
label(s) specified here.
For example, if you specify labels 'A' and 'B', the macro will display all
pages that have the label 'A', and all pages that have the label 'B', and
all pages that have both those labels.
Space(s) No (All Specify one or more space keys, separated by a comma or a space.
(spaces) spaces) The macro will display only the content which belongs to the space(s)
specified here.
When specifying a personal space, remember to use the tilde (~) sign
in front of the username, such as ~jbloggs or ~jbloggs@example
.com.
Maximum No 20 Define the maximum number of pages that the macro will show in a
Number of single set of results. If there are more pages to be shown, the macro
Pages will display a link labeled 'Find more results'. People viewing the page
(maxResults can choose the link to go to a search view, which shows all pages
) tagged with the specified label(s).
Which pages will appear? Before displaying the results, Confluence
will sort them by the date the page was last modified. The
most-recently created/updated pages will appear first.
Wiki markup
Wiki markup is not available for this macro. You cannot add this macro via wiki markup.
Contributors Macro
The Contributors macro displays a list of Confluence users who have made a contribution of some type to a
page. It can also be used to list watchers of the page.
The scope of this macro can be extended to include the immediate children or descendants of the specified
page. The list of contributors can be based on people who have:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 245
In this example, the Display Format parameter has been set to list.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Contribution Type authors Filters by either the type of contribution made to a page (and optionally
(include) its descendant pages), or the watches on the page. Contribution types
are:
authors - includes people who created or have edited the page(s)
comments - includes people who have added comments to the
page(s)
labels - includes people who have added labels to the page(s)
watches - includes people who are watching the page(s).
Sort By count Specifies the criteria used to sort contributors. Sort criteria are:
(order)
count - sorts people based on the total number of contributions to
the page(s)
name - sorts people into alphabetical order
update - sorts people based on the date of their last contribution to
the page(s).
Reverse Sort false Reverses the sort order of contributors in the list. Must be used in
(reverse) conjunction with the Sort By parameter.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 246
Maximum Number of no limit Limits the number of contributors in the list. If a number is not specified,
Contributors all contributors are included.
(limit)
Display Format inline Sets how the list of contributor's names is formatted:
(mode)
inline a comma-separated list
list a bullet list.
Show Anonymous false Sets whether to include those who contributed anonymously to a page.
Contributions?
(showAnonymous)
Show Count? false Sets whether to show the number of times each person made a
(showCount) contribution of the specified Contribution Type.
Show Last false Sets whether to show the last time each person made a contribution of
Contribution Time? the specified Contribution Type.
(showLastTime)
Page Name current Specifies the page to use when generating the list of contributors. If Pag
(page) e Name and Space(s) are left blank, the current page is assumed.
Label(s) none Filters the list of contributors to those who created the specified labels
(labels) from a page. You can specify one or more labels, separated by
commas.
Space(s) current Specifies the space key of the Confluence space that contains the page
(spaces) set in Page Name or alternatively, specifies the spaces to search.
Space keys are case-sensitive.
If no Page Name and Label(s) are specified, all pages from the
specified set of spaces are included.
Content Type both Restricts the content type to use when generating the list of
(contentType) pages contributors:
and blog
posts pages pages
blogposts blog posts.
Blog Post Date none Specifies the publish date for a blog post. The date format required is:
(publishDate) YYYY/MM/DD.
Include Page specified Specifies additional pages to include when generating the list of
Hierarchy page only contributors:
(scope)
children just the child pages of the specified page
descendants all descendants of the specified page.
Show Selected false Sets whether to show a list of the pages used to generate the list of
Pages contributors.
(showPages)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 247
Custom "None default Specifies the message to be used to override the default message that
Found" Message message is displayed when no contributors are found.
(noneFoundMessage
)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: contributors
{contributors:limit=10|spaces=ds,@personal|reverse=true|labels=chocolate
,cake|showPages=true|noneFoundMessage=Oh dear, no contributors
found|showCount=true|contentType=blogposts|include=authors,comments,labe
ls,watches|mode=list|showAnonymous=true|order=update|showLastTime=true|p
ublishDate=2012/06/30}
{contributors:limit=10|spaces=ds,@personal|reverse=true|scope=descendant
s|labels=chocolate,cake|showPages=true|noneFoundMessage=Oh dear, no
contributors
found|showCount=true|contentType=pages|include=authors,comments,labels,w
atches|mode=list|showAnonymous=true|order=update|page=ds:Advanced
Topics|showLastTime=true}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 248
In this example, all default parameter settings are used. For more information about this macro's parameters,
refer to the Parameters section below.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 249
Columns to edits,comments,labels Sets the columns that should appear in the table. The
Display statistics or type of information presented depends on the
(columns) basis for grouping set with the Group By parameter. Statistics
may be calculated for:
edits the number of times each contributor has edited
the page(s) or the number of edits made to each page.
edited a list of the pages edited by each contributor or
a list of contributors who have edited each page.
comments the number of times each contributor has
added comments to the page(s) or the number of
comments on each page.
commented a list of pages to which each contributor
has added comments or a list of contributors who have
commented on each page.
labels the number of times each contributor has
added labels to the page(s) or the number of labels on
each page.
labeled a list of pages to which each contributor has
added labels or a list of contributors who have added a
label to each page.
labellist a list of labels either added by each
contributor or on each page.
watches the number of pages being watched by each
contributor/person or the number of contributors/people
watching each page.
watching a list of pages being watched by each
contributor/person or a list of contributors/people watching
each page.
lastupdate the last time each contributor made an
update or when each page was last updated. Valid
updates can include edit, comment or label modifications
to a page.
Sort By edits Sets the criterion used for sorting items in the table. The items
(order) sorted depend on the basis for grouping set with the Group
By parameter. Sort criteria are:
edits sorts items in the table based on the total
number of edits made, either by a contributor or to a page.
name sorts items in the table in alphabetical order,
either by contributor or page name.
editTime sorts items in the table based on when the
contributor last edited a page (or a specified set of pages)
or when the page was lasted edited.
update sorts items in the table based on when the
contributor last made any contribution to a page (or a
specified set of pages) or when the page last had any
contribution made to it.
Reverse Sort false Reverses the sort order of items in the table, as specified
(reverse) using the Sort By parameter. (Used only in conjunction with
the Sort By parameter.)
Maximum Number no limit Limits the number of contributors or pages in the table to the
of Items value specified. If no number is specified, all items are
(limit) included.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 250
Show Anonymous false Includes individuals who have made anonymous contributions
Contributions? to a page.
(showAnonymous)
Show Zero false Sets whether contributors or pages are included for which a
Counts? calculated statistic is zero.
(showZeroCounts
)
Page Name current Sets the page for which to calculate the contribution-based
(page) statistics. If no values for Page Name and Space(s) are
specified, the current page is assumed.
Space(s) current Specifies the space key of the Confluence space which
(spaces) contains the specified page name or alternatively, specifies a
scope of spaces to search. Space keys are case-sensitive.
Content Type both pages and blog Restricts page types to either pages (pages) or blog posts (bl
(contentType) posts ogposts). If no value is specified in the Macro Browser, both
pages and blog posts are included.
Available values pages and blogposts.
Blog Post Date none Specifies the publish date for a blog post. The date format
(publishDate) required is: YYYY/MM/DD.
Include Page specified page only Includes either the immediate children or all descendants of
Hierarchy the specified page. If no value is indicated in the Macro
(scope) Browser, only the specified page is included.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: contributors-summary
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 251
{contributors-summary:limit=10|spaces=ds,@personal|reverse=true|showAnon
ymous=true|order=update|labels=chocolate,cake|columns=edits,comments,lab
els,lastupdate|groupby=pages|contentType=blogposts|showZeroCounts=true|p
ublishDate=2012/06/07}
{contributors-summary:limit=10|spaces=ds,@personal|reverse=true|showAnon
ymous=true|scope=descendants|order=update|page=ds:Advanced
Topics|labels=chocolate,cake|columns=edits,comments,labels,lastupdate|gr
oupby=pages|contentType=pages|showZeroCounts=true}
Example
Screenshot: A page with three buttons, all displayed by the 'Create from Template' macro
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 252
Button 'Create from The description that people will see when viewing this macro on the
Text Template' page.
Template None Select the template or blueprint to base the new page on. Only
Name global and user-created templates for the current space appear
(unless you have specified a different space in the 'Space Key'
field).
Template Blank Specify a default title for pages created using this macro (optional).
Title You can include @currentDate, @spaceName and @spaceKey
variables in the title.
Space The space Supply the unique space identifier (space key), to determine where
Key where the the new page will be created when someone uses this macro to
current page create a page.
is located
Wiki markup
Wiki markup is not available for this macro. You cannot add this macro via wiki markup.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Icon Size large Specify whether to use large or small icon. Available values:
size
large
small
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: create-space-button
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 253
{create-space-button:size=small}
{create-space-button:height=50px|width=50px}
width No Natural The width of the icon to be displayed, specified in pixels. Confluence
size of will stretch or shrink the width of the icon to the number of pixels
icon specified.
(1:1 Note: This parameter is not available via the macro browser.
pixel
ratio)
height No Natural The height of the icon to be displayed, specified in pixels. Confluence
size of will stretch or shrink the height of the icon to the number of pixels
icon specified.
(1:1 Note: This parameter is not available via the macro browser.
pixel
ratio)
Example
The paragraph below shows an example of an Excerpt Include macro, containing content from an excerpt which
we have defined on the Excerpt Macro page. On the Excerpt Include macro below, we have set the options to
show both the title of the page and the panel surrounding the content.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 254
Page Containing the none Type the name of the page that contains the excerpt to be displayed.
Excerpt You can use an excerpt from a page in the same space or another space
(default-parameter in the same wiki.
)
When you type the name of the page into the Excerpt Include macro
dialog, Confluence will offer a list of matching pages, including those
from other spaces.
Alternatively, you can type the space key followed by a colon (:) and the
page name, like this:
SPACEKEY:Page name
Remove Surrounding false Determines whether Confluence will display a panel around the
Panel excerpted content. The panel includes the title of the page containing the
(nopanel) excerpt, and the border of the panel. By default, the panel and title are
shown.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: excerpt-include
Excerpt Macro
The Excerpt macro is used to mark a part of a page's content for re-use. Defining an excerpt enables other
macros, such as the Excerpt Include and Blog Posts macros, to display the marked content elsewhere.
You can only define one excerpt per page. In other words, you can only add the Excerpt macro once to a page.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
2.
Confluence 6.4 documentation 255
it. Note that this option affects only the page that contains the Excerpt macro. It does not affect any pages
where the content is reused.
Screenshot: The Excerpt macro placeholder and options panel
1. New line
2. Inline
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Hide false Controls whether the page content contained in the Excerpt macro placeholder is
Excerpted displayed on the page.
Content
(hidden) Note that this option affects only the page that contains the Excerpt macro. It
does not affect any pages where the content is reused.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: excerpt
{excerpt:hidden=true|atlassian-macro-output-type=BLOCK}
This is the *text* I want to reuse in other pages. This text is inside
an Excerpt macro.
{excerpt}
Expand Macro
The Expand macro displays an expandable/collapsible section of text on your page.
Here is an example:
Expand me...
This text is hidden until you expand the section.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 256
To insert the Expand macro into a page using the macro browser:
1. In the Confluence editor, choose Insert > Other Macros
2. Find and select the required macro
Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of
suggested macros. Details are in Autocomplete for links, files, macros and mentions.
To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open,
where you can edit the parameters of the macro.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Title Click here to expand... Defines the text that appears next to the expand/collapse icon.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: expand
{expand:This is my message}
This text is _hidden_ until you expand it.
{expand}
Notes
Text is expanded in PDF and HTML exports. When you export the page to PDF or HTML, the text
between the macro tags is expanded so that readers can see it in the PDF and HTML versions of the
page.
Nesting your Expand macros. You can put one Expand macro inside another, and Confluence will
correctly show and hide the contents of all Expand macros, including the nested ones.
Favorite Pages Macro
Use the Favorite Pages macro to list the pages you've saved for later on a Confluence page. You can also get
to your saved pages from the Dashboard.
Screenshot: The Favorite Pages Macro in Confluence
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 257
To insert the favorite pages macro into a page using the Macro Browser:
1. In the Confluence editor, choose Insert > Other Macros
2. Find and select the required macro
Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of
suggested macros. Details are in Autocomplete for links, files, macros and mentions.
To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open,
where you can edit the parameters of the macro.
There are no parameters for this macro.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: favpages
{favpages}
Gadget Macro
Gadgets are small applications that can offer dynamic content. They are typically served from a web application
server and can be re-used in many other web applications. In Confluence, use the Gadget macro to add gadgets
to pages or blog posts.
Confluence comes bundled with a few of its own gadgets that you can add to your pages or blog posts.
However, you can access additional gadgets in this list if your Confluence Administrator has:
Installed additional gadgets in Confluence (typically as a Confluence plugin) or
Registered gadgets served from an external web application or website (such as those from a JIRA
application).
Unlike other macros, the name of each gadget macro is unique and follows the convention "<gadget-name>
macro", where <gadget-name> is the name supplied by the gadget itself.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 258
Almost all gadgets allow you to set basic parameters (listed below), which appear on the right of the macro
dialog. Each gadget may also have its own set of parameters, which appear on the left of the macro dialog.
Width 450 pixels Set the width of the gadget, using one of the following conventions:
Width in pixels, using px or plain numbers. For example, 500px or 500
A percentage of the page width, using %. For example, 50%
Automatic resizing of the gadget to fit 100% of the page width: auto
In the addition to the standard parameters, the gadget macro contains 'parameter-like' content, which represents
specific property settings that are particular to each gadget. Hence they are not documented here. Typically, this
content would only be changed by customizing the gadget's default properties using the macro browser.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: gadget
{gadget:width=500|border=false|url=rest/gadgets/1.0/g/com.atlassian.conf
luence.plugins.gadgets:confluence-page-gadget/gadgets/confluence-page-ga
dget.xml}
spaceName=Documentation&spaceKey=DOC&quickfind-space=Documentation&pageI
d=753666&pageName=Documentation%20Home&quickfind-page=Documentation%20Ho
me&isEditable=true&isConfigured=true&refresh=15&showLink=false {gadget}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 259
{gadget:url=rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:
confluence-news-gadget/gadgets/confluence-news-gadget.xml} {gadget}
url Yes (none) This is the location of the gadget specification (XML
file).
A note about editing a gadget's properties (preferences) in markup: It is possible to edit the values of
these properties directly in the wiki markup or storage format. However, this will allow the entry of invalid
values. If a gadget property supports a certain set of values, the macro browser will restrict the user to
selecting only valid values for that property. For that reason, we recommend that you use the macro browser
to edit a gadget's properties.
Gallery Macro
The Gallery macro displays a collection of thumbnail images in a table, based on the images attached to a
Confluence page. When viewing the page, a user can click a thumbnail image to zoom into a screen-sized
image and then view the images as a slide show.
Overview:
The images shown in the gallery are taken from the files attached to the Confluence page. You can also
specify a different page where the attachments are located. For information about attaching images to a
page, see Upload Files.
The captions below the images are drawn from the comments on the attachments. For information about
adding comments to attachments, see Upload Files.
By default, the gallery will include all the images attached to the page. You can also exclude or include
images using parameters.
You can sort your images into a particular order.
You can specify a title for the gallery and also configure how many columns you want for the table in
which your images are displayed.
Illustration: Live example of the Gallery macro
Error rendering macro 'gallery' : Could not initialize class org.apache.commons.lang.text.StrTokenizer
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 260
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
The full list of parameters is shown in the following table. If the name of an attached file or page contains a
comma, you can refer to it in the relevant parameters below by enclosing it in single or double quotes, for
example "this,that.jpg", theother.png
Images to No exclusions. The gallery will ignore any pictures specified. You can specify
Exclude Include all the more than one picture, separated by commas.
(exclude) pictures on the page. Note: The filename and filetype for this parameter are
case-sensitive. For example, 'my picture.PNG' will not be
recognized as 'my picture.png'.
Include these Include all the If you specifically include one or more pictures, the gallery will
Images Only pictures on the page. show only those pictures. You can specify more than one picture,
(include) separated by commas.
Note: The filename and filetype for this parameter are
case-sensitive. For example, 'my picture.PNG' will not be
recognized as 'my picture.png'.
Exclude Images No exclusions. The gallery will ignore any pictures that have the specified label.
with these Include all the You can specify more than one label, separated by commas. For
Labels pictures on the page. information on labeling the attachments, see Add, Remove and
(excludeLabel Search for Labels.
)
Include Images None. The images Filters the images to display, based on a list of labels. If you wish
with these are not filtered by to enter more than one label, separate the labels with commas.
Labels Only label. Confluence will show only images that have all the labels
(includeLabel specified. (The match is an AND, not an OR.) For information on
) labeling the attachments, see Add, Remove and Search for
Labels.
Use Images in If no page is Specify the title of the page which contains the images you want
these Pages specified, the gallery displayed. You can specify more than one page name, separated
(page) macro displays the by commas. To specify a page in a different space, use the
images attached to following syntax: SPACEKEY:Page Title
the page on which
the macro is used.
Sort Images By None. The sort order Specify an attribute to sort the images by. Sort order is
(sort) is unspecified and ascending, unless you select the Reverse Sort parameter (see
therefore below). Options are:
unpredictable.
name file name.
comment comment linked to the attached file.
date date/time last modified.
size size of the attached file.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 261
Reverse Sort Off. Sort order is Used in combination with the Sort Images By parameter above.
(reverse) ascending Use Reverse Sort to reverse the sort order, from ascending to
descending.
Available values in storage format and wikimarkup:
true Sort order is descending.
false Sort order is ascending.
You can attach image files of any format to a page. Confluence supports the following image formats in the
Gallery macro and when displaying an image on a page:
gif
jpeg
png
bmp (depending on browser support)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: gallery
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 262
Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of
suggested macros. Details are in Autocomplete for links, files, macros and mentions.
To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open,
where you can edit the parameters of the macro.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Width of 99% Specify the width of the table in which the links are displayed, as a percentage of
Table the window width.
(width)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: global-reports
{global-reports:width=50%}
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 263
HTML Page's URL Yes None The URL of the page to include.
(url)
The HTML Include macro is disabled by default. You'll need Confluence Administrator or System Administrator
permissions to enable this macro.
Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks. You should
only turn on these macros if you trust all your users not to attempt to exploit them. We strongly recommend
leaving this macro disabled if you allow self-signed up or anonymous users to create content.
To enable the HTML Include macro:
1. Go to
> Add-ons
2. Select System from the drop down and search for the Confluence HTML Macros add-on.
3. Expand the add-on and enable the html-include (html-include-xhtml) module.
Administrators can also choose to use the whitelist to restrict URLs that can be displayed in the HTML Include
macro.
Troubleshooting
Administrators can define a whitelist of trusted URLs. If a URL is not in the whitelist, you will see an error
message in the HTML Include macro.
You can only use the HTML Include macro for pages with absolute links. If you use the macro to include
an HTML page that has relative links, you will see a 'Page Not Found' error. See
CONFSERVER-6567 - HTML Include macro should rewrite relative links to point to remote site
RESOLVED .
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: html-include
{html-include:url=http://www.example.com}
HTML Macro
The HTML macro allows you to add HTML code to a Confluence page.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 264
suggested macros. Details are in Autocomplete for links, files, macros and mentions.
To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open,
where you can edit the parameters of the macro.
There are no parameters for this macro.
Enter the HTML code into the body of the macro placeholder.
The HTML macro is disabled by default. You'll need Confluence Administrator or System Administrator
permissions to enable this macro.
Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks. You should
only turn on these macros if you trust all your users not to attempt to exploit them. We strongly recommend
leaving this macro disabled if you allow self-signed up or anonymous users to create content.
To enable the HTML macro:
1. Go to
> Add-ons.
2. Select System from the drop down and search for the Confluence HTML Macros add-on.
3. Expand the add-on and enable the html (html-xhtml) module.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: html
IM Presence Macro
The IM Presence macro indicates graphically when a contact is signed into an Instant Messaging (IM) service.
The IM Presence macro appears as a small icon on the page.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 265
Parameter Description
User ID/Screen Identify the user by their ID, account name or screen name.
Name
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: im
{im:MySkypeName|service=skype|showid=false}
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 266
Page to None This is the name of the Confluence page or blog post that you want to include in the
Include current page. Start typing a page title, and Confluence will suggest matching pages
from the current space and other spaces.
Alternatively you can specify the page as follows:
If the page or blog post is located in another space, add the space key and a colon
in front of the page name. For example, DOC:My page name. The space key is
case sensitive.
To include a blog post, specify the date as well as the title of the blog post. For
example: /2010/12/01/My blog post.
You can include pages from personal spaces using ~username as the space key,
where 'username' is the person's username. For example, ~jsmith:My page
name.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: include
Notes
If you want to include part of a page rather than the whole page, use the Excerpt and Excerpt Include mac
ros.
To display a page's contents, you need 'View' permission for that page. Similarly, people who view the
page will need 'View' permissions for the embedded page as well as the page into which it is embedded.
See space permissions or contact your Confluence space administrator for more information.
If you want to embed an external page into a Confluence page, you need the HTML Include Macro.
Sample Include Page
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 267
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Optional Title none The title of the box. If specified, the title text will be
(title) displayed in bold next to the icon.
This example is useful when you want to add a macro outside the editor, for example as custom content in
the sidebar, header or footer of a space.
Macro name: info/tip/note/warning
{info:title=This is my title|icon=false}
This is _important_ information.
{info}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 268
Pie chart
Pie charts can be used to report on issue status, priority, assignee and more.
To further control how this chart appears on your page. Choose Display options:
Chart by - select the field you want to segment the pie chart by such as:
Status
Fix version
Assignee name
Priority
Component
Issue type
Width - define the total width of the chart area. You can enter values in pixels, percent or leave blank
to auto fit.
Show border - add a border around the chart area.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 269
Show chart information - include a text summary under the chart with the total issues count and
chart by value.
Created vs Resolved charts can be used to show the difference between the number of issues created
versus the number of issues resolved over time.
To further control how this chart appears on your page choose Display options:
Period - choose a time frame to report by (week, month, quarter etc).
Days previously - the total number of days to report on (counting back from today).
Cumulative totals - choose to progressively add totals or report individual values for each period.
Show unresolved trend - add a subplot showing unresolved issues over time.
Show versions - indicate version release dates as a vertical line on the chart.
Width - define the total width of the chart area. Enter values in pixels, percent or leave blank to auto
fit.
Show border - add a border around the chart area
Show chart information - include a text summary under the chart with the total issues count and
chart by value.
Two Dimensional Charts can be used to show issue statistics in a matrix. You can configure the X and Y
axes to display these issue fields:
Status
Priority
Assignee
Fix version
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 270
Component
Issue type.
For example you could use the chart to show issue types by status (as shown above).
To configure the chart axes choose Display options:
X Axis - the issue field to display on the X axis (columns).
Y Axis - the issue field to display on the Y axis (rows).
Rows to display - the maximum number to display in the chart.
The functionality is provided by an add-on (plugin) called 'JIRA Macros'. This macro is also used for the JIRA
Issues macro. To make the macro unavailable on your site, you can disable the add-on. See Disabling and
enabling add-ons.
Notes
HTTPS: The JIRA Chart macro can access a JIRA site running under SSL provided the Confluence server is
configured to accept the JIRA SSL certificate. See Connecting to LDAP or JIRA applications or Other
Services via SSL.
Authentication: If the query includes issues that require authentication (issues that are not visible to
anonymous users in JIRA), users will be prompted to authenticate to view charts on the Confluence page.
In order to search for issues in the macro browser you may need to authenticate. With JIRA 5.x you will be
able to search for unrestricted issues as an anonymous user, however with JIRA 6.x you must be
authenticated to search for any issues.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 271
Create new issues and display the issues on your page without leaving Confluence.
You can use the macro to display a table of issues on your page, based on the results of a search using JIRA
Query Language (JQL).
JQL is a simple query language that is similar to SQL. A basic JQL query consists of a field, followed by an oper
ator (such as = or >), followed by one or more values or functions.
Examples:
The following query will find all issues in the 'TEST' project:
project = "TEST"
The following query will find all issues in the 'documentation' component of the 'CONF' project:
For more information about JQL syntax, see Advanced searchingin the JIRA Software documentation.
To display a table of issues based on a JQL search:
1. Insert the JIRA Issues macro onto your Confluence page, as described above.
2. Choose a JIRA server next to the Search button.
3. If prompted, log in to the JIRA server.
4. Enter the JQL query into the Search box.
5.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 272
5. Choose Search.
6. If you want to customize the display, choose Display options and adjust the columns and number of
issues that will appear in your table of issues.
7. Choose Insert.
Screenshot: Display options in the JIRA Issues macro browser.
You can paste any of the following JIRA application URLs into the JIRA Issues macro. Confluence will
immediately convert the URL to a JQL search.
Any URL for an issue search or filter.
A URL for a single issue.
The URL of the XML view of a search.
Auto-convert: You can paste URLs directly into the Confluence editor (without calling up the macro browser).
Confluence will automatically convert the URL into a JIRA Issues macro.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 273
You can choose to display the number of issues returned by your search, rather than a table of issues. The JIRA
Issues macro will display a count of issues, linked to the search in your JIRA application.
Screenshot: The JIRA Issues macro displaying an issue count on a Confluence page
While editing a Confluence page, you can create an issue in JIRA and display it on your Confluence page,
without leaving the Confluence editor.
To create an issue and add it to your page:
1. Add the JIRA Issues macro to the page, as described above.
2. Choose Create New Issue.
3. Supply the information about your JIRA server, project, and issue, as prompted.
4. Choose Insert.
Confluence will send a request to your JIRA application, to create the issue, then display the newly created issue
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 274
on your page.
Limitations
The JIRA Issues macro will notify you if it is unable to create an issue in the selected project. This may be
because the project has a required field, field configuration or other customization that is not supported by the
JIRA Issues macro. In this situation you will need to create the issue directly in your JIRA application.
Before you can use this macro, your Confluence and JIRA sites must be connected via Application Links.
If the JIRA site allows anonymous users to view issues, you must configure an application link, but there's no
need to configure any incoming or outgoing authentication between the JIRA application and Confluence.
People viewing the Confluence page will see the publicly accessible issues.
If your JIRA site has restricted viewing, or if some projects or issues are restricted to viewing by certain people,
then people will be prompted to Log in & Approve before seeing the restricted issues.
Formatted fields from JIRA can be displayed in Confluence if you set up a Confluence-to-JIRA application link.
Otherwise, such formatted fields will be escaped within the output of the JIRA issues macro. This is to prevent
the possibility of malicious HTML being served by an untrusted JIRA server. The most likely field where you will
notice this is in the description field.
This example shows how a description column may be displayed in JIRA:
Description
This is
the description
of my issue
If there is no application link between JIRA and Confluence, the description will appear in the JIRA issues macro
like this:
Description
<p>This is<ul><li>the description</li><li>of my issue</li></ul></p>
The functionality is provided by an add-on (plugin) called 'JIRA Macros'. To make the macro unavailable on your
site, you can disable the add-on. See Disabling and enabling add-ons.
Notes
HTTPS: The JIRA Issues macro can access a JIRA application running under SSL provided the Confluence
server is configured to accept the JIRA SSL certificate. See Connecting to LDAP or JIRA applications or Other
Services via SSL.
Custom fields can be added as columns to the table simply by using the name of the field with no quotes. Earlier
versions of the macro required you to use the custom field id, e.g. customfield_10100.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: jiraissues
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 275
{jiraissues:anonymous=true|url=https://jira.atlassian.com/issues/?filter
=41225}
A number of additional parameters that are not available via the macro browser are available in storage format
and wiki markup.
See additional parameters...
anonymous No false If this parameter is set to 'true', your JIRA application will return
only the issues which allow unrestricted viewing. That is, the
issues which are visible to anonymous viewers. If this
parameter is omitted or set to 'false', then the results depend
on how your administrator has configured the communication
between the JIRA application and Confluence. By default,
Confluence will show only the issues which the user is
authorized to view.
Note: This parameter is available only if you insert the macro
via wiki markup or by editing the storage format of the page.
The macro browser does not offer this parameter.
baseurl No The value of If you specify a 'baseurl', then the link in the header, pointing to
the 'url' your JIRA application, will use this base URL instead of the
parameter value of the 'url' parameter. This is useful when Confluence
connects to JIRA with a different URL from the one used by
other users.
count No false If this parameter is set to 'true', the issue list will show the
number of issues in JIRA. The count will be linked to your JIRA
site.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 276
cache No on The macro maintains a cache of the issues which result from
the JIRA query. If the 'cache' parameter is set to 'off', the
relevant part of the cache is cleared each time the macro is
reloaded. (The value 'false' also works and has the same effect
as 'off'.)
Note: This parameter is available only if you insert the macro
via wiki markup or by editing the storage format of the page.
The macro browser does not offer this parameter.
height No 480 (if The height in pixels of the table displaying the issues.
render mode Note that this height specification is ignored in the following
is dynamic) situations:
If the 'renderMode' parameter (see below) is set to 'static'.
When the issues are displayed in a PDF or Word
document, in an email message or in an RSS feed.
Note: This parameter is available only if you insert the macro
via wiki markup or by editing the storage format of the page.
The macro browser does not offer this parameter.
renderMode No static If the value is 'dynamic', the JIRA Issues macro offers an
interactive display which people can manipulate as follows:
Click the column headers to sort the output.
Drag and drop the columns into a different order.
Temporarily remove a column from the display.
View a page of issues at a time, for faster response times.
A value of 'static' will disable the dynamic display features.
Note: This parameter is available only if you insert the macro
via wiki markup or by editing the storage format of the page.
The macro browser does not offer this parameter.
title No JIRA Issues You can customize the title text at the top of the issues table
with this parameter. For instance, setting the title to
'Bugs-to-fix' will replace the default 'JIRA Issues' text. This can
help provide more context to the list of issues displayed.
Note: This parameter is available only if you insert the macro
via wiki markup or by editing the storage format of the page.
The macro browser does not offer this parameter.
url Yes none The URL of the XML view of your selected issues.
Note: If the URL in the 'url' parameter does not contain a temp
Max argument, then the value of tempMax will default to 500. If
your JIRA server is version 3.12 or earlier, this means that the
JIRA Issues macro will return a maximum of 500 issues. If your
JIRA server is version 3.13 or later, a value of 500 means that
the JIRA Issues macro will return a maximum of 500 issues per
page.
width No 100% The width of the table displaying the issues. Can be entered as
a percentage (%) or in pixels (px).
Note: This parameter is available only if you insert the macro
via wiki markup or by editing the storage format of the page.
The macro browser does not offer this parameter.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 277
server. JUnit is a unit testing framework which allows programmers to ensure that individual units of Java source
code are functioning correctly.
For security reasons JUnit test result files can only be imported from a specified location in the
Confluence server's file system. We recommend administrators create a folder in their Confluence home
directory, add the system property confluence.junit.report.directory and specify the location for
JUnit test result files to be imported from. JUnit Test result files cannot be imported from the server until this
system property is set.
The JUnit Report macro appears as shown in the screenshot below.
Screenshot: The JUnit Report macro in Confluence
Note:When generating reports from the JUnit Report macro, set the Apache Ant formatter to 'XML'.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
URL of the test Must None URL of a particular test result XML file. Is overridden by the Directory (URL) o
result XML file include your test result files parameter if you use both.
(url) either the d
Example, from a Confluence instance: http://yourConfluenceInstance
irectory
om/download/attachments/<page id>/file.xml
or the url
parameter For Confluence installations without anonymous user access, you can specify
logon credentials as part of this parameter in the form of URL parameters:
os_username The username of a Confluence user with permission to
access to the JUnit test results.
os_password The password of the Confluence user specified in the os
username parameter.
Directory (URL) Must None URL of a directory containing your test result files. This must be a directory nam
of your test include and not the XML file itself. Overrides the URL of the test result XML file para
result files either the d eter if you use both.
(directory) irectory
Example, file:///C:/TEMP/
or the url
parameter Example, for a network drive: http://*host*/*path*
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 278
Report Detail No all Detail for the report. Can be all, fixture, summary or failuresonly.
(reportdetail
)
Debug No None Shows the content of failures, as well as the error messages.
(debug)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: junitreport
{junitreport:directory=file:///C:/TEMP/}
{junitreport:url=http://*host*/*path*}
{junitreport:url=http://yourConfluenceInstance.com/download/attachments/
<page id>/file.xml}
{junitreport:url=http://yourConfluenceInstance.com/download/attachments/
<page id>/file.xml?os_username=admin&os_password=secret}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 279
To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open,
where you can edit the parameters of the macro.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Restrict to this Space No Current The key of the space whose labels you want to
Key space display.
(spaceKey)
Excluded label(s) No Blank The labels that you do not want to appear in the list.
(excludedLabels)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: listlabels
{listlabels:spaceKey=DOC}
Livesearch Macro
The Livesearch macro allows you to add a search box to a Confluence page. When users enter a search term
into the search box, Confluence will dynamically display matching results as they type.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Restrict to this all Specify a space key to limit the search to the given space. Case-sensitive.
Space Key spaces
(spaceKey) Alternatively, use @self to restrict the search to the current space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 280
Restrict to Specify labels to limit the search to content with that label. If unspecified will
label(s) search all content regardless of label.
(labels)
Placeholder Specify the placeholder text to appear in the search field, for example 'Search
text this space'
(placeholder
)
Type all Specify the content types to be included in the search - choose from pages,
(type) blogs, comments, space descriptions, or all content types.
Additional space Display the space name, a page excerpt or nothing under the search result.
(additional) name
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: livesearch
Loremipsum Macro
The Loremipsum macro displays paragraphs of pseudo-Latin text (more information). You can use this macro to
generate more-or-less meaningless text for demonstration purposes in pages showing a draft layout or
arrangement of page elements. The text is deliberately non-meaningful so that it does not influence the viewer's
perception of the page arrangement or design.
A basic example of the Loremipsum text:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum vestibulum est. Cras
rhoncus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis
egestas. Sed quis tortor. Donec non ipsum. Mauris condimentum, odio nec porta tristique, ante
neque malesuada massa, in dignissim eros velit at tellus. Donec et risus in ligula eleifend
consectetur. Donec volutpat eleifend augue. Integer gravida sodales leo. Nunc vehicula neque ac
erat. Vivamus non nisl. Fusce ac magna. Suspendisse euismod libero eget mauris.
Parameters
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 281
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Number of 3 Determines the amount of pseudo-Latin (space-filler) text to display. The macro
Paragraphs will display a maximum number of 30 paragraphs.
Parameter is unnamed in storage format and wikimarkup.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: loremipsum
{loremipsum:2}
Multimedia Macro
Use the multimedia macro to embed attached video, animation, and other multimedia files to your page. The
macro uses the HTML5 <video> tag, so the type of video your page viewers can see depends on the video
formats their browser supports with the HTML5 <video> tag. For example, Quicktime videos (.mov or .qt) can
only be viewed in Safari, as that file type is not supported by other browsers.
If you want to display online multimedia content, like YouTube and Vimeo videos, take a look at the Wid
get Connector Macro.
The file preview also supports MP3 audio and MP4 video files. This is handy when you want to play a
video in a larger format.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 282
Page name ( No Current page The name of the page to which the multimedia file is
page) attached. Start typing the name of the page and then select it
from list of suggested pages. Include the spacekey if you
want to specify a page in another space (for example, MYSPA
CE:My Page Title)
File* (name) Yes None File name of the attached multimedia file.
Width No If not specified, Width of the movie window to be displayed on the page. By
the browser will default, this value is specified in pixels. You can also choose
determine the to specify a percentage of the window's width, or any other
width based on value accepted by HTML.
the file type.
Height No If not specified, Height of the movie window to be displayed on the page. By
the browser will default, this value is specified in pixels. You can also choose
determine the to specify a percentage of the window's height, or any other
height based on value accepted by HTML.
the file type.
Autoplay (au No false If the parameter is set to true then the video or audio file will
tostart) start playing as soon as the page is loaded. If this option is
set to false then the file will not play until the user clicks the
icon or image on the page.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: multimedia
{multimedia:space=DOC|page=My macros|name=ninjas.swf|autostart=true}
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 283
Label none Specify the label associated with the pages you want to show in the navigation
map.
This parameter is unnamed in storage format and wikimarkup.
Cell Width 90 Specify the cell width (enter a number only, don't include px)
(Pixels)
(cellWidth)
Cell Height 60 Specify the cell height (enter a number only, don't include px)
(Pixels)
(cellHeight
)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: navmap
{navmap:mylabel|wrapAfter=4|title=My map
name|cellHeight=50px|theme=navmap-mytheme.vm|cellWidth=80px}
Network Macro
The Network macro displays a list of Network activity on a Confluence page or blog post. You can specify the
user whose network activity you wish to show. These interactions include the users that the specified user is
following or users who are following the specified user. The Network macro shows each listed user by their
profile picture. It also provides a choice of two themes and the ability to limit the number of users in the list.
Screenshot: Network macro
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 284
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Username Current The username of the Confluence user whose network interactions you wish to
user's show. If no username is specified, then current user's (that is, your) network
username interactions are shown.
Mode following Determines which users are listed, with respect to the specified user:
following those who the user is following.
followers those who are following the user.
This parameter is unnamed in storage format and wikimarkup.
Maximum No limit Restricts the number of users displayed. If the number of users exceeds the
Results imposed up specified maximum, then a Show All link is provided. This link leads to the
to a specified user's Network view, showing the complete list of network interactions.
(max) maximum of
30
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: network
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 285
{network:followers|username=admin|max=10|theme=full}
The Network macro is provided by the 'network' module in the 'Profile Macros' plugin. To remove the macro from
your site, you can disable the module in the plugin. See Disabling and enabling add-ons.
Noformat Macro
The Noformat macro displays a block of text in monospace font with no other formatting.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: noformat
{noformat:nopanel=true}http://www.example.com{noformat}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 286
The Office Excel macro displays the content of an Excel spreadsheet on a wiki page. First attach the
spreadsheet to a Confluence page, then use the macro to display the content. When viewing the page, people
will see the content of the spreadsheet, without needing to have Office installed.
For details, see the View File Macro.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: viewxls
{viewxls:col=5|page=Docs|name=My
document.xls|grid=false|sheet=mysheet|row=5}
The Office PowerPoint macro displays the content of a PowerPoint presentation on a wiki page. First attach the
presentation to a Confluence page, then use the macro to display the content. When viewing the page, people
will see the content of the presentation, without needing to have Office installed.
For details, see the View File Macro.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: viewppt
{viewppt:height=20%|page=Docs|width=20%|name=My document.ppt|slide=4}
The Office Word macro displays the content of a Word document on a wiki page. First attach the document to a
Confluence page, then use the macro to display the content. When viewing the page, people will see the content
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 287
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: viewdoc
{viewdoc:page=Docs|name=My document.doc}
The Page Index macro can be quite memory hungry in large spaces. To prevent it causing out of
memory errors in your site, we don't show page excerpts when there are more than 200 pages in the
space, and don't list any pages if there are more than 5000 in the space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 288
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: index
{index}
Next you need to add the Page Properties Report macro to another page.
Here's an example of the Page Properties macro in the editor. Deadline, Current Status, and Team will be
column headings in the report.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 289
Here's what the example above will look like in the Page Properties Report.
You can also set up the Page Properties macro horizontally. To do this:
Create a two row rather than two column table, and ensure the first row has the heading row style
applied.
List your keys in the first row, and values in the second row.
The Page Properties Report Macro will be able to pull this information accurately even if you're using the
Page Properties Macro vertically elsewhere.
You can add multiple Page Properties macros on a single page, and choose whether to include all or only
specific macros in the report. You might use multiple macros because you want the information in the macro
to display in context with the rest of the page, or because you want to be able to report on individual Page
Properties macros separately.
The Page Properties macro includes an optional ID parameter that can be used to identify specific Page
Properties macros.
To show the contents of all Page Properties macros in the report:
1. Add a label to the page containing the Page Properties macros
2. Specify this label in the Page Properties Report macro
To show the contents of selected Page Properties macros in the report:
1. Add a label to the page containing the Page Properties macros
2. Specify an ID in the Page Properties macro that you want to report on
3. Specify both the label and ID in the Page Properties Report macro
Note: The Page Properties Report macro can only accept one page label, and one ID.
See the Page Properties macro in action in How to document product requirements in Confluence.
This powerful macro lets you create a summary page that pulls in information from multiple pages.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 290
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Page (None) Optional ID used to identify a particular Page Properties macro on a page. Specify
Properties this ID in the Page Properties Report to include summary information from macros
ID with this ID only.
Hidden False Determines whether the data in the Page Properties macro will be displayed on the
current page. This setting does not affect the display of the detail in the Page
Properties Report macro.
Notes
You can't use macros in the left column as the data in this column is used to populate the column
headings in your Page Properties Report macro.
It is not possible to reference the metadata using the metadata key from within the page, or anywhere
else on a Confluence page.
There is a known issue where the Page Properties Report macro does not correctly display content
CONFSERVER-34141
from multiple Page Properties macros. See RESOLVED for more
information.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 291
It's possible to add multiple Page Properties macros on a page, and choose whether to include all or only
specific macros in the report. The Page Properties macro includes an optional ID parameter that can be
used to identify specific Page Properties macros.
To show the contents of:
Selected Page Properties macros in the report - specify the label for the page and the ID of the
particular Page Properties macro (under Options)
All Page Properties macros in the report - specify just the label for the page - leave the Page
Properties ID field blank.
Note: The Page Properties Report macro can only accept one ID.
CQL fields
CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in
some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add
filters to build up a search query, adding as many filters as you need to narrow down the search results.
Use the Add a filter link to add more filters to your query.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 292
So to show pages with 'label-a', 'label-b' or both you'd put 'label-a' and 'label-b' in the same Label
field, like this:
For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a second
Label field to the macro, and put 'label-b' in the second one, like this:
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to
add that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.
You can use the following CQL filters to build your query:
Label* Include pages, blog posts or attachments with these OR (multiple values in the
labels. same filter)
AND (multiple Label filters)
With Include pages that are children of this page. OR (multiple values in the
ancestor same filter)
This allows you to restrict the macro to a single page tree.
Contributor** Include pages or blog posts that were created or edited by OR (multiple values in the
these people. same filter)
Mentioning Include pages and blog posts that @mention these people. OR (multiple values in the
user same filter)
With parent Include only direct children of this page (further sub-pages EQUALS (one page only)
won't be included)
Including Include items that contain this text. CONTAINS (single word or
text** phrase)
With title Include items that contain this text in the title. CONTAINS (single word or
phrase)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 293
** You can add these filters in CQL-powered macros but in search they're part of the standard search filters,
so they don't appear in the Add a filter menu.
Page Blank If not specified, the report will show data from all Page Properties macros on a
Properties page, where there are multiple macros. Specify an ID to include only data from
ID Page Properties macros with the same ID.
Title Title The heading to display on the first column in the report table. This column
column contains links to pages displayed by the report. The default column heading is
heading 'Title'.
Columns If not specified, the report will show all columns. You can specify a comma
to show separated list of columns to include.
If your column heading includes commas, use double quotes around the column
name. If your column heading includes quotes, use double quotes. For example,
A column, "My ""new"" column, yes", Third column
Number of 30 Number of items to display in the table before displaying pagination options for
items to additional items.
display
Sort by Modified Sort the table by a specific column heading. Enter the column name, exactly as it
appears in the corresponding Page Properties macro.
Select the Reverse Sort check box to sort the table in reverse order.
Show No Displays the number of comments for each page in the table.
Comments
Count
Show No Displays the number of likes for each page in the table.
Likes
Count
Troubleshooting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 294
Macro Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Root Page The Specify the parent page for the page tree. The tree will include all
(root) home children of the given page, plus their children and grand-children etc.
page of The tree will not include the root page itself.
the
space Specify the page title or a special value as follows:
Your page title to specify a page name for the parent or root of
the tree. The tree will include all children and grand-children of the
specified root. The tree will not include the specified root page itself.
'@home' will include all pages under the home page of the space
(default).
'@self' will include all pages under the current page.
'@parent' will include all pages under the parent of the current
page, including the current page.
'@none' will include all pages in the space, including orphaned
pages and the home page.
Sort Pages By position Specify the order to display the pages in the tree. This sort order is for
(sort) display purposes only. It does not permanently re-arrange the page
order. The value may be one of the following:
bitwise sort alphabetically, for example: title1, title10, title2.
creation sort by date of creation.
modified sort by order of date last modified.
natural sort in 'natural' alphabetical order, for example: title1,
title2, title10.
position sort by the default Confluence sorting rules. If your
pages have been ordered manually, this sort will respect the defined
order. Otherwise the pages will be displayed in the 'natural'
alphabetical order, such as: title1, title2, title10.
Include Excerpts in false Select if you want the page tree to show excerpts from each page. The
Page Tree excerpts must be defined on each page by the Excerpt macro.
(excerpt)
Reverse Order false Select to show the pages in reverse (descending) natural order. Must
(reverse) be used in combination with the Sort Pages By parameter.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 295
Include Search Box false Select if you want to include a search box above the page tree. The
above Page Tree search box allows your readers to search within the page tree for the
(searchBox) specified value.
Show false Select if you want to display the 'expand all' and 'collapse all' links at the
Expand/Collapse top of your page tree. Your readers can click these links to open or
Links close all branches of the tree at once.
(expandCollapseAll
Available values in wikimarkup and storage format:
)
true Show the 'expand all' and 'collapse all' options.
false Do not show the options.
Start Depth 1 Enter any number greater than 0 to set how many levels of children the
(startDepth) tree should show when it opens for the first time.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: pagetree
{pagetree:root=Page
Name|sort=natural|excerpt=true|reverse=false|startDepth=3|expandCollapse
All=true|searchBox=true}
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 296
Name of none The name of the root page whose hierarchy of pages will be searched by this macro.
Root Page If this not specified, the root page is the current page.
(root)
Note: Unlike the Page Tree macro, the Page Tree Search macro does not accept the
special values that start with an @ sign, such as @home or @self.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: pagetreesearch
Panel Macro
The Panel macro displays a block of text within a customizable panel, like this:
Handy hint: You can use panels within columns, in table cells and in the sections defined by page layouts.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Panel Title none The title of the panel. If specified, this title will be displayed in its own title
(title) row.
Border Style solid The style of the panel's border. Accepted values are solid, dashed and
(borderStyle) other valid CSS border styles.
Border Color The color of the panel's border. Colors can be specified as HTML color
(borderColor) names or hexadecimal codes.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 297
Border Pixel Width The width of the panel's border (in pixels).
(Value Only)
(borderWidth)
Background Color The background color of the panel. Colors can be specified as HTML color
(bgColor) names or hexadecimal codes.
Title Background The background color of the title row of the panel. Colors can be specified
Color as HTML color names or hexadecimal codes.
(titleBGColor)
Title Text Color The color of the text in the title row of the panel. Colors can be specified as
(titleColor) HTML color names or hexadecimal codes.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: panel
{panel:title=My
title|borderStyle=dashed|borderColor=blue|titleBGColor=#00a400|titleColo
r=white|bgColor=#72bc72}
A formatted panel
{panel}
PDF Macro
The PDF macro displays the content of a PDF document on a page. First attach the document to a Confluence
page, then use the macro to display the document.
For details, see the View File Macro.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: viewpdf
{viewpdf:page=Docs|name=My document.pdf}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 298
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Number of Labels 100 Specifies the total number of labels to display in the heatmap.
to Display
(count)
Restrict Labels to none Restricts the list of popular labels to the specified space.
this Space Key
(spaceKey)
Style of Labels list list displays the popular labels as a bulleted list, ordered by popularity
(style) (highest first).
heatmap displays the popular labels using different font sizes for each
label depending on the label's popularity, ordered by label names.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: popular-labels
{popular-labels:style=heatmap|count=20|spaceKey=ds}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 299
1.
er Macros
2. Find and select the 'Profile picture' macro
3. Search for and select the user and choose Sa
ve
Wiki markup
Wiki markup is not available for this macro. You cannot add this macro via wiki markup.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Space(s) The space which Filter content by space. The macro will display only the pages etc
(spaces) contains the page which belong to the space(s) you specify here. You can specify
on which the one or more space keys, separated by commas.
macro is added
Use '*' for all spaces.
Include these all types Filter content by type. You can specify one or more types,
Content Types separated by commas. Available types are: page, blogpost or
Only news, spacedesc, attachment, comment, mail, userinfo.
(types)
Label(s) none Filter content by label. The macro will display only the pages etc
(labels) which are tagged with the label(s) you specify here. You can
specify one or more labels, separated by commas.
Note: If there are no pages matching any of the specified labels,
then Confluence will ignore the labels and will list all recently
updated pages.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 300
User(s) all users Filter by username of the user who updated the content. The
(users) macro will only display content created and updated by the
user(s) you specify here. You can specify one or more
usernames separated by commas.
Width of Table 100% Specify the width of the macro display, as a percentage of the
(width) window width.
Show User Profile false Select whether profile pictures of the users who updated the
Pictures content are displayed.
(showProfilePic
)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: recently-updated-dashboard
{recently-updated-dashboard:spaces=ds|users=admin|width=50%|showProfileP
ic=true|labels=choc|types=page}
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Author(s) by None Filter the results by author. The macro will display only the pages etc
username specified. which were last modified by the author(s) you specify here.
(author) That is,
display all You can specify multiple users.
content
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 301
Space(s) @self This parameter allows you to filter content by space. The macro will
(spaces) display only the pages etc which belong to the space(s) you specify here.
That is,
the space You can specify one or more space keys, separated by a comma or a
which space.
contains
the page To exclude content in a specific space, put a minus sign (-)
on which immediately in front of that space key. For example: If you specify a
the macro space key of -BADSPACE you will get only content which is not in the
is used BADSPACE.
To indicate that the results must come from a specific space, put a
plus sign (+) immediately in front of that space key. For example: If
you specify a space key of +GOODSPACE you will get only content in
GOODSPACE. (Note that this is not particularly useful, because each
content item belongs to one space only. If you put a plus sign next to
one space key and list other space keys too, the other space keys will
be ignored.)
Special values:
@self The current space.
@personal All personal spaces.
@global All site spaces.
@favorite The spaces you have marked as favorite.
@favourite The same as @favorite above.
@all All spaces in your Confluence site.
* The same as @all above.
When specifying a personal space, remember to use the tilde (~) sign in
front of the username, such as ~jbloggs or ~jbloggs@example.com.
Label(s) None Filter the results by label. The macro will display only the pages etc which
(labels) specified are tagged with the label(s) you specify here.
i.e.
display all You can specify one or more label values, separated by a comma or a
content space.
To exclude content which matches a given label, put a minus sign (-)
immediately in front of that label value. For example: If you specify a
label value of -badpage you will get only content which is not labeled
with 'badpage'.
To indicate that the results must match a given label value, put a plus
sign (+) immediately in front of that label value. For example: If you
specify a label value of +superpage,+goodpage you will get only
content which has at least two labels, being 'superpage' and
'goodpage'.
The labels parameter only applies to the page and blog content types.
Width of Table 100% Specify the width of the macro display, as a percentage of the window
(width) width.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 302
Include these All types This parameter allows you to filter content by content type. The macro will
Content Types display only the content of the type you specify here.
Only
(types) You can specify one or more types, separated by a comma or a space.
To exclude content of a given content type, put a minus sign (-)
immediately in front of that content type. For example: If you specify a
content type of -blogpost you will get pages and all other content
except for blog posts.
Available values:
page Pages.
blogpost or news Blog posts, also known as news items.
comment Comments on pages and blog posts.
attachment Attachments.
Maximum Number 15 Specify the maximum number of results to be displayed. If this parameter
of Results is omitted, then a maximum of 15 results are displayed. The theoretical
(max) maximum value that this parameter can accept is 2 to the power of 31,
minus 1 (or 2147483647), though this has been limited to 200 in the code,
for performance reasons. More details are here.
Show User Profile false Specify showProfilePic=true to display the profile pictures of the
Pictures users who updated the content.
(showProfilePic
)
Hide Title False Determines whether the macro hides or displays the text 'Recently
(hideHeading) Updated' as a title above the list of content. Only available in wikimarkup
and storage format.
Accepted values:
true Title is hidden.
false Title is shown.
Notes
The Recently Updated Dashboard macro is similar to this macro, but is intended for display on the
Confluence dashboard.
If you would like to change the wording displayed by the Recently Updated macro, please refer to the
document on modifying the Confluence interface text.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 303
{recently-updated:spaces=ds|author=admin|max=10|hideHeading=true|width=5
0%|theme=sidebar|showProfilePic=true|labels=choc|types=page}
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Number of Labels 10 Specifies the total number of labels to display in the list.
to Display
(count)
Scope for global Specifies the scope of labels to be displayed in the list. Valid values include:
Retrieving Labels
(scope) global covers all site spaces (non-personal) in the Confluence
installation.
space the current space.
personal your own personal space.
Table Title none Adds a title to the top of the list in table style. Titles are only visible when the
(title) List Style parameter has been set to table.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: recently-used-labels
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 304
{recently-used-labels:title=My title|scope=space|style=table|count=20}
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Restrict to these none Specify the labels for which you want to view related labels. For example, doc
Labels umentation,my:stuff.
(labels)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: related-labels
{related-labels:labels=choc,cake}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 305
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 306
Parameters
This macro does not use the macro browser to set parameters. You also cannot add this macro via wiki
markup or by editing the storage format directly.
Notes
The Roadmap macro was previously available as an add-on from The Marketplace. The macro has changed
significantly. If you had an older version of the macro installed you will be able to view your existing
roadmaps but not edit them.
The RSS Feed macro may be disabled by your Confluence administrator. Also, your Confluence administrator
can define a whitelist of trusted URLs. You will see an error message on the Confluence page, if the included
URL is not in the whitelist.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
RSS Feed URL none The URL of the RSS feed link you want to show.
(url)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 307
Show Item Titles Only false Show only the titles of the news items, not the content.
(showTitlesOnly)
Show Name/Title of RSS Feed true Hide the feeds title bar.
(titleBar)
By default, the RSS Feed macro caches the feed results for 60 minutes before fetching the data again.
If you wish to change the default caching, use the Cache macro to define how often the RSS Feed macro
fetches the feed updates. You will need to install the Cache plugin onto your Confluence site.
Your Confluence Administrator can set up a whitelist of allowed URLs. If this is the case, you may see an error
on the pages which contain the RSS Feed macro.
A user can add the RSS Feed macro or the HTML-include macro to a Confluence page. The macro code
includes a URL from which the content is drawn. When the page is displayed, Confluence will check the URL
against the whitelist. If the URL is not allowed, Confluence will display an error message on the page.
The error message says that Confluence "could not access the content at the URL because it is not from an
allowed source" and displays the offending URL. If the person viewing the page is a Confluence Administrator,
they will also see a link to the Administration page where they can configure the URL whitelist.
Here is an example of the error message, including the link shown only to Confluence Administrators:
Authentication
RSS feeds which require authentication cannot be accessed using the RSS Feed macro.
This applies only to Confluence instances which have enabled HTTPS for all content. If your site is fully HTTPS,
the RSS Feed macro cannot access internal feeds. To enable the RSS Feed macro to access internal feeds
without affecting your HTTPS setup, enable local-only HTTP access:
1. Shut down Confluence.
2. Consult the SSL guide to enable HTTP access to Confluence. You'll want to ensure that you have an
HTTP connector and an SSL connector, both commented in. This means that Confluence will be
accessible via both HTTP and HTTPS. However, you should not have a redirect port, nor rules in web.xml
to redirect all traffic.
3. Instead of using web.xml to redirect traffic, insert a firewall rule to redirect all HTTP requests not from the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 308
3.
Confluence server to the equivalent HTTPS URL. This ensures that users will only be able to access
Confluence via HTTPS, as intended. If you have still left HTTP access for attachments enabled (to avoid
the IE download bug) you must selectively enable those URLS as well.
4. Modify your Confluence RSS Feed macro feed link to use the HTTP URL, and restart Confluence.
> Add-ons.
2. Select System from the drop down and search for the Confluence HTML Macros add-on.
3. Expand the add-on and enable the rss (rss-xhtml) module.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: rss
Macro body: None.
{rss:max=10|showTitlesOnly=true|url=http://myblog.com/feed|titleBar=fals
e}
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 309
Search Terms none The search terms which this macro will use to generate its results.
(query)
You can refine your search query by using operators such as 'AND' and 'OR'.
For example: my_query1 AND my_query2
Restrict to this all Start typing the space name to find the space, or specify the key of the space
Space Key you want to search in. Note that the key is case sensitive.
Content Type all Specify the content type. The content types are: page, comment, blogpost, att
(type) achment, userinfo (the content of user profiles only) and spacedesc (the
content of space descriptions only).
Last Modified all Specify a period of time in weeks, days, hours and/or minutes, to see the
(lastModified content modified within that time frame.
) These are the values you can use:
w = weeks
d = days
h = hours
m = minutes
For example:
2h 35m
3d 30m
Notes:
If no time category is specified, Confluence assumes minutes.
If you specify more than one time period (for example, weeks and days),
you must separate the periods with a space. You can put them in any order.
The time categories are not case sensitive. For example, ' 4d' is the same as
'4D'.
Restrict to this all Specify the username of a Confluence user, to show only content created or
Username updated by that user.
(contributor)
Notes
Permissions: When a user views the page containing the Search Results macro, the search results will show
only pages and other content types for which the user has 'View' permission.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: search
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 310
{search:lastModified=3w|query=choc|contributor=admin|maxLimit=10|type=pa
ge|spacekey=ds}
Section Macro
Used with the Column macro to define columns on a page. See Working with page layouts and columns and
sections.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: section
{section:border=true}
{column:width=100px}
This is the content of *column 1*.
{column}
{column}
This is the content of *column 2*.
{column}
{section}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 311
Parameters
The Space Attachments macro displays a list of all the attachments in a space. You can choose to show
attachments from the current space, or another space.
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Space (none) Selects the Confluence space to display attachments for. If you do not specify a
space, the current space will be used.
Show Filter true Determines whether or not the filter panel is shown. If you select this option,
Controls people viewing the page will be able to filter the list of attachments by file type
(showFilter (extension) and by label.
)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: space-attachments
{space-attachments:showFilter=false|space=ds}
Parameters
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 312
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Width of 100% The width of the space details table, specified as a percentage (%) of the page
Table width.
(width)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: space-details
{space-details:width=50%}
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Scope of no all The view from which spaces are listed. Available options are:
spaces
(blank) - All spaces in your site, with tabs.
all All spaces in your Confluence site.
category Spaces grouped according to space categories.
favorite Spaces which you have added to My Spaces.
new spaces created within the last 7 days.
This parameter is unnamed in wiki markup and storage format.
Width of List no 100% The width of the spaces list, specified as a percentage (%) of the
(width) window width.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 313
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: spaces
{spaces:favourite|width=80%}
Status Macro
The Status macro displays a colored lozenge (a
rounded box) that is useful for reporting project See the Status macro put to excellent use in
status. You can choose the color of the lozenge and How to build a release planning page in
the text that appears inside the lozenge. The macro Confluence.
also displays its current status in the editor, and you
can change the status directly in the editor.
ALL GOOD
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Color Grey The color of the lozenge. The following colors are available: Grey , Red, Yellow,
(colour) Green and Blue.
Title The The text that will appear inside the lozenge. If you do not specify any text, the title
(title) color that will be the color of the lozenge, that is 'Grey', 'Red', 'Yellow', 'Green' or 'Blue'.
you
select.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 314
Use False The style of the lozenge and its border. The default style lozenge is a solid
outline background color with white text. The outline style lozenge is white with a colored
style border and colored text as shown here
(subtle)
ALL GOOD!
This example is useful when you want to add a macro outside the editor, for example as custom content in
the sidebar, header or footer of a space.
Macro name: status
{status:colour=Green|title=On track|subtle=true}
Hint: For quick access from the editor toolbar, choose Insert > Table of Contents.
To add the Table of Contents macro to a page:
1. In the Confluence editor, choose Insert > Other Macros
2. Find and select the required macro
Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of
suggested macros. Details are in Autocomplete for links, files, macros and mentions.
To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open,
where you can edit the parameters of the macro.
Macro parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Display clear Select the check box to apply outline numbering to your headings, for
Section example: 1.1, 1.2, 1.3.
Numbering
(outline)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 315
List Style disc Select the style of bullet point for each list item. You can use any valid CSS
(style) style. For example:
none no list style is displayed
circle the list style is a circle
disc the list style is a filled circle. This is the typical bullet list, and is
used for this example list.
square the list style is a square
decimal the list is numbered (1, 2, 3, 4, 5)
lower-alpha the list is lower-case, alphabetized (a, b, c, d, e)
lower-roman the list style is lower roman numerals (i, ii, iii, iv, v, vi)
upper-roman the list style is upper roman numerals (I, II, III, IV, V,
VI)
Heading Sets the indent for a list according to CSS quantities. Entering 10px will
Indent successively indent heading groups by 10px. For example, level 1 headings
(indent) will be indented 10px and level 2 headings will be indented an additional
10px.
Separator brackets This parameter applies to flat lists only. You can enter any of the following
(separator) values:
brackets Each item is enclosed by square brackets: [ ].
braces Each item is enclosed by braces: { }.
parens Each item is enclosed by parentheses: ( ).
pipe Each item is separated by a pipe:
anything Each item is separated by the value you enter. You can enter
any text as a separator, for example "***". If using a custom separator, be
aware that text displays exactly as entered, with no additional white
space to further separate the characters.
Minimum 1 Select the highest heading level to start your TOC list. For example,
Heading Level entering 2 will include levels 2, and lower, headings, but will not include level
(minLevel) 1 headings.
Maximum 7 Select the lowest heading level to include. For example, entering 2 will
Heading Level include levels 1 and 2, but will not include level 3 headings and below.
(maxLevel)
Include Filter headings to include according to specific criteria. You can use wildcard
Headings characters. See Sun's Regex documentation for examples of constructing
(include) regular expression strings.
Exclude Filter headings to enclude according to specific criteria. You can use wildcard
Headings characters. See Sun's Regex documentation for examples of constructing
(exclude) regular expression strings.
Printable checked By default, the TOC is set to print. If you clear the check box, the TOC will
(printable) not be visible when you print the page.
CSS Class If you have custom TOC styles in your CSS style sheet, use this parameter
Name to output the TOC inside <div> tags with the specified class attribute.
(class)
Absolute URL By default, the links in the TOC are relative URLs pointing to the current
(absoluteURL page. If checked, the links in the TOC will be full URLs. This setting is useful
) when you are including a page with a Table of Contents in another page, and
want to control where the links should take the user.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 316
Examples
This example filters the headings to include those that contain 'Favorite', but excludes headings which end
with 'Things'. The list is styled with Roman numerals.
Parameter Value
Flat List
This example filters all headings to render a flat list of 'Unknowns' enclosed in square brackets (the default
list style).
Parameter Value
This example is useful when you want to add a macro outside the editor, for example as custom content in
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 317
{toc:printable=true|style=square|maxLevel=2|indent=5px|minLevel=2|cla
ss=bigpink|exclude=[1//2]|type=list|outline=true|include=.*}
{toc:printable=true|maxLevel=2|minLevel=2|class=bigpink|exclude=[1//2
]|type=flat|outline=true|separator=pipe|include=.*}
Notes
When you use a Table of Contents macro in a template, you will see an error when you preview the
template itself. But the Table of Contents macro works on the pages that people create from the
template the table of contents shows up after they have saved the page. (This is probably because
the template is not defined as a page, and the Table of Contents macro works for pages only.)
The Table of Contents macro only displays page or blog post content. You can't use it to add a table of
contents of headings in a comment for example.
Due to an outstanding issue in the Table of Contents macro (CONF-10619), the macro browser's Refr
esh function does not render any parameter modifications. Currently, the rendering of parameter value
modifications to the Table of Contents macro occurs only after the page is saved.
Using HTML heading markup with the Table of Contents macro
The Table of Contents macro cannot handle HTML heading markup on its own. Hence, if you use the
HTML and HTML Include macros to render HTML heading markup in a Confluence page, the Table of
Contents macro will not create a contents list out of these headings.
However, if you insert an HTML anchor into each HTML heading on your page (based on the following
syntax), the Table of Contents macro will incorporate these headings into your contents list.
The syntax for the anchor name is the page name and heading name separated by a hyphen.
Remove all spaces and convert all text to lower case. Convert all punctuation marks to their
URL-encoded equivalent.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 318
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
location both Specifies where in the zone the output list is displayed: top, bottom, or both,
(location) which encloses the page zone content.
Output Type list Specifies the layout for the table of contents:
(type)
list produces a vertical list, typical of a TOC.
flat produces a horizontal menu-type series of links, for example: [Heading 1]
[Heading 2] [Heading 3].
Display false Select to apply outline numbering to your headings, for example: 1.1, 1.2, 1.3.
Section
Numbering
(outline)
List Style none Specifies the style of bullet point for each list item. You can use any valid CSS
(style) style. For example:
none no list style is displayed
circle --- the list style is a circle
disc the list style is a filled circle. This is the typical bullet list, and is the
one we're using for this example list
square the list style is a square
decimal the list is numbered (1, 2, 3, 4, 5)
lower-alpha the list is lower-case, alphabetized (a, b, c, d, e)
lower-roman the list style is lower roman numerals (i, ii, iii, iv, v, vi)
upper-roman the list style is upper roman numerals (I, II, III, IV, V, VI)
Heading Sets the indent for a list output type, according to CSS quantities. Entering "10px"
Indent will successively indent list heading levels by 10px. For example, h1 headings will
(indent) be indented 10px and h2 headings will be indented an additional 10px.
Separator brackets Only applies to the flat output type. Specifies the display style of the links. You
(separator can enter any of the following values:
)
brackets Each item is enclosed by square brackets: [ ].
braces Each item is enclosed by braces: { }.
parens Each item is enclosed by parentheses: ( ).
pipe Each item is separated by a pipe:
anything Each is separated by the value you enter. You can enter any text
as a separator, for example '***'. If using a custom separator, be aware that
text displays exactly as entered, with no additional white space to further
separate the characters.
Minimum 1 Select the largest heading level to start your TOC list. For example, 2 will list h2,
Heading h3, and h4 headings, but will not include h1 headings.
Level
(minLevel)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 319
Max 7 Select the smallest heading level to include in the TOC. For example, 2 will list h1
Heading and h2, but will not include h3 and below.
Level
(maxLevel)
Include Filter the included headings according to specific criteria. You can use wildcard
Headings characters. See Sun's Regex documentation for examples of constructing regular
(include) expression strings.
Exclude Exclude headings according to specific criteria. You can use wildcard characters.
Headings See Sun's Regex documentation for examples of constructing regular expression
(exclude) strings.
Printable true By default, the TOC is set to print. If you clear this parameter, the TOC will not be
(printable visible when you print the page.
)
CSS Class If you have a custom TOC in your CSS style sheet, you can use this parameter to
Name output the TOC with the specified "class" attribute.
(class)
Examples
This example will filter all headings to include those that contain "Favorite", but will exclude any heading which
ends with the word "Things". The list is styled with upper-case Roman numerals.
Parameter Value
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 320
Flat List
This example will filter all headings to render a flat list of "Unknowns" enclosed in square brackets.
Parameter Value
Separator brackets
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: toc-zone
{toc-zone:printable=false|maxLevel=2|minLevel=2|location=top|type=flat|o
utline=true|separator=pipe}
Only headings within this block are included in the table of contents.
{toc-zone}
Notes
Due to an outstanding issue in the Table of Content Zone macro (CONF-10619), the Macro Browser's Ref
resh function does not render any parameter modifications. Currently, the rendering of parameter value
modifications to the Table of Content Zone macro occurs only after the page is saved.
Using HTML heading markup with the Table of Content Zone macro The Table of Content Zone macro
cannot handle HTML heading markup on its own. Hence, if you used the HTML and HTML Include macro
s to render HTML heading markup in a Confluence page, the Table of Content Zone macro will not create
a contents list out of these headings. (For more information on about this issue, please refer to TOC-93.)
However, if you insert an HTML anchor into each HTML heading on your page (based on the following
syntax), the Table of Content Zone macro will incorporate these headings into your contents list.
The syntax for the anchor name is the page name and heading name separated by a hyphen. Remove all
spaces and convert all text to lower case. Convert all punctuation marks to their URL-encoded equivalent.
Task Report Macro
Use the Task Report macro to display a list of tasks on a page. Filter the
tasks by space, page, user, label, created date and more.
See Add, Assign, and View Tasks for more information on creating and
assigning tasks. You can also use the Task Report blueprint, which will
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 321
create a page and add this macro for you. On this page:
Using
Using the Task Report macro the Task
Report
To add the Content Report Table macro to a page: macro
Parameter
1. In the Confluence editor, choose Insert > Other Macros
s
2. Find and select the required macro
Related pages:
Speeding up macro entry with autocomplete: Type { and the beginning of
the macro name, to see a list of suggested macros. Details are in Autocompl Add,
ete for links, files, macros and mentions. Assign,
and View
To edit an existing macro: Click the macro placeholder and choose Edit. A
Tasks
macro dialog window will open, where you can edit the parameters of the
macro.
Task Report macro showing incomplete tasks, on pages with the label 'meeting-notes'.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 322
Wiki markup
Wiki markup is not available for this macro. You cannot add this macro via wiki markup.
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 323
Group(s) none Specify the group name. Specify multiple groups separated by a comma,
(groups) or use * to show all users in Confluence.
See this knowledge base page for more information about controlling
which users can see the details of other users.
Display All
Online/Offline registered List online or offline users. Leave blank to show all users, irrespective of
Users users status.
(online) Accepted values:
Unspecified The macro will show all registered users.
true The macro will show only online users.
false The macro will show only offline users.
See below for information on how to configure this macro to display online
/ offline users.
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: userlister
{userlister:groups=confluence-users|online=false}
In order to use the Display Online / Offline Users parameter to indicate whether users are currently logged in
to Confluence, you will need to enable the User Log In Listener component in the add-on that provides this
macro. You'll need Confluence Administrator permissions to do this.
To enable the Display Online/Offline Users filter in the User List macro:
1. Go to
> Add-ons
2. Select System from the drop down and search for the User Lister add-on
3. Expand the add-on and enable the User Log In Listener module.
4. Restart Confluence for the change to take effect.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 324
Parameters
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Username none The username of the Confluence user whose profile summary you wish to show.
(user)
This example is useful when you want to add a macro outside the editor, for example as custom content in the
sidebar, header or footer of a space.
Macro name: profile
{profile:user=admin}
The View File macros allow you to embed an Office or PDF document on a page. First attach the document to a
page and then use one of the View File macros to display the document's content.
When people view the page, they will see the content of the Office or PDF document. They do not need to have
Office installed in order to see the content of the file.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 325
For a full list of Office Connector prerequisites and limitations, please refer to:
Office Connector Prerequisites
Office Connector Limitations and Known Issue
To display an Office or PDF document in a page, use one of the following View File macros in the macro
browser:
Office Excel
Office PowerPoint
Office Word
PDF
To add one of the View File macros to a page:
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
All View Page The page Enter a page name, if you wish to display a document which is
File Name which attached to another Confluence page.
macros contains the
macro
File Name none The file name of the Office or PDF document to be displayed. The
document must be attached to a page on your Confluence site.
Office Show true Select to show grid lines around each cell of the Excel spreadsheet.
Excel Grid? Clear to hide these grid lines.
Worksheet Last The name of the worksheet that you want displayed.
Name worksheet
viewed in
the
spreadsheet
Last Row Last row The number of the last row you want displayed, starting from '0' as
with content the first row.
Last Last column The number of the last column you want displayed, starting from '0'
Column with content as the first column.
Hint for reducing the size of the spreadsheet: Use the Last
Column and Last Row parameters to reduce the size of the
spreadsheet displayed on the wiki page. This is especially useful to
prevent the display from showing empty cells. This will also help to
prevent 'out of memory' errors.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 326
You can launch your Office application and edit Office documents displaying in the view file macros directly from
your Confluence page.
Word and Excel - choose the Edit Document link above the content
PowerPoint - choose the edit icon on the viewer.
You will find more information and other methods for editing attached Office documents in Edit Office Files.
Troubleshooting
Problems? Please refer to our guide to the Office Connector limitations and known issues.
Parameters
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 327
Parameters are options that you can set to control the content or format of the macro output. Where the
parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro
browser, it will be listed below in brackets (example).
Parameter Description
Web Site's This is the external site's URL. In some sites this will be the URL shown in the address bar
Widget of your browser, and in other sites you may need to click a Share or Link button to get the
URL URL.
(url)
Examples
Every site is a little different, so we've put together some info on what you'll need to do to embed each site's
content on a page.
YouTube
The fastest way to embed a YouTube video is to paste the URL into the editor. Confluence will autoconvert
the link and insert the macro for you, like magic. Autoconvert works with both long and short YouTube
URLs.
If you're pasting the URL into the Widget Connector macro URL field manually, you'll need to use the long
URL (from the address bar). Long URLs look something like this https://www.youtube.com/watch?v=
k6lK5hlB1nQ.
If you're not able to see the video in some browsers, try using https rather than http in your
link.
Links that contain a parameter to start a video at a particular time won't autoconvert or work in
the Widget Connector macro, like this link: https://www.youtube.com/watch?t=15&v=L
hHKkodOPFo. Paste in the short sharing URL to be sure it works.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 328
Vimeo
The fastest way to embed a Vimeo video is to paste the URL into the editor. Confluence will autoconvert the
link and insert the macro for you.
You can use the URL from the address bar in your browser or the Share button in Vimeo.
MySpace Video
We don't autoconvert MySpace videos, so you'll need to add the Widget Connector macro to your page first,
and then paste the video's URL into the URL field.
You can use the URL from the address bar in your browser or the Sharing options in MySpace.
Flickr
You can embed a single photo, a set, an entire user's photo stream or collection of photos with a particular
tag.
The fastest way is to paste a URL into the editor. This works for sets and tags. For other URLs you'll need to
add the Widget Connector macro to the page first and then paste your link into the URL field.
Use the URL from the address bar in your browser.
To embed a single tweet you'll need to click the Details link on the tweet so you can grab the URL for just
that tweet. The URL will look something like https://twitter.com/atlassian/status/3469765212
50037760.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 329
To embed a dynamic list of tweets you'll need to create a Widget in Twitter first:
1. In Twitter, go to Settings and Privacy > Widgets and create a new widget (search).
2. In Search Query, choose if want to search for a hashtag or a profile (for example,
#atlassian, @atlassian).
3. Create widget and copy only the data-widget-id from the HTML code generated (it should look
something like this example "854765133465255939").
4. The URL that you want for the Widget Connector Macro should look something like this https://tw
itter.com/settings/widgets/854765133465255939 (the numbers after the slash will be
different, you must change for the ones that you're going to generate in Twitter widget).
5. In Confluence, paste the URL into the Widget Connector.
6. The list of tweets will display, like this one below.
SlideRocket
We don't autoconvert SlideRocket presentations, so you'll need to add the Widget Connector macro to your
page first, and then paste the video's URL into the URL field.
You can get the URL from the Sharing button on the SlideRocket player.
Google Calendar
We don't autoconvert Google Calendars, so you'll need to add the Widget Connector macro to your page
first, and then paste the calender address into the URL field.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 330
You can only embed public calendars. To get your calendar's URL, in Google Calendar go to Calendar
Settings > Calendar Address and click the HTML button.
The URL will look something like this: https://www.google.com/calendar/embed?src=en.austral
ian%23holiday%40group.v.calendar.google.com&ctz=Australia/Sydney
Troubleshooting
If the Widget Connector can't display content from the external site, the macro will look like this:
example.com
We rely on the external website's APIs to display content in the Widget Connector macro. APIs do change
from time to time and this can cause the Widget Connector macro to stop rendering content.
If you experience problems, you can raise an issue about it to let us know.
This example is useful when you want to add a macro outside the editor, for example as custom content in
the sidebar, header or footer of a space.
Macro name: widget
{widget:height=400|width=400|url=http://youtube.com/watch?v=23pLByj_q
5U}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 331
update information about yourself, like your name, email address, and pass On this page:
word. You can also view other users' profiles.
Find your
user profile
Find your user profile Edit your
user profile
To find your user profile: Notes
Choose your profile picture at top right of the screen, then choose Profile, or Related pages:
choose the Profile link in the sidebar of your personal space.
Set Your
To find someone else's user profile: Profile
Picture
Create a
Personal
Space
Hover your mouse pointer over a user's linked name or profile picture and choose the user's linked name to
open their user profile. Alternatively, you can choose the Profile link in the sidebar of their personal space,
or go directly to this URL:
http://your.confluence.site/users/viewuserprofile.action?username=USE
RNAME
Profile View and edit your personal details, such as your name and email address details and
optionally, your photograph and other personal information. Note that as a security
precaution, in order to change your email address, you will be required to re-enter your
password.
Upload a profile picture (optional).
Change your password.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 332
Network View the recent activity of users that you are following via the Network view.
Follow other users from this view.
Watches View a list of the pages and spaces you are currently watching.
Drafts Retrieve any pages you were in the process of editing. See Working with Drafts.
1. Choose your profile picture at top right of the screen, then choose Profile
Or, choose the Profile link in the sidebar of your personal space.
2. Choose Edit Profile
3. Enter details about yourself in the form displayed
4. Choose Save
Detail Description
Email Your email address that will be used to send you mail notifications.
About me Information about yourself that other users can view (such as your professional information,
hobbies, and other interests). You can use Confluence wiki markup in this field.
Location Your location. This can be your town, city, region or country.
Handy Hint
Confluence administrators can configure Confluence to mask email addresses (e.g. 'example at
atlassian dot com'), protecting your email address from search engine spiders and the like.
Notes
The 'Administer User' link is visible to Confluence administrators only. The administrator can click this link to
go directly to the user management screen in the Administration Console.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 333
You're logged in, but you want or need to change your password
You've forgotten your password and can't log in, so you need to reset Related Topics:
your password
Your User
Change your password when you're logged in: Profile
Set Your
1. Choose your profile picture at top right of the screen, then choose Pr Profile
ofile Picture
2. On your Profile tab, click Password in the left-hand column Create a
3. Enter your current password and your new password in the form Personal
displayed Space
4. Click Submit
Setting Description
Site Homepage Select the page that you would like to see whenever you log into Confluence.
Use Keyboard Shortcuts Enable keyboard shortcuts, other than for the editor.
Text select Turn off the popup options panel when highlighting text.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 334
Setting your language preference in your user profile is described in the section above. This section gives
more information about that setting and other settings that affect the language Confluence will use.
Individual users can choose the language that Confluence will use to display screen text and messages.
Note that the list of supported languages depends on the language packs installed on your Confluence site.
The language used for your session will depend on the settings below, in the following order of priority from
highest to lowest:
The language preference defined in your user profile. Note that you need to be logged in for this
setting to take effect.
The language that you choose by clicking an option at the bottom of the Confluence login screen.
Confluence stores this value in a cookie. When the cookie expires, the setting will expire too.
The language set in your browser. The browser sends a header with a prioritized list of languages.
Confluence will use the first supported language in that list. Confluence administrators can disable this
option by setting the confluence.browser.language.enabled system property to false.
The default language for your site, as defined by your Confluence site administrator.
Editor Preferences
You can set some options that determine the way the Confluence editor works. Note that these settings
affect only you. Other people using Confluence can enable or disable the settings on their user profiles
independently.
To change your editor preferences:
1. Choose your profile picture at top right of the screen, then choose Settings
2. Click Editor under 'Your Settings' in the left-hand panel
3. Click Edit and make your changes
4.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 335
4. Click Submit
Setting Description
Disable Select to disable autocompletion when you press one of the trigger characters.
Autocomplete
Disable Select to disable autoformatting when you type wiki markup in the editor. Click ? on
Autoformatting the editor toolbar to learn more.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 336
You can't remove your profile picture, but you can upload a new one any
time.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 337
You can access the dashboard at any time using the dashboard URL. It'll look something like this: https
://yoursite.com/wiki/dashboard.action.
To save a page for later, hit the Save for later button at the top of the page.
The star icon will change to dark grey to indicate the page is saved. Hit the
button again if you want to remove the page from the list.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 338
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 339
Column Description
Name
Consumer The name of the Confluence gadget that was added on the consumer.
Consumer A description of this consumer application. This information would have been obtained from
Description the consumer's own OAuth settings when an OAuth relationship was established between
Confluence and that consumer.
If the consumer is another Atlassian application, this information is obtained from the Consu
mer Info tab's 'Description' field of the OAuth Administration settings. The application's
administrator can customize this Consumer Info detail.
Issued On The date on which the OAuth access token was issued to the consumer by Confluence. This
would have occurred immediately after you approved this gadget access to your Confluence
data (privy to your Confluence user account).
Expires On The date when the OAuth access token expires. This is seven days after the 'Issued On'
date. When this date is reached, the access token will be automatically removed from this
list.
Collaboration
Confluence is all about encouraging team collaboration to get the best Related pages:
results, so we've built in a number of ways you can notify other people about
content that may be of interest to them. Pages and
blogs
You can: Watch
Pages,
Work together with your team on a page or blog and see their
Spaces
changes in real time
and Blogs
Share a link to a page or blog post via email
Export
Mention a user when you write a page, blog post, comment, or add a
Content to
task
Word,
Like a page, blog post or comment
PDF,
Whenever you mention another user, they'll receive an email notification; if HTML and
XML
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 340
you like a page, blog post, or comment, the author will be notified that you lik
e the content.
Other users can also find out about changes to content in Confluence by wat
ching pages and spaces.
Another way to share Confluence content is by exporting it to other formats
such as XML, HTML, Microsoft Word and PDF.
Network Overview
You can Create a network of users who are important to you, to make sure On this page:
you're always up-to-date with their Confluence activity. You might want to
follow your boss or teammates, to see what they're working on, or whoever Follow
creates the most entertaining blog posts. another
user
When someone's part of your network, you'll be able to see when they: Access
your
Add or edit pages or blog posts
network
Comment on a page or blog post or edit existing comments
view
Update their user profile
Notes
Related pages:
Follow another user Network
Macro
You can follow another user by using either their Hover Profile or your
Subscribe
Network view.
to a
To follow a user with their Hover Profile, hover your mouse over their profile Network
picture when it appears in a page and choose Follow. RSS Feed
Email
Notification
s
If you want to see what's been happening in your network, access your network view as described above.
You can access another user's Network view using the Hover Profile by choosing More > Network Page.
Screenshot: Example of the Network view
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 341
Notes
RSS feeds: you can subscribe to any Confluence user's network RSS feed and receive summaries on
the activities of other users they're following in their network. See Subscribe to a Network RSS Feed.
Email notifications: you can request email notifications of any activity in your network. See Email
Notifications.
Go to <your confluence
URL>/plugins/likes/view-notifications.action
Mentions
Mentions (often known as @mentions) are a seamless way of drawing
someone's attention to a page or comment, or assigning a task to them.
When you mention a user, they'll receive a notification by email and in their
workbox; if you mention them in a task, the task is assigned to them and
appears in their tasks list.
There are two ways to mention someone: using autocomplete, or via the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 342
To mention someone using autocomplete, type '@' in the editor then start typing their name. Choose the
person you want to mention from the list of suggestions.
Screenshot: Autocomplete for mentions
The order Confluence suggests people is influenced by your network and the people you interact with on a
regular basis. People you follow or who are following you will be suggested first.
If you'd rather use the Insert menu, choose Insert > User Mention then search for and select the user you
want to mention.
Notes
Disable the user mention feature The functionality is provided by a plugin called the 'Confluence
Mentions Plugin'. If you need to remove the user mention functionality from your site, you can disable
the plugin. See Disabling or Enabling a Plugin.
Mentioning groups You can only mention individual users. There's a feature request to allow
CONFSERVER-23015 - Extend 'Mentions' to work with groups as well
mentions for groups: OPEN
Link to a user profile You can use a square bracket '[' and a person's name to trigger Confluence
autocomplete and link to a person's user profile or personal space. Confluence will send the person a
notification just as if you had used @mention (unless the administrator has disabled the user mention
feature).
Mention notifications - A notification is sent to the people you mention the first time you mention
them, but not for subsequent mentions. If you need to catch someone's attention, and you've already
mentioned them, try sharing the page with them instead.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 343
Notes:
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 344
1. Type your comment in the comment field at the bottom of the page On this page:
2. Optionally, choose Preview to see how your comment will appear
3. By default, Watch this page is ticked (This means you'll start Add a
receiving notifications about the page. Uncheck it if you don't want to page or
watch the page.) blog post
4. Choose Save (Ctrl+S or +S) comment
Add an
Other users can reply and/or like your comment, and you or a space inline
administrator can edit your comment(s). comment
Resolve
inline
comments
Rich
comments
Link to a
comment
Comment
permission
s
Notes
Related pages:
Create and
Edit Pages
Blog Posts
Share and
Comment
on Files
Share a
Page or
Blog Post
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 345
Hit Resolve to hide a set of inline comments once the conversation's finished. If you want to view resolved
comments, choose
> Resolved comments; to reopen a resolved comment, choose Reopen at the bottom left.
Rich comments
Inline and page comments might look simple, but they support rich text (like bold, underline, and italics), bull
eted and numbered lists, links, and @mentions. You can also drop images into any comment, to really
illustrate your point.
Link to a comment
You can link directly to a comment on a page. See Links for more information.
If you don't see a popup when you highlight text, check that Text Select is enabled in your profile
settings.
Comment permissions
Add a comment You need the 'Add Comments' permission in the space.
Edit a comment You need the 'Add Comments' permission. Space administrators can edit all
comments within their space. The date on a comment always indicates the time the comment was last
edited.
Delete a comment You need the 'Remove Comments' permission. Deleted comments cannot be
restored. If you don't have the 'Remove Comments' permission, you can delete your own comments,
but only if there are no replies to your comment.
Disable comments If you don't want comments in a particular space, remove the 'Add Comments'
permission from the 'confluence-users' or 'users' group, anonymous users and all other users and
groups. The option to add comments will no longer appear on pages or blog posts in that space.
See Space permissions for more information. There is no permission that controls comments across the
entire site.
Notes
Choose Watch at the top-right of the page to receive an email notification whenever anyone edits or
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 346
You can choose to watch all the pages and blog posts in a particular space.
The quickest way is to use the Watch option on a page or blog post, as described above.
To stop watching the space, deselect the relevant check box.
Alternatively, choose Pages in the space sidebar, then choose Watch this space at the top right.
You can choose to receive a notification whenever someone adds a blog post in the space. You will not
receive notification of updates to or deletions of blog posts, nor of comments on the blog posts.
To watch for new posts:
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 347
You can receive notifications about changes to the content of pages, blog posts and comments from all
spaces on a Confluence site.
To start watching for content changes across the whole site:
1. Choose your profile picture at top right of the screen, then choose Settings
2. Choose Email.
3. Choose Edit then choose Subscribe to daily updates.
4. Choose Submit.
You can choose to watch for all new blog posts in all spaces on the Confluence site. You will not receive
notification of updates to or deletions of blog posts, nor of comments on the blog posts.
To start watching for all new blog posts:
1. Choose your profile picture at top right of the screen, then choose Settings
2. Choose Email.
3. Choose Edit then choose Subscribe to all blog posts.
4. Choose Submit.
The 'Watches' page in your user profile displays a list of all pages and spaces you are currently watching.
To manage your watches:
1. Choose your profile picture at top right of the screen, then choose Watches.
2. Choose Stop Watching for any unwanted spaces or pages.
The email notifications that you receive from Confluence have some useful links at the bottom of the email
message. The links in each message vary, depending on the context. In general, the links allow you to view
the page online, reply to a comment, and so on.
In particular with respect to setting your notification preferences, you will see one or more of the following
links:
Stop watching page Click this link to stop watching the page that triggered the email notification.
Stop watching space Click this link to stop watching the space that triggered the email notification.
Stop following this user Click this link to stop following the user whose update triggered the email
notification.
Manage Notifications Click this link to go to the email settings page in your user profile.
Screenshot: Example email notification footer showing links
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 348
By default, Confluence will assign you as a watcher of any page or blog post that you create or edit. This
behavior is called 'autowatch'. You can turn autowatch on or off, and set other notification options, in the
email settings section of your user profile. See Edit Your User Settings.
Manage Watchers
As a space admin, you may want to control who's notified about changes Related pages:
and updates to pages and posts within a space. You'll do this by managing
the watchers of specific pages and posts, or of the entire space. Watch
Pages,
Take the example of a new member starting on your team, who should see Spaces
when changes are made in the team space you can add them as a space and Blogs
watcher so they get updates when any page or post in the space is Email
changed. If someone no longer needs to be notified, you can remove them Notification
as a watcher just as easily. s
Your
profile and
settings
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 349
Email Notifications
You can 'watch' a page, blog post or space. Confluence will then send you a
notification by email whenever anyone adds or updates content on that page On this page:
or space. You'll receive immediate emails for important notifications (like Subscribin
mentions and new pages), but when lots of changes are being made at the g to email
same time, you'll only receive a single email with all the changes (within a notification
short window, usually 10 minutes). s
Notes for
You can also subscribe to daily email reports and other notifications of administrat
various updates, as described below. ors
You'll only receive notifications for content that you have permission to view. Related pages:
Users that have been disabled by an administrator will not receive email
notifications. Watch
Pages,
Spaces
Subscribing to email notifications and Blogs
Subscribe
You can subscribe to be notified when: to RSS
Feeds
A blog post is added or changed in a space that you have permission
within
to view.
Confluenc
Someone you're following makes an update in a space that you have
e
permission to view.
Your
Someone follows you.
profile and
You can also subscribe to these summary reports: settings
Edit Your
A daily report of the 30 most popular updates to all spaces that you User
have permission to view. Settings
A daily or weekly report of recommended updates, in all spaces that
you have permission to view.
To edit your email notification settings:
1. Choose your profile picture at top right of the screen, then choose S
ettings
2. Click Email in the left-hand panel
3. Click Edit
Here's an explanation of all the email settings.
Option: Do you want Pages and blog posts that you create, edit or comment on.
Autowatch Confluence to
automatically add you as a
watcher on each page or
blog post that you add or
update? If you are a
watcher of a page or a
post, you will receive
notification of future
changes.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 350
Receive daily email reports Pages and blog posts that are added, edited or deleted.
Subscribe to showing changes to Comments on a page or blog post that are added, edited
daily updates
content in all spaces that or deleted.
you have permission to Updates by users who have changed their personal
view. profile.
Option: Do you want to All pages and spaces that you are watching.
Notify on my receive email notifications This affects all subscriptions set.
actions
for your own changes?
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 351
Receive a daily or weekly Confluence chooses the content to display, based on:
Subscribe to email message showing
recommended
the top content that is Pages and blog posts that people have recently liked.
updates
relevant to you from Pages and blog posts that people have recently
spaces that you have commented on.
permission to view. Pages and blog posts that have recently been created.
How do you set the 'Recent' means any activity that occurred since the last
frequency of the mail recommended updates message was sent to you.
message? A link in the The activities are listed in order of popularity, with the most
email message allows you popular at the top. Likes, comments and content creations are
to choose daily or weekly scored equally. Activity that involves people in your network ra
notifications. nks higher than activity not involving your network. Content
How do you enable and from My spaces also ranks higher than content in other
disable the notification? spaces. The recommended updates summary does not
You can turn off the include any content that you created yourself, and it gives a
notification by clicking a lower ranking to content that you have participated in, for
link in the email message. example by adding a comment or updating the page.
You can also turn the If there is no activity to report, Confluence will not send the
notification on or off by email message.
setting the 'Subscribe to
recommended updates'
option in your user profile.
To enable Confluence to send email notifications, a System Administrator must configure an email
server. See Configuring a Server for Outgoing Mail.
System Administrators can change the batching window for changes and comments on the same
page or blog post in the Send batched notifications scheduled job. Increase the time for fewer
emails or reduce the time if more immediate notifications are essential in your site.
Confluence Administrators can set the default options for the recommended updates
notification. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 352
RSS feeds allow you to track updates to content within Confluence. You will need an RSS newsreader to
read a feed.
You can create a customized RSS feed using the RSS Feed Builder or subscribe to one of the pre-specified
feeds generated by Confluence.
What would you like to do?
Create and subscribe to customized RSS feeds using the RSS Feed Builder Create a customized
RSS feed. For example, you can filter your feed using a label, specify the number of items and days to
include in your feed, and so on.
Subscribe to pre-specified RSS feeds
There is no need to try to delete or remove an RSS feed built by the Confluence RSS feed builder.
Explanation: The feeds generated by the RSS Feed Builder are dynamically generated via the parameters
included in the feed URL (address). For example, take a look at the following feed URL:
http://confluence.atlassian.com/createrssfeed.action?types=page&sort=
modified&showContent=true...
The above feed URL will generate a list of pages ('types=page'), sorted by the modification date and showing
the page content. The feed is generated at the time when the URL is fetched and there is no RSS feed
information stored on the database. For that reason, there is no need to remove anything.
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 353
1. Go to the space and choose Space tools > Content Tools from the Related pages:
bottom of the sidebar
2. Choose RSS Feeds The RSS
3. Copy and paste the link for one of the feeds into your RSS Feed
newsreader Builder
RSS Feed
Feeds include: Macro
Network
Overview
Pages Comments
Blog Attachments
Mail All content
To subscribe to predefined RSS feeds for a particular page (where available):
Note that the word 'page' here means a part of the Confluence user interface, rather than a page that
contains Confluence content. For example, your Network view offers an RSS feed.
1. Go to the page
2. Locate the following icon, which is available in the top-right corner of certain pages:
3. Copy and paste the icon's link into your RSS newsreader
Notes
The predefined RSS feed will return no more than 10 entries within the last 5 days, if you want to customize
your Confluence RSS feed (for example, use a label to filter your feed), use the RSS Feed builder instead of
the above instructions.
Option Description
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 354
Hints
Separate feeds. Try building separate feeds, one for pages only and one that includes comments as
well. This allows you to monitor only pages if you are short of time, and to read the comments when
you have more time.
Labels to customize your feed. You can use the RSS feed builder to track updates to labeled pages
and comments on those pages. Here is an idea for customizing your RSS feed by using your own
personal label(s). This is useful if you want to track updates to specific pages or blog posts, and you
do not want to deal with emails. You can use this method as an alternative to watching pages.
Build an RSS feed that returns pages, blog posts and comments labeled with a personal label,
such as 'my:feed'.
Each time you want to 'watch' a page, just label it with 'my:feed'.
All updates and comments will automatically come through your RSS feed.
Notes
http://confluence.atlassian.com/createrssfeed.action?types=page&
sort=modified&showContent=true...
The above feed URL will generate a list of pages ('types=page'), sorted by the modification date and
showing the page content. The feed is generated at the time when the URL is fetched and there is no
RSS feed information stored on the database. For that reason, there is no need to remove anything.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 355
Feed authentication options: Confluence can offer you the option of an anonymous feed or a feed
that requires authentication.
An anonymous feed will show only the content that is visible to anonymous users. The feed
URL does not contain the &os_authType parameter mentioned below. This feed is useful only
if your Confluence site allows anonymous access. If a feed is anonymous, you only get
anonymously-viewable content in the feed regardless of whether you are a Confluence user or
not.
An authenticated feed requires you to log in to Confluence before you can retrieve the content.
The feed URL contains the following parameter: &os_authType=basic.
The option to choose between an anonymous and an authenticated feed is currently not
available on the feed builder screen. The feed builder offers only authenticated feeds. See CO
NF-21601 for details and a workaround.
Confluence does not provide a way of customizing a network RSS feed via the user interface. However, you
can modify the maximum number of results and type of content displayed in these feeds by directly editing
the RSS feed link in your RSS newsreader.
To modify the maximum number of results displayed in your RSS feed:
1. Edit the RSS feed link in your RSS newsreader.
2. Change the value of the max parameter from its default value of 40 to a value of your choice.
Example:
http://confluence.atlassian.com/feeds/network.action?username=MYNAME&max=60&publicFeed=fals
e&os_authType=basic&rssType=atom
3. Save the modified link in your RSS newsreader.
To modify the type of content displayed in your RSS feed:
1. Edit the RSS feed link in your RSS newsreader.
2. Append the parameter contentType to the end of the link, followed by an equals sign (=) and then
add the appropriate content type value of your choice:
PAGE restricts the RSS feed to page additions or updates.
BLOG restricts the RSS feed to blog post additions or updates.
ATTACHMENT restricts the RSS feed to attachment additions or updates.
COMMENT restricts the RSS feed to comment additions or updates.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 356
Content type values are case-sensitive. Ensure that each parameter is separated from the other by an
ampersand (&).
Example:
http://confluence.atlassian.com/feeds/network.action?username=ggaskell&max=40&publicFeed=false
&os_authType=basic&rssType=atom&contentType=BLOG
Notes
It is not possible to filter for more than one type of content by adding multiple values to the contentType pa
rameter.
Workbox Notifications
The Confluence workbox
On this page:
Manage your notifications
displays all notifications collected from Confluence
Which notifications are included?
page watches, shares, mentions, and tasks. From
Keyboard shortcuts
your workbox you can reply to comments, like a
Manage notifications with
comment or page, watch a page, or open the
Confluence mobile
relevant page or blog post.
Notes
If your Confluence site is linked to a JIRA application
Related pages:
such as JIRA Software or JIRA Service Desk, you'll
also see notifications from your JIRA application in Configuring Workbox Notifications
the workbox. Email Notifications
Watch Pages, Spaces and Blogs
Looking to manage your notification email messages
Likes and Popular Content
instead? See Email Notifications.
in the header.
A number will appear the workbox icon, to indicate the number of unread notifications waiting
for your attention.
You can use the keyboard shortcut: Type g then n. (When in the Confluence editor, click
outside the editor before pressing the keyboard shortcut keys.)
2. Choose a notification from the list, to see the notification details. You can then:
Open the related page, blog post, or comment.
Like or Unlike the page, blog post, or comment.
Watch or Stop Watching to receive notifications, or stop receiving notifications, about a page
or blog post.
Reply a comment, without leaving the workbox.
Screenshot: Your Confluence notifications in the workbox
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 357
The workbox displays a notification when someone does one of the following in Confluence:
Shares a page or blog post with you.
Mentions you in a page, blog post, comment or task.
Comments on a page or blog post that you are watching.
Likes a page or blog post that you are watching.
The workbox does not show notifications triggered because you are watching a space. Only watches on
pages and blog posts are relevant here.
The notification in your workbox appears as 'read' if you have already viewed the page or blog post.
If your Confluence site is linked to a JIRA application, you will also see the following JIRA notifications in your
workbox:
Comments on issues that you are watching.
Mentions.
Shares of issues, filters and searches.
Keyboard shortcuts
Shortcut Action
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 358
n Move down to the next notification for a particular page or blog post.
You can also view and respond to notifications on your phone or other mobile device. See Confluence Mobile
for more about mobile platforms.
Notes
but the notification is not added to the workbox. You need to close workbox and re-open it to see the
new notification.
The ability to receive notifications from JIRA or another Confluence site is available in Confluence
4.3.3 and later. To receive JIRA notifications, you need JIRA 5.2 or later.
Administrators can enable and disable the workbox on your Confluence site. They can also connect a
JIRA site or another Confluence site, so that notifications from those sites appear in your workbox too.
See Configuring Workbox Notifications.
The Confluence workbox is provided by a set of plugins. To remove the personal notifications and
tasks functionality from your site, you can disable the following plugins. See Disabling or Enabling a
Plugin for instructions. Disabling these plugins will disable the entire workbox . It is not possible to
disable only tasks or only notifications:
Workbox - Common Plugin
Workbox - Host Plugin
Workbox - Confluence Provider Plugin
If you want to re-enable the plugins, do so in the following order: Common Plugin, Host Plugin,
Confluence Provider Plugin.
There is no option to disable the workbox for an individual user.
Search
Confluence gives you a few ways to find what you're looking for. Here's an
overview of Confluence search, and a few tips to help you find things more
easily.
Quick search
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 359
choose the Search for option at the bottom of the search results to do a full
search. On this page:
Quick
search
Full search
Filter your
search
results
Filter with
CQL
Advanced
search
Search
Confluenc
e from
your
browser's
search
field
Related pages:
Confluenc
e Search
Syntax
Confluenc
e Search
Fields
Recently
Viewed
Pages and
Blog Posts
Search
Results
Macro
Livesearch
Macro
Search the
People
Directory
You can also search for administrative options in the quick search. For example, type 'general' into
the search field to go to the General Configuration screen.
Full search
The full search allows you to search all content in all spaces (site and personal), mail, personal profiles,
attachments and space descriptions, or filter the results to show only what you're after.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 360
The search will also look at the content of the following types of attachments:
Word Excel
Text PDF
PowerPoint HTML
To search the content of other attachment types, you will need to use an attachment content extractor
plugin. For more information, take a look at the following:
Existing extractor plugins which you can install on your Confluence site. See this search on Atlassian
Marketplace.
Guidelines on developing your own attachment content extractor plugin. See our developer
documentation on extractor plugins.
To use the full search:
1. Type your query into the search field at the top-right corner of every screen (or at the top of the Search
screen)
2. Hit the Enter key
Screenshot: Search results page
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 361
You need to enter at least two letters. For example, if you enter just 'john s', the filter will look
for users called 'john' and will ignore the 's'.
In space Only search in a particular space or list of spaces. There are also preset groups of spaces
favorite (my spaces), site, and personal spaces which you can choose from the list of suggested
spaces. Tick the checkbox to include archived spaces if you need to.
Last modified Choose or enter a date range to only show content updated within a particular period
of time.
Of type Only return content of a certain type, like pages, blog posts, or comments.
For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a
second Label field to the macro, and put 'label-b' in the second one, like this:
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able
to add that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that
label.
You can use the following CQL filters to build your query:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 362
Label* Include pages, blog posts or attachments with these OR (multiple values in the
labels. same filter)
AND (multiple Label filters)
With Include pages that are children of this page. OR (multiple values in the
ancestor same filter)
This allows you to restrict the macro to a single page
tree.
Contributor** Include pages or blog posts that were created or edited OR (multiple values in the
by these people. same filter)
Mentioning Include pages and blog posts that @mention these OR (multiple values in the
user people. same filter)
With parent Include only direct children of this page (further EQUALS (one page only)
sub-pages won't be included)
Including Include items that contain this text. CONTAINS (single word or
text** phrase)
With title Include items that contain this text in the title. CONTAINS (single word or
phrase)
Advanced search
Still need more ways to search? For more advanced search syntax, check out Confluence Search Syntax fo
r more ways to refine the text you enter in the search field. You can also read Confluence Search Fields for
special parameters you can use to search various types of content metadata.
If you're using Firefox or Internet Explorer, you can add your Confluence site as a search provider using the
dropdown menu next to the browser's search field.
The example below shows the 'Extranet' Confluence site offered for inclusion as a search engine in the
browser's search field.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 363
Use double quotes to search for content that contains the phrase 'cheese
one', or a phrase where 'cheese' and 'one' are the major words:
"cheese one"
Note: Confluence will ignore common words (stop words), including 'and',
'the', 'or', and more, even if they are included within double quotes. See the
default list of stop words used by Confluence's search engine, Lucene, in
the Lucene documentation.
For example:
1. Searching for "cheese one" returns only pages in which 'one' appears
as the first word after 'cheese'.
2. Searching for "the one" returns all pages containing 'one' because
'the' is a stop word.
If you'd like to override Lucene's tokenization and stemming, cast your vote
on this improvement request:
CONFSERVER-14910 - Provide ability to override Lucene tokenisation and
stemming and search for exact text OPEN
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 364
On this page:
Matched
phrase
search
OR search
AND
search
NOT
search
Excluded
term
search
Group
search
terms
Title
search
Date range
search
Wildcard
searches
Proximity
searches
Range
search
Fuzzy
search
Combined
search
Searching
for macros
Searching
for labels
Related pages:
Search
Confluenc
e Search
Fields
Search the
People
Directory
OR search
To search for content that contains one of the terms, 'chalk' or 'cheese', use the operator OR in capital letters
:
chalk OR cheese
AND search
To search for content that contains both the terms 'chalk' and 'cheese', use the operator AND in capital
letters:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 365
NOT search
To search for content that contains 'chalk' but NOT 'cheese', use the operator NOT in capital letters:
To search for content that contains 'chalk' and 'butter' but not 'cheese':
To search for content that must contain 'chalk' but can contain either 'cheese' or 'butter', use brackets to
group the search terms:
Title search
To search for pages and posts with certain words in the title, use the Add a filter option at the bottom left of
the page and choose With title. Enter the words you're looking for, in any order, and hit enter.
Confluence search filters are powered by CQL.
What's CQL, and how do I use it?
CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in
some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add
filters to build up a search query, adding as many filters as you need to narrow down the search results.
Use the Add a filter link to add more filters to your query.
For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a
second Label field to the macro, and put 'label-b' in the second one, like this:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 366
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able
to add that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that
label.
You can use the following CQL filters to build your query:
Label* Include pages, blog posts or attachments with these OR (multiple values in the
labels. same filter)
AND (multiple Label filters)
With Include pages that are children of this page. OR (multiple values in the
ancestor same filter)
This allows you to restrict the macro to a single page
tree.
Contributor** Include pages or blog posts that were created or edited OR (multiple values in the
by these people. same filter)
Mentioning Include pages and blog posts that @mention these OR (multiple values in the
user people. same filter)
With parent Include only direct children of this page (further EQUALS (one page only)
sub-pages won't be included)
Including Include items that contain this text. CONTAINS (single word or
text** phrase)
With title Include items that contain this text in the title. CONTAINS (single word or
phrase)
To search for content modified within a certain date range, pick a timeframe in the Last modified section on
the left. If you're looking for something created within a particular date range, use the Add a filter option at
the bottom left of the page and choose Created. For either option, you can pick from some predefined
options, like last 24 hours and last week.
Confluence search filters are powered by CQL.
What's CQL, and how do I use it?
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 367
CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in
some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add
filters to build up a search query, adding as many filters as you need to narrow down the search results.
Use the Add a filter link to add more filters to your query.
For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a
second Label field to the macro, and put 'label-b' in the second one, like this:
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able
to add that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that
label.
You can use the following CQL filters to build your query:
Label* Include pages, blog posts or attachments with these OR (multiple values in the
labels. same filter)
AND (multiple Label filters)
With Include pages that are children of this page. OR (multiple values in the
ancestor same filter)
This allows you to restrict the macro to a single page
tree.
Contributor** Include pages or blog posts that were created or edited OR (multiple values in the
by these people. same filter)
Mentioning Include pages and blog posts that @mention these OR (multiple values in the
user people. same filter)
With parent Include only direct children of this page (further EQUALS (one page only)
sub-pages won't be included)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 368
Including Include items that contain this text. CONTAINS (single word or
text** phrase)
With title Include items that contain this text in the title. CONTAINS (single word or
phrase)
Wildcard searches
You can use one or more wildcard characters in your search. For example, you could search for http*.atl
assian.* to find https://www.atlassian.com or http://www.atlassian.jp.
Leading wildcards
Lucene doesn't allow wildcards at the beginning of your search, but you can format your search as a
regular expression as a workaround. For example, you can't search for *hum* or ?hum*, as they
begin with a wildcard, but you can search for /.*hum.*/ and find things like hum, human, and
inhumane.
Wildcards can either replace a single character in your search, or multiple characters.
Single character
To replace a single character in your search, use a question mark (?) as a wildcard, For example, to search
for 'butter', 'bitter', 'better', or 'batter'.
b?tter
Multiple characters
To replace multiple characters in your search, use an asterisk (*) as a wildcard. For example, to search
for 'chicken' or 'chickpea':
chick*
Multiple wildcards
Use multiple wildcards in your search. The following query will search find 'chick', 'coconut', or 'chickpea':
c*c*
You can also combine wildcard characters in one search. For example, the search term below will return
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 369
c*c?
Note: Confluence doesn't support leading wildcards. This means searching for *heese will not return
cheese.
Proximity searches
Use a tilde character followed by a number, to find two words within a certain number of words of each other.
For example, the following search will return 'Octagon blog post', but not 'Octagon team blog post':
"octagon post"~1
The following search isn't valid, because you can't search for two words within zero words of each other. If
you think the words are next to each other, use the matched phrase search.
"octagon post"~0
Range search
Use the operator 'TO', in capital letters, to search for names that fall alphabetically within a specified range:
[adam TO ben]
Note: You can't use the AND keyword inside this statement.
Fuzzy search
octogan~
Combined search
You can search Confluence content to find where a macro is used. Start your search string with macroName
: and type the macro name after the colon. For example, to search for all excerpt-include macros:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 370
macroName:excerpt-include*
For more information about macroName and other search fields, see Confluence Search Fields.
To search for pages and posts with a particular label or labels, use the Add a filter option at the bottom left
of the page and choose Label.
Confluence search filters are powered by CQL.
What's CQL, and how do I use it?
CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in
some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add
filters to build up a search query, adding as many filters as you need to narrow down the search results.
Use the Add a filter link to add more filters to your query.
For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a
second Label field to the macro, and put 'label-b' in the second one, like this:
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able
to add that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that
label.
You can use the following CQL filters to build your query:
Label* Include pages, blog posts or attachments with these OR (multiple values in the
labels. same filter)
AND (multiple Label filters)
With Include pages that are children of this page. OR (multiple values in the
ancestor same filter)
This allows you to restrict the macro to a single page
tree.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 371
Contributor** Include pages or blog posts that were created or edited OR (multiple values in the
by these people. same filter)
Mentioning Include pages and blog posts that @mention these OR (multiple values in the
user people. same filter)
With parent Include only direct children of this page (further EQUALS (one page only)
sub-pages won't be included)
Including Include items that contain this text. CONTAINS (single word or
text** phrase)
With title Include items that contain this text in the title. CONTAINS (single word or
phrase)
Before you dive into learning more about Lucene fields, you may want to
learn about the powerful search filtering offered by Confluence Query
Language (CQL).
What's CQL, and how do I use it?
CQL (Confluence Query Language) is a query language developed for
Confluence, which you can use in some macros and the Confluence
search. Confluence search and CQL-powered macros allow you to add
filters to build up a search query, adding as many filters as you need to
narrow down the search results.
Use the Add a filter link to add more filters to your query.
For an AND search, add more than one filter and specify a
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 372
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 373
title:"Some Title"
labelText:chalk
The field specification applies only to the term directly preceding the colon.
For example, the query below will look for "Some" in the title field and will
search for "Heading" in the default fields.
title:Some Heading
Below are the fields which can be searched, listed by content type.
Personal Information
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 374
Pages
macroName true true false The name of a macro used on the page
Blog
macroName true true false The name of a macro used in the blog
Attachments
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 375
Mail items
Useful plugins
Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's
information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our
guidelines on add-on support.
This plugin extends the Confluence search, so that you can search for macro parameter names and
values: the Confluence Macro Indexer plugin.
Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 376
To search for a particular person, type their first name and/or last name into the search box and choose Sear
ch.
To see everyone who uses your Confluence site, choose All People.
To see just those people who have set up a personal space, choose People with Personal Spaces.
Confluence's network features allow you to 'follow' (that is, keep track of) other people's activities in your
Confluence site. For more information, please refer to Network Overview. You can use the hover profile
feature in the people directory to start following other people.
To start following someone, move your mouse over their name or profile picture and choose Follow in
their profile popup.
To stop following someone, move your mouse over their name or profile picture and choose Stop
Following in their profile popup.
Once you start following another person, their activities will start appearing in your network view.
Screenshot: The people directory
Notes
The people directory uses the hCard microformat for simple integration with a variety of
microformat-enabled tools. hCard is an open data format for representing people, companies,
organizations, and places. Read more about microformats and hCard.
By default, deactivated users (disabled user accounts) are excluded from the people directory. You
can include them by adding the showDeactivatedUsers parameter to the URL. For example:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 377
http://my.confluence.com/dopeopledirectorysearch.action?showDeac
tivatedUsers=true
By default, externally deleted users (for example, users deleted from an LDAP repository) are
excluded from the people directory. You can include them by adding the showExternallyDeletedU
sers parameter to the URL. For example:
http://my.confluence.com/dopeopledirectorysearch.action?showExte
rnallyDeletedUsers=true
The Confluence administrator can hide the people directory. If it is hidden, you will not see the People
Directory option.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 378
Global permissions
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 379
Space permissions
Every space has its own independent set of permissions, managed by the space admin(s), which determine
the access settings for different users and groups.
They can be used to grant or revoke permission to view, add, edit, and delete content within that space, and
can be applied to groups, users, and even to anonymous users (users who aren't logged in) if need be.
One thing to watch out for is where a user is a member of multiple groups. You may have revoked
permission for that individual user to add pages, for example, but if they're a member of a groups
that is allowed to add pages, they'll still be able to create new pages in the space.
If you can't get the result you want from space permissions, or you're not sure, check with one of
your Confluence administrators to determine what permissions you should apply to individuals and
groups.
Page restrictions
Page restrictions work a little differently to global and space permissions. Pages are open to viewing or
editing by default, but you can restrict either viewing or editing to certain users or groups if you need to. Page
restrictions can be applied to published or unpublished pages and blog posts (drafts).
Don't forget, every page in Confluence lives within a space, and space permissions allow the space admin to
revoke permission to view content for the whole space. Even the ability to apply restrictions to pages is
controlled by the 'restrict pages' space permission.
You can restrict viewing of a page or blog post to certain users or groups, so that even if someone has the
'view' permission for the space, they won't be able to view the content of the page or blog post.
If someone's a space admin and you've used page restrictions to prevent them viewing a page, they won't be
able to see the page when they navigate to it. As a space admin though, they can see a list of restricted
pages in the space and remove the restrictions.
What about links?
Space permissions and page restrictions affect how links between Confluence pages are displayed.
If someone doesn't have 'View' space permission, links to pages in that space will be visible, but they'll
get a "page not found" message. The space key is not revealed in the link URL.
If someone has the "View" space permission, but the page has view restrictions, the link will be visible
but they'll get an "access denied" message when they click the link.
Links to attachments are also affected. If the visitor doesn't have permission to view the page the attachment
lives on, the link won't be rendered.
Confluence Groups
For Confluence administrators, grouping users in Confluence is a great way
to cut down the work required when managing permissions and restrictions.
Groups are also very useful, however, to anyone who's a space admin, or
can apply page restrictions.
If you're a space admin, you can assign a set of space permissions to a
group rather than to each individual user. And as a page creator with
'Add/Delete Restrictions' permission, you can also add and remove page
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 380
Anonymous Users
All users who don't log in when they access Confluence are know as 'anonymous' users. By default,
anonymous users don't have access to view or change any content in your Confluence instance, but
Confluence admins can assign permissions to this group if it's required.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 381
If you're using Confluence as a knowledge base for JIRA Service Desk, your JIRA Service
Desk administrator can choose to allow all active users and customers (that is logged in users who do not
have a Confluence license) to view specific spaces.
These users have very limited access, and cannot be granted permissions in the same was as an individual
or group. However, it's important to note that this permission overrides all existing space permissions, so any
logged in Confluence user will also be able to see the space (regardless of their group membership). This is
due to the way Confluence inherits permissions.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 382
<yourjirasite.com>/browse/CONF-
1234 will insert the JIRA Issues macro
and display a single issue.
<yourjirasite.com>/issues/?filt
er=56789 will insert the JIRA Issues
macro and display a list of issues
matching the saved filter.
<yourjirasite.com>/issues/?jql=
project%20%3D%20CONF will insert the
JIRA Issues macro and display a list of
issues matching the JIRA search.
Alternatively, you can add the JIRA Issues Macro to the page and search for issues directly:
1. In the editor choose Insert > JIRA Issue.
2. Follow the prompts in the macro browser to choose a project and search for an issue you can even
use JIRA Query Language (JQL).
Once you've added the macro, you can customize how the issue or list of issues appears on the page,
including how much information to display, how many issues, and more.
Reporting on information stored in JIRA is simple in Confluence. In addition to the JIRA Issues Macro, you
can use the JIRA Report blueprint or JIRA Chart macro to show information from your JIRA application
visually. It's the best way to give your stakeholders a snapshot of your team or project's progress.
You can:
Use the JIRA Report blueprint to create a Change Log or Status report.
Use the JIRA Chart Macro to display data as a chart, including pie charts, created vs resolved, and
two dimensional charts.
Use JIRA Gadgets to display detailed JIRA reports and charts on pages.
You can create issues while viewing a page or from the within the editor. This is really useful if you use
Confluence for planning and gathering requirements.
To create an issue when viewing a page:
1. Highlight some text on your page and choose the
Create JIRA issue icon that appears above the highlighted text.
2. Enter your server (if you have multiple JIRA sites connected to Confluence), project, issue type and
description. Your highlighted text will populate the issue summary automatically.
3. Choose Create.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 383
The issue will be created in JIRA and added to your page. If your text is in a table, you'll have the option to
create multiple issues using text from the same column.
If you don't see a popup when you highlight text, check that Text Select is enabled in your profile settings.
To create an issue in the editor:
1. In the editor choose Insert > JIRA Issue > Create new issue.
2. Enter your server (if you have multiple JIRA sites connected to Confluence), project, issue type, su
mmary, and description.
3. Choose Insert.
The issue will be created in JIRA and added to your page.
There are some limitations when creating JIRA issues from Confluence. The JIRA Issues macro or Create
JIRA Issue dialog will notify you if it's unable to create an issue in the selected project. You can find out more
in the JIRA Issues Macro page.
Whenever you add a link to JIRA issues in Confluence, or link to a Confluence page from your JIRA
application, the JIRA Links button appears at the top of the Confluence page. This makes it really easy to
jump from Confluence to JIRA and vice versa, speeding up your workflow.
The number on the JIRA Links button indicates the total number of issues, epics, and sprints connected to
that page, regardless of whether you have permission to view them. The dropdown, however, will only show
details of issues, epics, and sprints that you have JIRA permissions to view.
The button doesn't detect links from issues displayed in the JIRA Issues macro in table format.
Here's some suggestions to help you get the most out of Confluence and JIRA Software and unleash the
potential in your agile development team.
Confluence is the perfect place to start defining your requirements. You can use the Product Requirements
Blueprint to capture your requirements, then create your JIRA epic and other issues right from the
requirements page in Confluence.
Here's how it works:
1. Create a Confluence page using the Product Requirements Blueprint.
2. Choose the placeholder text 'Link to JIRA epic or feature' and choose Create new issue to create
your epic in JIRA.
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 384
3. Collaborate with your team to define your stories and save the page.
4. Highlight text on your requirements page and choose the Create JIRA issue
link to create stories in JIRA, and automatically link them to your epic.
5. Track the progress of the stories from the Confluence page or from within JIRA.
The tight integration between Confluence and JIRA Software means you can easily access issues from the
Confluence page and see their status at a glance, and from within JIRA Software you can see links to related
Confluence pages. All the information you need is right there.
There's often a lot of material in Confluence that provides useful context for your team during a sprint. These
might be requirements documents, designs, tech specs, customer research and more. By linking these
pages to epics, you make them easy for your team to find during the sprint.
Here's how you can use Confluence to support your sprint from within JIRA Agile:
In JIRA Software, create a Confluence page to plan your sprint. The page is created using the Meeting
Notes Blueprint a handy template that helps capture the details you need and is automatically
linked to the sprint.
In an epic, link to useful Confluence pages, including requirements, designs, and more.
Report on your progress to stakeholders using the JIRA Report blueprint in Confluence.
Use the Retrospective Blueprint in Confluence at the end of your sprint to take stock of what went well
and not so well.
For people who work mostly in JIRA Software, the integration means that useful Confluence pages are only a
click away.
If you use JIRA Service Desk, you can help your customers resolve their issues without creating a request by
connecting your Service Desk project to a knowledge base in Confluence.
In Service Desk, head to Project settings > Knowledge base to connect or create a Confluence space.
When Service Desk customers search in the Customer Portal, pages in the linked knowledge base space will
be suggested, allowing customers to help themselves.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 385
The Knowledge Base space blueprint, along with templates for how-to and troubleshooting articles make
creating new knowledge base articles super simple for your Service Desk agents.
The templates used in the how-to and troubleshooting blueprints are completely customizable too. Set up the
template with all your standard information and let your agents take it from there.
If your Confluence instance is not public, you can still make a knowledge base space available via the
customer portal.
When you link your JIRA Service Desk project to a Confluence space, you can choose to allow all active
users and customers to see pages in the linked space, even if they don't have a Confluence license. These
people get very limited Confluence access.
Unlicensed users can:
View pages via the JIRA Service Desk customer portal.
Follow a URL to a page and then navigate within the linked space.
Unlicensed users can't:
Like, comment on or edit pages (or be granted permission to do this).
See the dashboard, user profiles, the people directory or space directory.
Search the whole site.
This permission can only be enabled via JIRA Service Desk, but you can revoke access to the whole site or
to particular spaces via Confluence's global permissions or space permissions.
A note about Confluence permissions...
Allowing all active users and customers to view a space will override all existing space permissions, so
any logged in, licensed Confluence user will also be able to see the space (regardless of their group
membership). This is due to the way Confluence inherits permissions.
As you've seen, Confluence has many integration points, some of which are only available in particular JIRA
applications or versions.
This matrix outlines the specific JIRA applications you'll need for each feature. We've also included the
minimum legacy JIRA Server version (plus any add-ons) that you'll need if you're not using the latest JIRA
applications.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 386
That's it? Time to jump into Confluence and give some of these great features a try with your team or
project.Want to find out more about how to connect your JIRA application to Confluence? Check out Integrati
ng JIRA and Confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 387
If you're a space admin, connect your space to a HipChat room by going to Space Tools > Integration > Hip
Chat and selecting which rooms you'd like to connect. A space can be connected to as many HipChat rooms
as you like, and a HipChat room can be connected to multiple spaces.
When choosing which rooms to connect, you can also choose which notifications you'd like to send to each
room.
Notifications appear in realtime, and clicking on them takes you straight to Confluence.
You can choose different notification settings for each space-room connection. A design team working on a
specific project could choose to get updates from that project's space whenever a page is updated, so they
can keep close track of its progress. From their team space, though, they might choose to be notified only
when theres a new a blog post, so theyre up to date on important team news but don't get interrupted by
any other changes in that space.
Change the notification settings whenever you like by going to Space Tools > Integration > HipChat, and
clicking on Edit Notifications next to the room name.
Find content you've viewed or worked on in Confluence in your HipChat sidebar, so you can easily resume,
share or discuss work with your team. Once a space has been linked to a room, you can find this in your
sidebar either under the space name or, if you have multiple spaces linked to your room, under the name of
your instance.
Select the name of your space or instance, then follow the prompts to authenticate your account. This will let
you open up a Confluence glance in your sidebar. Switch tabs to view either all Updates from the space
linked to that room, or My Work from across Confluence.
The My Work tab lets you filter all the content from Confluence that you've been Mentioned in, Recently
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 388
Worked on, Recently Visited or Saved for later. Now, when you want to share an important piece of
information with your team, ask them to review your work or collaborate with you, you can find and link them
to relevant content directly from HipChat.
Got questions about something someone else has worked on? Once your Confluence instance is linked to
your HipChat group, you can hover over a user mention or a byline in Confluence to see if the user is
available in HipChat. Green for available, yellow for away, or red for do not disturb.
In the editor go to Insert > Emoticons to bring your pages to life with
emoticons. You can also type them right into the editor like this (success)
.
All HipChat's default emoticons can be found here, along with any custom ones people in your organization
have added.
Setting up a new team or project? Create a new HipChat room at the same time, through Confluence. If
you're a space admin, go to Space Tools > Integration > HipChat and instead of selecting an existing room
in the dropdown, type in the name of the new room you want to create and hit Add.
If you're a global admin for both Confluence and HipChat, you can send users HipChat invites directly from
Confluence. Go to
> General Configuration > HipChat Integration > Invite users to HipChat.
You'll need at least one space integrated with a room to see the Invite users link.
Request Add-ons
The Atlassian Marketplace website offers hundreds of add-ons that the administrator of your Atlassian
application can install to enhance and extend Confluence. If the add-on request feature is enabled for your
Confluence instance, you can submit requests for add-ons from the Marketplace to your Confluence
administrator.
The 'Atlassian Marketplace for Confluence' page provides an integrated view of the Atlassian Marketplace from
within your Confluence instance. The page offers the same features as the Marketplace website, such as
searching and category filtering, but tailors the browsing experience to Confluence.
This in-product view of the Marketplace gives day-to-day users of the Atlassian applications, not just
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 389
administrators, an easy way to discover the add-ons that can help them work. When you find an add-on of
interest, you can submit a request with just a few clicks.
After submitting the request, you can update your message at any time. Click the Update Request button next
to the listing in the Atlassian Marketplace page to modify the message to your administrator.
The administrator is not notified of the update. However, your updated message will appear as you have
modified it in the details view for the add-on immediately.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 390
Accessing Confluence through a native client is useful for performing bulk actions. Before you can start creating
and moving things around, it's useful to understand how the content is organized.
The hierarchy in the file system looks like this:
Type of space (global or personal)
Space (folder name is the spacekey)
Homepage (and other top level pages)
Child pages (folder name is the name of the page)
Attachments (filename of the attachment)
Essentially the file structure is the same as the page tree in your space. Here's how the Confluence
demonstration space looks in Finder.
1. Space key
2. Page title
3. Attached file
Here's some things you might choose to do in a local client, rather than in your browser:
Move pages to another space
Select the page folders, and drag them into the other space's folder (drag them from Space A to Space B)
Delete multiple pages
Select all the page folders you want to delete and delete them.
Delete multiple attachments from a page
Navigate down to the page folder, select the attachments you want to delete and delete them.
Upload multiple attachments
Navigate to the page folder, and drag the files into the folder (note you can attach multiple files through
the insert dialog as well).
Mail Archives
Confluence allows you to collect and archive mail within each space. It's Related pages:
useful for storing the email messages that relate to a particular project you
can put them in the same Confluence space as the content for that project. Spaces
Add a Mail
You can download mail from one or more POP or IMAP accounts, or import Account
mail from an mbox file on your local system or on the Confluence server.
You need space administration permissions to manage the mail archives.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 391
Notes
Only site spaces not personal spaces can store mail archives. See Spaces for information on site
and personal spaces.
You can also search the mail messages and their attachments. See Search.
Confluence mail archiving is an optional feature. This means that the 'Mail' options may be disabled
and will therefore not appear in the Confluence user interface. Mail archiving features are contained in
a bundled plugin. To activate mail archiving features in Confluence, enable the plugin choose
> General Configuration > Manage Add-ons. Then choose System in the drop down, and enable
the Confluence Mail Archiving Plugin.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 392
1. Go to the space and choose Space tools > Integrations from the bottom of the sidebar.
2. Choose Mail Accounts > Add mail account.
3. Enter configuration details for the account:
Account Name: Enter a name for this account by which it will be known in Confluence.
Description: Provide a description for this account (optional).
Protocol: Choose from POP, IMAP, POPS or IMAPS.
Hostname: Enter the host name of the mail server on which the account resides.
Port: Don't edit this field. The mail server's port number will be displayed by default.
Username: Enter a username that has permission to retrieve mail from this account.
Password: Enter the account's password.
4. Choose Test Connection to verify the details
5. Choose Create to add the account to Confluence
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 393
For each mail account you add, you can perform these actions in the Mail Accounts tab:
Edit: Change the configuration settings for the mail account.
Remove: Remove the account permanently.
Disable/Enable: Temporarily disable the account, or enable a disabled account.
Fetching Mail
Confluence automatically fetches mail from the server once every 30 minutes. You can manually retrieve
new mail from the configured mail accounts by selecting the Mail tab and choosing Fetch new mail.
You need to be a space administrator to manually retrieve mail. See Space Permissions.
Notes
Only site spaces not personal spaces can store mail archives. See Spaces for information on site
and personal spaces.
Confluence mail archiving is an optional feature. This means that the 'Mail' options may be disabled
and will therefore not appear in the Confluence user interface. Mail archiving features are contained in
a bundled plugin. To activate mail archiving features in Confluence, enable the plugin choose
> General Configuration > Manage Add-ons. Then choose System in the drop down, and enable
the Confluence Mail Archiving Plugin.
Once mail is fetched it will be removed from the server.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 394
Notes
Only site spaces can store mail archives. Personal spaces cannot. See Spaces for an explanation of
site spaces and personal spaces.
Confluence mail archiving is an optional feature. This means that the 'Mail' options may be disabled
and will therefore not appear in the Confluence user interface. Mail archiving features are contained in
a bundled plugin. To activate mail archiving features in Confluence, enable the plugin choose
> General Configuration > Manage Add-ons. Then choose System in the drop down, and enable
the Confluence Mail Archiving Plugin.
For security reasons mail can only be imported from a specified location in the Confluence server's file
system. We recommend administrators create a folder in their Confluence home directory, add the
system property confluence.mbox.directory and specify the location for mailboxes to be
imported from . Mail cannot be imported from the server until this system property is set. See Configuri
ng System Properties.
Gadgets
Gadgets allow you to add dynamic content to a Confluence page or JIRA
application dashboard. Confluence can display gadgets that support the Op
enSocial specification, including third party gadgets.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 395
Where a similar result can be achieved using standard Confluence macros (for example using the Include
Page Macro instead of Confluence Page Gadget), we recommend using macros as they have better
performance and are easier to configure than gadgets.
To add a Confluence gadget to a page:
In the editor go to Insert > Other Macros.
Select the gadget you wish to add, and use the preview area to configure the gadget.
Choose Insert.
See Gadget Macro for more information on adding the macro to your page, configuring the gadget itself and
display options.
For displaying basic JIRA information, such as issues and charts, we recommend using the JIRA Issues
Macro and JIRA Chart Macro as these macros have better performance and are easier to configure than
gadgets.
If the JIRA information you want to display is not available from either of these macros a gadget will likely do
the trick.
To add a JIRA Gadget to a Confluence page:
In the editor go to Insert > Other Macros.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 396
Select the gadget you wish to add, and use the preview area to configure the gadget.
Choose Insert.
See Gadget Macro for more information on adding the macro to your page, configuring the gadget itself and
display options.
If you don't see any JIRA Gadgets in the macro browser, ask your Confluence administrator to add
the JIRA Gadget urls to the list of authorized external gadgets in Confluence, and check that the
application link between Confluence and your JIRA application is configured correctly.
If you don't see any Confluence gadgets in the JIRA gadget directory, ask your JIRA administrator to
add the gadget URLs as follows.
To add a Confluence gadget to your JIRA application's gadget directory:
1. In Confluence, go to Help > Available Gadgets and copy the gadget URL for the gadget you
want to make available in JIRA.
2. In JIRA, go to the dashboard and choose Add Gadget.
3. Choose Manage Gadgets or Add Gadget to Directory (depending on your JIRA application
and version)
4. Paste in the Confluence gadget URL and choose Add Gadget.
The gadget will now be available from the JIRA Gadget Directory.
Properties are settings for Confluence gadgets that allow the user to control the content or presentation of data
retrieved by the gadget. These are similar to a Confluence macro's parameters. The table below lists relevant
properties for this gadget.
These properties are located in the preview panel in the macro browser.
Title Yes None Adds a title to the top of the Activity Stream.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 397
Available Yes All If you have application links to other sites, JIRA or another
streams Confluence site, you can choose to include activity from those
streams also.
Display No Never/false Specify the time interval between each 'refresh' action undertaken
options: by the activity stream gadget. A refresh makes the activity stream
Refresh gadget reflect any new activity that has been conducted on the
Interval Confluence site.
Clicking an item in the Confluence news gadget takes you directly to the selected blog post of the Confluence
Product Blogs feed or event details on the events at Atlassian page.
Clicking More news takes you to the Confluence Product Blogs feed page and clicking More events takes you
to the events at Atlassian page.
Screenshot: The News Gadget
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 398
Confluence: News Gadget Properties
Properties are settings for Confluence gadgets that allow the user to control the content or presentation of data
retrieved by the gadget. These are similar to a Confluence macro's parameters. The table below lists relevant
properties for this gadget.
Show News? No True Shows a short list of the most recent Confluence Product Blogs.
Show Events? No True Shows a short list of the most recent events at Atlassian.
Properties are settings for Confluence gadgets that allow the user to control the content or presentation of
data retrieved by the gadget. These are similar to a Confluence macro's parameters. The table below lists
relevant properties for this gadget.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 399
Space No None Specify the space that your desired page is located in. Suggestions
will display in a dropdown when you start typing.
(Note, this property is only used to make searching for pages
easier. It is not required.)
Page Yes None Specify the page that you want to display in your gadget.
Suggestions will display in a dropdown when you start typing.
Show No Yes Select whether to display a link to view the page on your
View Confluence site. Clicking the link will open the page in Confluence.
Link
Show No No Select whether to display a link to edit the page on your Confluence
Edit Link site. Clicking the link will open the page for editing in Confluence.
Refresh No Never/false Specify the time interval between each 'refresh' action undertaken
Interval by the page gadget. A refresh makes the activity stream gadget
reflect any new activity that has been conducted on the Confluence
site.
Working Macros
The Confluence page gadget will only render a subset of the macros that are used in Confluence correctly.
Refer to the table below for the list of macros that work and do not work with the page gadget and known
limitations.
Some of the issues with macros in the page gadget can be worked around, if you are comfortable
developing in Confluence. Please see Troubleshooting Macros in the Page Gadget for more
information.
Key:
Works with the page gadget
* Partially works with the page gadget
Does not work with the page gadget
Activity You cannot have another gadget embedded within the Confluence Page Gadget
Stream
Attachments N/A
Chart N/A
Children N/A
Display
Content By N/A
Label
Content By N/A
User
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 400
Excerpt N/A
Gallery N/A
Include N/A
Page
Info N/A
Livesearch N/A
Note N/A
Metadata N/A
Metadata N/A
Summary
Pagetree N/A
Search
Pagetree N/A
Panel N/A
Quick Nav You cannot have another gadget embedded within the Confluence Page Gadget
Recently N/A
Updated
Table of * Works, however links will be opened in a new browser window when clicked.
Contents
View File (P * Works, but you may need to refresh the gadget the first time (see CONF-19932)
DF or PPT) .
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 401
site. For more information on how to use this feature, refer to the Quick Navigation Aid section of Search.
Confluence use-cases
This section describes some specific use cases for Confluence. Related pages:
Using Confluence for technical documentation Confluenc
A technical communicator's guide to using Confluence see Develop e
Technical Documentation in Confluence. administrat
or's guide
Setting up a knowledge base Add-ons
A support engineer's guide to using Confluence as a knowledge base and
see Use Confluence as a Knowledge Base. You can also check out integration
our handy guides on writing how-to and troubleshooting articles. s
Setting up an intranet
A quick guide to setting up an intranet wiki see Use Confluence as
your Intranet.
Gadgets
How to add gadgets to a wiki page, or use Confluence gadgets on other sites see Gadgets.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 402
can help you capture, distribute, and update your technical documentation. On this page:
Below are some tips to help you get your technical documentation site
started, and to save you time and effort managing your documentation's life Create
cycle. your
Document
ation
Create your Documentation Space Space
Save time
Creating spaces in Confluence is quick and easy. All you need to do to get by re-using
your documentation started is choose Spaces > Create space from the content
Confluence header. To make things even easier, choose the Use page
'Documentation Space' option in the create space dialog; it'll give you a templates
custom home page with a search box (the livesearch macro) to search just Draft your
your documentation space, a recently updated macro, and a few other work
goodies. Use links
and
Give your space a name, and Confluence will automatically create the home
anchors
page and space key for it (change the space key if you're not happy with the
Useful
one Confluence chooses for you). Feel free to customize the home page at
macros
any time; what it looks like is completely up to you!
Keep track
of page
updates
Customize
Save time by re-using content PDF
export
If there's something you're going to use multiple times in your Other
documentation space whether it's a word, sentence or paragraph; an useful
image; a product version number; or anything else you can create it once tools and
and include it on as many pages as you like (or use it in the header and/or add-ons
footer). Inclusions not only save you typing the same thing many times, they Document
also make it easier when things change it's much better to update the info ation
in one place, than 47! theme
(discontinu
ed)
Related pages:
Spaces
For example, let's say you create release notes for each major release of your product, and you want to
include the intro from each release notes page on a 'what's new' page. Place each release notes intro in an E
xcerpt macro, then add an Excerpt Include macro for each set of release notes to the what's new
page. Your intros will magically appear on the what's new page, and if you update the release notes it'll
automatically update the what's new.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 403
> Copy it's actually an Include Page macro. We have a page with just that image on it, so we can include
it whenever we need an ellipsis.
Why do we do use an Include Page macro for one tiny image? Well, just in case that UI element is ever
changed. If we attach the image to every page, there might be 50 pages we need to update when things
change; if we use an Include Page macro, we update once and it's changed everywhere. Doing it this way
also allows us to know how many pages we're using the image on. By going to
> Page Information, we can see how many incoming links there are to this page, and that tells us how
many pages use the image.
You can include content from any Confluence page, but you may want to create an 'inclusions library' to hold
content that's specifically for re-use. The inclusions library isn't a specific feature of Confluence; the pages in
the inclusions library are just like any other Confluence page. This is just a technique you can use if you want
a place to store content that's specifically for re-use.
To create your inclusions library:
1. Choose Create and create a new page in your space
2. Enter a suitable title. We use '_ConfluenceInclusions' (the underscore before the title helps to let
people know this page is special)
3. Enter some content and save the page
We enter text explaining the purpose of the inclusions library and how to re-use the content
4. Choose Space tools > Reorder pages and drag your new page above the space homepage
5. Go to your new inclusions page and choose Create to add child pages containing your re-usable
content
Because you've moved the pages to the root of the space, they won't appear in the page tree in the
sidebar. The pages will be picked up by other searches though, as they're normal Confluence pages.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 404
1. Inclusions library location: drag your inclusions library here, above the rest of your documentation.
Creating one or more page templates can be a real time-saver if you're creating a lot of pages with the same
layout. If you're constantly adding the same macros, like panels and table of contents, save yourself from RSI
and put them into a template you can start with one, but make as many as you need to maximize your
efficiency.
To create a page template that's available in all spaces:
1. Go to
To get to Global Templates and Blueprints , or any other admin page quickly, hit / on your
keyboard and start typing the name of the admin page you're looking for.
When you're creating a new page in your documentation, you'll likely want to do it over time, saving as you
go, and have a select few people review it to provide feedback. A loose description of this workflow is 'draft,
review, publish'.
You don't want any half-finished pages being seen by your users, and most documentation needs to be
reviewed before it's finalized, so here's a technique for drafting pages and allowing for review:
1. Create a page and restrict its permissions
For example, you might restrict viewing to a group of people such as your team, or a few select
individuals. On a public site, you might restrict viewing to staff members, so that the general public
can't see the page.
2. Write your page content
3. Share the page with your reviewers and ask them for feedback (make sure you haven't restricted them
from seeing the page!)
The reviewers can add comments to the bottom of the page or highlight text to add a comment inline.
If you give them permission, they can also edit the page content directly.
4. Publish the page when ready, by doing the following:
a. Delete any comments on the page
b. Remove page restrictions so that your audience can see it
You've now published your page. The space permissions and site permissions now determine who can see
and/or update the page.
Add links
In any documentation site, it's essential to be able to link from one page to another, and often to specific
sections on a page. You can add any URL to a Confluence page and Confluence will automatically detect
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 405
The anchor macro allows you to create anchors in your documentation, which can be linked to from
anywhere. I've added an anchor at the top of this page so you can click to go back to the top.
To add a macro and link to it from the same page:
1. Type {anchor in the editor, select the anchor macro and give your anchor a name (top in my
example)
2. Select the text that'll link to the macro and hit Ctrl+K (Windows) or Cmd+K (Mac) (this opens the link
dialog)
3. Choose Advanced from the options on the left and type # followed by your anchor name (#top in my
example)
Check out our documentation for links and anchors to get the full rundown on linking to anchors on other
pages and other anchor goodness.
Useful macros
Confluence ships with a great range of macros, and there are a few that are particularly useful in technical
documentation. Here's a few:
The Table of Contents macro helps people navigate lengthy pages by summarizing the content structure and
providing links to headings used on the page. The best part is, you don't need to do anything except add the
macro; once you've added it, it'll automatically detect headings and add them to the table of contents.
Often when creating documentation, there are elements of a page that you want to highlight or draw the the
viewers' attention to. Confluence ships with the Tip, Info, Warning, Note and Panel macros, which will help
you focus a viewer's attention on a particular part of your content.
In Confluence, it's quite usual for a number of different people to update a single page. Technical writers
need to know what happens to our documents, both during review and after publication.
So that you know when changes are made, it's a good idea to watch pages or even the entire space. That
way, when changes are made to pages you're watching, or someone comments on them, you'll get an email
notification letting you know who changed what.
Whenever you're on a page in your documentation space, choose the Watch button at the top-right of the
page. From there, you can choose to watch just that page, or all pages in the space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 406
Confluence creates a new version of the page every time someone edits the page. The page history shows
all the versions, with date, author, and any comments made on the update.
To view page history, go to the page and choose
If you want to see at a glance who's updated a page or pages, you can add the contributors macro. This
macro displays a customizable list of people who've contributed by creating, editing, or, optionally,
commenting on the page.
If you're planning to provide a PDF version of your documentation whether it be for email, download, print,
or any other form of delivery you can customize the look of the PDF by adding a title page, header, and
footer.
The process you take depends on whether you're trying to customize the PDF export for one space or for
your whole site, so, if you're keen to make these changes, take a look at our page on Customize Exports to
PDF for more detailed instructions.
Confluence is already a great tool for technical documentation, but you can still add to it depending on your
documentation and workflow needs. Here are some useful add-ons available on the Atlassian Marketplace,
most of which we use ourselves, which can extend the functionality of Confluence.
Scroll Versions, by K15t, allows you to tie versions of your documentation to versions of your product, so that
when a new version of your product ships you can publish that version of your documentation. Create as
many versions of your documentation as you like, make the changes you need to, and keep them up your
sleeve until release time. You can even publish different variations of your documentation like if you have
versions of your documentation for different operating systems to different spaces or Confluence instances.
The Copy Space add-on, by Atlassian Labs, does what its name suggests; it allows a space administrator to
copy a space, including the pages within the space. Great for when you want a space template that you can
copy to create other spaces.
This plugin is also useful when you need to archive a copy of a current space at a particular point in time, like
when you're moving from one version of your product to the next copy the space, give it a new name, and
keep it wherever you like, all without losing the existing space.
At this point this plugin won't copy page history, blog posts and email.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 407
If you're going to produce a PDF of your documentation space, wouldn't you like it to be professionally
formatted? The Scroll PDF Exporter, by K15t, lets you style single pages or whole spaces for export, using
handy PDF templates.
Gliffy (supported)
Create diagrams, wireframes, flowcharts and more with Gliffy. Gliffy features a highly intuitive drag-and-drop
interface, and allows you to export your diagrams in multiple formats, including: JPEG, PNG and SVG. Add
Gliffy flowcharts, UI wireframes, and network diagrams directly to your Confluence pages to communicate
your ideas visually, making them easy to understand and faster to spread through your team.
Lucidchart (supported)
Lucidchart is available in versions for Cloud and Server, and allows you to create and insert diagrams within
your Confluence Cloud environment. Quickly draw flowcharts, wireframes, UML diagrams, mind maps, and
more inside our feature-rich editor.
The server version also comes with a free Visio viewer, so you can view Microsoft Visio (.vsd) files, Visio
stencils (.vss) and it also supports exporting back to Visio.
Confluence historically provided a theme specifically for documentation. This theme was removed
in Confluence 6.0.A number of the original Documentation theme features, such as headers, footers and the
ability to add custom content to the sidebar, are now available in Confluence's more modern default theme,
which make it a great choice for your documentation space.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 408
To make it easy for your users to create knowledge base articles, such as your help desk or support team,
we recommend customizing the how-to and troubleshooting article templates to make them relevant for your
organization. The more guidance and structure you can put in your template, the faster it will be for your team
to create great articles.
To edit the article templates:
1. Go to Space Admin > Content Tools > Templates.
2. Edit the How-to or Troubleshooting article templates.
3. Add headings and instructional text (choose Template > Instructional Text).
You can also add additional templates, such as a policy or procedure page templates.
We also recommend customizing the look and feel of your space. Simple changes like a space logo and
welcome message can make a huge difference.
To change the look and feel:
Add a space logo and useful shortcuts to the sidebar (choose Space Tools > Configure Sidebar)
Edit the homepage to add a custom welcome message.
Edit the color scheme (choose Space Tools > Look and Feel > Color Scheme).
Channels of communication with your audience, internal or external, are essential in a good knowledge base.
Here are some out-of-the-box options:
Blog - blog updates and important notices, and encourage people to watch for new blogs in your
space.
Watch - encourage people to watch pages that interest them, or watch the entire space.
Comments - allow logged in users (or even anonymous users) to comment on knowledge base
articles. This is a simple way to connect with your end users.
RSS - create an RSS feed and add the link to your knowledge base homepage (choose Help > Feed
Builder). Alternatively encourage users to create their own feed - useful if they want to keep up with
particular topics (labels), rather than receive notifications for the whole space.
If your Confluence site is connected to another Atlassian product (via an application link), you can make use
of these great integration features:
If you use any JIRA application - add a JIRA Issues macro to your troubleshooting article to provide
quick access to known issues. This has the added advantage of automatically updating when an issue
is resolved or its status changes. One simple way to do this would be to add some labels to JIRA to
indicate the issue should appear in the knowledge base (for example 'printer-kb'), and then add a JIRA
Issues macro with a query like 'label = 'printer-kb and status <> resolved'' on all articles with the printer
topic.
If you use JIRA Service Desk - link a Confluence space to be used as a knowledge base. Users
(including those without a Confluence license) can search your knowledge base directly from within
the Service Desk customer portal.
If you use Questions for Confluence Server - add a Questions list macro to troubleshooting articles,
to highlight the top questions with the same topic as the article, and an Ask a Question button to the
knowledge base homepage.
The Atlassian Marketplace has a large number of add-ons for Confluence. A common addition to Knowledge
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 409
Base spaces is a survey or form tool, which enables you to get feedback on the usefulness or usability of
your knowledge base articles.
Search for 'knowledge base' on Marketplace and see if there is an add-on that's right for your knowledge
base.
It's quick and easy to add users to your Confluence site. Allow people to add themselves as users of the site;
invite people to sign up by sending them an invitation link; add new users manually; or use an existing
directory like an LDAP directory for authentication and to manage users and groups.
Whichever way you choose, you can quickly build a community of Confluence users and give them access to
your intranet; you'll also have a ready-made people directory.
Upload your company logo, and Confluence's auto look and feel will change the color scheme to match. It'll
make your intranet feel more familiar to your colleagues, and help with adoption.
A Confluence space is essentially a container for a group of pages and blog posts with related content.
When you're starting out with Confluence, the easiest way to organize things is to create a space for each
team or department within your organization. Each team's space is then a place for them to create and share
pages, blog posts, meeting notes, files, and much more and becomes the place to go for team members to
get the information they need.
Just choose Spaces > Create space from the header, and Confluence provides a list of space blueprints to
help get you started.
Each space can have its own color scheme and has a customizable home page, which you can edit to suit
your purpose like displaying and tracking team goals and displaying a list of team members. Use the
built-in 'Team Space' template to automatically add all members of the team to the homepage, to help
everyone get to know each other.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 410
You can set permissions for each space, so if there's sensitive information that should only been seen by
certain users or groups, it's easy to secure it with Confluence.
Don't feel restricted to creating spaces for teams though; you can also create spaces for projects (large or
small), events, and anything else where you want to collect information under a common heading or
permissions structure.
Once you have some spaces set up, create some pages and blog posts to give your colleagues an example
of how Confluence can be used, then invite them to create their own pages and blogs.
Every Confluence user, including you, can also create their own personal space; it can be a place to keep
your own work, add shortcuts to your most used content, and you even get your own blog for sharing your
ideas and opinions with the rest of your organization (or just those that you want to see them).
You can create pages for anything you want in Confluence - meeting notes, project plans, decisions, and
more. Pages are editable so others can contribute and keep them up to date after you create them. Choose
Create from the Confluence header and choose a blank page, or use a template to get you started.
Type your page, change its layout, add images and links, and do it all without any specialist skills or training.
You can also attach files allowing everyone in a team access to assets that are critical to the project like
mockups and requirements. You and your colleagues can like the page, and comment on it to start a
conversation about the content.
Confluence also offers a series of useful built-in page blueprints, which help you with the content and
formatting of the page. The meeting notes and decisions blueprints are two that can be really useful when
others need to be in-the-know about what happened, and why it happened.
Each space you create in Confluence has its own blog, where you and your teams can share news and
events, discuss important projects and developments, or congratulate a teammate for a special effort;
blogging is a great way to foster company culture and celebrate achievements across your organization.
You can watch any blog to make sure you get updated when there's a new post. Blog posts are automatically
organized by date, and grouped by year and month, so they're also easy to find.
If you need to be sure that the right people see a page or blog post, Confluence offers a range of ways to
make sure you can get their attention. Type the @ symbol and the name of a Confluence user to mention the
m in a page, blog post, or comment. They'll get an email notification that you've mentioned them, with a link
to the page, post or comment.
There's also a Share button at the top right of every page. Type the name or email address of a user or
group and send them a short message with a link to the content you're sharing.
Don't miss out on important updates. Watching spaces, pages, and blogs is a great way to stay up-to-date
with what's happening in your own team, or any other team or person you need to keep up with. When you
watch something, you'll get email updates when changes are made or a comment is added.
The Confluence dashboard also has a recent activity feed, which allows you and your team to see what's
trending throughout the company or in your network.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 411
If you want to communicate in-the-moment, HipChat our private service for chat, video, and screen sharing
is built for teams. Share ideas and files in persistent group chat rooms, or chat 1-1 for that personal touch.
HipChat integrates with Confluence, so you can get real-time notifications in HipChat whenever new
information is shared in Confluence pages and blogs.
Got a question (that's not rhetorical)? Why not ask your team? Questions for Confluence is an addon for
Confluence that gives you knowledge sharing with your own Q&A service. Run company-wide polls to gauge
reaction to a new marketing initiative, or let people vote on the venue for the Christmas party. Ask questions,
get answers, and identify experts.
You can also try Team Calendars for Confluence for organizing and sharing team events, leave, and other
important appointments. Embed each team's calendar on their home page so that everyone knows what's
happening, and when.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 412
Create sprint retrospective How to make better decisions How to document releases
and demo pages (like a BOSS) as a development team and share release notes
Like what you see? Start creating these pages and more in
Confluence!
This guide covers features and functions that are only available to administrators.
For information on creating and administering spaces, See Spaces.
This guide assumes that you are using the Confluence default theme. If your Confluence site has been
customized the header may look different, and menu items appear in different locations to the examples
given in this guide.
Getting Started as Confluence Administrator Downloads
Manage Users
Add and Invite Users
Delete or Disable Users Download the Confluence documentation
Restore Passwords To Recover Admin in PDF format.
User Rights
Edit User Details Other resources
Change a Username
Managing Site-Wide Permissions and Confluence installation and upgrade guide
Groups
Configuring User Directories Confluence Knowledge Base
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 413
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 414
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 415
After installing Confluence, you will perform the initial configuration via a web interface called the Confluence
Setup Wizard.Introducing the Confluence Administration Console: From this point onwards, many of the
admin functions are available from the Confluence Administration Console, which is part of the Confluence
web interface. If you have administrative permissions, you'll have access to the Confluence Administration
Console via your web browser, using the standard Confluence URL for your site.
To access the Confluence Administration Console:
1. Open your Confluence URL in your web browser
2. Choose
Is this a new Confluence site? Here are some things to get started with:
Decide whether you want to allow public (anonymous) access to your site.See Setting Up Public
Access.
Add a space and some content. See Create a Space then Pages and blogs.
Invite some users to your site. See Add and Invite Users.
Decide whether you will manage your users in Confluence or hook up an external LDAP directory. See
Configuring User Directories.
Make sure you have set up an email server. The above task list will include this step, but it is worth
mentioning it here again. Email notifications are an important part of collaborating on Confluence. See
Configuring a Server for Outgoing Mail.
Now you can continue getting to know your site, as described in the next section.
Has the site been around a while, but you are new to Confluence administration? Take a look at these topics:
Understand the Confluence permission scheme. See Permissions and restrictions.
Get to know the power of add-ons (also called plugins), for extending and customizing your
Confluence site. See Managing Add-ons or Plugins.
Investigate more ways of customizing Confluence. See Customizing your Confluence Site.
Manage Users
A Confluence user is a person who can read or
update a Confluence site. You can choose whether
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 416
Authentication
Seraph
Almost all authentication in Confluence (and JIRA applications) is performed through Seraph, Atlassian's
open source web authentication framework. The goal of Seraph is to provide a simple, extensible
authentication system that we can use on any application server.
Seraph is implemented as a servlet filter. Its sole job is, given a web request, to associate that request with a
particular user (or no user if the request is anonymous). It supports several methods of authentication,
including HTTP Basic Authentication, form-based authentication, and looking up credentials already stored in
the user's session.
Seraph itself performs no user management functions. It merely checks the credentials of the incoming
request and delegates any user management functions (looking up a user, checking a user's password) to
Confluence's user management system.
If you want to integrate Confluence with your own single sign-on (SSO) infrastructure, you would do so by
installing Atlassian Crowd or by writing a custom Seraph authenticator. See our developer documentation on
HTTP authentication with Seraph.
Normally, requests for Confluence's XML-RPC and SOAP APIs (deprecated) will include an authentication
token as the first argument. With this method of authentication, XML-RPC and SOAP authentication requests
are checked directly against the user management framework, and tokens are assigned directly by the
remote API subsystem. These requests do not pass through Seraph authenticators.
However, if the token argument is blank, Seraph will be used as a fallback authentication method for remote
API requests. So, to use a custom Seraph authenticator with XML-RPC or SOAP requests, ensure that you
pass an empty string as the authentication token to remote API methods.
Password authentication
By default, password authentication is delegated from Seraph to the user management system. This is not
necessary, however. Single sign-on systems may have no password authentication at all, and get all the
necessary credentials from the SSO provider.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 417
If you have a Confluence Data Center license you can connect Confluence to your SAML 2.0 identity
provider for authentication and single sign-on.
See SAML SSO for Confluence Data Center for more information.
You can restrict the signup to people whose email addresses are within a given domain or domains. This is
useful if you want to ensure that only people within your organization can add their own usernames.
You will still be able to add or invite users manually, whether user signup is enabled or not.
You need Confluence Administrator or System Administrator permissions to change the signup options.
To set the user signup options:
1. Choose
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 418
By default, Confluence will send an email notification to all Confluence administrators whenever someone
signs up to your Confluence site. The administrators (people with Confluence Administrator or System
Administrator permissions) will receive this message when someone signs up either by clicking the 'Sign Up'
link or by clicking the invitation URL sent by an administrator.
To disable this notification:
1. Choose
You can invite new users to the site by sending them a signup URL, called an 'invitation link'. You can copy
the invitation link and paste it onto a page or into an email message, or you can prompt Confluence to send
an email message containing the same link.
The option to send invitations is independent of the signup options. You can send invitations if signup is open
to all, restricted by domain, or disabled entirely. Even if signup is restricted or disabled, a person who has
received an invitation will be able to sign up.
When someone visits the invitation link in a browser, a Confluence signup screen will appear.
To invite people to sign up:
1. Choose
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 419
1.
http://confluence.example.com/signup.action?token=d513a04456312c47
This security token is a shared token individual invitations don't have unique tokens. Anyone who obtains
this token will be able to sign up to Confluence.
You can change the token at any time, by choosing Reset. The previous invitation link will then become
unusable.
Screenshot: Inviting users
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 420
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 421
Notes
Multiple directories You can define multiple user directories in Confluence, so that Confluence
looks in more than one place for its users and groups. For example, you could use the default
Confluence internal directory and connect to an LDAP directory server. In that case, you can define
the directory order to determine where Confluence looks first when processing users and groups.
Here is a summary of how the directory order affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
See Managing Multiple Directories.
Email server required for domain restricted signup and for invitations You need to set up a mai
l server for Confluence, before you can configure domain restricted signup or send email invitations to
users.
Are the user management options not visible? If you have external user management turned on,
internal user management is disabled. To configure external user management, go to
> General Configuration> Security Configuration. See Disabling the Built-In User Management.
Avoid hash, slash and question characters in usernames - there is a known issue where users
CONFSERVER-43494
with #, ? or / in their username cannot create spaces. See OPEN and
CONFSERVER-13479
OPEN for more information.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 422
Someone with a disabled user account can no longer log in to Confluence, and they don't add to your license
count.
To delete or disable a user:
1. Choose
Notes
The Administer User link is only visible if you are logged in as an administrator.
You can also delete or disable users using the Administration Console.
You can edit the groups that a user belongs to, to change their permissions without completely
preventing their access to Confluence.
Multiple user directories You can define multiple user directories in Confluence, so that
Confluence looks in more than one place for its users and groups. For example, you could use the
default Confluence internal directory and connect to an LDAP directory server. In that case, you can
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 423
define the directory order to determine where Confluence looks first when processing users and
groups.
Here is a summary of how the directory order affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
See Managing Multiple Directories.
Number of users and your license The Confluence 'License Details' screen tells you how many
users your Confluence instance is licensed to support, and how many are currently registered. The
number of registered users includes only users who have the 'Can Use' global permission.
Deactivated users, as described above, aren't included. Choose Refresh to make sure you see the
latest count.
If the user resides in a Read Only external directory, the option to disable the user won't appear.
The following instructions include example SQL that should work on MySQL and PostgreSQL. You may need
to customize the queries for other databases or for your installation.
We strongly recommend testing the queries on a test database before modifying your production database.
If you know the admin username with a valid email address, and you have outgoing mail configured,
you can reset the password using the forgot password link on the log in screen.
We'll send a link to your admin email account to reset your password.
If you're using the embedded H2 database, you can find the files containing your database in <confluence
-home-directory>/database. See Embedded H2 Database for information on how to connect.
If you're using an external production database, connect to the database with your normal tools. You'll need
to have permission to run queries and update data in the database.
To find out which usernames have admin privileges, connect to your database using a database admin tool
such as DBVisualiser. Download a database admin tool now if you don't have one installed already. Then
connect to your database and retrieve the list of administrator usernames and IDs with:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 424
If there are multiple results, choose one ID/username combination to use for the following steps.
If there are no results, skip down to If No Local Administrator Exists.
It's important to make sure that the "active" field contains a value of "T". Without this flag, trying to
authenticate with this user is a non starter.
To set active to true run the following query replacing "<user_name>" with the username from the
previous query
UPDATE cwd_user
SET active = 'T'
WHERE user_name ='<user_name>';
There may be no administrators in your Internal Directory. If this is the case, you need to add one:
1. Add a new admin user by running:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 425
If you're using an Oracle database, use sysdate instead of a string for the created_date column.
x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB+XU
RPWx1ONxp3Y3pB37A==
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 426
Start Confluence, and try logging in with the username of the user you updated/created and the password
'admin'. If this works, skip to Step 4; otherwise, your Internal Directory doesn't have high enough priority.
To put your Internal Directory in first position:
1. Find the directory names and their order:
2. Take note of the ID with list_index 0, and the list_index and ID of the Confluence Internal Directory
3. Switch the order of the directories:
4. Check to see if the directory is active (the 'active' column should be set to 'T'):
Step 4. Clean Up
To tidy up:
1. Start Confluence
2. Log in with your modified/created username and use password admin
3. Change your password
Don't leave your password as admin; if you do, your instance won't be secure.
4. If you created a new user in Stage 2, create a new admin via the UI and delete the admin you created
in Stage 2
5. If you followed Stage Three, go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation
5.
427
> General Configuration > User Directories and rearrange your directories so they're correctly
configured again.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 428
Confluence records the number of failed logins attempts made against each user account. When the login
attempts exceed a preset number, the user is prompted to authenticate using CAPTCHA until they
successfully log in.
If the user you're administering has any failed login attempts, you can manually set the failed login count for a
user back to zero by clicking Reset Failed Login Count.
Change a Username
As a Confluence administrator, you can change a user's username. This
could be for any reason, but might happen when someone changes their
name, for example.
Each active users must have a unique username, so no two active users
can have the same username. You can, however, assign the username of a
disabled user to another active user.
The procedure for changing a username depends on where you manage
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 429
your users. See Configuring User Directories for more info. On this page:
Confluenc
e-manage
d users
Users
managed
in an
external
directory
Notes
Confluence-managed users
If you manage your users in the Confluence internal directory, you can rename your user in Confluence.
You'll need Confluence Administrator permissions to change a username.
To change a username:
1. Choose
If you don't manage your users in the Confluence internal directory, you may still be able to change
someone's username. Confluence can't update external users, but it will detect changes in usernames
coming from some external directories.
The following table shows the instances where you may be able to change a username in your external
directory and have the change detected in Confluence.
Internal directory with LDAP Rename the user in the LDAP directory, Confluence will detect the
authentication renamed user.
Note: you must have 'Copy User on Login' enabled. See Copying Users
on Login for more information.
JIRA 6.1 or later Rename the user in JIRA, Confluence will automatically detect the
renamed user.
Atlassian Crowd 2.7 or later Rename the user in Crowd, Confluence will automatically detect the
renamed user.
LDAP Rename the user in your LDAP directory, Confluence will automatically
detect the renamed user.
Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 430
Personal Spaces If a Confluence Administrator renames a user who has a personal space, the
space key for that space will remain as the original username. For example, if jsmith's username is
changed to jbrown, their personal space key will remain ~jsmith.
The Confluence administrator global permission and the confluence-administrators group are not
related. Going by the names, you would think they are the same thing, but they are not. Granting a user or a
group Confluence administrator global permission provides access to a sub-set of administrative functions.
Granting membership to the confluence-administrators group gives complete access to all functions
and content.
View the comparison table.
Anonymous users
All users who don't log in when they access Confluence are considered 'anonymous'. You can grant
anonymous users the 'Use Confluence' permission via the Global Permissions screen if you need to. This will
allow non-registered users to access pages and spaces in Confluence. A space administrator can further
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 431
Granting the Confluence Administrator permission to someone allows them access to many, but not
all, options in the administration console (
> General configuration). Expand the comparison table to view the options available to people granted the
Confluence Administrator permission, and to those in the confluence-admin group.
Click to view the comparison table
CONFIGURATION
General Configuration
Further Configuration
Manage Referrers
Languages
Shortcut Links
Import Templates
Mail Servers
User Macros
In-app Notifications
HipChat Integration
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 432
Attachment Storage
Spam Prevention
WebDAV Configuration
Office Connector
ATLASSIAN MARKETPLACE
Manage add-ons
Purchased add-ons
Users
Groups
Security Configuration
Global Permissions
Space Permissions
User Directories
Whitelist
Themes
Color Scheme
Layouts
Stylesheet
PDF Layout
PDF Stylesheet
Custom HTML
ADMINISTRATION
System Information
Content Indexing
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 433
Mail Queue
Cache Management
Scheduled Jobs
License Details
Thread Dump
Application Links
Application Navigator
Analytics
Clustering
Notes
Multiple user directories: You can define multiple user directories in Confluence, so that Confluence
looks in more than one place for its users and groups. For example, you could use the default
Confluence internal directory and connect to an LDAP directory server. In that case, you can define
the directory order to determine where Confluence looks first when processing users and groups.
Here is a summary of how the directory order affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
See Managing Multiple Directories.
This is the recommended method. It allows you to manage the group membership for a number of users at
the same time.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 434
You can update a user's group membership from the user management screen. This functionality allows you
to update one user at a time.
To add a user to a group or remove a user from a group:
1. Go to the user management screen for the user concerned. There are two ways to do this:
Either,
Go to the user's Profile and choose Administer User on the user's profile screen.
Or, Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 435
You can define multiple user directories in Confluence, so that Confluence looks in more than one
place for its users and groups. For example, you could use the default Confluence internal directory
and connect to an LDAP directory server. In that case, you can define the directory order to
determine where Confluence looks first when processing users and groups.
Here is a summary of how the directory order affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
See Managing Multiple Directories.
Global Description
Permission
Can Use This is the most basic permission that allows users to access the site.
Users with this permission count towards the number of users allowed by your license.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 436
Attach Files This allows the user to upload files to be stored in their user profile.
to User
Profile This feature was made obsolete by the introduction of personal spaces in Confluence 2.2.
Hence, this permission is no longer relevant. Attachments can be accessed from a user
profile view (for example, an image within the 'About Me' field of a profile view) by
attaching these files to a page within that user's personal space and referencing them
using appropriate wiki markup code.
Create This permission allows users to create new spaces within your Confluence site. When a
Space(s) space is created, the creator automatically has the 'Admin' permission for that space and
can perform space-wide administrative functions.
Confluence This permission allows users to access the 'Administration Console' that controls site-wide
Administrator administrative functions. Users with this permission can perform most, but not all, of the
Confluence administrative functions. See the comparison of 'System Administrator' and
'Confluence Administrator' below.
System This permission allows users to access the 'Administration Console' that controls site-wide
Administrator administrative functions. Users with this permission can perform all the Confluence
administrative functions, including the ones which the 'Confluence Administrator'
permission does not allow. See the comparison of 'System Administrator' and 'Confluence
Administrator' below. Refer also to the note about the 'confluence-administrators' group bel
ow.
Comparing the System Administrator permission with the Confluence Administrator permission
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 437
Application People with the 'Confluence Administrator' permission can add, modify and remove
Links application links and project links. For example, they can link Confluence to JIRA.
However, Confluence administrators can configure only OAuth authentication for
application links.
The default confluence-administrators group is a special, 'super-user' group that gets permissions
above and beyond the Confluence administrator and system administrator global permissions. Members of
this group can perform site-wide administration functions, and also see the content of all pages and spaces in
the Confluence site, regardless of space permissions or page restrictions.
Restricted pages and blog posts are not visible to members of the confluence-administrators group in
the dashboard, blog roll, search and most macros, but will be visible in the following places:
In the sidebar (visible with Page Tree navigation, but not visible with Child Pages navigation)
Pages index page
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 438
You can't change the global permissions granted to the confluence-administrators group. If you don't
want your admins to be able to see all spaces and restricted pages, you can create a new group, and grant
that group the Confluence administrator and system administrator global permissions.
The Confluence administrator global permission and the confluence-administrators group are not
related. Going by the names, you would think they are the same thing, but they are not. Granting a user or a
group Confluence administrator global permission provides access to a sub-set of administrative functions.
Granting membership to the confluence-administrators group gives complete access to all functions
and content.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 439
If you're using Confluence as a knowledge base for JIRA Service Desk, you can choose to allow all active
users and customers (that is logged in users who do not have a Confluence license) to view pages in specific
spaces. This permission can only be turned on via JIRA Service Desk.
To revoke access for unlicensed users:
1. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 440
This section only appears on the Global Permissions page in Confluence if you have linked a space to your
Service Desk project (as a Knowledge base), and chosen to allow all active users and customers to access
without a Confluence license. See Serving customers with a knowledge base in the Service Desk
documentation for more info.
Confluence will let you know if there is a problem with some permissions. In rare situations, you may see the
following error messages below a permission:
'User/Group not found' - This message may appear if your LDAP repository is unavailable, or if the
user/group has been deleted after the permission was created.
'Case incorrect. Correct case is: xxxxxx' - This message may appear if the upper/lower case in the
permission does not match the case of the username or group name. If you see a number of
occurrences of this message, you should consider running the routine supplied to fix the problem.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 441
To disable anonymous access to your site, deselect the can use check box, then choose Save All. People
will not be able to see the content on the site until they have logged in.
To enable public access to a Confluence space, you must grant the following permissions to anonymous
users:
The site-wide 'can use' permission, as described above.
The relevant space permissions. If you want a space to be publicly accessible, the anonymous user
must have at least the 'View Space' permission. To set space permissions, choose Browse > Space
Admin > Permissions.
Notes
Connecting to a Directory
You can add the following types of directory servers and directory managers:
Confluence's internal directory. See Configuring the Internal Directory.
Microsoft Active Directory. See Connecting to an LDAP Directory.
Various other LDAP directory servers. See Connecting to an LDAP Directory.
An LDAP directory for delegated authentication. See Connecting to an Internal Directory with LDAP
Authentication.
Atlassian Crowd or JIRA 4.3 or later. See Connecting to Crowd or JIRA for User Management.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 442
You can add as many external user directories as you need. Note that you can define the order of the
directories. This determines which directory Confluence will search first, when looking for user and group
information. See Managing Multiple Directories.
Updating Directories
You cannot edit, disable or remove the directory your user belongs to. This precaution is designed to prevent
administrators from locking themselves out of the application by changing the directory configuration in a way
that prevents them logging in or removes their administration permissions.
This limitation applies to all directory types. For example:
You cannot disable the internal directory if your user is an internal user.
You cannot disable or remove an LDAP or a Crowd directory if your user comes from that directory.
In some situations, reordering the directories will change the directory that the current user comes from, if a
user with the same username happens to exist in both. This behavior can be used in some cases to create a
copy of the existing configuration, move it to the top, then remove the old one. Note, however, that duplicate
usernames are not a supported configuration.
You cannot remove the internal directory. This precaution aligns with the recommendation below that you
always keep an administrator account active in the internal directory.
Recommendations
The recommended way to edit directory configurations is to log in as an internal user when making changes
to external directory configuration.
We recommend that you keep either an administrator or system administrator user active in your internal
directory for troubleshooting problems with your user directories.
You can enable or disable a directory at any time. If you disable a directory, your configuration details will
remain but the application will not recognize the users and groups in that directory.
You have to disable a directory before you can remove it. Removing a directory will remove the details from
the database.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 443
Diagram above: Confluence using its internal directory for user management.
Overview
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 444
Server Settings
Setting Description
Name Enter a meaningful name to help you identify the LDAP directory server. Examples:
Example Company Staff Directory
Example Company Corporate LDAP
Directory Select the type of LDAP directory that you will connect to. If you are adding a new LDAP
Type connection, the value you select here will determine the default values for many of the options
on the rest of screen. Examples:
Microsoft Active Directory
OpenDS
And more.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 445
Use SSL Check this if the connection to the directory server is an SSL (Secure Sockets Layer)
connection. Note that you will need to configure an SSL certificate in order to use this setting.
Username The distinguished name of the user that the application will use when connecting to the
directory server. Examples:
cn=administrator,cn=users,dc=ad,dc=example,dc=com
cn=user,dc=domain,dc=name
user@domain.name
By default, all users can read the uSNChanged attribute; however, only
administrators or users with relevant permissions can access the Deleted Objects
container. The specific privileges required by the user to connect to LDAP are "Bind"
and "Read" (user info, group info, group membership, update sequence number,
deleted objects), which the user can obtain by being a member of the Active
Directory's built-in administrators group.
Note that the incremental sync will fail silently if the Active Directory is accessed by a
user without these privileges. This has been reported as CWD-3093.
Schema Settings
Setting Description
Base DN The root distinguished name (DN) to use when running queries against the directory server.
Examples:
o=example,c=com
cn=users,dc=ad,dc=example,dc=com
For Microsoft Active Directory, specify the base DN in the following format: dc=domain1,
dc=local. You will need to replace the domain1 and local for your specific
configuration. Microsoft Server provides a tool called ldp.exe which is useful for finding
out and configuring the the LDAP structure of your server.
Additional This value is used in addition to the base DN when searching and loading users. If no value is
User DN supplied, the subtree search will start from the base DN. Example:
ou=Users
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 446
Additional This value is used in addition to the base DN when searching and loading groups. If no value
Group is supplied, the subtree search will start from the base DN. Example:
DN
ou=Groups
If no value is supplied for Additional User DN or Additional Group DN this will cause the subtree
search to start from the base DN and, in case of huge directory structure, could cause performance
issues for login and operations that rely on login to be performed.
Permission Settings
Note: You can only assign LDAP users to local groups when 'External Management User Management' is
not selected.
Setting Description
Read Only LDAP users, groups and memberships are retrieved from your directory server and can only
be modified via your directory server. You cannot modify LDAP users, groups or
memberships via the application administration screens.
Read LDAP users, groups and memberships are retrieved from your directory server and can only
Only, with be modified via your directory server. You cannot modify LDAP users, groups or
Local memberships via the application administration screens. However, you can add groups to
Groups the internal directory and add LDAP users to those groups.
Note for Confluence users: Users from LDAP are added to groups maintained in
Confluence's internal directory the first time they log in. This is only done once per user.
There is a known issue with Read Only, with Local Groups in Confluence that may apply to
you. See
CONFSERVER-28621 - User Loses all Local Group Memberships If LDAP Sync is Unable to find the
User, but the User appears again in subsequent syncs RESOLVED
Read/Write LDAP users, groups and memberships are retrieved from your directory server. When you
modify a user, group or membership via the application administration screens, the changes
will be applied directly to your LDAP directory server. Please ensure that the LDAP user
specified for the application has modification permissions on your LDAP directory server.
Setting Description
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 447
Default Option available in Confluence 3.5 and later, and JIRA 4.3.3 and later. This field appears if
Group you select the 'Read Only, with Local Groups' permission. If you would like users to be
Memberships automatically added to a group or groups, enter the group name(s) here. To specify more
than one group, separate the group names with commas.
In Confluence 3.5 to Confluence 3.5.1: Each time a user logs in, their group memberships
will be checked. If the user does not belong to the specified group(s), their username will
be added to the group(s). If a group does not yet exist, it will be added locally.
In Confluence 3.5.2 and later, and JIRA 4.3.3 and later: The first time a user logs in, their
group memberships will be checked. If the user does not belong to the specified group(s),
their username will be added to the group(s). If a group does not yet exist, it will be added
locally. On subsequent logins, the username will not be added automatically to any
groups. This change in behavior allows users to be removed from automatically-added
groups. In Confluence 3.5 and 3.5.1, they would be re-added upon next login.
Please note that there is no validation of the group names. If you mis-type the group
name, authorization failures will result users will not be able to access the applications or
functionality based on the intended group name.
Examples:
confluence-users
confluence-users,jira-administrators,jira-core-users
Advanced Settings
Setting Description
Enable Nested Enable or disable support for nested groups. Some directory servers allow you to define
Groups a group as a member of another group. Groups in such a structure are called nested
groups. Nested groups simplify permissions by allowing sub-groups to inherit
permissions from a parent group.
Manage User If true, you can activate and deactivate users in Crowd independent of their status in the
Status Locally directory server.
Filter out If true, user accounts marked as expired in ActiveDirectory will be automatically
expired users removed. For cached directories, the removal of a user will occur during the first
synchronization after the account's expiration date.
Note: This is available in Embedded Crowd 2.0.0 and above, but not available in the
2.0.0 m04 release.
Use Paged Enable or disable the use of the LDAP control extension for simple paging of search
Results results. If paging is enabled, the search will retrieve sets of data rather than all of the
search results at once. Enter the desired page size that is, the maximum number of
search results to be returned per page when paged results are enabled. The default is
1000 results.
Follow Choose whether to allow the directory server to redirect requests to other servers. This
Referrals option uses the node referral (JNDI lookup java.naming.referral) configuration
setting. It is generally needed for Active Directory servers configured without proper
DNS, to prevent a 'javax.naming.PartialResultException: Unprocessed Continuation
Reference(s)' error.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 448
Naive DN If your directory server will always return a consistent string representation of a DN, you
Matching can enable naive DN matching. Using naive DN matching will result in a significant
performance improvement, so we recommend enabling it where possible.
This setting determines how your application will compare DNs to determine if they are
equal.
If this checkbox is selected, the application will do a direct, case-insensitive, string
comparison. This is the default and recommended setting for Active Directory,
because Active Directory guarantees the format of DNs.
If this checkbox is not selected, the application will parse the DN and then check the
parsed version.
Enable Enable incremental synchronization if you only want changes since the last
Incremental synchronization to be queried when synchronizing a directory.
Synchronization
Please be aware that when using this option, the user account configured for
synchronization must have read access to:
The uSNChanged attribute of all users and groups in the directory that need to be
synchronized.
The objects and attributes in the Active Directory deleted objects container.
If at least one of these conditions is not met, you may end up with users who are added
to (or deleted from) the Active Directory not being respectively added (or deleted) in the
application.
This setting is only available if the directory type is set to "Microsoft Active Directory".
Synchronization Synchronization is the process by which the application updates its internal store of user
Interval data to agree with the data on the directory server. The application will send a request
(minutes) to your directory server every x minutes, where 'x' is the number specified here. The
default value is 60 minutes.
Read Timeout The time, in seconds, to wait for a response to be received. If there is no response
(seconds) within the specified time period, the read attempt will be aborted. A value of 0 (zero)
means there is no limit. The default value is 120 seconds.
Search Timeout The time, in seconds, to wait for a response from a search operation. A value of 0 (zero)
(seconds) means there is no limit. The default value is 60 seconds.
Setting Description
User This is the name of the class used for the LDAP user object. Example:
Object
Class user
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 449
User The attribute field to use when loading the username. Examples:
Name
Attribute cn
sAMAccountName
NB: In Active Directory, the 'sAMAccountName' is the 'User Logon Name (pre-Windows 2000)'
field. The User Logon Name field is referenced by 'cn'.
User The RDN (relative distinguished name) to use when loading the username. The DN for each
Name LDAP entry is composed of two parts: the RDN and the location within the LDAP directory
RDN where the record resides. The RDN is the portion of your DN that is not related to the directory
Attribute tree structure. Example:
cn
User First The attribute field to use when loading the user's first name. Example:
Name
Attribute givenName
User Last The attribute field to use when loading the user's last name. Example:
Name
Attribute sn
User The attribute field to use when loading the user's full name. Example:
Display
Name displayName
Attribute
User The attribute field to use when loading the user's email address. Example:
Email
Attribute mail
User The attribute field to use when loading a user's password. Example:
Password
Attribute unicodePwd
User The attribute used as a unique immutable identifier for user objects. This is used to track
Unique I username changes and is optional. If this attribute is not set (or is set to an invalid value), user
D renames will not be detected they will be interpreted as a user deletion then a new user
Attribute addition.
This should normally point to a UUID value. Standards-compliant LDAP servers will implement
this as 'entryUUID' according to RFC 4530. This setting exists because it is known under
different names on some servers, e.g. 'objectGUID' in Microsoft Active Directory.
Setting Description
Group Object Class This is the name of the class used for the LDAP group object. Examples:
groupOfUniqueNames
group
Group Object Filter The filter to use when searching group objects. Example:
(&(objectClass=group)(cn=*))
Group Name Attribute The attribute field to use when loading the group's name. Example:
cn
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 450
Group Description Attribute The attribute field to use when loading the group's description. Example:
description
Setting Description
Group Members Attribute The attribute field to use when loading the group's members. Example:
member
User Membership Attribute The attribute field to use when loading the user's groups. Example:
memberOf
Use the User Membership Check this if your directory server supports the group membership attribute
Attribute, when finding the on the user. (By default, this is the 'memberOf' attribute.)
user's group membership
If this checkbox is selected, your application will use the group
membership attribute on the user when retrieving the list of groups to
which a given user belongs. This will result in a more efficient retrieval.
If this checkbox is not selected, your application will use the members
attribute on the group ('member' by default) for the search.
If the Enable Nested Groups checkbox is seleced, your application will
ignore the Use the User Membership Attribute option and will use the
members attribute on the group for the search.
Use the User Membership Check this if your directory server supports the user membership attribute on
Attribute, when finding the the group. (By default, this is the 'member' attribute.)
members of a group
If this checkbox is selected, your application will use the group
membership attribute on the user when retrieving the members of a
given group. This will result in a more efficient search.
If this checkbox is not selected, your application will use the members
attribute on the group ('member' by default) for the search.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 451
Diagram above: Confluence connecting to an LDAP directory with permissions set to read only and local
groups.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 452
Initial Pool The number of LDAP connections created when initially connecting to the pool. 1
Size
Preferred The optimal pool size. LDAP will remove idle connections when the number of 10
Pool Size connections grows larger than this value. A value of 0 (zero) means that there is
no preferred size, so the number of idle connections is unlimited.
Pool Timeout The length of time, in seconds, that a connection may remain idle before being 30
(seconds) removed from the pool. When the application is finished with a pooled
connection, the connection is marked as idle, waiting to be reused. A value of 0
(zero) means that the idle time is unlimited, so connections will never be timed
out.
Pool Protocol Only these protocol types will be allowed to connect to the LDAP directory plain
server. If you want to allow multiple protocols, enter the values separated by a ssl
space. Valid values are: (Both
plain
plain
and ssl)
ssl
Pool Only these authentication types will be allowed to connect to the LDAP directory simple
Authentication server. If you want to allow multiple authentication types, enter the values
separated by a space. See RFC 2829 for details of LDAP authentication
methods. Valid values are:
none
simple
DIGEST-MD5
Notes:
The connection pool settings are system wide and will be used to create a new connection pool for
every configured LDAP directory server.
You must restart your application server for these settings to take effect.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 453
server, onto your Confluence server and then install On this page:
the certificate into your JVM keystore.
Prerequisites
Step 1. Install the Active Directory
Certificate Services
Step 2. Obtain the Server
Certificate
Step 3. Import the Server
Certificate
Related pages:
Connecting to an LDAP Directory
Configuring User Directories
Updating user, group, and membership details in Active Directory requires that your Atlassian application be
running in a JVM that trusts the AD server. To do this, we generate a certificate on the Active Directory
server, then import it into Java's keystore.
Prerequisites
To generate a certificate, you need the following components installed on the Windows Domain Controller to
which you're connecting.
Internet Information Services This is required before you can install Windows Certificate Services.
(IIS)
Windows Certificate Services This installs a certification authority (CA) which is used to issue
certificates. Step 1, below, explains this process.
Windows 2000 Service Pack Required if you are using Windows 2000
2
Windows 2000 High Required if you are using Windows 2000. Provides the highest available
Encryption Pack (128-bit) encryption level (128-bit).
If Certificate Services are already installed, skip to step 2, below. The screenshots below are from Server
2008, but the process is similar for Server 2000 and 2003.
1. Log in to your Active Directory server as an administrator.
2. Click Start, point to Administrative Tools, and then click Server Manager.
3. In the Roles Summary section, click Add Roles.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 454
4. On the Select Server Roles page, select the Active Directory Certificate Services check box. Click
Next twice.
5. On the Select Role Services page, select the Certification Authority check box, and then click Next
.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
5. 6.4 documentation
Confluence 455
6. On the Specify Setup Type page, click Enterprise, and then click Next.
7. On the Specify CA Type page, click Root CA, and then click Next.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
7. 6.4 documentation 456
8. On the Set Up Private Key and Configure Cryptography for CA pages, you can configure optional
configuration settings, including cryptographic service providers. However, the default values should
be fine. Click Next twice.
9.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 457
9. In the Common name for this CA box, type the common name of the CA, and then click Next.
10. On the Set Validity Period page, accept the default values or specify other storage locations for the
certificate database and the certificate database log, and then click Next.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 458
11. After verifying the information on the Confirm Installation Selections page, click Install.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 459
12. Review the information on the results screen to verify that the installation was successful.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 460
The steps above describe how to install the certification authority (CA) on your Microsoft Active Directory
server. Next, you will need to add the Microsoft Active Directory server's SSL certificate to the list of accepted
certificates used by the JDK that runs your application server.
The Active Directory certificate is automatically generated and placed in root of the C:\ drive, matching a file
format similar to the tree structure of your Active Directory server. For example: c:\ad2008.ad01.atlass
ian.com_ad01.crt.
You can also export the certificate by executing this command on the Active Directory server:
You might still fail to be authenticated using the certificate file above. In this case, Microsoft's LDAP over SSL
(LDAPS) Certificate page might help. Note that you need to:
1. Choose "No, do not export the private key" in step-10 of Exporting the LDAPS Certificate and
Importing for use with AD DS section
2. Choose "DER encoded binary X.509 (.CER)" in step-11 of Exporting the LDAPS Certificate and
Importing for use with AD DS section. This file will be used in the following step.
For an application server to trust your directory's certificate, the certificate must be imported into your Java
runtime environment. The JDK stores trusted certificates in a file called a keystore. The default keystore file
is called cacerts and it lives in the jre\lib\security sub-directory of your Java installation.
In the following examples, we use server-certificate.crt to represent the certificate file exported by
your directory server. You will need to alter the instructions below to match the name actually generated.
Once the certificate has been imported as per the below instructions, you will need to restart the application
to pick up the changes.
Windows
1. Navigate to the directory in which Java is installed. It's probably called something like C:\Program
Files\Java\jdk1.5.0_12.
cd /d C:\Program Files\Java\jdk1.5.0_12
2. Run the command below, where server-certificate.crt is the name of the file from your
directory server:
3. keytool will prompt you for a password. The default keystore password is changeit.
4. When prompted Trust this certificate? [no]: enter yes to confirm the key import:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 461
You may now change 'URL' to use LDAP over SSL (i.e. ldaps://<HOSTNAME>:636/) and use the 'Secure
SSL' option when connecting your application to your directory server.
UNIX
1. Navigate to the directory in which the Java used by JIRA is installed. If the default JAVA installation is
used, then it would be
cd $JAVA_HOME
2. Run the command below, where server-certificate.crt is the name of the file from your
directory server:
3. keytool will prompt you for a password. The default keystore password is changeit.
4. When prompted Trust this certificate? [no]: enter yes to confirm the key import:
Password:
Enter keystore password: changeit
Owner: CN=ad01, C=US
Issuer: CN=ad01, C=US
Serial number: 15563d6677a4e9e4582d8a84be683f9
Valid from: Tue Aug 21 01:10:46 ACT 2007 until: Tue Aug 21
01:13:59 ACT 2012
Certificate fingerprints:
MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE
SHA1:
73:73:4E:A6:A0:D1:4E:F4:F3:CD:CE:BE:96:80:35:D2:B4:7C:79:C1
Trust this certificate? [no]: yes
Certificate was added to keystore
You may now change 'URL' to use LDAP over SSL (i.e. ldaps://<HOSTNAME>:636/) and use the 'Secure
SSL' option when connecting your application to your directory server.
Mac OS X
1. Navigate to the directory in which Java is installed. This is usually
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
1.
Confluence 6.4 documentation 462
cd /Library/Java/Home
2. Run the command below, where server-certificate.crt is the name of the file from your
directory server:
3. keytool will prompt you for a password. The default keystore password is changeit.
4. When prompted Trust this certificate? [no]: enter yes to confirm the key import:
Password:
Enter keystore password: changeit
Owner: CN=ad01, C=US
Issuer: CN=ad01, C=US
Serial number: 15563d6677a4e9e4582d8a84be683f9
Valid from: Tue Aug 21 01:10:46 ACT 2007 until: Tue Aug 21
01:13:59 ACT 2012
Certificate fingerprints:
MD5: D6:56:F0:23:16:E3:62:2C:6F:8A:0A:37:30:A1:84:BE
SHA1:
73:73:4E:A6:A0:D1:4E:F4:F3:CD:CE:BE:96:80:35:D2:B4:7C:79:C1
Trust this certificate? [no]: yes
Certificate was added to keystore
You may now change 'URL' to use LDAP over SSL (i.e. ldaps://<HOSTNAME>:636/) and use the 'Secure
SSL' option when connecting your application to your directory server.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 463
Server Settings
Setting Description
Name A descriptive name that will help you to identify the directory. Examples:
Internal directory with LDAP Authentication
Corporate LDAP for Authentication Only
Directory Select the type of LDAP directory that you will connect to. If you are adding a new LDAP
Type connection, the value you select here will determine the default values for some of the options
on the rest of screen. Examples:
Microsoft Active Directory
OpenDS
And more.
Use SSL Check this box if the connection to the directory server is an SSL (Secure Sockets Layer)
connection. Note that you will need to configure an SSL certificate in order to use this setting.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 464
Username The distinguished name of the user that the application will use when connecting to the
directory server. Examples:
cn=administrator,cn=users,dc=ad,dc=example,dc=com
cn=user,dc=domain,dc=name
user@domain.name
Setting Description
Copy User This option affects what will happen when a user attempts to log in. If this box is checked,
on Login the user will be created automatically in the internal directory that is using LDAP for
authentication when the user first logs in and their details will be synchronized on each
subsequent log in. If this box is not checked, the user's login will fail if the user wasn't
already manually created in the directory.
If you check this box the following additional fields will appear on the screen, which are
described in more detail below:
Default Group Memberships
Synchronize Group Memberships
User Schema Settings (described in a separate section below)
Default This field appears if you check the Copy User on Login box. If you would like users to be
Group automatically added to a group or groups, enter the group name(s) here. To specify more
Memberships than one group, separate the group names with commas. Each time a user logs in, their
group memberships will be checked. If the user does not belong to the specified group(s),
their username will be added to the group(s). If a group does not yet exist, it will be added
to the internal directory that is using LDAP for authentication.
Please note that there is no validation of the group names. If you mis-type the group
name, authorization failures will result users will not be able to access the applications or
functionality based on the intended group name.
Examples:
confluence-users
bamboo-users,jira-administrators,jira-core-users
Synchronize This field appears if you select the Copy User on Login checkbox. If this box is checked,
Group group memberships specified on your LDAP server will be synchronized with the internal
Memberships directory each time the user logs in.
If you check this box the following additional fields will appear on the screen, both
described in more detail below:
Group Schema Settings (described in a separate section below)
Membership Schema Settings (described in a separate section below)
Note: 'Copy Users on Login' must be enabled if you want to be able to change usernames.
Schema Settings
Setting Description
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 465
Base The root distinguished name (DN) to use when running queries against the directory server.
DN Examples:
o=example,c=com
cn=users,dc=ad,dc=example,dc=com
For Microsoft Active Directory, specify the base DN in the following format: dc=domain1,dc
=local. You will need to replace the domain1 and local for your specific configuration.
Microsoft Server provides a tool called ldp.exe which is useful for finding out and
configuring the the LDAP structure of your server.
User The attribute field to use when loading the username. Examples:
Name
Attribute cn
sAMAccountName
Advanced Settings
Setting Description
Enable Enable or disable support for nested groups. Some directory servers allow you to define a
Nested group as a member of another group. Groups in such a structure are called nested groups.
Groups Nested groups simplify permissions by allowing sub-groups to inherit permissions from a
parent group.
Use Enable or disable the use of the LDAP control extension for simple paging of search results. If
Paged paging is enabled, the search will retrieve sets of data rather than all of the search results at
Results once. Enter the desired page size that is, the maximum number of search results to be
returned per page when paged results are enabled. The default is 1000 results.
Follow Choose whether to allow the directory server to redirect requests to other servers. This option
Referrals uses the node referral (JNDI lookup java.naming.referral) configuration setting. It is
generally needed for Active Directory servers configured without proper DNS, to prevent a
'javax.naming.PartialResultException: Unprocessed Continuation Reference(s)' error.
Note: this section is only visible when Copy User on Login is enabled.
Setting Description
Additional This value is used in addition to the base DN when searching and loading users. If no value is
User DN supplied, the subtree search will start from the base DN. Example:
ou=Users
User This is the name of the class used for the LDAP user object. Example:
Object
Class user
User The RDN (relative distinguished name) to use when loading the username. The DN for each
Name LDAP entry is composed of two parts: the RDN and the location within the LDAP directory
RDN where the record resides. The RDN is the portion of your DN that is not related to the directory
Attribute tree structure. Example:
cn
User First The attribute field to use when loading the user's first name. Example:
Name
Attribute givenName
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 466
User Last The attribute field to use when loading the user's last name. Example:
Name
Attribute sn
User The attribute field to use when loading the user's full name. Example:
Display
Name displayName
Attribute
User The attribute field to use when loading the user's email address. Example:
Email
Attribute mail
Note: this section is only visible when both Copy User on Login and Synchronize Group Memberships ar
e enabled.
Setting Description
Additional This value is used in addition to the base DN when searching and loading groups. If no
Group DN value is supplied, the subtree search will start from the base DN. Example:
ou=Groups
Group Object This is the name of the class used for the LDAP group object. Examples:
Class
groupOfUniqueNames
group
Group Object The filter to use when searching group objects. Example:
Filter
(objectCategory=Group)
Group Name The attribute field to use when loading the group's name. Example:
Attribute
cn
Group The attribute field to use when loading the group's description. Example:
Description
Attribute description
Note: this section is only visible when both Copy User on Login and Synchronize Group Memberships ar
e enabled.
Setting Description
Group Members Attribute The attribute field to use when loading the group's members. Example:
member
User Membership Attribute The attribute field to use when loading the user's groups. Example:
memberOf
Use the User Membership Check this box if your directory server supports the group membership
Attribute, when finding the attribute on the user. (By default, this is the 'memberOf' attribute.)
user's group membership
If this box is checked, your application will use the group membership
attribute on the user when retrieving the members of a given group
. This will result in a more efficient retrieval.
If this box is not checked, your application will use the members
attribute on the group ('member' by default) for the search.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 467
Diagram above: Confluence connecting to an LDAP directory for authentication only, with each user
synchronized with the internal directory that is using LDAP authentication when they log in to Confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 468
1. Go to your Crowd Administration Console and define the Confluence application to Crowd. See the
Crowd documentation: Adding an Application.
2. Choose the cog icon
Setting Description
Name A meaningful name that will help you to identify this Crowd server amongst your list of
directory servers. Examples:
Crowd Server
Example Company Crowd
Application The name of your application, as recognized by your Crowd server. Note that you will need to
Name define the application in Crowd too, using the Crowd administration Console. See the Crowd
documentation on adding an application.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 469
Application The password which the application will use when it authenticates against the Crowd
Password framework as a client. This must be the same as the password you have registered in Crowd
for this application. See the Crowd documentation on adding an application.
Note: There is a known issue where the password is not saved in some instances
CONFSERVER-33979 - New JIRA/Crowd password not saved after test
OPEN when configuring
Confluence to use JIRA/Crowd as a external user directory.
Crowd Permissions
Setting Description
Read Only The users, groups and memberships in this directory are retrieved from Crowd and can only
be modified via Crowd. You cannot modify Crowd users, groups or memberships via the
application administration screens.
Read/Write The users, groups and memberships in this directory are retrieved from Crowd. When you
modify a user, group or membership via the application administration screens, the changes
will be applied directly to Crowd. Please ensure that the application has modification
permissions for the relevant directories in Crowd. See the Crowd documentation: Specifying
an Application's Directory Permissions.
Setting Description
Enable Nested Enable or disable support for nested groups. Before enabling nested groups, please
Groups check to see if the user directory or directories in Crowd support nested groups. When
nested groups are enabled, you can define a group as a member of another group. If
you are using groups to manage permissions, you can create nested groups to allow
inheritance of permissions from one group to its sub-groups.
Enable Enable or disable incremental synchronization. Only changes since the last
Incremental synchronization will be retrieved when synchronizing a directory. Note that full
Synchronization synchronization is always executed when restarting FishEye.
Synchronization Synchronization is the process by which the application updates its internal store of user
Interval data to agree with the data on the directory server. The application will send a request
(minutes) to your directory server every x minutes, where 'x' is the number specified here. The
default value is 60 minutes.
Note that the license tiers for your JIRA application and Confluence do not need to match to use this
feature. For example, you can manage a Confluence 50 user license with JIRA Software, even if
JIRA Software only has a 25 user license.
Subject to certain limitations, you can connect a number of Atlassian applications to a single JIRA application
for centralized user management.
When to use this option: You can connect to a server running JIRA 4.3 or later, JIRA Software 7.0 or later,
JIRA Core 7.0 or later, or JIRA Service Desk 3.0 or later. Choose this option as an alternative to Atlassian
Crowd, for simple configurations with a limited number of users.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 470
3. In order to use Confluence, users must be a member of the confluence-users group or have
Confluence 'can use' permission. Follow these steps to configure your Confluence groups in your JIRA
application:
a. Add the confluence-users and confluence-administrators groups in your JIRA
application.
b. Add your own username as a member of both of the above groups.
c. Choose one of the following methods to give your existing JIRA users access to Confluence:
Option 1: In your JIRA application, find the groups that the relevant users belong to. Add
the groups as members of one or both of the above Confluence groups.
Option 2: Log in to Confluence using your JIRA account and go to the Confluence Admi
nistration Console. Click 'Global Permissions' and assign the 'can use' permission to
the relevant JIRA groups.
4. In Confluence you can now define the directory order by clicking the blue up- and down-arrows next
to each directory on the 'User Directories' screen. Here is a summary of how the directory order
affects the processing:
The order of the directories is the order in which they will be searched for users and groups.
Changes to users and groups will be made only in the first directory where the application has
permission to make changes.
For details see Managing Multiple Directories.
Ensure that you have added Confluence URL into JIRA Whitelist in JIRA Administration >>
System >> Security >> Whitelist. For example: https://confluence.atlassian.com/ or refer to
this guide: Configuring the whitelist.
Setting Description
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 471
Name A meaningful name that will help you to identify this JIRA server in the list of directory
servers. Examples:
JIRA Service Desk Server
My Company JIRA
Application The name used by your application when accessing the JIRA server that acts as user
Name manager. Note that you will also need to define your application to that JIRA server, via the '
Other Applications' option in the 'Users, Groups & Roles' section of the 'Administration'
menu.
Application The password used by your application when accessing the JIRA server that acts as user
Password manager.
JIRA Permissions
Setting Description
Read The users, groups and memberships in this directory are retrieved from the JIRA server that is
Only acting as user manager. They can only be modified via that JIRA server.
Setting Description
Enable Nested Enable or disable support for nested groups. Before enabling nested groups, please
Groups check to see if nested groups are enabled on the JIRA server that is acting as user
manager. When nested groups are enabled, you can define a group as a member of
another group. If you are using groups to manage permissions, you can create nested
groups to allow inheritance of permissions from one group to its sub-groups.
Synchronization Synchronization is the process by which the application updates its internal store of user
Interval data to agree with the data on the directory server. The application will send a request to
(minutes) your directory server every x minutes, where 'x' is the number specified here. The default
value is 60 minutes.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 472
Diagram above: Confluence, JIRA and other applications connecting to Crowd for user management.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 473
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 474
Diagram above: Confluence connecting to JIRA for user management, with JIRA in turn connecting to LDAP.
Troubleshooting
Below are some error messages you may encounter. If you run into problems, you should turn on WARN
logging for the relevant class. See Configuring Logging.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 475
error.jirabaseurl.not.valid This is not a valid url for a A runtime exception has occured.
JIRA application. Refer to the Confluence log files for
further troubleshooting information.
Use this option if you have only a few users and groups.
1. Log in to Confluence as a Confluence system administrator.
2. Go to the user directories administration screen and move the internal directory to the top of the list of
directories, by clicking the arrows in the 'Order' column.
3. Make sure that you have at least one user from the internal directory in each of the confluence-us
ers and confluence-administrators groups.
4. Make sure that you have a username in the internal directory with Confluence system administrator
permissions.
If you do not have such a user, add a new one now, and log out of Confluence.
Log back in as the user you just added, and go back to the user directories administration
screen.
5. Disable the 'Atlassian Crowd' directory.
6. Manually add the required users and groups in Confluence. They will be added to the internal
directory, because you have moved it to the top of the list of directories.
If you have assigned Confluence permissions to a group which exists in your JIRA application,
you must create a group in Confluence with the same name.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
6.
Confluence 6.4 documentation 476
If a user who exists in your JIRA application has created content or has had permissions
assigned to them in Confluence, you must also create that user in Confluence.
7. Add the users to the required groups.
Option 2 Transfer Crowd/JIRA application Users and Groups to the Confluence Database
Use this option to migrate External Application (Crowd or JIRA applications) users into the Confluence
database. You need a knowledge of SQL to perform this task.
The SQL commands given below are tailored for MySQL. If you are using a database other than MySQL,
you will need to modify the SQL to work in your database.
Creating backups is the only way to restore your data if something goes wrong.
1. From Confluence, create a full XML site backup including attachments.
2. Stop Confluence.
3. Make a backup copy of the Confluence home and installation directories.
4. Repeat the above steps for your External Application.
5. From your MySQL administration tool, create a database backup for the Crowd/JIRA application and
Confluence databases.
Use the SQL below to move groups and users from your External Application to Confluence by transferring
table content. The SQL provided is specific to MySQL and must be modifed for other databases.
Find the IDs for your Directories
1. Run the following command and take note of the resulting number. It will be referenced throughout the
following instructions as <Confluence Internal ID>.
2. From the User Directories administration page, find the name of the directory who's users/groups you
want to move. Run the following command and take note of the resulting number. It will be referenced
throughout the following instructions as <External Application ID>.
a. If you have results from the previous query, for each of the group names that have duplicates,
find the id for the group in the Confluence Internal Directory (<internal group id>) and the
External Application (<external group id>). Run the following:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 477
2. Move all the groups in the External Application to the Confluence Internal Directory.
a. If you have results from the previous query, for each of the user names that have duplicates,
find the id for the user in the Confluence Internal Directory (<internal user id>) and the External
Application (<external user id>). Run the following:
2. Move all the users in the External Application to the Confluence Internal Directory.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 478
b. If you have more than two directories, you need to rearrange them so the Internal Directory is at
the top (list_index 0) and the External Application directory you are deleting is at the bottom.
List the directories and their order using
Change the list indexes so that they are in the order you want. Directory order can be
rearranged using
2. When the directories are ordered correctly, delete the External Application directory from the directory
order:
3. The External Application directory is referenced in several other tables in the database. You need to
remove the remaining references to it:
4. All references to the External Directory should now have been removed. Delete the directory using:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
4. 6.4 documentation
Confluence 479
Reset passwords
1. All users who were in the External Directory you deleted, including admins, will be unable to log in.
Their passwords need to be reset by choosing the 'Forgot your password?' link on the login page.
Alternatively, use the instructions at Restore Passwords To Recover Admin User Rights to reset the
administrator password, then set the users' passwords for them via the Manage Users page in the
administration screen.
You can change the order of your directories as defined to Confluence. Select 'User Directories' from the
Confluence Administration Console and click the blue up- and down-arrows next to each directory.
Notes:
Please read the rest of this page to understand what effect the directory order will have on
authentication (login) and permissions in Confluence, and what happens when you update users and
groups in Confluence.
Before you move an external directory above Confluence's internal directory, make sure you (and your
admin users) are members of a group called confluence-administrators in your external
directory or you may accidentally lock yourself out of the Confluence admin console.
This section summarizes the effect the order of the directories will have on login and permissions, and on the
updating of users and groups.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 480
Login
The directory order is significant during the authentication of the user, in cases where the same user exists in
multiple directories. When a user attempts to log in, the application will search the directories in the order
specified, and will use the credentials (password) of the first occurrence of the user to validate the login
attempt.
Permissions
The directory order is not significant when granting the user permissions based on group membership as
Confluence uses an aggregating membership scheme by default. If the same username exists in more than
one directory, the application will aggregate (combine) group membership from all directories where the
username appears.
Example:
You have connected two directories: The Customers directory and the Partners directory.
The Customers directory is first in the directory order.
A username jsmith exists in both the Customers directory and the Partners directory.
The user jsmith is a member of group G1 in the Customers directory and group G2 in the Partners
directory.
The user jsmith will have permissions based on membership of both G1 and G2 regardless of the
directory order.
For administrators upgrading to Confluence 5.7 or later:
How group memberships are determined for users that belong to multiple user directories (such as LDAP,
Active Directory, Crowd) changed in Confluence 5.7. Group memberships are now aggregated from all direct
ories, not the first one the user appears in. In most cases, this change will have no impact as users generally
only exist in one directory, or their memberships are correctly synchronized between user directories. In
some rare cases, where group memberships are out of synch, the change may lead to users gaining
permissions to view spaces and pages (if they are a member a group in a user directory that was previously
being ignored by Confluence).
Here's an example scenario...
This is Issac. Something went wrong a while ago, so he's got the same username in two user
directories, but belongs to different groups.
Right now, the user directories in his organization's Confluence site look like this:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 481
This means after the 5.7 upgrade he can see any pages and spaces that are restricted to the 'developers'
group.
Non-aggregating membership
It is possible to use the REST API to tell Confluence to use a non-aggregating membership scheme as
follows:
Turning on non-aggregating membership...
The REST resource supported JSON and XML. You'll need to be a system administrator and logged in to
do this.
If you've chosen non-aggregating membership, the directory order is significant. If the same username exists
in more than one directory, the application will look for group membership only in the first directory where the
username appears, based on the directory order.
Example:
You have connected two directories: The Customers directory and the Partners directory.
The Customers directory is first in the directory order.
A username jsmith exists in both the Customers directory and the Partners directory.
The user jsmith is a member of group G1 in the Customers directory and group G2 in the Partners
directory.
The user jsmith will have permissions based on membership of G1 only, not G2.
If you update a user or group via the application's administration screens, the update will be made in the first
directory where the application has write permissions.
Example 1:
You have connected two directories: The Customers directory and the Partners directory.
The application has permission to update both directories.
The Customers directory is first in the directory order.
A username jsmith exists in both the Customers directory and the Partners directory.
You update the email address of user jsmith via the application's administration screens.
The email address will be updated in the Customers directory only, not the Partners directory.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 482
Example 2:
You have connected two directories: A read/write LDAP directory and the internal directory.
The LDAP directory is first in the directory order.
All new users will be added to the LDAP directory. It is not possible to add a new user to the internal
directory.
RELATED TOPICS
Configuring User Directories
Configuring the Internal Directory
Connecting to an LDAP Directory
Connecting to an Internal Directory with LDAP Authentication
Connecting to Crowd or JIRA for User Management
Managing Multiple Directories
Managing Nested Groups
Synchronizing Data from External Directories
Diagrams of Possible Configurations for User Management
User Management Limitations and Recommendations
Requesting Support for External User Management
Disabling the Built-In User Management
This section explains how nested groups affect logging in, permissions, and viewing and updating users and
groups.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 483
Login
When a user logs in, they can access the application if they belong to an authorized group or any of its
sub-groups.
Permissions
The user can access a function if they belong to a group that has the necessary permissions, or if they
belong to any of its sub-groups.
If you ask to view the members of a group, you will see all users who are members of the group and all users
belonging its sub-groups, consolidated into one list. We call this a flattened list.
You can't view or edit the nested groups themselves, or see that one group is a member of another group.
If you add a user to a group, the user is added to the named group and not to any other groups.
If you try to remove a user from a flattened list, the following will happen:
If the user is a member of the top group in the hierarchy of groups in the flattened list, the user is
removed from the top group.
Otherwise, you see an error message stating that the user is not a direct member of the group.
Examples
In an LDAP directory server, we have the groups engineering-group and techwriters-group. We want to
grant both groups developer-level access to the JIRA. We will have a group called jira-developers that has
developer-level access.
Add a group called jira-developers.
Add the engineering-group as a sub-group of jira-developers.
Add the techwriters-group as a sub-group of jira-developers.
Group memberships are now:
jira-developers sub-groups: engineering-group, techwriters-group
engineering-group sub-groups: dev-a, dev-b; users: pblack
dev-a users: jsmith, sbrown
dev-b users: jsmith, dblue
techwriters-group users: rgreen
When the JIRA application requests a list of users in the jira-developers group, it receives the following list:
pblack
jsmith
sbrown
dblue
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 484
rgreen
Notes
Possible impact on performance. Enabling nested groups may result in slower user searches.
Definition of nested groups in LDAP. In an LDAP directory, a nested group is a child group entry
whose DN (Distinguished Name) is referenced by an attribute contained within a parent group entry.
For example, a parent group Group One might have an objectClass=group attribute and one or
more member=DN attributes, where the DN can be that of a user or that of a group elsewhere in the
LDAP tree:
member=CN=John Smith,OU=Users,OU=OrgUnitA,DC=sub,DC=domain
member=CN=Group
Two,OU=OrgUnitBGroups,OU=OrgUnitB,DC=sub,DC=domain
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 485
On this page:
Affected Directory Types
How it Works
Finding the Time Taken to
Synchronize
Manually Synchronizing the Cache
Configuring the Synchronization
Interval
Related pages:
Configuring User Directories
Data caching and synchronization apply to the following user directory types:
LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to re
ad only.
LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to re
ad only, with local groups.
LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to re
ad/write.
Atlassian Crowd.
Atlassian JIRA.
Data caching and synchronization do not occur for the following user directory types:
Internal Directory with LDAP Authentication.
Internal Directory.
How it Works
The 'User Directories' screen shows information about the last synchronization operation, including the
length of time it took.
You can manually synchronize the cache by clicking 'Synchronize' on the 'User Directories' screen. If a
synchronization operation is already in progress, you cannot start another until the first has finished.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 486
Note: The option to configure the synchronization interval for Crowd and JIRA directories is available in Confl
uence 3.5.3 and later. Earlier versions of Confluence allow you to configure the interval for LDAP directories
only.
You can set the 'Synchronization Interval' on the directory configuration screen. The synchronization
interval is the period of time to wait between requests for updates from the directory server.
The length you choose for your synchronization interval depends on:
The length of time you can tolerate stale data.
The amount of load you want to put on the application and the directory server.
The size of your user base.
If you synchronize more frequently, then your data will be more up to date. The downside of synchronizing
more frequently is that you may overload your server with requests.
If you are not sure what to do, we recommend that you start with an interval of 60 minutes (this is the default
setting) and reduce the value incrementally. You will need to experiment with your setup.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 487
Diagram above: Confluence using its internal directory for user management.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 488
Diagram above: Confluence connecting to an LDAP directory with permissions set to read only and local
groups.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 489
Diagram above: Confluence connecting to an LDAP directory for authentication only, with each user
synchronized with the internal directory that is using LDAP authentication when they log in to Confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 490
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 491
Diagram above: Confluence connecting to JIRA for user management, with JIRA in turn connecting to LDAP.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 492
Diagram above: Confluence, JIRA and other applications connecting to Crowd for user management.
General Recommendations
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 493
Please consider the following limitations and recommendations when connecting to an LDAP user directory.
The connection to your LDAP directory provides powerful and flexible support for connecting to, configuring
and managing LDAP directory servers. To achieve optimal performance, a background synchronization task
loads the required users and groups from the LDAP server into the application's database, and periodically
fetches updates from the LDAP server to keep the data in step. The amount of time needed to copy the users
and groups rises with the number of users, groups, and group memberships. For that reason, we
recommended a maximum number of users and groups as described below.
This recommendation affects connections to LDAP directories:
Microsoft Active Directory
All other LDAP directory servers
The following LDAP configurations are not affected:
Internal directories with LDAP authentication
LDAP directories configured for 'Authentication Only, Copy User On First Login'
Please choose one of the following solutions, depending on the number of users, groups and memberships
in your LDAP directory.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 494
Up to 10 000 (ten thousand) Choose the 'LDAP' or 'Microsoft Active Directory' directory type. You
users, 1000 (one thousand) can make use of the full synchronization option. Your application's
groups, and 20 (twenty) groups database will contain all the users and groups that are in your LDAP
per user server.
More than the above Use LDAP filters to reduce the number of users and groups visible to
the synchronization task.
The LDAP connections do not support the configuration of two or more LDAP servers for redundancy
(automated failover if one of the servers goes down).
When the application synchronizes with Active Directory (AD), the synchronization task requests only the
changes from the LDAP server rather than the entire user base. This optimizes the synchronization process
and gives much faster performance on the second and subsequent requests.
On the other hand, this synchronization method results in a few limitations:
1. Externally moving objects out of scope or renaming objects causes problems in AD. If you
move objects out of scope in AD, this will result in an inconsistent cache. We recommend that you do
not use the external LDAP directory interface to move objects out of the scope of the sub-tree, as
defined on the application's directory configuration screen. If you do need to make structural changes
to your LDAP directory, manually synchronize the directory cache after you have made the changes to
ensure cache consistency.
2. Synchronizing between AD servers is not supported. Microsoft Active Directory does not replicate
the uSNChanged attribute across instances. For that reason, we do not support connecting to different
AD servers for synchronization. (You can of course define multiple different directories, each pointing
to its own respective AD server.)
3. Synchronizing with AD servers behind a load balancer is not supported. As with synchronizing
between two different AD servers, Microsoft Active Directory does not replicate the uSNChanged
attribute across instances. For that reason, we do not support connecting to different AD servers even
when they are load balanced. You will need to select one server (preferably one that is local) to
synchronize with instead of using the load balancer.
4. You must restart the application after restoring AD from backup. On restoring from backup of an
AD server, the uSNChanged timestamps are reverted to the backup time. To avoid the resulting
confusion, you will need to flush the directory cache after a Active Directory restore operation.
5. Obtaining AD object deletions requires administrator access. Active Directory stores deleted
objects in a special container called cn=Deleted Objects. By default, to access this container you need
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 495
to connect as an administrator and so, for the synchronization task to be aware of deletions, you must
use administrator credentials. Alternatively, it is possible to change the permissions on the cn=Deleted
Objects container. If you wish to do so, please see this Microsoft KB article.
6. The User DN used to connect to AD must be able to see the uSNChanged attribute. The
synchronization task relies on the uSNChanged attribute to detect changes, and so must be in the
appropriate AD security groups to see this attribute for all LDAP objects in the subtree.
Please consider the following limitations and recommendations when connecting to a JIRA server for user
management.
When you connect to a JIRA application for user management, you will not have single sign-on across the
applications connected in this way. JIRA, when acting as a directory manager, does not support SSO.
JIRA applications, Confluence, FishEye, Crucible and Bamboo can connect to a JIRA server for user
management. Custom application connectors will need to use the new REST API.
Earlier versions of JIRA supported OSUser Providers. It was therefore possible write a special provider to
obtain user information from any external user directory. This is no longer the case.
If your JIRA instance is already under high load, then using it as a User Server will increase that load.
You cannot use JIRA Cloud applications to manage standalone users. Cloud users and users within your
self-hosted Atlassian applications need to be managed separately.
Recommendations
If all the following are true: Your environment meets the optimal requirements for
using a JIRA application for user management.
Your JIRA application is not under high
load.
You want to share user and group
management across just a few applications,
such as one JIRA Software server and one
Confluence server, or two JIRA servers.
You do not need single sign-on (SSO)
between your JIRA application and
Confluence, or between two JIRA servers.
You do not have custom application
connectors. Or, if you do have them, you
are happy to convert them to use the new
REST API.
You are happy to shut down all your servers
when you need to upgrade your JIRA
application.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 496
If one or more of the following are true: We recommend that you install Atlassian Crowd for
user management and SSO.
If your JIRA application is already under
high load.
You want to share user and group
management across more than 5
applications.
You need single sign-on (SSO) across
multiple applications.
You have custom applications integrated via
the Crowd SOAP API, and you cannot
convert them to use the new REST API.
You are not happy to shut down all your
servers when you need to upgrade JIRA.
If you are considering creating a custom Please see if one of the following solutions will work for
directory connector to define your own storage you:
for users and groups...
If you have written a custom provider to support a
specific LDAP schema, please check the supported
LDAP schemas to see if you can use one of them
instead.
If you have written a custom provider to support
nested groups, please consider enabling nested
groups in the supported directory connectors
instead.
If you have written a custom provider to connect to
your own database, please consider loading the
data into the application's database instead.
If you need to keep the custom directory
connection, please consider whether Atlassian
Crowd meets your requirements. See the
documentation on Creating a Custom Directory
Connector.
The configuration screen for external directories in Confluence has a 'Test Settings' button. This will help
you to diagnose problems with user management in Active Directory and other LDAP servers.
To test your directory connection:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 497
1.
Confluence Server
If you have implemented a custom authenticator or in any way modified seraph-config.xml or ser
aph-paths.xml, please provide the modified file.
Diagnostics
###
# Atlassian User
###
#log4j.logger.com.atlassian.user=DEBUG
#log4j.logger.com.atlassian.confluence.user=DEBUG
#log4j.logger.bucket.user=DEBUG
#log4j.logger.com.atlassian.seraph=DEBUG
#log4j.logger.com.opensymphony.user=DEBUG
Remove the '#' signs at the beginning of the lines, so that it looks like this:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 498
###
# Atlassian User
###
log4j.logger.com.atlassian.user=DEBUG
log4j.logger.com.atlassian.confluence.user=DEBUG
log4j.logger.bucket.user=DEBUG
log4j.logger.com.atlassian.seraph=DEBUG
log4j.logger.com.opensymphony.user=DEBUG
After enabling both the above, please attempt a Confluence LDAP account login and attach a copy of
the log files that are produced when the problem occurs. To do this, locate your install directory, then
zip the full /logs directory into a single file for us to examine.The logs directory is located in your
Confluence Home directory.
In some circumstances you may want to disable Confluence's built in user management, and delegate all user
management to an external application, such as JIRA Software or JIRA Service Desk. You can disable internal
user management by turning on Confluence's External User Management setting. You'll need to be a system
administrator to do this.
You might disable Confluence's internal user management:
When Crowd's directory permissions are configured so that Confluence cannot update the Crowd
directories (as a system error will occur when Confluence attempts to write data into Crowd). See Connec
ting to Crowd or JIRA for User Management for more information.
If you are using a JIRA application for user management. This centralizes all user management in that
JIRA app. See Connecting to Crowd or JIRA for User Management.
To disable management of users and groups within Confluence:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 499
SAML single sign-on should work with any identity provider implementing the SAML 2.0 Web Browser SSO
Profile, using the HTTP POST binding.
We currently perform tests with the following identity providers:
Microsoft Active Directory (using ADFS 3.0)
Microsoft Azure Active Directory
OneLogin
Okta
PingIdentity
You'll need to configure your application and your IdP to provide single sign-on for your users.
Set up SSL/TLS
To make sure that SAML authentication is secure and private, you need to set up SSL/TLS in the application.
See Running Confluence Over SSL or HTTPS for more information.
Once set up, you need to make sure that the application's configured base URL is using the HTTPS protocol.
If you want to use a reverse proxy, check out the following guides:
Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http)
Securing your Atlassian applications with Apache using SSL
When using a reverse proxy that terminates SSL/TLS, you need to make sure that the request URL the
application server sees matches the fully-qualified domain name for the reverse proxy. This is usually
achieved by configuring the <Connector> directive with the appropriate proxyName, proxyPort, secure and sc
heme settings. Please check the documentation above for specific examples.
If you want Confluence to provide SSO, you'll need to add it to your IdP. The exact process varies depending
on the IdP, but you'll usually need to:
Define an 'application' in your IdP
Provide some data about the application, including data you can access on your application's Authenti
cation screen
Make sure the NameID attribute of the users in your IdP is set to the username in your Atlassian
application
Give the appropriate users permission to use the application
At the end of the setup process your IdP will provide you with a set of data that you'll need to configure your
Atlassian application.
Setting Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 500
Single This value is provided by your IdP, as part of setting up SAML. It's sometimes also
sign-on called 'Entity ID'
issuer
The issuer is the IdP your application will be accepting authentication requests from
X.509 This value is provided by your IdP, as part of setting up SAML. This is sometimes
Certificate referred to as a 'Signing certificate'. The key usually starts with '-----BEGIN
CERTIFICATE-----'.
This contains the public key we'll use to verify that all received SAML authentication
requests have been issued by your IdP.
Login This defines how your users can use single-sign on. The options are:
mode
Use SAML as secondary authentication the default way to log in will be the
standard application login form. You can log in using SAML if you go to your IdP
and select your application, or by using the this URL to log in: BASE-URL/plugins/
servlet/external-login. We recommended this method so you can test that
everything is configured correctly, and that users can log in using SSO.
Use SAML as primary authentication in this mode, all browser-based users
will be redirected from the application's login screen to the IdP to log in. It's still
possible to authenticate by:
Basic Auth
Form-based auth via dedicated REST endpoint
Existing Remember Me tokens
You should only enable this mode once you've verified that SAML
authentication is working as expected.
Remember When checked, successful user logins will be remembered in the user's browser.
user logins When browsing to their application, users will be logged in automatically without
having to authenticate again using SAML.
Confluence Data Center uses 'remember me' to enable users to move seamlessly
between nodes. Turning Remember user logins off in this screen can override this
Confluence behaviour and lead to users needing to log in again each time they move
to another node. We recommend keeping Remember user logins enabled.
3. The following information is provided on the Authentication screen, and will be required to configure
your IdP:
Assertion Consumer Service This is the URL the IdP will return SAML authentication requests
URL to.
Audience URL (Entity ID) This is the URL the IdP will prepare SAML authentication
requests for.
Best practices
SAML authentication requests are only valid for a limited time. You should make sure the clocks on
the server running your application/s and the IdP are synchronised.
If users and groups in your application are configured using User Directories, you'll usually want to use
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 501
the same LDAP directory to be the source of users for both your IdP and Atlassian application. Users
need to exist in the user directory before they can log in using SSO.
Troubleshooting
If you make a mistake configuring the SAML authentication, or are unable to log in using your IdP, you
can restore login form authentication by using issuing a DELETE request (using a username and
password for an administrator configured in your user directory):
If an authentication error occurs, the user will only see basic details about what went wrong. For
security reasons, the details about the underlying problem are not shown. You'll need to check the
application logs to see the cause of the problem.
In some cases you might also experience errors shown by your IdP. For those you will need to use the
support and tools provided by your IdP, rather than Atlassian support.
When using SAML as primary authentication and you have CAPTCHA enabled in the
application, users that use HTTP basic authentication (for example in REST resource calls) may get
locked out if they enter an incorrect password too many times. In these cases, an administrator will
need to reset the user's CAPTCHA in the user list screen.
Add-ons are managed via the Universal Plugin Manager (known as the UPM). The UPM can be found in most
Atlassian applications, and provides a consistent experience for administering add-ons. To visit the UPM, go to
You can disable or unsubscribe from user installed add-ons that are no longer being used on your site. See Disa
bling and enabling add-ons to find out how to do this.
Once the add-on is disabled, its features are immediately unavailable. If the add-on included macros, pages that
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 502
contained those macros will show an 'unknown macro' error. To avoid this, you can check which macros are
being used on your site before disabling an add-on by checking the macro usage statistics.
Go to
Macro name This is the name of the macro, as it appears in the code.
Visibility This controls who can see this macro in the macro browser or auto-complete. Options
are:
Visible to all users
Visible only to system administrators
Note that if you select Visible only to system administrators, users will still see the
output of the macro on a page, and the macro placeholder will still be visible when a
user edits a page. It is only hidden in the macro browser and autocomplete.
All macro information is discoverable, including the macro title, description, parameter
names and other metadata. Do not include confidential data anywhere in the definition
of a user macro, even if it is marked as visible only to system administrators.
Macro Title This is the title that will appear in the macro browser and auto-complete.
Description This is the description that will appear in the macro browser. The macro browser's
search will pick up matches in both the title and description.
Categories Select one or more macro browser categories for your macro to appear in.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 503
Documentation If you have documentation for your macro, enter the URL here.
URL
Macro Body Specify how Confluence should process the body before passing it to your macro.
Processing
The macro body is the content that is displayed on a Confluence page. If your macro
has a body, any body content that the user enters will be available to the macro in the $
body variable.
Template This is where you write the code that determines what the macro should do.
Use HTML and Confluence-specific XML elements in the macro template.
You can use the Velocity templating language. Here is more information on the
Velocity project.
If your macro has a body, your template can refer to the macro body text by
specifying '$body'.
Each parameter variable you use must have a matching metadata definition. Use @
param to define metadata for your macro parameters.
When using the information passed using parameters, refer to your parameters as
$paramXXX where 'XXX' is the parameter name that you specifed in the @param m
etadata definition.
Use @noparams if your macro does not accept parameters.
See User Macro Template Syntax for more information and examples.
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 504
1. Go to
Best practices
This section contains tips and suggestions for best practices when creating your own user macros.
We recommend that you include a short description as a comment at the top of the Template field as shown
below.
The macro browser is the easiest way for users to configure your macro. You can specify the macro
category, link to an icon, define the parameters that the macro browser will use to prompt the user for
information, and more.
As you can't guarantee that a user has supplied parameters, one of the first things to do in the macro is
check that you have received some value if you expect to rely on it later on in the macro code.
In the example below, the macro expects three parameters, and substitutes sensible defaults if they are not
supplied.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 505
#set($spacekey= $paramspacekey)
#set($numthreads= $paramnumthreads)
#set($numchars= $paramnumchars)
Field Value
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 506
Template Enter the code below in the template field - this example will print the text straight
onto the page.
## @noparams
Hello World!
$body
If you wanted the text to appear in a panel you could include the relevant AUI
message class as shown here.
## @noparams
<div class="aui-message closeable">
Hello World!
$body
</div>
Now you can add the macro to your Confluence page using the Macro Browser, or by typing {hello in the
editor and selecting the macro from the list of suggestions.
NoPrint
This example demonstrates how to create a user macro that can contain text that is visible when viewing
a page, but does not print.
Field Value
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 507
## @noparams
<div class="noprint">$body</div>
Now you can add the macro to your Confluence page using the Macro Browser. Text entered into the
body of the macro placeholder will not be printed, but will appear when the page is viewed online.
Field Value
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 508
Template Enter the code below in the template field. If your macro requires more than one
parameter, you can use variables $param0 to $param9 to represent them.
## @param 0:title=colour|type=string
## @param 1:title=size|type=string
<span style="color: $param0; font-size:
$param1">$body</span>
Alternatively, you can also use explicitly-named parameters in your macro. These
macro parameters will appear as variables with the name $param<x> where <x> is
the name of your parameter.
## @param Colour:title=colour|type=string
## @param Size:title=size|type=string
<span style="color: $paramColour; font-size:
$paramSize">$body</span>
Formatted Panel
This example demonstrates how to write a user macro that creates a panel that is preformatted with
specific colors. It will create a panel that looks like this:
(Title)
Note: The panel's title will be empty if the user does not give a value for the title parameter.
Field Value
Categories Formatting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 509
Template Enter the code below in the template field. See below for a more detailed explanation of the code b
## @param Title:title=Title|type=string|desc=Title
<ac:structured-macro ac:name="panel">
<ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>
<ac:parameter ac:name="borderStyle">solid</ac:parameter>
<ac:parameter ac:name="borderColor">#6699CC</ac:parameter>
<ac:parameter ac:name="borderWidth">2</ac:parameter>
<ac:parameter ac:name="titleColor">#000000</ac:parameter>
<ac:parameter ac:name="title">$!paramTitle</ac:parameter>
<ac:rich-text-body>$body</ac:rich-text-body>
</ac:structured-macro>
Item Description
defines the
description of the
parameter in the
macro browser.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 510
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 511
On this page:
Accessing your macro's body
Accessing your macro's body
Use the $body object within your user macro Using parameters in your user
template to access the content passed to your macro
macro in the macro body. Objects available to your macro
Controlling parameter appearance
The $body object is available if you have specified
in the editor placeholder
that your macro has a body (in other words, if you
have not selected No macro body). Related pages:
Example: Let's assume your macro is called hello Writing User Macros
world.
Enter the following code in your template:
From Matthew
You can specify parameters for your macro, so that users can pass it information to determine its behavior on
a Confluence page.
When adding a macro to a Confluence page, the macro browser will display an input field for each macro
parameter. The field type is determined by the parameter type you specify.
Additional notes:
The order of the parameters in the template determines the order in which the macro browser displays
the parameters.
We recommend that you define the parameters at the top of the template.
There may be additional attributes, depending on the parameter type you specify.
The sections below describe each of the attributes in detail.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 512
(an A unique name for the parameter. The parameter name is the first Required
unnamed, attribute in the list. The name attribute itself does not have a name. See
first the section on name below.
attribute)
title The parameter title will appear in the macro browser. If you do not specify Recommended
a title, Confluence will use the parameter name.
type The field type for the parameter. See the section on type below. Recommended
desc The parameter description will appear in the macro browser. Optional
required Specifies whether the user must enter information for this parameter. Optional
Defaults to false.
multiple Specifies whether the parameter accepts multiple values. Defaults to Optional
false.
Parameter name
The parameter name is the first attribute in the list. The name attribute itself does not have a name.
Example: The following code defines 2 parameters, named 'foo' and 'bar':
## @param foo
## @param bar
Parameter type
The field type for the parameter. If you do not specify a type, the default is string.
boolean Displays a checkbox to the user and passes the value 'true' or 'false' to the macro as a string.
enum Offers a list of values for selection. You can specify the values to appear in a dropdown in the macro
browser. Example of specifying the enum values:
## @param
colour:title=Colour|type=enum|enumValues=Grey,Red,Yellow,Green
Note about i18n: Confluence does not support internationalization of the enum values.The value the
user sees is the one passed to the macro as the parameter value, with the capitalization given. In th
case 'Grey', 'Red', etc.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 513
string A text field. This is the default type. Example with a required field:
## @param
status:title=Status|type=string|required=true|desc=Status to
display
confluence-content Offers a control allowing the user to search for a page or blog post. Example:
## @param
page:title=Page|type=confluence-content|required=true|desc=Select
a page do use
spacekey Offers a list of spaces for selection. Passes the space key to the macro. Example:
## @param space:title=Space|type=spacekey
date Confluence accepts this type, but currently treats it in the same way as 'string'. Example:
Note about dates: A user can enter a date in any format, you should validate the date format in your
user macro.
int Confluence accepts this type, but treats it in the same way as 'string'. Example with a default value:
## @param numPosts:title=Number of
Posts|type=int|default=15|desc=Number of posts to display
percentage Confluence accepts this type, but treats it in the same way as 'string'. Example:
## @param pcent:title=Percentage|type=percentage|desc=Number of
posts to display
The parameters are available in your template as $paramfoo, $parambar for parameters named "foo" and
"bar".
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 514
Normally, a parameter like $paramfoo that is missing will appear as '$paramfoo' in the output. To display
nothing when a parameter is not set, use an exclamation mark after the dollar sign like this: $!paramfoo
Using no parameters
If your macro does not accept parameters, you should use @noparams in your template.
If the user macro contains no parameters and does not specify @noparams, then the macro browser will
display a free-format text box allowing users to enter undefined parameters. This can be confusing if the
macro does not accept parameters.
Example: Add the following line at the top of your template:
## @noparams
Including the macro body and parameters, the following Confluence objects are available to the macro:
$body The body of the macro (if the macro has a body) String
$paramfoo, $paramba Named parameters ("foo", "bar") passed to your macro. String
r, ... $param<name>
$space The Space object that this content object (page, blog Space
post, etc) is located in (if relevant).
Macros can also access objects available in the default Velocity context, as described in the developer
documentation.
You can determine which macro parameters should appear in the placeholder in the Confluence editor.
By default as many parameters as can fit will be displayed in the placeholder, as shown here:
You can control which parameters you want to display here, to ensure the most relevant information is visible
to the author.
For example, the Confluence Warning macro has two parameters, title and icon. We consider title to be the
most interesting parameter, so we have configured the Warning macro to show only the value of the title para
meter.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 515
Let's assume an author adds the Warning macro to a page, and gives it a title of 'The title of the warning'.
The macro configuration leads to a placeholder as shown here:
To configure the macro placeholder for a user macro, you will add attributes to the @param entry in the
template.
For example, if our Warning macro is a user macro, the configuration for the title parameter is as follows:
## @param
title:type=string|option-showNameInPlaceholder=false|option-showValue
InPlaceholder=true
The attribute showNameInPlaceholder specifies that the title parameter's name should not be shown.
The attribute showValueInPlaceholder specifies that the title parameter's value should be shown.
If none of the parameters in a macro include any of the above attributes, then the default behavior is to show
all the parameters that fit in the placeholder: full title and value.
If one or more parameters has either attribute set, then all parameters that do not include the attributes will
default to false (that is, they will not be shown).
Related pages:
Integrating Confluence with Other Applications
Tracking Customizations Made to your
Confluence Installation
Confluence administrator's guide
Changes you make to the whole site will also apply Working With Decorator Macros
to all spaces that are inheriting the global look and Customizing a Specific Page
feel. Users with space administrator permissions Upgrading Customized Site and
can further customize the appearance of a Space Layouts
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 516
space and override the global look and feel for that
space. See Customize your Space for more.
If you want more control, you can choose to use an ordinary Confluence page as your site landing page,
instead of sending people to the dashboard. See Configuring the Site Home Page to find out more.
Using a page instead of the dashboard can be useful if most people will be reading, rather than creating,
pages in your site. However, for sites where you want to encourage teams to collaborate, the dashboard
provides the best tools for resuming work in progress and keeping up with what is happening in the site.
Advanced customizations
You can further customize the dashboard by editing the global layout file. See Customizing Site and Space
Layouts for more information on how to do this. You'll need some knowledge of Velocity to modify the layout
files.
There are two locations that you can add content to:
Web panels added to atl.dashboard.secondary will appear below the site welcome message.
Web items added to system.dashboard.button will appear next to the Create space and Invite
users button at the top right of the dashboard.
If you modify layouts in Confluence you will need to reapply your modifications each time you upgrade
Confluence. The more dramatic your customizations are, the harder it may be to reapply the changes when
upgrading. See Upgrading Customized Site and Space Layouts to find out what will be involved before
modifying the layouts.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 517
The Site Logo appears in the header and is visible throughout Confluence. You need Confluence
Administrator permissions to change the site logo.
To change the site logo:
1. Choose the cog icon
> General Configuration > Color Scheme > Edit and then choose Reset to revert back to the default
scheme.
1. Site logo: auto look and feel has updated the header colours to complement the logo.
2. Site title: this is the name of your site.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 518
You can also change the site favicon (the icon that appears in your browser tab). You need Confluence
Administrator permissions to do this.
1. Go to
The Space Logo appears in the sidebar and as an icon in the Sites Directory. The default space logo applies
to all spaces that do not have a custom space logo applied - see Configure the Sidebar.
You need to be a Confluence Administrator to change the default space logo.
To change the default space logo:
1. Go to
Space Administrators can change the logo for their space. This overrides the default space logo and any cha
nges to the default space logo will not appear in these spaces. See example above - 'Sample Space' has a
custom logo.
See see Configure the Sidebar to find out how to change the logo in a specific space.
When you upload a site logo, Confluence automatically detects the colors in your logo and customizes the
color scheme for you.
You can change the color scheme as above, or reset your color scheme back to the default (and still keep
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 519
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 520
application does not mean that the functionality is not available. Every user can still change their style from
within their browsers, or access the URL directly. Don't rely on CSS to disable parts of Confluence.
Features Should Not Be Disabled
Users familiar with Confluence will expect to find the same controls that they are accustomed to. Removing
buttons or controls from the interface is not advised as it may frustrate your users and cause them to
circumvent your design by using direct URL access, as mentioned above.
Custom CSS does not apply to Admin screens
Any CSS styling applied to your site will not be applied to the Administration console. This is to ensure
changes to CSS do not prevent administrators from accessing Admin functions in future.
Confluence Version Compatibility
Be aware of any plans to upgrade your Confluence instance. Future versions of Confluence may not be
compatible with your custom CSS this may cause your CSS to break, requiring maintenance when
Confluence is upgraded. Ask your Confluence administrator for more information.
Test on Different Web Browsers
As a rule you should test your modifications on different web browsers. Internet Explorer, Firefox, Opera and
Safari (on Mac OS X) are some of the more popular browsers.
Note about supported web browsers: Please ensure that you are using one of the web browsers
supported by Confluence. If you are using an unsupported browser or browser version, some features may
not work correctly. Check the Supported Platforms page to find the list of supported web browsers and
browser versions on this page.
CSS Customization is Not Supported
As creating custom CSS has potentially limitless possibilities, Atlassian will not support issues that are
caused by or related to CSS customization.
Getting Started
Editing the CSS
To edit a space's CSS style sheets:
1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
2. Choose Stylesheet then Edit.
3. Paste your custom CSS into the text field.
4. Save your changes. The new CSS will be visible on all content pages in the space.
To edit your global CSS stylesheet:
1. Choose the cog icon
CSS Resources
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 521
W3resource.com
The header is the menu area at the top of a default Confluence page where the Breadcrumb Links, Browse
menu, User menu and the Quick Search box reside. In this example, we are going to change the
background of the header to include a custom graphic.
1. Create a custom graphic. For this example, we created a custom header graphic of 1046 x 61 pixels.
2. Upload the custom graphic to a page in the space that you are customizing.
3. Note the page ID of the page where you uploaded the new graphic. (in this example, the page ID was '
658833839'.
4. Compose your custom CSS for the header. The example below loads the new graphic (called 'header.
png') from a specific page (denoted by page ID ' 658833839') in the same space.
#header .aui-header {
background-image:url('../download/attachments/658833839/header.p
ng');
background-repeat: no-repeat;
}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 522
satisfied with your space design, test it thoroughly until you are confident that it has no problems. Then, you
can look into advanced customization of the Confluence CSS such as adjusting the Search page, the
Dashboard and other integral pages.
Use the Right Tools
As the Confluence CSS is reasonably sophisticated, web development applications will help you to
understand how the page styles have been created. In particular, you will need to view the existing source for
the pages you're starting to work on. If you don't already have some, tools such as the following free
applications will allow you to do this.
1. Firebug
Firebug, a plugin for the Firefox web browser, allows you to take a look at the style of each element on your
page. This is very useful to see what styles are currently applied, for example styles applied to the header
only.
2. Web Developer
The Web Developer plugin for Firefox allows you to edit CSS inline and create new page designs.
3. CSS Edit
CSS Edit is a stand-alone CSS editor for Macintosh that extracts all existing styles from a given page and
allows you to overwrite these.
Edit Simple Elements First
Begin by editing simple elements and checking that they work. By making changes, then checking that each
one worked, you can easily isolate any CSS code that is causing problems. Be aware that some page
elements are more suited to customization than others. For example, adding a gradient to the toolbar is less
likely to 'break' the page than changing the page width. Editing reasonably static elements such as
background graphics will render more predictably than designs which attempt to completely change the user
interface or the Javascript-powered drop-down menus (which we don't recommend editing).
Notes
Note: By default, only system administrators can edit the CSS for a space or for the site. To allow any user
with Space Admin permissions to edit the CSS for a space, go to
> General Configuration > Security Configuration and select Custom Stylesheets for Spaces.
In order to customize the fonts in Confluence, you first need to set the body font to the font you want.
Secondly, you may want to adjust the font size because different fonts have different relative sizes.
The relevant CSS is shown below. It changes Confluence's font from the default of Helvetica/Arial sans
serif to Times/Times New Roman serif. To adjust for the fact that Times is a bit smaller than Helvetica, we
increase the font size to 14 pixels. The many styles that 'wiki-content' in their definition are necessary to
change the font size for all the tags in the wiki content.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 523
body {
font-family: Times, "Times New Roman", serif;
font-size: 14px;
}
.wiki-content,
.wiki-content p,
.wiki-content table,
.wiki-content tr,
.wiki-content td,
.wiki-content th,
.wiki-content ol,
.wiki-content ul,
.wiki-content li {
font-size: 14px;
}
Notes
Note: By default, only system administrators can edit the CSS for a space or for the site. To allow any user
with Space Admin permissions to edit the CSS for a space, go to
> General Configuration > Security Configuration and select Custom Stylesheets for Spaces.
Confluence comes with a single default theme installed, or you can Apply a
download and install other themes from The Atlassian Marketplace. Theme to
a Space
Once a theme is installed it can be applied to the whole site or to individual Applying a
spaces. Theme to
a Site
To see the themes installed in your site: Creating a
1. Go to Theme
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 524
1.
Creating a Theme
If you want to create your own theme, you will need Related pages:
to write a Confluence plugin. Please refer to the
following pages in our developer documentation: Applying a Theme to a Site
Apply a Theme to a Space
Get started with plugin development.
Follow the developer's tutorial for writing a
Confluence theme.
Create a theme using the theme plugin
module.
When you edit a site layout, you'll be modifying the Related pages:
default decorators in every space in your site, except Velocity Template Overview
for those that have already been edited in a space. Basic Introduction to Velocity
See Customize Space Layouts for more information Customizing your Confluence Site
on how to edit the decorators for a single space.
You'll need System Administrator permissions to edit
site layouts.
If you modify layouts in Confluence you will need to reapply your modifications each time you
upgrade Confluence. The more dramatic your customizations are, the harder it may be to reapply the
changes when upgrading. See Upgrading Customized Site and Space Layouts to find out what will
be involved before modifying the layouts.
Confluence is built on top of the open source SiteMesh library, a web-page layout system.
To edit the layout of Confluence, you will need to modify these decorator files. A decorator file is a .vmd file
and is written in Velocity. You can learn more from the Velocity User Guide.
Once you are familiar with Velocity, you can edit the decorator files to personalize the appearance of
Confluence.
The decorator files in Confluence are grouped into the following categories:
Site layouts: These are used to define the controls that surround each page in the site. For example,
the header, footer and dashboard.
Content layouts: These control the appearance of content such as pages and blog posts. They do
not change the way the pages themselves are displayed, but allow you to alter the way the
surrounding comments or attachments are displayed.
Export layouts: These control the appearance of spaces and pages when they are exported to
HTML.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 525
When editing Custom Decorator Templates, there are a number of macros available to define complex or
variable parts of the page such as menus and breadcrumbs. You may insert these macros anywhere in your
templates. More information on Working With Decorator Macros.
Advanced customizations
The velocity directory is at the front of Confluence's Velocity template search path. As such, you can
override any of Confluence's Velocity templates by placing an identically named file in the right place. While
we don't recommend you do this unless you know exactly what you're doing, it does give you complete
control over the look of every aspect of Confluence. It also means that you can edit your templates in a
text-editor if you wish, rather than through the web interface.
Caching
Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows
to reload that page from disk. If you are editing the pages on disk, you will either have to turn off velocity's
caching temporarily in WEB-INF/classes/velocity.properties, or restart the server to make your
changes visible.
You will find the Velocity files in your Confluence installation directory. The primary Velocity files are located
in the <CONFLUENCE-INSTALLATION>\confluence\decorators directory. For example, you will find
the following files in that directory: main.vmd, space.vmd, form-aui.vmd, global.vmd, and more.
If the layout has changed so extensively as to not be visible, you can browse to the URL directly:
http://<confluence base
url>/admin/resetdecorator.action?decoratorName=decorators/main.vmd
If you are using custom layouts based on defaults from a previous Confluence version, you run the
risk of breaking functionality, or worse, missing out on great new features!
Take care on each new release of Confluence to reapply your changes to the new default templates.
To reapply your custom layouts, you need to:
1. Obtain the source of your custom layouts from your current version of Confluence.
2.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 526
Ideally, you should keep a record of each customization you have applied to each of your Confluence site or
space layouts.
If not, you should be able to find your customizations using the following method. This method extracts all
site- and space-level layouts from your Confluence site as a single output. From this output, you should be
able to identify your customizations.
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:
This example was tested on MySQL, but should be applicable to all SQL databases.
When you upgrade Confluence to another major release of Confluence, you will need to manually reapply
any customizations you made to any site-wide or space-specific layouts. Unless otherwise stated, you should
not need to reapply customizations after conducting a minor release upgrade of Confluence.
What are 'major' and 'minor' releases? Major release upgrades are ones where the 1st digit of
Confluence's version number or the 1st digit after the 1st decimal place differ after the upgrade, for example,
when upgrading from Confluence 3.0 to 3.1, or 2.8 to 3.0. Minor release upgrades are ones where the 1st
digit of Confluence's version number and the 1st digit after the 1st decimal place remain the same after the
upgrade, for example, when upgrading Confluence 3.0 to 3.0.1.
If you have made Confluence site-wide layout customizations:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 527
4. Click Reset Default next to the layout whose customizations need to be reapplied.
5. Click Create Custom next to the same layout and reapply your customizations (by copying and
pasting them) into the appropriate locations within the new default layout.
6. Click the Save button.
7. Repeat this procedure from step 5 for each layout whose customizations need to be reapplied.
Changes may interact unpredictably with future versions of Confluence. When upgrading, you should always
test your custom modifications thoroughly before deploying them on a live site. It's beyond the scope of
Atlassian Support to test and deploy these changes.
Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows
to reload that page from disk. If you are editing the pages on disk, you will either have to turn off Velocity's
caching temporarily in WEB-INF/classes/velocity.properties, or restart the server to make your
changes visible.
The velocity.properties file is available in the confluence-x.x.x.jar file, where x.x.x is the
Confluence version number. The JAR file is located in the WEB-INF/lib directory. If you wish to make
modification to the files in the JAR, we recommend the following steps:
1. Stop Confluence.
2. Make a backup copy of the JAR file.
3. Un-jar the file
4. Locate and edit the appropriate file that you wish to modify.
5. Re-jar the confluence-x.x.x.jar file.
6. Relocate the JAR file to the appropriate directory.
7. Restart Confluence.
Decorator Macros are Velocity macros which are used to draw complex or variable parts of the page such as
menus and breadcrumbs when editing Custom decorators. Decorator macros can be inserted anywhere in your
templates.
The macro is called by inserting a string of the form: #macroName("argument1" "argument2" "argument3").There
are no commas between the arguments. Unless otherwise noted, these macros take no arguments.
NOTE: These macros will only work reliably when customizing main.vmd. They may not work in other Velocity
decorators. Decorator macros will not work inside normal confluence pages.
Macro Usage
#breadcrumbs() Draws the "You are here" breadcrumbs list, like the one found above the
page name in the default template.
#includePage(pageTitle) Includes a confluence page with the specified title. If you have 2 or more
pages with the same title across multiple spaces, this macro will include the
page belonging to the space you are currently viewing.
#searchbox() Inserts a search box into the page, like the one to the far right of the
breadcrumbs in the default template.
#globalnavbar(type) Draws the global navigation bar, as found in the top right-hand corner of the
default template. The navigation bar can be displayed in two modes:
#globalnavbar("table") Displays the navigation bar in its default mode: drawn as a table of links with
colored backgrounds and mouse-over effects.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 528
#usernavbar() Draws the user-specific navigation-bar. This bar contains the links to the
user's profile and history, or to the login and signup pages if the user is not
logged in.
#helpicon() Draws the help icon, and link to the Confluence help page.
#printableicon() On pages where a printable version is available, draws the printable page
icon, linking to the printable version of the page. Otherwise, draws nothing
#pagetitle(class) When you are viewing a page in a Confluence space, draws the name of the
space that page is in. Otherwise, writes the word "CONFLUENCE".The
"class" argument is the CSS class that the title should be drawn in. Unless
you have customized your Confluence installation's CSS file, you should call
this with "spacenametitle" as the class: #pagetitle("spacenametitle"
)
#bottomshadow() Draws the fading shadow-effect found at the bottom of the content area in
the default template.
About Decorators
Confluence is built on top of the Open Source SiteMesh library, a web-page layout system that provides a
consistent look and feel across a site. SiteMesh works through "decorators" that define a page's layout and
structure, and into which the specific content of the page is placed. If you are interested, you can read more in
the SiteMesh documentation.
What this means for Confluence is that you can customize the look and feel of parts of your Confluence site
through editing decorators, for example:
The "Main" decorator defines the generic header and footer
The "Page" decorator defines how a page is displayed
The "Printable" decorator defines the look and feel of the printable versions of pages.
You can view and edit these decorators from within Confluence. Changes to the decorators will affect all spaces
in that Confluence installation.
The decorator that is used to draw Confluence's administrative pages cannot be edited from within Confluence.
This means that if you make a mistake that renders the rest of the site unuseable, the administrative pages
should still be available for you to fix the template.
At any time, you can browse the default decorators that come packaged with Confluence by following the "View
Default" links on the "Site Layouts" page. The template browser also allows you to view the "#parsed" templates
that are included within the template when it is compiled. While you can't edit these included templates, you will
probably have to copy some or all of them into your custom template as you do your customization.
To edit Confluence decorators you will need a good knowledge of HTML, and some understanding of the Velocit
y templating language.
To edit a decorator:
1. Go to Confluence Admin > Layouts.
2. Choose Create Custom beside the decorator you wish to edit.
3. Save your changes.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 529
If you make a mistake or want to undo your changes, choose Reset Default beside the edited decorator.
Alternatively, the custom templates are stored in the DECORATOR table in the database. If you have somehow
managed to render Confluence completely unuseable through editing your templates, delete the relevant entries
from the DECORATOR table.
Macros
Some parts of the page are drawn using Velocity macros, including the navigation bar. The macros you should
know about when editing decorators are described in Working With Decorator Macros.
The velocity directory is at the front of Confluence's velocity template search path. As such, you can override
any of Confluence's velocity templates by placing an identically named file in the right place.
While we don't recommend you do this, it does give you complete control over the look of every aspect of
Confluence. It also means that you can edit your templates in a text-editor if you wish, rather than through your
browser.
There are, however, two important caveats:
1. Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it
knows to reload that page from disk. If you are editing the pages on disk, you will either have to turn off
velocity's caching temporarily in WEB-INF/classes/velocity.properties, or restart the server to
make your changes visible.
2. Changes may interact unpredictably with future versions of Confluence. When upgrading, you should
always test your custom modifications thoroughly before deploying them on a live site.
Customizing a Specific Page
If you'd like to change the appearance of a specific page, you can modify the corresponding Velocity template.
Here's how to find out which one:
1. Access the page. Note the name of the action. For example, the "Contact Administrators" page is <baseU
rl>/administrators.action.
2. Browse to <confluence-install>/confluence/WEB-INF/lib/confluence-x.y.jar. Copy the file.
3. Unzip or unjar the file using a standard unzipper or the java jar utility.
4. Open xwork.xml. Search the file for the name of the action corresponding to the page you'd like to modify.
You'll see an entry like:
<action name="administrators"
class="com.atlassian.confluence.user.actions.AdministratorsAction">
<interceptor-ref name="defaultStack"/>
<result name="success"
type="velocity">/administrators.vm</result>
</action>
5. The file to look for is the vm or vmd file. In the above example, it's administrators.vmd. Because there is
no context path (just a / before the name of the file), its in the root of the Confluence webapp. For the
stand-alone, that's <confluence-install>/confluence folder.
6. Modify the file.
For details on how to configure the file, check the Velocity Template Overview.
Customizing the Login Page
This page gets you started on customizing the Confluence login page, to
add your own logo or custom text. This will not customize the login process,
just what users sees when they log in.
Notes:
Customizations to the Confluence login page will need to be
reapplied when you upgrade Confluence. Consider this before
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 530
making drastic changes to the layout, and be sure to keep a list of Related pages:
what you have changed for your upgrade process later.
Please test your changes on a test Confluence site first. Changing
the Site
Only administrators with access to the server where Confluence is running Logo
can modify the Confluence login page. Velocity
Template
Overview
Customizin
g Site and
Space
Layouts
Changing
the Look
and Feel of
Confluenc
e
Modify
Confluenc
e Interface
Text
All Confluence UI text is contained in a single Java properties file. This file can be modified to change the default
text, and also to translate Confluence into languages other than English.
The UI text file is ConfluenceActionSupport.properties. From your Confluence install directory:
\confluence\WEB-INF\lib\confluence-x.x.x.jar
Replace "x.x.x" with your Confluence version, for example for 4.3.2, it
will be named "confluence-4.3.2.jar".
Within this File, the relevant file to edit is
:\com\atlassian\confluence\core\ConfluenceActionSupport.properties.
parameter.name=Parameter value
Parameter names are any text before the '=' character and should never be modified. Any text after the '='
character is the parameter value, which can be modified freely and can also contain variables. An example
involving variables is:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 531
popular.labels=The three most popular labels are {0}, {1} and {2}.
For more information on replacing values, check out Translating ConfluenceActionSupport Content. Note that
plugins store their text internally, so you must modify plugin text individually.
1. Stop Confluence
2. Under your install directory, open \confluence\WEB-INF\lib\confluence-x.x.x.jar\com\atl
assian\confluence\core\ConfluenceActionSupport.properties
3. Search for the text you wish to modify, replace it and save the file in <Confluence-Install>\conflu
ence\WEB-INF\classes\com\atlassian\confluence\core. Please create this folder structure, if
it does not exist already.
If you re-bundle the JAR file, rather than re-deploy the class in the WEB-INF\classes directory,
make sure to move the backup JAR file out of the /lib directory, or the backup may be deployed
by mistake.
4. Restart Confluence
Confluence provides a set of keyboard shortcuts. You could customize the shortcuts by making modifications
inside the ConfluenceActionSupport.properties file.
To disable a particular shortcut, you can simply just comment out a respective line of code. One may like
to disable the shortcut to one of the navigation links: View, Edit, Attachments, Info . For instance, to
disable shortcut to Attachmentsone would comment out the following line:
#navlink.attachments.accesskey=a
To modify an access key, one could simply just change the letter, bearing in mind the fact that the letter
must be unique.
Customizing Email Templates
Customizing the Confluence email templates is not supported. If you do decide to edit the templates
we strongly recommend you use a test instance of Confluence.
Any customizations you make to the Confluence email notification templates will need to be reapplied
after upgrading Confluence.
Email notification templates are contained within the confluence-email-notifications plugin, which is a
bundled plugin (add-on) that is installed automatically when you install Confluence.
Only administrators with access to the Confluence installation directory can modify the Confluence email
templates.
Confluence uses Soy templates (also known as Closure templates) for email notifications. You can find out more
in the Google Developer docs or see our developer tutorial which contains a short introduction to using Soy
templates.
To change the email notification templates:
1. In the Confluence web application folder, find the file /confluence/WEB-INF/atlassian-bundled-
plugins/confluence-email-notifications-plugin-x.x.jar
Note: This plugin is independently versioned, the version number will not necessarily match Confluence's
version number.
2. Copy this file to a working location and extract the jar file. Find out more about how to edit files within .jar
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 532
2.
archives.
3. Within the jar file, templates are stored in the /templates/ folder. Edit the Soy templates to make your
changes.
4. Zip all the files and change the file extension to .jar (or refer to the guide on editing files within .jar
archives for other methods).
5. Drop the new jar file into the /confluence/WEB-INF/atlassian-bundled-plugins folder
(replacing the original file - you might want to make a copy of the original file for easy roll back) and then
restart your instance.
6. Test your changes carefully before installing the updated plugin in production.
We strongly recommend you use a test instance for editing the templates contained within the plugin. If you are
unable to enable the plugin, check the Confluence logs for information, it may be that there are problems with
your edits to the Soy templates.
RELATED TOPICS
Customizing Site and Space Layouts
Changing the Look and Feel of Confluence
Modify Confluence Interface Text
Changing the Default Behavior and Content in Confluence
Confluence comes with some handy default settings that determine what Related pages:
people see when they first enter the Confluence site, and the default content
that is put into new spaces and other areas of Confluence. Changing
the Look
Confluence administrators can change the settings to customize the and Feel of
behavior and the default content of their Confluence site: Confluenc
e
A template is a predefined page that can be used as a prototype when creating new pages. Templates can be
created by users, or provided by a blueprints. See Page Templates and Blueprints.
Administrators can import templates, to make them available to other people using Confluence. See Importing
Templates.
Confluence also provides 'system templates' which contain default content for the site welcome message (see E
diting the Site Welcome Message) and default space content (see Customizing Default Space Content).
Administrators can also disable templates and blueprints, to stop them appearing in the Create and Create
Space dialogs anywhere in their Confluence site.
To disable a template or blueprint across the entire Confluence site:
Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 533
To see the template bundles that are currently available for import on your Confluence site:
1. Log in to Confluence as a System Administrator or Confluence Administrator.
2. Choose the cog icon
Step 2. (Optional) Download and install additional template bundles from the Atlassian Marketplace
Follow the steps below if you want to add more template bundles to your site.
Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's
information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our
guidelines on add-on support.
To upload more templates:
1. Go to the Atlassian Marketplace and download the template bundle that you need. It will be in the form
of a JAR file. Save the JAR file somewhere in your file system.
2. Log in to Confluence as a System Administrator.
3. Choose the cog icon
You now have one or more template bundles on your site. The templates are not available until you have
'imported' them.
To import a template:
1. Log in to Confluence as a System Administrator or Confluence Administrator.
2. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation
2. 534
Notes
Building your own template bundles. You can build a template bundle as an add-on (also called a
'plugin') and then upload it to your Confluence site. You can then import the templates from your
custom template bundle, as described above. You will need some programming knowledge to develop
a template bundle. See Creating A Template Bundle.
Duplicate template names. If a template with the same name already exists on import, a duplicate
template of the same name will be created. You will need to check the templates and rename them
manually.
Removing the template. Removing the add-on that contains a template will not remove the template
from your Confluence site if you have already imported it. You will need to remove the template
manually via the administration console or space administration screen.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 535
1.
Confluence comes with the following languages installed and ready to use:
Deutsch (Deutschland)
Eesti (Eesti)
English (UK)
English (US)
Espaol (Espaa)
Franais (France)
slenska (sland)
Italiano (Italia)
Norsk (Norge)
Portugus (Brasil)
Romn (Romnia)
Slovenina (Slovensk republika)
Suomi (Suomi)
()
()
()
()
Individual users can choose the language that Confluence will use to display screen text and messages.
Note that the list of supported languages depends on the language packs installed on your Confluence site.
The language used for your session will depend on the settings below, in the following order of priority from
highest to lowest:
The language preference defined in your user profile. Note that you need to be logged in for this
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 536
This feature is useful if you are working on creating translations of the Confluence user interface. After
opening the Confluence dashboard, you can add the following action to the end of your Confluence URL:
?i18ntranslate=on
This will cause each element of the user interface to display its special key name. This makes it easier to
find the context for each key within the user interface. You can then search for the key on http://translations.a
tlassian.com where you can enter an appropriate translation for your custom language pack.
The key names are displayed with a 'lightning bolt' graphic. For example:
To turn off the translation view, add the following to the end of the Confluence URL:
?i18ntranslate=off
You can customize the message that is presented to the user on the ' Contact Site Administrators' page.
To edit the administrator contact message:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 537
By default, the 'contact administrators message' looks much like the highlighted area in the screenshot
below, starting with 'Please enter information...'.
Screenshot: The default 'Contact Site Administrators' message
To restore the message to its default simply remove the custom message you entered when following the
instructions above, so that the 'Custom Contact Administrators Message' field is empty.
If you prefer to disable the ability for users to send an email message to the site administrators, you can
disable the form portion of this screen. You can only disable the form if you first provide a 'Custom Contact
Administrators Message' as described above.
To enable or disable the administrator contact form:
1. Choose the cog icon
You can configure Confluence to use Captcha to help prevent spam, including the spamming of Confluence
administrators. The administrator contact form is covered by the site-wide Captcha settings as documented
in Configuring Captcha for Spam Prevention.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 538
If you choose to set a page as your site homepage but would like your users to still be able to access the
Confluence dashboard, you can add a link to the Application Navigator.
To add the Confluence Dashboard to the Application Navigator:
1. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 539
The following variables are available to be added to the default space content templates.
$spaceKey - inserts the space key into the site space homepage
$spaceName - inserts the space name into the site space homepage
$userFullName - inserts the user (owner of the personal space) into the personal space homepage
$userEmail - inserts the email address of the user (owner of the personal space) into the personal
space homepage.
Default space templates differ from ordinary page templates in that they do not present the user with a form
to complete, so variables should be limited to those listed in the Variables menu.
Some macros, such as the Table of Contents macro, may not display correctly when you preview the
template as they are designed to work on a page. The macros will display correctly on the home page when
you create a new space. For more information on editing a template, including adding macros see - Adding
Content to a Template.
You'll need Confluence administrator permissions to Configuring the Site Home Page
edit the site welcome message. Changing the Site Title
Changing the Site Logo
To edit the site welcome message:
Confluence administrators can either click the Edit li
nk below the site welcome message on the
dashboard, or:
1. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 540
1.
The site welcome message is a template, not a page, so you'll be using the template editor to make your
changes.
You can add text, links and macros, as you would in any confluence page, but the process for adding files,
including images is a little different.
You can't upload an image or other file into a template directly. First you'll need to upload the file to a page in
your site, then in your template, choose Insert > Files > Search on other pages to embed the file or image.
You can allow people who are not Confluence administrators to edit the site welcome message by using the
include Include Page macro to include content from elsewhere in your site, rather than adding content
directly to the template.
To include content from a page in the site welcome message:
1. Create a new page in a space that is visible to all users. It's important that all users can see content in
that space - if a person does not have permissions to view the space where you've created the page,
they won't be able to see the page content on the dashboard.
2. Add some text, images or macros, then save the page.
3. Restrict who can edit the page (this is optional, but useful if you only want to allow some people to
change the content).
4. Edit the site welcome message template (as described above) and use the Include page macro to
include the contents of your newly created page.
5. Save the template.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 541
People with permission to edit the page will now be able to make changes at any time, and their changes will
be visible on the dashboard as soon as the page is saved.
Application Links (sometimes called "AppLinks") is a bundled plugin that allows you to link Atlassian applications
to each other. Linking two applications allows you to share information and access one application's functions
and resources from within the other.
Atlassian recommends only using OAuth authentication for application links, because of the greater security
inherent with that protocol. We no longer recommend the Trusted Applications and Basic authentication types.
Linking Confluence to other applications allows you to include information from those applications in pages or
blogs that you create in Confluence. For example, you could link Confluence to JIRA Software and display
issues on a Confluence page using the JIRA Issues Macro.
1. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 542
The workbox displays a notification when someone does one of the following in Confluence:
Shares a page or blog post with you.
Mentions you in a page, blog post, comment or task.
Comments on a page or blog post that you are watching.
Likes a page or blog post that you are watching.
The workbox does not show notifications triggered because you are watching a space. Only watches on
pages and blog posts are relevant here.
The notification in your workbox appears as 'read' if you have already viewed the page or blog post.
If your Confluence site is linked to a JIRA application, you will also see the following JIRA notifications in your
workbox:
Comments on issues that you are watching.
Mentions.
Shares of issues, filters and searches.
The polling intervals are used by the Confluence server that displays in-app notifications and tasks in its
workbox.
Option Description
Active This is the number of seconds that Confluence will wait before checking (polling) for new
polling notifications relevant to the page that the user is currently viewing. This setting applies to the
interval page open in the browser tab that currently has focus. It does not matter whether the user has
the workbox open or not.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 543
Inactive This is the number of seconds that Confluence will wait before checking (polling) for new
polling notifications relevant to all pages that are not currently in focus. These pages may be on the
interval Confluence server that displays the workbox, or on other Confluence or JIRA servers that send
their notifications to this server.
This setting defines an upper limit. For inactive pages, Confluence starts with a polling interval
equal to the active polling interval, then gradually increases the interval between polls until it
reaches the limit defined here.
If your Confluence site is connected to a JIRA application, you can include notifications from your JIRA
application, for example JIRA Software or JIRA Service Desk.
To include notifications from a JIRA application:
Your JIRA application and Confluence must be connected via an application link with OAuth authentication
(without impersonation). See Linking to Another Application.
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 544
You may wish to configure Confluence to display its own notifications in its workbox, but prevent notifications
from JIRA applications from appearing in the workbox, even when JIRA applications and Confluence are
linked via application links.
The JIRA administration interface does not offer a way of disabling notifications sent to Confluence.
To stop JIRA applications from sending notifications to Confluence: Disable the following plugins in
JIRA. (See the Universal Plugin Manager guide to disabling plugins.)
'Workbox Common Plugin'
'Workbox JIRA Provider Plugin'
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 545
Notes:
Your Confluence servers must be running Confluence 4.3.3 or later.
Confluence can display notifications from more than one server.
Confluence can send notifications to only one server.
Only one of the linked Confluence servers can display the in-app notifications.
Screenshot: This Confluence server displays in-app notifications from itself, from JIRA, and from another
Confluence server
You can configure Confluence to send all notifications to a different Confluence server. In this case, the
current Confluence server will not display the workbox.
To send notifications to another Confluence server: Follow the instructions in our example for Confluenc
eQuiet above.
Screenshot: This Confluence server sends its in-app notifications to another Confluence server
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 546
We recommend running JIRA and Confluence in separate stand-alone instances behind an Apache Web
Server. The following documentation will guide you through the installation processes:
Installing Confluence
Installing JIRA applications
Running Confluence behind Apache
Integrating JIRA with Apache
We don't support deploying Confluence and any other application (including JIRA) in the same Tomcat
container. See Can Multiple Atlassian Products Be Deployed in a Single Tomcat Container? for more
information.
This is the fun stuff. Check out Use JIRA applications and Confluence together to find out about all the
integration points, great time saving features, and to check exactly which JIRA application and version you'll
need.
If you already have a JIRA application you can choose to delegate user management to JIRA, and manage
all your users in one place. You can control which JIRA groups also have permissions to use Confluence.
Your license tiers for each application do not need to be the same.
See Configuring JIRA Integration in the Setup Wizard to delegate user management to JIRA when installing
Confluence for the first time.
See Connecting to Crowd or JIRA for User Management to delegate user management to JIRA for an
existing Confluence site.
See Linking to Another Application to find out how to connect Confluence to your JIRA application using an
application link. This only needs to be done once.
If you delegated user management to JIRA as part of Confluence's setup process, an application link to JIRA
will be all set up and ready to go.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 547
We've developed a guide to troubleshooting application links, to help you out. Take a look at it if you
need a hand getting around any errors or roadblocks with setting up application links.
In addition to registering the external gadgets, we recommend that you set up an OAuth or Trusted
Application relationship between the application that serves the gadget (the service provider) and Confluence
(the consumer). The trust relationship is required for gadgets that access restricted data from the external
web application.
See how to configure OAuth or Trusted Applications Authentication, using Application Links.
If the external web application provides anonymous access to all the data you need in the gadgets, then you
do not need a trust relationship.
For example, if your gadgets will retrieve data from JIRA and your JIRA server includes projects and issues
that are restricted to logged-in users, then you will need a trust relationship between Confluence and JIRA. If
you do not set up the trust relationship, then the gadgets will show only the information that JIRA makes
visible to anonymous users.
You can add all the gadgets from your JIRA, Bamboo, FishEye or Crucible site or from another Confluence
site to your Confluence gadget directory. People can then pick and choose the gadgets to add to their
Confluence pages.
To subscribe to another site's gadgets:
1. Go to
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 548
3. Enter the base URL of the application you want to subscribe to, for example, http://example.com
/jira or http://example.com/confluence.
4. Choose Add. Confluence will convert the URL to a gadget feed and place it in the list of 'Added
Gadget Feeds'.
If you cannot subscribe to an application's gadgets, you will need to register the gadgets one by one. This is
necessary for applications and websites that do not support gadget subscription, and for applications where
you cannot establish a trusted relationship via Application Links.
First you will need to get the gadget URL and copy it to your clipboard.
http://example.com/my-gadget-location/my-gadget.xml
If the gadget is supplied by a plugin, the URL will have this format:
http://my-app.my-server.com:port/rest/gadgets/1.0/g/my-plugin.key:my-gadget/my-p
ath/my-gadget.xml
For example:
http://mycompany.com/jira/rest/gadgets/1.0/g/com.atlassian.streams.streams-jira-
plugin:activitystream-gadget/gadgets/activitystream-gadget.xml
To find a gadget's URL in JIRA:
Go to your dashboard by clicking the Dashboards link at the top left of the screen.
Click Add Gadget to see the list of gadgets in the directory.
Find the gadget you want, using one or more of the following tools:
Use the scroll bar on the right to move up and down the list of gadgets.
Select a category in the left-hand panel to display only gadgets in that category.
Start typing a key word for your gadget in the Search textbox. The list of gadgets will change as
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 549
you type, showing only gadgets that match your search term.
Right-click the Gadget URL link for that gadget and copy the gadget's URL into your clipboard.
To find a gadget's URL in Confluence:
Choose Help > Confluence Gadgets to see the list of available Confluence gadgets.
Find the gadget you want.
Right-click the Gadget URL link for that gadget and copy the gadget's URL into your clipboard.
If the gadget comes from a non-Atlassian web application or web site, please consult the relevant
documentation for that application to get the gadget URL.
Now that you have the gadget's URL, you can register it in Confluence, so that people can add it to their
pages. You need system administrator permissions to register a gadget.
To register the gadget in Confluence:
1. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 550
To remove a single gadget from Confluence, click the Delete button next to the gadget URL.
If you have subscribed to an application's gadgets, you will need to remove the entire subscription. You
cannot unregister a single gadget. Click the Delete button next to the gadget feed URL.
The gadget(s) will no longer be available in the macro browser, and people will not be able to add them using
the Gadget macro. Any pages that already use the gadget will show a broken gadget link.
> Add-ons
2. Choose System from the filter drop down and then search for Office Connector
3. Expand the Office Connector add-on listing. From here you can:
Choose Configure to specify preferences for the Office Connector (this opens the configuration
screen described below)
Click Disable to disable all modules of the add-on
Expand the modules list to enable or disable selected Office Connector modules
Note: only some Office Connector modules can be disabled. Modules that are integral to the operation of the
add-on cannot be disabled, and do not have an Enable or Disable button. Modules that can be disabled
include the button and provide a brief, on-screen description of the module.
Users with System Administrator permissions can configure the behavior of the Office Connector.
To set the configuration options for the Office Connector:
1. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 551
Edit in word Page Where the button for editing the content in Word is located. You can configure the button t
button location action icon action icon or from the view page tab.
Note: This setting has no effect in the Confluence default theme.
Warnings: Disabled If this option is enabled, the user will receive a warning when importing a Word document.
Show a user when they are about to overwrite existing content.
warning before
allowing a
user to
perform an
import
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 552
Advanced Disabled Note: This feature requires a third party add-on that is not supported for Confluence 5.
Formatting
Options: Use If this option is enabled, a Confluence page created from an imported Word document will
the footnote from Adaptavist to render any footnotes contained in the document. Note that you will nee
macro for add-on onto your Confluence site. For more information about this add-on and macro, plea
Word add-on.
footnotes
Authentication: Disabled If this option is enabled, the Office Connector will use authentication tokens in the URL.
Allow
authentication This needs to be enabled to edit Office 2013 documents.
tokens in the
URL path
Temporary The The {viewfile} macro will cache data temporarily. This option allows you to set the location
storage for Confluence settings are:
viewfile macro Home
directory. Confluence home directory The temporary file will be stored in your Confluence Ho
A directory specified in the directories.properties file You can specify a lo
Office Connector's directories.properties file:
1. Locate the OfficeConnector-x.xx.jar file (where x.xx is the version number)
Home directory and copy it to a temporary location
2. Unzip the JAR file and find the resources/directories.properties file. The
like this:
3. Edit the last line, adding the path to your required temporary location directly after
example:
On Windows:
com.benryan.confluence.word.edit.cacheDir=c:\my\path\
On Linux:
com.benryan.confluence.word.edit.cacheDir=/home/myuse
4. Save the file, recreate the JAR and put it back in your Confluence Home directory,
JAR.
Maximum file 500 This is the maximum size of the cache used by the {viewfile} macro. (See above.)
space for
cache (MB)
Number of 6 This is the maximum number of threads used to convert PowerPoint, Excel files or PDF sl
Conversion this setting to manage Confluence performance, by limiting the number of threads so that
Queues does not consume too many resources.
Click Manage Queues to view attachments that are still pending conversion.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 553
period. It also defines the number of users who are On this page:
entitled to use Confluence.
Viewing your license details
To quickly check the status of your license you can Updating your license
go to Understanding the user count for
your license
> General Configuration > Support Tools. Exceeding your licensed user
count
You'll need need Confluence Administrator or Reducing your user count
System Administrator permissions to view and edit Downgrading your license
your license. Finding your Support Entitlement
Number (SEN)
Viewing your license details
Related pages:
To view your Confluence license:
Upgrading Beyond Current
1. Go to Licensed Period
Confluence installation and
> General Configuration. upgrade guide
2. Choose License Details in the left-hand Confluence administrator's guide
panel.
The License Details page tells you:
The type of license (for example: Commercial, Academic, Community, or Evaluation).
Number of users you are licensed for, and how many are currently in use.
Your license expiry date, for support and upgrade eligibility.
Your server ID which is generated when you install Confluence for the first time and remains the same
for the life of the installation (including after upgrades or changes to your license).
Your support entitlement number (SEN).
includes only users who have the 'can use' global permissions for the Confluence site.
does not include anonymous users, who may access your Confluence site if you have allowed
anonymous access.
does not include deactivated users.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 554
If you exceed the number of users included in your license, your Confluence instance will become read-only,
that means no users will be able to create or edit content until you reduce the number of users.
You can reduce your user count by removing or deactivating users who do not require access to
Confluence. See Delete or Disable Users.
If you have connected Confluence to an LDAP directory, you may want configure Confluence to only
synchronize a subset of users from LDAP rather than all users. See How to change the number of users
synchronized from LDAP to Confluence in the Knowledge Base. This can be a complicated process and we
recommend that you only use this method if necessary.
If you decide to downgrade your Confluence license to pay for fewer users you need to ensure that the
number of users currently signed up (as shown on the License Details page) is lower that the number
allowed by your new license before your apply the new license.
If you have more users than your new license allows you will need to reduce your user count before applying
the new license.
You can find your Support Entitlement Number (SEN) in three places:
In Confluence - go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 555
Database Configuration
This document provides information on connecting On this page:
Confluence to an external database. Choosing an external database
About the embedded H2
Choosing an external database
database
Database setup
Note: Take time to choose your database wisely. Database troubleshooting
The XML backup built into Confluence is not suited Notes
for migration or backup of large data sets. If you Related pages:
need to migrate later, you'll need to use a third party
database migration tool. Database JDBC Drivers
Supported Platforms
Below is more information on selecting and Embedded H2 Database
migrating to an external database: Managing Confluence Data
Migrating to a Different Database
Supported Databases
Database Troubleshooting
Your Confluence installation includes an embedded H2 database, to enable you to try Confluence without
setting up an external database. The embedded H2 database is only supported while you are evaluating
Confluence. You must migrate to a supported external database before using Confluence as a production
system.
To find out if you are still using the embedded database, go to
Database setup
Database troubleshooting
Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 556
and install the driver listed below before you can set up Confluence. On this page:
If you use PostgreSQL or Microsoft SQL Server, the drivers are bundled Adding
with Confluence, so you're ready to. your
database
Adding your database driver (MySQL and Oracle) driver
(MySQL
The Confluence setup wizard will stop you at the Database configuration
and
step if it can't find an appropriate driver for the database you select.
Oracle)
To make your database driver available to Confluence: Supported
drivers
1. Stop Confluence.
2. Download and extract the appropriate driver from the list below.
3. Drop the .jar file in your <installation-directory>/confluen Related pages:
ce/WEB-INF/lib directory. Database
4. Restart Confluence then go to http://localhost:<port> in your Configurati
browser to continue the setup process. on
The setup wizard will return to the database configuration step, and you're Supported
back on your way. Platforms
Supported drivers
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 557
If you attempt to use an unsupported or custom JDBC driver (or a driverClassName from an unsupported
or custom driver in your JINDI datasource connection) collaborative editing will fail. You must use a
supported driver.
If you do not already have an operational Oracle database server, download the installation package from the
Oracle download page and follow the instructions in the Oracle documentation.
Then follow the steps below, to deploy Confluence to a schema in your Oracle server.
Note: Your database should be configured to use the same character encoding as Confluence. The
recommended encoding is AL32UTF8 (the Oracle equivalent of Unicode UTF-8). See Configuring Database
Character Encoding.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 558
In this step you will create a Confluence user in Oracle and grant the appropriate roles to the user, so that the
user can set up a connection, can create objects in its own schema, and can configure the schema.
To create the user and assign its privileges:
1. Access the command line interface to Oracle via the 'sqlplus' command.
You must add the 'as sysdba' or 'as sysoper' option if you are logging in with the user 'sys'. This
determines which sys role you are using.
Once logged in, you can type arbitrary SQL commands.
2. Create a Confluence user (<user>) in Oracle, and grant the appropriate roles only to the user:
connect role is required to set up a connection.
resource role is required to allow the user to create objects in its own schema.
Create table, sequence and trigger are required to configure the schema.
Notes:
It is very important that the user is granted the exact privileges indicated above.
Confluence requires only these privileges so you should grant specific privileges to the
user, and not assign a role to the user.
Do not grant the user the select any table permission. That permission can cause
problems with other schemas.
When you create a user, specify the tablespace for the table objects as shown above.
Install Confluence if you have not done so already. See the Confluence Installation Guide. Stop immediately
after the installation, before opening the Confluence Setup Wizard in your browser, and follow the
steps below.
If you have already got part-way through the Confluence Setup Wizard, stop at the database setup step and
follow the steps below. You will be able to restart the setup wizard at the same step later.
The JDBC thin driver for Oracle use three different styles of URL:
New style:
New Style
jdbc:oracle:thin:@//[HOST][:PORT]/SERVICE
Old style:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 559
Old Style
jdbc:oracle:thin:@[HOST][:PORT]:SID
'tnsnames' style:
tnsnames
jdbc:oracle:thin:@(DESCRIPTION=
(SDU=32768)
(enable=broken)
(LOAD_BALANCE=yes)
(FAILOVER=yes)
(ADDRESS=
(PROTOCOL=TCP)
(HOST=dbserver1.example.com)
(PORT=1525))
(ADDRESS=
(PROTOCOL=TCP)
(HOST=dbserver2.example.com)
(PORT=1525))
(CONNECT_DATA=
(SERVICE_NAME=CONFDB)))
Notes:
The tnsnames style is required for connecting to an Oracle RAC cluster. For easy reading, we have
split the example above over multiple lines, but you should compact it into a single line. These values
may need more analysis than documented here, so you should seek the assistance of an experienced
DBA.
If you use the new style URL, then SERVICE can be either an SID or Service Name.
If you use the old style URL, then SERVICE can only be the SID.
To determine the host, port, service name, and/or SID, execute the following command as the user running
Oracle. (By default, the user is "oracle"):
lsnrctl status
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 560
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=<HOSTNAME>)(PORT=8080))(Pre
sentation=HTTP)(Session=RAW))
Services Summary...
Service "PLSExtProc" has 1 instance(s).
Instance "PLSExtProc", status UNKNOWN, has 1 handler(s) for this
service...
Service "XE" has 1 instance(s).
Instance "XE", status READY, has 1 handler(s) for this service...
Service "XEXDB" has 1 instance(s).
Instance "XE", status READY, has 1 handler(s) for this service...
The command completed successfully
Notes:
The host and port are determined by the line containing PROTOCOL=tcp, without Presentation=H
TTP.
Under Services Summary, each service which has an instance with READY status is a connectable
service. The name following Service is a service name for connecting to the database name
following Instance on the next line.
The SID is the name of the database instance, as defined by the $ORACLE_SID variable when you
have sourced the Oracle environment to your shell.
For example, assuming that you are running Confluence on the same server as the Oracle database, with
the above lsnrctl status output, you would use one of the following URLs:
jdbc:oracle:thin:@//localhost:1521/XE
jdbc:oracle:thin:@localhost:1521:XE
The URL can be used in either a direct JDBC connection or using a Tomcat datasource.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 561
For further information on Oracle JDBC URLs, see the Oracle JDBC FAQ.
Decide whether you will set up a direct JDBC connection or a datasource connection to Oracle, to suit
your environment. If unsure, choose direct JDBC.
To set up a direct JDBC connection:
If you plan to set up a direct JDBC connection to Oracle, you will need to copy the Oracle JDBC driver to
your Confluence installation.
1. Download the latest compatible database driver. Links to the appropriate database drivers are
available on this page: Database JDBC Drivers.
2. Copy the driver JAR file to the <Confluence installation>/confluence/WEB-INF/lib folder
in your new Confluence installation.
To set up a datasource connection:
If you plan to set up a datasource connection to Oracle, follow the steps described in Configuring a
datasource connection.
Start Confluence, and go to the Confluence Setup Wizard in your browser. Follow these steps to set up the
new configuration:
1. Follow the initial steps in the Confluence Setup Guide.
2. When prompted to choose an evaluation or production installation, choose production installation.
3. When prompted to choose My own database, then select your database type (Oracle).
4. Choose either the direct JDBC or the datasource connection, to suit the choice you made earlier when
setting up the Oracle database driver.
For the JDBC connection: Enter the database URL to match the JDBC URL you determined in
the previous section. Enter the user name (for example, confluenceuser) and password yo
u chose when adding the Confluence database to Oracle.
For a datasource connection: Set the JNDI name to java:comp/env/jdbc/confluence.
5. Confluence will then create the schema in Oracle. This might take a few minutes.
Congratulations! Confluence is now using your Oracle database to store its data.
Troubleshooting
The following page contains common issues encountered when setting up your Oracle database to
work with Confluence: Known Issues for Oracle.
If Confluence complains that it is missing a class file, you may have placed the JDBC driver in the
wrong folder.
If none of the above describes your issue, please create a support ticket at http://support.atlassian.co
m and be sure to include your logs (found in <CONFLUENCE-INSTALLATION>/logs and <CONFLUE
NCE-HOME>/logs).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 562
If you have been evaluating Confluence and wish to transfer your On this page:
data to a new database, consult the following guide first: Migrating to
Another Database. Step 1.
If you are migrating from another database, consult the following Check the
guide first: Migrating to Another Database. prerequisit
es
Step 2. Install PostgreSQL Step 2.
Install
If you do not already have an operational PostgreSQL database, install it PostgreSQ
now. L
Step 3. Set
up your
PostgreSQ
L database
and user
Step 4.
Install
Confluenc
e and the
PostgreSQ
L database
driver
Step 5. Set
up your
database
connection
in the
Confluenc
e Setup
Wizard
Notes
Troublesho
oting
Related pages:
Database
Configurati
on
Known
issues for
PostgreSQ
L
1. Download and install PostgreSQL. Please note the following information when installing PostgreSQL:
The password that you are prompted to provide during the installation process is for the
'postgres' account, which is the database root-level account, sometimes called the super user
('postgres'). Remember this username and password. You will need it each time you log in to
the database.
The default port for PostgreSQL is 5432. If you decide to change the default port, please
ensure that your new port number does not conflict with any services running on that port. You
will also need to remember to update all further mentions of the database port.
Choose the locale that best fits your geographic location.
Do not launch Stack Builder at the completion of the installer.
Next you need to create a database within PostgreSQL to hold your Confluence data, and a database user
with authority to access that database.
1. Create a database user (for example confluenceuser)
Your new user must be able to create database objects and must have can login permission.
2.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 563
You can use pgAdmin as an alternative to the command line to complete this step. If you used the graphical
installer when installing PostgreSQL, pgAdmin will be already installed on your computer.
Decide whether you will set up a direct JDBC connection or a datasource connection to PostgreSQL, to
suit your environment. If unsure, choose direct JDBC.
Install Confluence if you have not done so already. See the Confluence Installation Guide.
If you plan to set up a direct JDBC connection to PostgreSQL, you can run the Confluence
installation and move directly on to the Confluence Setup Wizard, as described below. The PostgreSQ
L JDBC driver is bundled with Confluence, as documented on this page: Database JDBC Drivers.
If you plan to set up a datasource connection to PostgreSQL:
Stop immediately after the Confluence installation, before opening the Confluence Setup
Wizard in your browser. If you have already got part-way through the Confluence Setup Wizard,
stop at the database setup step. You will be able to restart the setup wizard at the same step
later.
Follow the steps described in Configuring a datasource connection.
Start Confluence, go to the Confluence Setup Wizard in your browser, and follow these steps:
1. When prompted to choose an evaluation or production installation, choose production installation.
2. When prompted to choose My own database, then select your database type (PostgreSQL).
3. Choose either the direct JDBC or the datasource connection, to suit the choice you made earlier.
For the JDBC connection:
When prompted for a Driver Class Name, enter:
org.postgresql.Driver
jdbc:postgresql://<server>:<port>/<database>
Note: If you need to connect to an SSL database, add the ssl=true parameter in the
database URL. For example: jdbc:postgresql://localhost:5432/confluence
?ssl=true
Enter the username (for example confluenceuser) and password you chose earlier
when setting up your Confluence database.
For a datasource connection: Set the Datasource Name to the following: java:comp/env/
jdbc/confluence
That's it - Confluence is now using your PostgreSQL database to store its data.
Notes
If the server that is hosting the PostgreSQL database is not the same server as Confluence, then
please ensure that the Confluence server can contact the database server. Please also refer to the Po
stgreSQL documentation on how to set up pg_hba.conf. If the pg_hba.conf file is not set properly,
remote communication to the PostgresSQL server will fail.
Running SQL queries: For ongoing maintenance of your server, you can continue to use PGAdmin III
as your SQL browser.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 564
Troubleshooting
If you get the following error message, verify that you have given the confluenceuser user all the
required database permissions when connecting from localhost.
If Confluence complains that it is missing a class file, you may have placed the JDBC driver in the
wrong folder.
If you are unable to connect to the database from Confluence and they are on different machines,
most likely you have a firewall in between the two machines or your pg_hba.conf file is
misconfigured. Verify that your firewall is set to allow connections through 5432 or double check your
hba configuration.
The following page contains common issues encountered when setting up your PostgreSQL database
to work with Confluence: Known issues for PostgreSQL.
If none of the above describes your issue, please create a support ticket at http://support.atlassian.co
m and be sure to include your logs (found in <CONFLUENCE-INSTALLATION>/logs and <CONFLUE
NCE-HOME>/logs).
If you do not already have an operational SQL Server database, download the installation package from the
Microsoft SQL Server download page and follow the instructions on MSDN.
In this step you will create a database within SQL Server to hold your Confluence data, and a database user
with authority to access that database. The database user should be in the db_owner role.
1. Identify which character encoding to use. To do this, check the encoding currently used by your applic
ation server and Confluence. All three must use compatible encoding. For example, the default SQL
Server encoding of UCS-2 is compatible with UTF-8.
2. Using your SQL administrator permissions, create a new database in SQL Server.
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 565
3. If you set your application server and Confluence to use an encoding incompatible with UCS-2, specify
that character encoding for the database.
4. Set the default collation for the database to be 'SQL_Latin1_General_CP1_CS_AS' (case sensitive).
You can do this by issuing the following SQL query:
Note: if you receive an error stating 'The database could not be exclusively locked to perform the
operation', you may need to prevent other connections by setting the mode to single user for the
transaction:
5. Configure the database to use the isolation level, 'Read Committed with Row Versioning'. You can do
this by issuing the following SQL query:
Return value:
1 = READ_COMMITTED_SNAPSHOT option is ON. Read operations under the read-committed
isolation level are based on snapshot scans and do not acquire locks.
0 = READ_COMMITTED_SNAPSHOT option is OFF (default). Read operations under the
read-committed isolation level use share locks.
6. Using your SQL administrator permissions, create a new SQL user account for Confluence (for
example, confluenceuser). Give this user full create, read and write permissions for the database
tables. Note that Confluence must be able to create its own schema.
Refer to the documentation for your database for more information on how to create a new database
user.
Decide whether you will set up a direct JDBC connection or a datasource connection to SQL Server, to
suit your environment. If unsure, choose direct JDBC.
Install Confluence if you have not done so already. See the Confluence Installation Guide.
If you plan to set up a direct JDBC connection to SQL Server, you can run the Confluence
installation and move directly on to the Confluence Setup Wizard, as described below. The SQL
Server JDBC driver is bundled with Confluence, as documented on this page: Database JDBC Drivers
.
If you plan to set up a datasource connection to SQL Server:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 566
Stop immediately after the Confluence installation, before opening the Confluence Setup
Wizard in your browser. If you have already got part-way through the Confluence Setup Wizard,
stop at the database setup step. You will be able to restart the setup wizard at the same step
later.
Follow the steps described in Configuring a SQL Server Datasource in Apache Tomcat.
Start Confluence, and go to the Confluence Setup Wizard in your browser. Follow these steps to set up the
new configuration:
1. Follow the initial steps in the Confluence Setup Guide.
2. When prompted to choose an evaluation or production installation, choose production installation.
3. When prompted to choose My own database, then select your database type (Microsoft SQL Server
).
4. Choose either the direct JDBC or the datasource connection, to suit the choice you made earlier when
setting up the SQL Server database driver.
For the JDBC connection:
Use the default Driver Class Name:
com.microsoft.sqlserver.jdbc.SQLServerDriver
Enter your Database URL in the following format, replacing your hostname, port and
database name:
jdbc:sqlserver://<hostname>:<port>;database=<database>
Enter the username (for example, confluenceuser) and password you chose earlier.
For a datasource connection: Set the Datasource Name to java:comp/env/jdbc/conflue
nce
Congratulations! Confluence is now using your SQL Server database to store its data.
We are replacing the open source jTDS driver for Microsoft SQL Server with the official Microsoft JDBC
Driver for SQL Server. From Confluence 6.4, all new Confluence installations will use the Microsoft JDBC
Driver for SQL Server by default.
Existing instances will continue to use the bundled jTDS driver. We'll help you migrate to the Microsoft driver
in a later release.
If you have an existing Confluence installation and need to set up a test environment that replicates your
production environment (including the jTDS driver), you can do this in the setup wizard by selecting Unsupp
orted Database in the database selection screen and then specifying the jTDS driver as follows:
Driver class name: net.sourceforge.jtds.jdbc.Driver mkfdvd
Database URL (example format): jdbc:jtds:sqlserver://<hostname>:<port>/<database>
Hibernate dialect: com.atlassian.confluence.impl.hibernate.dialect.SQLServerDia
lect
Troubleshooting
If you get the following error message, verify that you have given the confluenceuser user all the
required database permissions when connecting from localhost.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 567
The following page contains common issues encountered when setting up your SQL Server database
to work with Confluence: Known Issues for SQL Server.
Additional ports may be required to be opened. See this support document from Microsoft about the
ports required for SQL Server.
If none of the above describes your issue, please create a support ticket at http://support.atlassian.co
m and be sure to include your logs (found in <CONFLUENCE-INSTALLATION>/logs and <CONFLUE
NCE-HOME>/logs).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 568
[mysqld]
...
character-set-server=utf8
collation-server=utf8_bin
...
[mysqld]
...
default-storage-engine=INNODB
...
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 569
[mysqld]
...
max_allowed_packet=256M
...
[mysqld]
...
innodb_log_file_size=2GB
...
Ensure that the global transaction isolation level of your Database had been set
to READ-COMMITTED.
[mysqld]
...
transaction-isolation=READ-COMMITTED
...
In this step you will create a database within MySQL to hold your Confluence data, and a database user with
authority to access that database.
To create the database and user privileges:
1. Run the 'mysql' command as a MySQL super user. The default user is 'root' with a blank password.
2. Create an empty Confluence database schema by running this command:
3. Create the Confluence database user by running this command. Replace 'confluenceuser' and
'confluencepass' with a username and password of your choice. If Confluence is not running on the
same server as your MySQL database server, replace 'localhost' with the hostname or IP address of
the Confluence server:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 570
Install Confluence if you have not done so already. See the Confluence Installation Guide. Stop Confluence
immediately after the installation, before opening the Confluence Setup Wizard in your browser , and
follow the steps below.
If you have already got part-way through the Confluence Setup Wizard, stop Confluence at the database
setup step and follow the steps below. You will be able to restart the setup wizard at the same step later (if
you installed Confluence as a service you'll need to restart the service before continuing with step 8 below).
If you are upgrading Confluence to a later version, and you are already using the recommended
MySQL driver (JDBC Connector/J 5.1), you can skip the instructions in this section. The Confluence
upgrade task will automatically copy over your existing driver to the upgraded installation.
If you are installing Confluence, or you are upgrading Confluence and not using the recommended MySQL
driver (JDBC Connector/J 5.1), follow the steps below.
Choose whether you will set up a direct JDBC connection or a datasource connection to MySQL, to suit
your environment. If unsure, choose direct JDBC.
To set up a direct JDBC connection:
If you plan to set up a direct JDBC connection to MySQL, you will need to copy the MySQL JDBC driver to
your Confluence installation.
1. Get the MySQL driver:
If you are installing Confluence, download the recommended MySQL driver . Links to the
appropriate database drivers are available on this page: Database JDBC Drivers.
You can download either the .tar.gz or the .zip archive. Extract the driver JAR file (for
example, mysql-connector-java-x.x.x-bin.jar, where x.x.x is a version number)
from the archive.
If you are upgrading Confluence to a later version, and you are not using the
recommended MySQL driver (JDBC Connector/J 5.1), copy the driver JAR file from your
existing Confluence installation before you upgrade. The driver will be in the <Confluence
installation> /confluence/WEB-INF/lib folder.
2. Copy the driver JAR file to the <Confluence installation> /confluence/WEB-INF/lib fol
der in your new or upgraded Confluence installation.
To set up a datasource connection:
If you plan to set up a datasource connection to MySQL, follow the steps described in Configuring a
datasource connection.
If you are using a existing database, use the status command to verify database character encoding
information. The results should be UTF-8. See Configuring Database Character Encoding.
Start Confluence (if you're running Confluence as a service, restart the service), and go to the Confluence
Setup Wizard in your browser. Follow these steps to set up the new configuration:
1. Follow the initial steps in the Confluence Setup Guide.
2. When prompted to choose an evaluation or production installation, choose production installation.
3. When prompted to choose My own database, then select your database type (MySQL).
You may see a warning that a driver is required. You downloaded or copied the driver in step 6 so you
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation
3.
571
Congratulations! Confluence is now using your MySQL database to store its data.
Troubleshooting
If you get the following error message, verify that you have given the confluenceuser user all the
required database permissions when connecting from localhost.
The following page contains common issues encountered when setting up your MySQL database to
work with Confluence: Known issues for MySQL
If Confluence complains that it is missing a class file, you may have placed the JDBC driver in the
wrong folder.
If none of the above describes your issue, please create a support ticket at http://support.atlassian.co
m and be sure to include your logs (found in <CONFLUENCE-INSTALLATION>/logs and <CONFLUE
NCE-HOME>/logs).
Embedded H2 Database
To enable you to try Confluence without setting up Related pages:
an external database, your Confluence installation
includes an embedded H2 database. Confluence Home and other
important directories
The embedded H2 database is used by default when Database Configuration
you choose the Trial installation path.
The embedded database files are stored in your Confluence home directory <confluence-home>/databa
se.
The embedded H2 database is only supported while you are evaluating Confluence. You must migrate to a s
upported external database before using Confluence as a production system.
To find out if you are still using the embedded database, go to
DBVisualizer is just one database administration tool. You can use any administration tool that supports
embedded H2 databases. The steps will be similar.
1. Shut down Confluence.
2. Back up your <confluence-home>/database directory.
3. Launch DBVisualizer.
4. Choose Create new database connection and follow the prompts to set up the connection.
The information you'll need is:
Database driver: H2 embedded
Database Userid: sa
Database password: leave this field blank
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 572
Database filename:<confluence-home>/database/h2db
leave off the .h2.db file extension.
5. Connect to the database.
Refer to the DBVisualizer documentation for help using DBVisualizer.
Alternatively you can connect using the browser based H2 console. The easiest way to access the console is
to double click the H2 database jar file at <installation-directory>\confluence\WEB-INF\lib\h
2-x.x.x.jar.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 573
On this page:
Limitations of database migration
Database migration
Method one standard procedure
Step 1: Take note of your
add-ons
Step 2: Back up your data
Step 3: Set up the new
database
Step 4. Install Confluence
(same version number) in a
new location
Step 5. Download and
install the database driver if
necessary
Step 6. Run the Confluence
setup wizard and copy your
data to your new database
Step 7. Re-install your
add-ons
Step 8. Check settings for
new machine
Method two for installations with
a large volume of attachments
Before you start
Step 1: Take note of your
add-ons
Step 2: Back up your data
Step 3: Set up the new
database
Step 4. Install Confluence
(same version number) in a
new location
Step 5. Download and
install the database driver if
necessary
Step 6. Run the Confluence
setup wizard and copy your
data to your new database
Step 7: Copy your
attachments across
Step 8. Re-install your
add-ons
Step 9. Check settings for
new machine
A note about case sensitivity in
your database
Setting up a New
Confluence Instance
Migrating an Existing
Confluence Instance to a
Different Database
Troubleshooting
Related pages:
Database Configuration
Confluence Home and other
important directories
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 574
Note: The XML export built into Confluence is not suited for the backup or migration of large data sets. There
are a number of third party tools that may be able to assist you with the data migration. If you would like help
in selecting the right tool, or help with the migration itself, we can put you in touch with one of the Atlassian
Experts.
Database migration
There are two ways you can perform the migration, both described on this page:
1. Method one is the standard procedure.
2. Use method two if the total size of attachments in your installation exceeds 500MB.
Take note of the add-ons (plugins) currently installed and enabled in Confluence, so that you can reinstate
them later. Make a note of the following for each add-on:
Add-on name
Version
Enabled or disabled status. This is useful if you have enabled or disabled modules yourself, making
your configuration differ from the default.
1. Create an XML backup of your existing data, via the Confluence administration console. See Manu
ally Backing Up the Site. Make a note of the location where you put the XML file. You will need it later
to import your Confluence data into your new database.
2. Shut down Confluence.
3. Make a copy of the Confluence Home directory. This is a precautionary measure, to ensure you can
recover your data if it is mistakenly overwritten.
4. If you are using an external database, make a separate backup using the utilities that were installed
with that database. This also is a precautionary measure.
Choose the database setup instructions for your new database, and follow those instructions to do the
following:
Install the database server.
Perform any required configuration of the database server, as instructed.
Add the Confluence database and user. Make a note of the username and password that you define in
this step. You will need them later, when running the Confluence Setup Wizard.
Now you will install Confluence again, with a different home directory path and installation path.
Note: You must use the same version of Confluence as the existing installation. (If you want to upgrade
Confluence, you must do it as a separate step.) For example, if your current site is running Confluence 5.1.2,
your new installation must also be Confluence 5.1.2.
When running the Confluence installer:
Choose Custom Install. (Do not choose to upgrade your existing installation.)
Choose a new destination directory. This is the installation directory for your new Confluence. It
must not be the same as the existing Confluence installation.
Choose a new home directory. This is the data directory for your new Confluence. It must not be the
same as the existing Confluence installation.
Note that Confluence bundles some database drivers, but you'll need to install the driver yourself if it is not
bundled. Follow the database setup instructions for your new database, to download and install the database
driver if necessary.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 575
Step 6. Run the Confluence setup wizard and copy your data to your new database
Note: If you choose not to restore during the Confluence setup wizard, you can do the import later. Go to the
Confluence administration console and choose to restore an XML backup. See Site Backup and Restore.
Re-install any add-ons (plugins) that are not bundled with Confluence.
Use the same version of the add-on as on your old Confluence site.
The data created by the add-ons will already exist in your new Confluence site, because it is included
in the XML backup.
If you are moving Confluence to a different machine, you need to check the following settings:
Configure your new base URL. See Configuring the Server Base URL.
Check your application links. See Linking to Another Application.
Update any gadget subscriptions from external sites pointing to this Confluence site. For example, if
your JIRA site subscribes to Confluence gadgets, you will need to update your JIRA site.
Review any other resources that other systems are consuming from Confluence.
These instructions only apply to attachments stored in the file system. If you store attachments in the
database see Attachment Storage Configuration to find out how to migrate between different attachment
storage methods.
Take note of the add-ons (plugins) currently installed and enabled in Confluence, so that you can reinstate
them later. Make a note of the following for each add-on:
Add-on name
Version
Enabled or disabled status. This is useful if you have enabled or disabled modules yourself, making
your configuration differ from the default.
1. Create an XML backup of your existing data, via the Confluence administration console. See Manu
ally Backing Up the Site. Make a note of the location where you put the XML file. You will need it later
to import your Confluence data into your new database.
2. Shut down Confluence.
3. Make a copy of the attachments directory (<CONFLUENCE-HOME-DIRECTORY>\attachments) in
your Confluence Home directory. You will need it later to copy your Confluence attachments data into
your new Confluence installation.
4. If you are using an external database, make a separate backup using the utilities that were installed
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 576
4.
Choose the database setup instructions for your new database, and follow those instructions to do the
following:
Install the database server.
Perform any required configuration of the database server, as instructed.
Add the Confluence database and user. Make a note of the username and password that you define in
this step. You will need them later, when running the Confluence Setup Wizard.
Now you will install Confluence again, with a different home directory path and installation path.
Note: You must use the same version of Confluence as the existing installation. (If you want to upgrade
Confluence, you must do it as a separate step.) For example, if your current site is running Confluence 5.1.2,
your new installation must also be Confluence 5.1.2.
When running the Confluence installer:
Choose Custom Install. (Do not choose to upgrade your existing installation.)
Choose a new destination directory. This is the installation directory for your new Confluence. It
must not be the same as the existing Confluence installation.
Choose a new home directory. This is the data directory for your new Confluence. It must not be the
same as the existing Confluence installation.
Note that Confluence bundles some database drivers, but you'll need to install the driver yourself if it is not
bundled. Follow the database setup instructions for your new database, to download and install the database
driver if necessary.
Step 6. Run the Confluence setup wizard and copy your data to your new database
Note: If you choose not to restore during the Confluence setup wizard, you can do the import later. Go to the
Confluence administration console and choose to restore an XML backup. See Site Backup and Restore.
Re-install any add-ons (plugins) that are not bundled with Confluence.
Use the same version of the add-on as on your old Confluence site.
The data created by the add-ons will already exist in your new Confluence site, because it is included
in the XML backup.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 577
Step 9. Check settings for new machine
If you are moving Confluence to a different machine, you need to check the following settings:
Configure your new base URL. See Configuring the Server Base URL.
Check your application links. See Linking to Another Application.
Update any gadget subscriptions from external sites pointing to this Confluence site. For example, if
your JIRA site subscribes to Confluence gadgets, you will need to update your JIRA site.
Review any other resources that other systems are consuming from Confluence.
'Collation' refers to a set of rules that determine how data is sorted and compared. Case sensitivity is one
aspect of collation. Other aspects include sensitivity to kana (Japanese script) and to width (single versus
double byte characters).
Case sensitive or case insensitive collation how should you create your Confluence database? What about
when you are migrating your existing Confluence instance from one database to another?
For new Confluence instances, we recommend using case sensitive collation for your Confluence database.
This is the default collation type used by many database systems.
Note: Even if the database is configured for case sensitive collation, Confluence reduces all usernames to
lower case characters before storing them in the database. For example, this means that 'joebloggs',
'joeBloggs' and 'JoeBloggs' will be treated as the same username.
The default Confluence configuration uses case sensitive database collation. This is typical of databases
created under default conditions. If you are migrating from this type of configuration to a new database, we
recommend that the new database uses case sensitive collation. If you use case insensitive collation, you
may encounter data integrity problems after migration (for example, via an XML import) if data stored within
your original Confluence site required case sensitive distinctions.
Troubleshooting
See our troubleshooting guide if you're unable to restore your XML backup.
MySQL
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 578
jdbc:mysql://hostname:port/database?useUnicode=true&characterEncoding
=utf8
If you are modifying confluence.cfg.xml directly rather than via the Confluence Installation GUI,
you'll need to escape out the & in the URL string as this is a reserved XML token and will break the
syntax when the XML is parsed. An effective URL could be similar to:
<property
name="hibernate.connection.url">jdbc:mysql://hostname:port/data
base?useUnicode=true&characterEncoding=utf8</property>
MySQL
2. You will also need to set the Server Characterset to utf8. This can be done by adding the
following in my.ini for Windows or my.cnf for other OS. It has to be declared in the Server section,
which is the section after [mysqld]:
[mysqld]
default-character-set=utf8
If the above option does not work, try using character_set_server=utf8 in lieu of default-character-set=
utf8
3. Use the status command to verify database character encoding information.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 579
4. In some cases, the individual tables collation and character encoding may differ from the one that the
database as a whole has been configured to use. Please use the command below to ensure all tables
within your Confluence database are correctly configured to use UTF-8 character encoding and binary
UTF-8 collation:
use confluence;
show table status;
Check for the value listed under the Collation column, to ensure it has been set to utf8_bin (that is,
case-sensitive) collation for all tables.
If not, then this can be changed by the following command, executed for each table in the Confluence
database:
Please substitute the <tablename> above, with each table within the confluence database.
Relevant MySQL manual for more detailed explanation:
Specifying Character Sets and Collations documentation.
Connection Character Sets and Collations.
SHOW TABLE STATUS Syntax.
ALTER TABLE Syntax.
PostgreSQL
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 580
Please note that international characters sets are only fully supported and functional when using PostgreSQL
8.1 and above under Microsoft Windows.
Please make sure you check the following to ensure proper handling of international characters in
your database
When PostgreSQL creates an initial database cluster, it sets certain important configuration options based on
the host enviroment. The command responsible for creating the PostgreSQL environment initdb will check
environment variables such as LC_CTYPE and LC_COLLATE (or the more general LC_ALL) for settings to
use as database defaults related to international string handling. As such it is important to make sure that
your PostgreSQL environment is configured correctly before you install Confluence.
To do this, connect to your PostgreSQL instance using pgsql and issue the following command:
SHOW LC_CTYPE;
If LC_CTYPE is set to either "C" or "POSIX" then certain string functions such as converting to and from
upper and lower case will not work correctly with international characters. Correct settings for this value take
the form <LOCALE>.<ENCODING> (en_AU.UTF8 for example).
If your LC_CTYPE is incorrect please check the PostgreSQL documentation for information on configuring
database localization. It is not easy to change these settings with a database that already contains data.
Before proceeding with the following changes, please backup your database.
This example shows how to change your database from latin1 to utf8, where your database is named
"confluence".
1. Dump the database (except the plugindata table) to a text file using the mysqldump tool from the
command-line :
mysqldump -p --default-character-set=latin1 -u <username>
--skip-set-charset --ignore-table='`confluence`.plugindata'
--ignore-table='`confluence`.attachmentdata' confluence >
confluence_database.sql
2. Dump the plugindata and attachmentdata tables to a text file using mysqldump separately. This is
done separately as the recode step below can corrupt the binary data in these tables :
mysqldump -p --default-character-set=latin1 -u <username>
--skip-set-charset confluence attachmentdata plugindata >
confluence_blobtables.sql
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 581
In MySQL:
1. DROP DATABASE confluence;
2. CREATE DATABASE confluence CHARACTER SET utf8 COLLATE utf8_bin;
Reimport the UTF-8 text file, and also the plugindata and attachmentdata dumps:
1. mysql -u <username> -p --default-character-set=utf8
--max_allowed_packet=64M confluence < /home/confluence/confluence_utf8.sql
2. mysql -u <username> -p --default-character-set=latin1
--max_allowed_packet=64M confluence <
/home/confluence/confluence_blobtables.sql
To support large imports, the parameter '--max_allowed_packet=64M' used above sets the maximum size of
an SQL statement to be very large. In some circumstances, you may need to increase it further, especially if
attachments are stored in the database.
Finally, since the plugindata and attachmentdata tables were not actually converted before, you need to
instruct MySQL to convert all the text fields manually:
1. ALTER TABLE plugindata CONVERT TO CHARACTER SET utf8;
2. ALTER TABLE attachmentdata CONVERT TO CHARACTER SET utf8;
See Troubleshooting Character Encodings for a number of tests you can run to ensure your database
encoding is correct.
If database queries are taking too long to perform, and your application is becoming unresponsive, you can
configure a timeout for database queries. There is no default timeout in Confluence.To configure a database
query timeout, do the following on your test server:
1. Shut down Confluence.
2. Extract databaseSubsystemContext.xml from the confluence-x.x.x.jar that is in confluence/WE
B-INF/lib/, and put a copy in confluence/WEB-INF/classes/.
<bean id="tenantedTransactionManager"
class="org.springframework.orm.hibernate.HibernateTransactionManager"
plugin:available="true">
<property name="sessionFactory" ref="sessionFactory"/>
<property name="defaultTimeout" value="120"/>
</bean>
The timeout is measured in seconds and will forcibly abort queries that take longer than this. In some cases,
these errors are not handled gracefully by Confluence and will result in the user seeing the Confluence error
page.
4. Start Confluence.
Once the timeout is working properly in your test environment, migration the configuration change to Confluence.
You will need to reapply these changes when upgrading Confluence, as the original databaseSubsystemC
ontext.xml file changes from version to version.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 582
A common administration issue when configuring Confluence is identifying database connectivity problems. This
page tells you about a helper utility, in the form of a JSP page, that can help you to isolate database connectivity
issues. It checks whether you can connect to a database with your application server. If your application server
cannot connect to the database, Confluence will not be able to connect to the database either.
1. Record the DB settings you are using for your direct JDBC or datasource connection in the 'Configure
Database' step of your setup.
2. Download the attached testdatabase.jsp to your <confluence-install>\confluence directory.
3. Rename your <confluence-install>\confluence\WEB-INF\web.xml file to backup web.xml.
This disables redirection.
4. Restart Confluence.
5. Go to http://MY-CONF-SERVER:MY-CONF-PORT/testdatabase.jsp.
6. Check that your database driver is loaded into memory. If not, check the system classpath for the JDBC
driver file, and that the driver is in the <confluence-install>\common\lib directory as described in
these instructions.
7. Enter the DB settings you recorded and test the database. If an error appears, check that the db service
is running, the location matches, and that any users specified actually exist with the right login and
permissions. You may be able to find a workaround by Googling the error.
8. After correcting the error, rename <confluence-install>\confluence\WEB-INF\backup
web.xml back to web.xml.
Notes
If you use this utility, please let us know ways in which we could improve it or leave helpful hints for others here.
For a comprehensive set of database instructions that might be helpful for troubleshooting, please refer to the
following links:
PostgreSQL
MySQL
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 583
If you are still stuck after attempting the suggestions above, raise a request with our support team with
information on your database setup.
Surviving Database Connection Closures
When a database server reboots or a network failure has occurred, all connections in the database connection
pool are broken. To overcome this issue, Confluence would normally need to be restarted.
However, database connections in the database connection pool can be validated by running a simple SQL
query. If a broken database connection is detected in the pool, a new one is created to replace it.
To do this, you can specify an optional validation query for your database connection. Depending on whether
you are using a direct JDBC URL, or a data source, this is configured differently.
Different database types have slightly different SQL syntax requirements for their validation query. The validation
query should be as simple as possible, as this is run every time a connection is retrieved from the pool.
The following validation queries are recommended for the following types of databases:
MySQL select 1
PostgreSQL select 1
confluence.cfg.xml (excerpt)
...
<property name="hibernate.c3p0.acquire_increment">1</property>
<property name="hibernate.c3p0.idle_test_period">100</property>
<property name="hibernate.c3p0.max_size">60</property>
<property name="hibernate.c3p0.max_statements">0</property>
<property name="hibernate.c3p0.min_size">20</property>
<property name="hibernate.c3p0.timeout">30</property>
<property name="hibernate.c3p0.validate">true</property>
<property name="hibernate.c3p0.preferredTestQuery">select
1</property>
...
4. Save confluence.cfg.xml
5. If you're using Confluence 5.10.3 or earlier you'll need to add the following system property with the
validation query for your database.
For example:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 584
-Dc3p0.preferredTestQuery="select 1"
6. Restart Confluence
server.xml (excerpt)
...
<Resource name="jdbc/confluence" auth="Container"
type="javax.sql.DataSource"
username="postgres"
password="postgres"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://localhost:5432/yourDatabaseName"
maxTotal="60"
maxIdle="20"
validationQuery="select 1" />
...
4. Save conf/server.xml
5. Restart Confluence (or the Tomcat installation running Confluence).
You should now be able to recover from a complete loss of all connections in the database connection pool
without the need to restart Confluence or the application server running Confluence.
Performance Considerations:
Setting this option has a performance impact. The overall decrease in performance should be minimal, as
the query itself is quick to run. In addition, the query will only execute when you make a connection. Thus,
if the connection is kept for the duration of a request, the query will only occur once per request.
If you are running a large Confluence installation, you may wish to assess the performance impact of this
change before implementing it.
Configuring a datasource connection
This guide covers how to configure a JNDI datasource connection to your
database. With this type of connection, Confluence asks the application
server (Tomcat) for your database connection information.
If you'd prefer to use a JDBC connection see the guide for your database:
Database Setup for PostgreSQL
Database Setup for SQL Server
Database Setup For MySQL
Database Setup for Oracle
Direct JDBC is the most common way to connect Confluence to your
database and is the easiest method when it comes time to upgrade
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 585
1. Stop Confluence
In the Confluence setup wizard, you'll be prompted to choose your database. At this point, you should:
1. Use bin/stop-confluence.sh or bin/stop-confuence.bat to stop Confluence.
2. Back up the following files, in case you need to revert your changes:
<installation-directory>/conf/server.xml
<installation-directory>/confluence/WEB-INF/web.xml
<home-directory>/confluence.cfg.xml
3. Insert the following DataSource Resource element for your specific database directly after the lines
above (inside the Context element, directly after the opening <Context.../> line, before Mana
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
3.
Confluence 6.4 documentation 586
ger).
PostgreSQL...
If you're using Confluence 6.3 or earlier, you'll need to specify the jTDS driver for SQL Server. See
Configuring a SQL Server Datasource in Apache Tomcat in our 6.3 documentation for a sample
configuration.
Microsoft SQL Server...
driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://<host>:1433;database=<database-name>"
maxTotal="60"
maxIdle="20"
validationQuery="select 1"/>
MySQL...
url="jdbc:mysql://<host>:3306/<database-name>?useUnicode=true&
amp;characterEncoding=utf8"
maxTotal="60"
maxIdle="20"
defaultTransactionIsolation="READ_COMMITTED"
validationQuery="Select 1"/>
Oracle...
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 587
Replace <database-user>, <password>, <host> and <database-name> (or <SID> for Oracle)
with details of your own database. You may also need to change the port, if your database server is
not running on the default port.
4. Configure the connection pool and other properties. See the Apache Tomcat 8 Datasource
documentation for more information.
Configurable properties...
Here are the configuration properties for Tomcat's standard data source resource factory (org.ap
ache.tomcat.dbcp.dbcp.BasicDataSourceFactory):
driverClassName - Fully qualified Java class name of the JDBC driver to be used.
maxTotal - The maximum number of active instances that can be allocated from this pool
at the same time.
maxIdle - The maximum number of connections that can sit idle in this pool at the same
time.
maxWaitMillis - The maximum number of milliseconds that the pool will wait (when there
are no available connections) for a connection to be returned before throwing an exception.
password - Database password to be passed to the JDBC driver.
url - Connection URL to be passed to the JDBC driver. (For backwards compatibility, the
property driverName is also recognized.)
user - Database username to be passed to the JDBC driver.
validationQuery - SQL query that can be used by the pool to validate connections
before they are returned to the application. If specified, this query MUST be an SQL
SELECT statement that returns at least one row. When a database server reboots, or there
is a network failure, all the connections in the connection pool are broken and this normally
requires a application server reboot. However, the Commons DBCP (Database Connection
Pool) used by Tomcat can validate connections before issuing them by running a simple
SQL query, and if a broken connection is detected, a new one is created to replace it. To do
this, you will need to set the "validationQuery" option on the database connection pool.
5. If you plan to use collaborative editing, you'll need to make sure:
You're using a supported database driver. Collaborative editing will fail if you're using an
unsupported or custom JDBC driver or driverClassName in your datasource. See Database
JDBC Drivers for the list of drivers we support.
Your database connection pool allows enough connections to support both Confluence and
Synchrony (which defaults to a maximum pool size of 15)
You're using simple username and password authentication for your database.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 588
2. Insert the following element just before </web-app> near the end of the file:
<resource-ref>
<description>Connection Pool</description>
<res-ref-name>jdbc/confluence</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
Now that your datasource is configured, you can continue with the setup wizard.
1. Use bin/start-confluence.sh or bin/start-confuence.bat to restart Confluence
2. Go to http://localhost:8090 to return to the setup wizard.
3. When prompted choose My own database > Datasource.
4. Enter the JNDI name of your datasource, for example,java:comp/env/jdbc/confluence
5. Follow the prompts to finish setting up Confluence.
<property name="hibernate.setup"><![CDATA[true]]></property>
<property
name="hibernate.dialect"><![CDATA[com.atlassian.hibernate.dialec
t.MySQLDialect]]></property>
<property
name="hibernate.connection.datasource"><![CDATA[java:comp/env/jd
bc/confluence]]></property>
Restart Confluence.
If you're upgrading Confluence (manually or using the installer) you will need to:
Stop Confluence (if you have attempted to start it).
Copy your database driver into the <installation-directory>/lib directory.
Edit <installation-directory>/conf/server.xml and add your datasource resource.
Edit <installation-directory>/confluence/WEB-INF/web.xml to configure Confluence to
use this datasource.
If you forget to do these steps, Confluence will not start up after upgrade and you'll see the following error:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 589
Atlassian recommends establishing a backup strategy using a native database tool for production
installations of Confluence.
By default, Confluence backs up all data and attachments once a day to an XML backup file. These files are
called XML site backups, and are stored in the backups directory of Confluence home. You can also create
XML site backups manually. This mechanism is intended for small to medium-sized deployments of Confluence.
It is not intended for use with large deployments with lots of pages and attachments (see below).
Restore your site from an XML site backup
Manually create an XML site backup
Configuring Backups
User Submitted Backup & Restore Scripts
XML site backups are fine for most small to medium-sized instances of Confluence, containing a few thousand
pages and attachments. However, large instances of Confluence may find that backups become slow to create
and use large amounts of disk space.
Note: Plugins are not included in the XML backup. After importing your backup into a new Confluence site, you
will need to re-install all plugins (add-ons) that are not bundled with Confluence. (The plugindata table is not
backed up in a manual backup.)
XML site backups are unsuitable for installations of Confluence that contain thousands of pages, as XML
backups take progressively longer to complete as the amount of text increases. Another issue with XML site
backups is that Confluence instances with gigabytes of attachments will consume disk space rapidly. This is
because each site backup contains all content needed for a site restore. For example, if a 1 GB instance of
Confluence is backed up daily, it will create 30 GB of backups per month if left unattended. When administering
a large instance, you can reduce disk space by setting XML site backups to exclude attachments, then manually
scheduling a backup of your attachments from the Confluence home directory or database. The backup
manager can save space by saving changed files instead of all content.
Acceptable Unacceptable XML site backup minus attachments, plus manual backup of attachments
Creation Delay is the time it takes to create an XML site backup minus attachments.
Disk Usage can be estimated by multiplying the frequency of your XML site backups by their current size.
Manual backups
Confluence's Attachment Storage Configuration can be set to store attachments in the Confluence home
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 590
Backing up the whole home directory is the safest option, however most files and directories are populated
on startup and can be ignored. At minimum, these files/directories must be backed up:
<conf-home>/confluence.cfg.xml
<conf-home>/attachments
The rest of the directories will be auto-populated on start up. You may also like to backup these directories:
<conf-home>/config if you have modified your ehcache.xml file.
<conf-home>/index if your site is large or reindexing takes a long time this will avoid the need for
a full reindex when restoring.
The location of the home directory is configured on installation and is specified in the confluence.init.p
roperties file. For installation created with the automatic installer the default locations are:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 591
For Clustered instances only: Backing up the whole shared home directory is the safest option, however
some files and directories are populated at runtime and can be ignored:
<conf-home>/thumbnails
<conf-home>/viewfile.
The commands to back up your database will vary depending on your database vendor, for example the
command for PostgreSQL is pg_dump dbname > outfile.
You should refer to the documentation for your particular database to find out more.
How do I restore?
Our guide on Migrating Confluence Between Servers has instructions on restoring a backup using this
technique.
Other processes
XML backups are described and used for other processes in Confluence, like upgrading and moving servers.
Using the backup strategy described above will work for those processes too.
Our upgrade guide does not require the use of an XML backup (although the earlier Confluence
upgrade procedure, and the JIRA upgrade guide, do use XML backups).
Our migrate server procedure used to set up a test server can use a SQL dump as well.
The database migration procedure uses the XML backup for small data sets. Large data sets will
require third party database migration tools.
Note: The XML export built into Confluence is not suited for the backup or migration of large data sets. There
are a number of third party tools that may be able to assist you with the data migration. If you would like help
in selecting the right tool, or help with the migration itself, we can put you in touch with one of the Atlassian
Experts.
Configuring Backups
Confluence backs up your data regularly into a On this page:
zipped XML file. By default, this backup is performed
at 2.00 a.m. each day and the backup files are Configuring Confluence Backups
stored in the backups folder under the Confluence Enabling Backup Path
Home directory. The default naming convention for Configuration
the backup files is 'backup-yyyy_MM_dd'. Notes
Confluence can write backups to both local and
mapped network drives.
From the Backup Administration section of Confluence's administration console, you can:
Include or exclude attachments in backups.
Configure a different path to store backup files. (By default, this option is not available. See below for
information about enabling the configuration option.)
Change the naming format used for the files.
You can also change the schedule of this backup using Confluence's scheduled jobs feature.
You need to have System Administrator permissions in order to configure these options.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation
4.
592
input field.
To use a different date format Enter the date format in the 'Backup File Date Pattern' input
field using the syntax described in simple date format.
To exclude attachments from backups Deselect 'Backup Attachments'. By default, this
feature is 'On'.
To specify an alternate path to store backup files (if enabled) Select ' Custom' and then enter
the path. The directory must be on either a local drive or a mounted network drive.
Notes:
By default, this option is not available. See below for information about enabling the
configuration option.
Please ensure the mapped drive is on a physical server, not a Virtual Machine image.
5. 'Save' your changes.
You can disable Confluence backups through the scheduled jobs feature.
By default, it is not possible to specify a backup path via the Confluence Administration Console. This feature
is disabled by default for security reasons. Administrators can restore this functionality by updating the
relevant configuration property as described below. However, we recommend that you turn the feature off in
production environments. For production environments, please review our Production Backup Strategy.
To enable the configuration option:
1. Edit the confluence.cfg.xml file found in the Confluence Home and other important directories.
2. Set the value of property admin.ui.allow.daily.backup.custom.location to 'true' (without
the quotation marks).
confluence.cfg.xml
<property
name="admin.ui.allow.daily.backup.custom.location">true</propert
y>
3. Restart Confluence.
If the value of the above configuration property is 'true', it will be possible to specify a backup path via the
Confluence Administration Console. If the value of this property is 'false' or the property is not present in the
configuration file, the backup path is not configurable.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 593
If you choose to enable the configuration option, and then later migrate your Confluence site to a new server
or change your architecture, you will need to update your backup location through the Confluence Admin
console (simply changing the location of your home directory will not change the backup location if this option
is enabled).
Notes
The time zone is taken from the server on which Confluence is running.
To check the time according to the server, do the following:
1. Choose the cog icon
Consider using the production backup strategy if your Confluence site is large or you are encountering
problems with your automated backup.
These scripts are user-submitted and should be used with caution as they are not covered by Atlassian technical
support. If you have questions on how to use or modify these scripts, please post them to Atlassian Answers.
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
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 594
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:
Or, using the older form of the tail command if your system does not support the standard form:
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
BACKUP_DIR="/data/web/confluence/backups"
DAYS_TO_RETAIN=14
#!/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
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 595
Good to know:
We recommend you use the Production backup strategy, especially if you have a large or
mission critical site, rather than relying on XML exports as your main backup method.
Add-ons are not included in the XML export. After importing your site export file into a new
Confluence site, you'll need to re-install all add-ons that are not bundled with Confluence as
the plugindata table is not backed up in a manual backup.
You can't import a site export file into a version of Confluence that is earlier than the one it
was exported from.
If you repeatedly experience timeout errors, try creating the export directly from Tomcat. This will speed up
the process and prevent timeouts.
For example, your URL might may normally be something like http://<domain>.com. To bypass this and
access Tomcat directly, use this URL: http://localhost:8090/confluence/admin/backup.action
. directly from your server.
The site export includes spaces (including pages, blogs, comments, attachments, and unpublished changes),
users and groups. Essentially everything in your site except add-ons.
Confluence will create the backup as a zipped XML file in your <home-directory>/backups> directory.
You'll need access to the Confluence server itself in order to retrieve this file.
By default, you can't retrieve the backup file from within Confluence. This feature is disabled for security
reasons, but you can choose to enable it. Once enabled, Confluence will prompt you to download the backup
file when the backup process finished. We recommend that you keep this feature off in production
environments.
To enable download of the backup file from within Confluence:
1. Stop Confluence.
2. Edit the <confluence-home>\confluence.cfg.xml file.
3. change admin.ui.allow.manual.backup.download to true.
4. Restart Confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 596
If the value of the above configuration property is 'true', it will be possible to download the backup file after
manually backing up the site via the Confluence Administration Console. If the value of this property is 'false'
or the property is not present in the configuration file, you will need to retrieve the backup file from the file
system on the Confluence server. By default, the value is 'false'.
There are some restrictions on which Confluence versions you will be able to import this file into. The most
important is that you can't import into an earlier version of Confluence. See Restoring a Site for more
information and troubleshooting tips.
Restoring a Site
This page describes how to restore data from an On this page:
XML site export file into an existing Confluence site.
If you want to import data into a new site, see restori Related pages:
ng from backup during setup. Production Backup Strategy
You need System Administrator permissions in order Exporting a site
to perform this function. Importing a Space
All content replaced. Importing a site will replace all your content and users. Back up your database
before you start.
Selective space restoration not possible. You can't select a single space to restore from the entire
site backup.
Version compatibility. Confluence accepts site backups from many previous Confluence versions.
You can check which versions are accepted in the Backup and Restore screen. You can only import
into a later version of Confluence, not an earlier one.
For best results, export from and import into the same Confluence version.
XML export files should not be used to upgrade Confluence. Upgrade Confluence by following Up
grading Confluence.
Here's what it looks like for Confluence 5.9. The accepted versions for your Confluence version may
be different.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 597
There are two ways to import a site - by uploading a file, or from a directory on your Confluence server.
Uploading a file is only suitable for small sites. For best results, we recommend importing from the restore
directory.
To upload and import a small site:
1. Go to
Building the index is optional during the import process. The content of your site won't be searchable until the
index is created, but if you have a very large site, you may choose to rebuild the index manually after the
import is complete.
If you're using Confluence Data Center with collaborative editing enabled there are a few extra
steps. You need to stop Synchrony completley, and we also recommend performing the import with
just one Confluence node running, and directing traffic away from that node.
Once the import is complete, you can restart Synchrony, and then restart your remaining nodes (one
at a time).
Troubleshooting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 598
Production backup strategy preferred. We recommend that you follow the Production Backup
Strategy (which involves backing up your database and home directory) for your production
Confluence site, because Confluence XML exports are not recommended as the sole backup
mechanism.
Restoring from other backups. If your daily backup zip files can't be restored for some reason, but
you have backups of both your database and your Confluence home directory, you'll be able to restore
from these backups.
Restoring a Space
You can export a space including pages, comments and attachments to On this page:
a zip that contains an XML file and, optionally, all the attachments in the Export and
space. To import the space to another Confluence site, restore the zip as import
described below. compatibili
ty
You need System Administrator permissions in order to restore a space
Importing a
from an XML zip file.
space from
an XML
Export and import compatibility
backup
To find out which versions your current Confluence version can accept Troublesho
space exports from, go to oting
Workaroun
d for
> General Configuration > Backup and Restore. restoring
If you need to import a space from Confluence 5.3 or earlier, you'll need to f spaces
ollow a workaround. from
Confluenc
e 5.3 and
earlier
Related pages:
Restoring
a Site
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 599
There are two ways to import a space by uploading a file, or from a directory on your Confluence server.
Uploading a file is only suitable for small spaces. For best results, we recommend importing from the restore
directory.
To upload and import a small space:
1. Go to
Building the index is optional during the import process. The content of your imported space won't be
searchable until the index is created, but, if you have a very large site, rebuilding the index can take a long
time and impact your site's performance. Alternatively, you can rebuild the index manually at a low peak time.
Troubleshooting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 600
If you need to import a space from a version prior to Confluence 5.3 into a later version of Confluence, you
can use a temporary Confluence installation to upgrade the space export to the right version number:
1. Download the same version of Confluence as the version you exported the space from (you can get
older versions of Confluence at the Confluence Downloads Archive).
2. Install that version of Confluence on a temporary server.
3. Import the space into this temporary Confluence site.
4. Upgrade Confluence on your temporary site to the same version as the site where you want to import
the space (see Upgrading Confluence for instructions).
5. Export the space from your temporary Confluence site (it'll now have the right version number).
6. Import the space into your production Confluence site.
Many Confluence administrators will have a production instance running the "live" version of Confluence, as well
as a test instance for testing upgrades and so on. In this situation, it's quite common that the two instances are
running different versions of Confluence. This document describes how to copy the data from a production
instance to a test instance, where the production version may be different to the test version.
Before proceeding with this guide, ensure you have read and understood the normal procedure for upgrading
Confluence.
Essentially, we are copying both the production home directory and database to the test instance. We then
update the database details on the test instance to point to the test database, leaving all other instance
metadata (most importantly the Confluence build number) the same as production.
1. Shut down your test instance.
2. Restore the production database to the test database server.
3. Create a backup of the confluence.cfg.xml file found in the home directory of the test instance.
4. Copy the production confluence-home directory to the test application server.
5. Open the confluence.cfg.xml which has been copied in a text editor. Change the database settings
to match the test database server. Ensure you do not point to your production database. (You can
compare with the backup you made in Step 3 if you need to get the database settings. Don't just copy this
file you need the build number unchanged from production to indicate the database is from an older
version of Confluence.)
Before starting your test instance, you need to do the following steps to ensure no contact with production
systems.
To ensure no contact with external systems, you will need to disable both inbound and outbound mail services.
1. Disable global outbound mail by running the following database query:
2.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 601
Change the 'SELECT *' to a 'DELETE' in the above queries once you are sure you want to remove the specified
accounts.
Once this is done, you can start your test instance without any mails being sent or retrieved. Think carefully
about other plugins which may access production systems (SQL macro, etc.). These should be disabled
promptly after starting the test instance.
You can create a developer license for this server and update the License Details after starting up.
See also
Upgrading Confluence
Migrating Confluence Between Servers
Restoring to a Test Instance of Confluence from Production
Restoring Data from other Backups
Typically, Confluence data is restored from the Administration Console or from the Confluence Setup Wizard.
If you are experiencing problems restoring from an zipped XML backup file, it is still possible to restore provided
you have:
1. A backup of your home directory.
2. A backup of your database (if you're using an external database).
Instructions for this method of restoring differ depending on whether you are using the embedded database or
an external database (like Oracle, MS SQL Server, MySQL or Postgres).
Embedded Database
If you are running against the embedded database, the database is located inside the database folder of your
Confluence Home Directory. Hence, all you need to do is:
1. Retrieve the most recent backup of your home directory.
2. Unpack the Confluence distribution and point the confluence-init.properties file to this directory.
External Database
1. Prepare backups of your home directory and database (preferably backups that are dated the same).
That is, make sure the home directory is accessible on the filesystem and the database available to be
connected to.
2. If this database happens to have a different name, or is on a different server, you need to modify the jdbc
url in the confluence.cfg.xml file inside the Confluence Home Directory. The value of this property is
specified as hibernate.connection.url.
3. Unpack the Confluence distribution and point the confluence-init.properties file to the home
directory.
Retrieving File Attachments from a Backup
File attachments on pages can be retrieved from a backup without needing to import the backup into
Confluence. This is useful for recovering attachments that have been deleted by users.
Both automated and manual backups allow this, as long as the 'Include attachments' property was set. If you
want to restore pages, spaces or sites, see the Confluence Administrator's Guide instead.
Before following the instructions for recovering attachments below, we will review how backups store file and
page information.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 602
The backup zip file contains entities.xml, an XML file containing the Confluence content, and a directory for
storing attachments.
Page attachments are stored under the attachments directory by page and attachment id. Here is an example
listing:
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.
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:
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:
Each file must be individually renamed and re-uploaded back into Confluence by following the instructions
below. Choose one of the three methods:
Best if you know each filename you need to restore, especially if you want just a few files:
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 603
Best if you have a small backup but want to restore many or all the attachments inside:
Following process is applicable to space export only. Site xml backups do not require page id to be
updated manually due to the nature of persistent page_id's.
Problem Solution
Exception while importing backup Follow Troubleshooting XML backups that fail on restore instead
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 604
Common problems
The errors may be caused by a slightly corrupt database. If you're seeing errors such as 'Couldn't backup
database data' in your logs, this guide will help you correct the error on your own. We strongly recommend
that you backup your database and your Confluence home directory beforehand, so that you can restore
your site from those if required. If you are unfamiliar with SQL, we suggest you contact your database
administrator for assistance.
Preferable solution
The Production Backup Strategy is a very reliable and more efficient way to do backups. If you are running
into problems with XML backups - whether memory related or because of problems like the one described
here - use the native backup tool as an alternate solution.
To work out where the data corruption or problems are, increase the status information reported during
backup, then edit the invalid database entry:
1. Stop Confluence.
2. If you have an external database, use a database administration tool to create a manual database
backup.
3. Backup your Confluence home directory. You will be able to restore your whole site using this and the
database backup.
4. Open the my_confluence_install/confluence/WEB-INF/classes/log4j.propertiesand
add this to the bottom and save:
log4j.logger.com.atlassian.confluence.importexport.impl.XMLDatab
inder=DEBUG, confluencelog
log4j.additivity.com.atlassian.confluence.importexport.impl.XMLD
atabinder=false
5. Find your atlassian-confluence.log. Move or delete all existing Confluence logs to make it easier to
find the relevant logging output.
6. Restart Confluence and login.
7. Begin a backup so that the error reoccurs.
8. You must now check your log files to find out what object could not be converted into XML format.
Open confluence-home/logs/atlassian-confluence.log. Scroll to the bottom of the file.
9. Do a search for 'ObjectNotFoundException'. You should see an error similar to this:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 605
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
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 606
11.
was an error writing the ContentPermission object with id 5 into XML. This translates as the row
with primary key 5 in the CONTENTLOCK tableneeds fixing. To work out what table an object maps to
in the database, here's a rough guide:
Pages, blogposts, comments --> CONTENT table
attachments --> ATTACHMENTS table
More information can be found in the schema documentation
12. Now you must find the primary key of the incorrect row in this table. In this case, you can check the
first line and see that the row has a primary key of 5.
13. Each property is written to a column, so the last property that was being written has the incorrect
value. The row being written to when the exception was thrown was CONTENT (line 5) with a value of 2
535 (line 6). Now you know the column and value. This value 2535 is the id of an entry that no longer
exists.
14. Using a database administrative tool, login ot the Confluence database. Locate the row in the relevant
table and correct the entry. Check other rows in the table for the default column value, which may be
null, 0 or blank. Overwrite the invalid row value with the default.
15. Restart Confluence.
16. Attempt the backup again. If the backup fails and you are stuck, please lodge a support request with
your latest logs.
this indicates that the Primary Key constraint 'PK_OS_PROPERTYENTRY_314D4EA8' has duplicate entries
in table 'OS_PROPERTYENTRY'.
You can locate the constraint key referring to 'PK_OS_PROPERTYENTRY_314D4EA8' in your table
'OS_PROPERTYENTRY' and locate any duplicate values in it and remove them, to ensure the "PRIMARY
KEY" remains unique. An example query to list duplicate entries in the 'OS_PROPERTYENTRY' table is:
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.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 607
Common problems
The errors may be caused by a slightly corrupt database. You will need to find the XML backup file entry that
is violating the DB rules, modify the entry and recreate the XML backup:
1. On the instance being restored, follow the instructions to disable batched updates (for simpler
debugging), log SQL queries and log SQL queries with parameters at Enabling Detailed SQL
Logging.
2. Once all three changes have been made, restart Confluence.
3. Attempt another restore.
4. Once the restore fails, check your log files to find out what object could not be converted into XML
format. For Confluence distribution users, check your Confluence install directory under the /logs/ a
nd check both atlassian-confluence.log and catalina.out file. The correct file will contain
SQL debug output.
5. Scroll to the bottom of the file and identify the last error relating to a violation of the database
constraint. For example:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 608
This example indicates a row in your attachment table with ID = 38 that has a null title.
6. Go to the server that the backup was created on. You must have a copy of the database from which
the backup was created. If you do not have this, use a DBA tool to restore a manual backup of the
database.
7. Open a DBA tool and connect to the original database instance and scan the table names in the
schema. You will have to modify a row in one of these tables.
8. To work out which table, open catalina.out, check the first line of the exception. To work out what
table an object maps to in the database, here's a rough guide:
Pages, blogposts, comments --> CONTENT table.
attachments --> ATTACHMENTS table.
9. To correct the example error, go to the attachment table and find that attachment object with id 38.
This will have a a null title. Give a title using the other attachments titles as a guide. You may have a
different error and should modify the database accordingly.
10. Once the entry has been corrected, create the XML backup again.
11. Import the backup into the new version.
12. If the import succeeds, revert the changes made in your SQL logging to re-enable disable batched
updates and turn off log SQL queries and log SQL queries with parameters.
13. Restart Confluence.
com.atlassian.confluence.importexport.ImportExportException: Unable
to complete import because the data does not match the constraints in
the Confluence schema. Cause:
MySQLIntegrityConstraintViolationException: Duplicate entry
'1475804-Edit' for key 'cps_unique_type'
This indicates that the XML export came from a version of Confluence with a corrupt permissions database,
caused by some 3rd party plugin. This is an issue that was fixed when CONF-22123 was implemented in
Confluence 3.5.2. The simplest workaround is to export the space again after upgrading the instance to 3.5.2
or above. If that is not an option, then either the export will need to be edited manually to remove the
duplicate permission entries or the source instance will need to have the offending entries removed. The
following SQL queries can be used to look for such entries:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 609
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 610
This indicates that the Primary Key constraint 'PK_OS_PROPERTYENTRY_314D4EA8' has duplicate entries
in table 'OS_PROPERTYENTRY'.
You can locate the constraint key referring to 'PK_OS_PROPERTYENTRY_314D4EA8' in your table
'OS_PROPERTYENTRY' and locate any duplicate values in it and remove them, to ensure the "PRIMARY
KEY" remains unique. An example query to list duplicate entries in the 'OS_PROPERTYENTRY' table is:
This means there's an unexpected null value in a table. In the above example, the error is in the name
column in the USERS table. We've also seen them in the ATTACHMENTS table.
Remove the row with the null value, redo the xml export, and reimport.
1. If you are using the embedded database, be aware that it is bundled for evaluation purposes and does
not offer full transactional integrity in the event of sudden power loss, which is why an external
database is recommended for production use. You should migrate to an external database.
2. If you are using an older version of Confluence than the latest, you should consider upgrading at this
point.
The problem with different settings for case sensitivity varies between databases. The case
sensitivity of the database is usually set through the collation that it uses. Please vote on the existing
issue
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 611
Earlier Confluence versions allowed attachments to be stored in WebDav or the Confluence database. This
is not an option for new installations.
By default, Confluence stores attachments in the attachments directory within the configured Confluence
home folder.
Database (deprecated)
Confluence 5.4 and earlier gives administrators the option to store attachments in the database that
Confluence is configured to use.
While storing attachments in the database can offer some advantages (such as ease of backup, and
avoiding issues with some characters in attachment filenames), please be aware that the amount of
space used by the database will increase because of greater storage requirements.
WebDav (deprecated)
If you are storing attachments in WebDav or your database, you can migrate to storing attachments in the file
system. When migrating attachments from your database to a filesystem, the attachments are removed from
the database after migration.
When the migration occurs, all other users will be locked out of the Confluence instance. This is to
prevent modification of attachments while the migration occurs. Access will be restored as soon as
the migration is complete.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 612
5.
that displays the progress of the migration.
Screenshot: migration warning
The following external website provides further information on migrating attachments from database to file
system storage that you might find helpful - https://www.scandio.de/blog/de/2013/05/confluence-attachment-
migration-the-safe-way-2.
When a file is uploaded, Confluence will attempt to extract and index its text. This allows people to search for
the content of a file, not just the filename. This process is quite memory intensive and can cause out of
memory errors when very large files are uploaded. Confluence has a number of safeguards to prevent this
happening:
If the uploaded file is larger than 100 MB, Confluence will not attempt to extract text or index the file
contents. Only the filename will be searchable.
If the uploaded file is one of the following types, Confluence will only extract up to:
1 MB of text from Excel (.xlsx)
8 MB of text from PDF (.pdf)
10 MB of text from other text files (including .txt, .xml, .html, .rtf etc)
16 MB of text from Word (.docx)
If the text extracted from the file was greater than 1 MB, it will be searchable, but Confluence will not
show this text as an excerpt with the search result.
If Confluence stops extracting text, only a portion of the file's content will be searchable.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 613
Confluence will only attempt to extract and index the file once. If it fails, it will not try again.
Some of the values above are configurable via system properties. If you experience out of memory errors
when people upload large files, you may want to reduce these limits further, using the following properties:
atlassian.indexing.attachment.maxsize
officeconnector.excel.extractor.maxlength
officeconnector.textextract.word.docxmaxsize
atlassian.indexing.contentbody.maxsize
The way attachments are stored changed significantly in Confluence 3.0. If you are upgrading from
Confluence 2.10 or earlier see Upgrading Confluence for recommended upgrade paths, and read the
version of the Hierarchical File System Attachment Storage page in our Confluence 3.0 documentation
which provides more detail about migrating to the new file system structure.
Confluence stores attachments, such as files and images, in a file system. Confluence's attachment storage
layout is designed to:
1. Limit the number of entries at any single level in a directory structure (as some file systems have a limit
on the number of files that can be stored in a directory).
2. Partition attachments per space making it possible for a system admin to selectively back up attachments
from particular spaces.
Attachments in Confluence have a number of identifying attributes: content id of the file itself, the space id and c
ontent id of the page the file is attached to. This means the file logically belongs to a piece of content which
logically belongs in a space (not all content belongs to a space). For files within a space in Confluence, the
directory structure is typically 8 levels, with the name of each directory level based on the following algorithm:
3 The next 3 least significant digits of the space id, modulo 250
5 The least significant 3 digits of the content id of the page the file is attached to, modulo 250
6 The next 3 least significant digits of the content id of the page the file is attached to, modulo 250
The modulo calculation is used to find the remainder after division, for example 800 modulo 250 = 50.
Within the 8th level will be a file for each version of that attachment, named to match the version number e.g. 1
An example:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 614
To find the directory where attachments for a particular space are stored, go to <confluence
url>/admin/findspaceattachments.jsp and enter a space key. It will return the directory on the file
system where attachments for that space are stored.
File D in the above diagram is stored in a slightly different structure. Files that are not conceptually within a
space replace the level 2 - 4 directories with a single directory called 'nonspaced'. Examples of such files are the
global site logo and attachments on unsaved content.
Confluence Data Model
This document provides a diagram of the
Confluence schema and a conceptual overview of
the data model.
Notes:
The Hibernate mapping files are the
authoritative reference for the Confluence
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 615
Database diagrams
Detailed diagrams
The following SVG images (Scalable Vector Graphics) include all the tables in the Confluence database.
Click the links below to open the images in your browser, or download the SVG files for later use. You can
use the browser's zoom (Ctrl++ or Cmd++) to see more detail in the diagrams:
ConfluenceTables-KeysOnly.svg Shows all tables, with primary keys only for each table.
ConfluenceTables-AllColumns.svg Shows all tables, and all columns for each table.
Overview diagram
This image shows the core tables. Note that the image is very large. You may need to download it (right-click
on the image) and view it in an image viewer. Alternatively, use the SVG images linked in the previous
section.
Click here to show/hide the image...
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 616
Expand the link below to see a table of the primary and foreign keys for each table.
Click here to show/hide the table...
Primary key table Primary key Foreign key table name Foreign key Foreign key name
name column column name
name
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 617
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 618
The following sections describe the principal tables involved in each logical area of Confluence
authentication, content, system information, and so on.
Authentication
This section describes the tables involved in user authentication, which is implemented via the Atlassian
Crowd framework embedded in Confluence.
Table Description
cwd_directory The user directories in your Confluence site. Examples of directories are the
Confluence internal directory, or an LDAP directory.
cwd_application The applications (JIRA, Confluence, and so on) defined in the authentication
framework.
Content
This section describes the tables involved in storing content. Content is the information that Confluence users
are storing and sharing.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 619
Table Description
attachmentdata The binary data for attached files. This table is only used when Confluence is
configured to store attachments in the database. Otherwise, attachments are
stored in the local file system.
content_perm_set A one-to-many mapping for content items and their permissions, with added
metadata.
Clustering
Table Description
clustersafety Normally, this table only contains one row. The value of the safetynumber is what
Confluence uses to find out whether another Confluence site is sharing its database
without being part of the cluster.
System information
These tables store data related to the status and configuration of the Confluence site.
Table Description
confversion Used by the upgrade system to determine what to expect from the database, so as to
negotiate upgrades.
plugindata A record of the plugins that have been installed, and when.
data is a blob of the actual plugin JAR file. This is principally cluster-related.
Spaces
Table Description
spaces Information about the spaces themselves: key, human-friendly name and numeric ID.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 620
Appearance
The following table contains information about the look and feel of your Confluence site.
Table Description
Miscellaneous
Table Description
bandana A catch-all persistence layer. This table contains things like user settings and
space- and global-level configuration data, and is used as storage by plugins
such as the Dynamic Task List plugin. Essentially, for storing arbitrary data
that doesn't fit anywhere else.
hibernate_unique_key Used by the high/low ID generator the subsystem which generates our
primary keys.
If you interfere with this table, you may not be able to create objects in
Confluence.
indexqueueentries Manages full-content indexing across the system. The table generally
contains the last 12 hours (approximately) of updates, to allow re-syncing of
cluster nodes after restarts.
keystore Used by the trusted apps framework to store the server's private key, and
other servers' public keys.
links Tracks links within the server (that is, across and within spaces).
Sometimes, you want to know what is not being used. It's great to know what's getting most attention, but what
about stagnant pages, or even entire spaces that are no longer active?
While viewing space activity can provide hints, it doesn't always provide enough detail. It is possible to find out
this information directly from the database.
The following query identifies the last date on which content was modified in each space within a single
Confluence instance:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 621
It returns a list of space names, and the last date and time at which any content was added or changed.
Alternatively, this query identifies spaces where the content hasn't changed since a specified date:
SELECT spaces.spacename
FROM content, spaces
WHERE content.spaceid = spaces.spaceid
GROUP BY spaces.spacename
HAVING MAX(content.lastmoddate) < '2006-10-10';
Related pages:
Managing Confluence Data
Confluence Administrator's Guide
To make sure Confluence maintains the formatting of the text document, add <pre> to the beginning and
</pre> to the end. This will let Confluence know that it should treat the text as pre-formatted.
If you're working in a Unix-like environment, you can add the opening and closing tags to all files in a
particular directory by following these steps:
1. Go to the directory containing the files
2. Run the following command in the terminal:
for i in $(ls); do echo "<pre>" >> m$i; cat $i >> m$i; echo
"</pre>" >> m$i; mv m$i $i; done
5.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 622
5. Select Overwrite existing pages if you want to replace existing Confluence pages with the same title
with the one you're importing.
6. Choose Import.
Screenshot: Importing text files
Audit log
The audit log allows administrators to look back at changes that have been made in your site. This is useful
when you need to troubleshoot a problem or if you need to keep a record of important events, such as changes
to global permissions. You'll need Confluence Administrator permissions to view the audit log.
To view the audit log
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 623
The audit log doesn't record information directly relating to pages such as page edits (you can see these in the
page history) location, or changes to page restrictions.
By default, events are removed from the log after 3 years. You can choose how long to keep events in the log
settings (up to 10 years).
You can also export the log to CSV format if you'd like to explore it in more detail, or if you need to maintain a
longer term record.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 624
bin/setenv.bat or bin/setenv.sh
This file is used to edit CATALINA_OPTS
memory and garbage collection settings and
define system properties.
confluence/WEB-INF/classes/conflu
ence-init.properties
This file contains the location of the
Confluence Home directory.
The Confluence Home directory is the folder where Confluence stores its configuration information, search
indexes and page attachments. Another term for 'Home directory' would be 'data directory'.
> General Configuration > System Information > Confluence Information - Confluence Home.
If your Confluence instance is clustered, you will also have a shared home directory which will contain some
data (such as attachments and backups) that would otherwise reside in the home directory.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 625
The Confluence home directory contains some of the configuration data used by Confluence. This section
outlines the purpose of the files and directories in the Confluence home directory.
confluence.cfg.xml This file contains all of the information necessary for Confluence to start up,
such as:
Product license
Context path
Database details, such as location and connection pool settings
Paths to important directories
attachments/ This directory contains every version of each attachment stored in Confluence.
You can specify an alternative directory for attachment storage by setting the a
ttachments.dir property in confluence.cfg.xml.
backups/ Confluence will place its daily backup archives in this directory, as well as any
manually generated backups. Backup files in this directory take the following
form daily-backup-YYYY_MM_DD.zip
You can specify an alternative directory for backups by setting the daily.bac
kup.dir property in confluence.cfg.xml.
database/ This is where Confluence stores its database when configured to run with the E
mbedded H2 Database. In such cases this directory contains all Confluence
runtime data. Installations configured to run using an external database such as
MySQL will not use this directory.
The H2 database is provided for evaluating Confluence and is not supported as
a production database.
index/ The Confluence index is heavily used by the application for content searching
and recently updated lists and is critical for a running Confluence instance. If
data in this directory is lost or corrupted, it can be restored by running a full
reindex from within Confluence. This process can take a long time depending
on how much data is stored Confluence's database.
An alternative directory may be specified for the index by setting the lucene.i
ndex.dir property in confluence.cfg.xml.
journal/ Entries are added to the journal when changes occur (such as a comment, like,
new page). Journal entries are then processed and the entries added to the
index (about every 5 seconds). In a cluster, the journal keeps the indexes on
each node in sync.
plugin-cache/ All Confluence plugins are stored in the database. To allow for quicker access
to classes contained within the plugin JARs, Confluence will cache these
plugins in the plugin-cache directory. This directory is updated as plugins
are installed and uninstalled from the system and is completely repopulated
from the database every time Confluence is restarted. Removing plugins from
this directory does not uninstall them.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 626
resources/ The resources directory stores any space logos used in your Confluence
instance. Space logos are stored in directories named with the spacekey.
temp/ The temp directory is used for runtime functions such as exporting, importing,
file upload and indexing. Files in this directory are temporary and can be safely
removed when Confluence is offline. A daily job within Confluence deletes files
that are no longer needed.
An alternative directory may be specified for temporary data by setting the webw
ork.multipart.saveDir property in confluence.cfg.xml.
thumbnails/ Stores temporary files for image thumbnails. This directory is essentially a
thumbnail cache, and files deleted from this directory will be regenerated the
next time the image is accessed.
When Confluence first starts up, it reads the confluence-init.properties file to determine where to
look for the Home directory.
To change the location of the home directory edit the confluencee.home property in the confluence-in
it.properties file as follows:
Windows
In Windows, the path C:\confluence\data would be written as:
confluence.home=C:/confluence/data
Note that all backslashes (\) are written as forward slashes (/)
Linux / Solaris
On any Linux-based system, the property is defined using the normal directory syntax:
confluence.home=/var/confluence/
Symbolic links
There can be no symbolic links within the Confluence home directory. You must define an absolute path. If
disk space is an issue, place the entire confluence.home directory on a disk partition where there is
enough space. The absolute path of generated files (such as exports) is compared with the absolute path of
the confluence.home directory when constructing URLs. When a sub-directory has a different path, the
URL will be incorrect, and you may receive "Page not found" errors. These measures are in place to prevent
"directory traversal" attacks.
The Confluence configuration file: confluence-cfg.xml inside the home directory may contain references
to the original location of your Confluence home. You will need to edit this file to update these references to
also point to the new location. The two properties in this file that need to change are:
daily.backup.dir if you have not configured your backups to be placed elsewhere already
hibernate.connection.url if you are using the embedded HSQL database.
Database
All other data, including page content, is kept in the database. If you installed Confluence as a trial, or chose
to use the embedded HSQL database during setup, the database will store its files under database/ in
the Confluence Home Directory. Otherwise, the database management system you are connecting to is
responsible for where and how your remaining data is stored.
Temp directory
The temp directory is configured in the Java runtime and some Confluence components write temporary files
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 627
The following pages contain information about configuring your application server for Confluence:
Configuring URL Encoding on Tomcat Application Server
Managing Application Server Memory Settings
Switching to Apache Tomcat
Java Policy Settings for Enterprise or Webhosting Environments
Configuring URL Encoding on Tomcat Application Server
Application servers may have different settings for character encodings. We strongly recommend UTF-8 where
possible.
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 the
names of attachments or pages.
The Tomcat installation that is currently shipped with Confluence is already configured for UTF-8, so the
below changes are not required in recent versions.
To configure the URL encoding in Tomcat:
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="8090"/>
3. Restart Tomcat
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:
JkOptions +ForwardURICompatUnparsed
For comprehensive examples of how to use Tomcat and Apache with Confluence, see Running Confluence
behind Apache.
Managing Application Server Memory Settings
The minimum and maximum JVM heap space allocated to the application server affects performance.
Confluence administrators may wish to modify this value from the defaults depending on their server load. This
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 628
document only provides guidelines rather than rules, so administrators optimizing for performance should use
this document as a starting point only.
For a comprehensive overview of memory management, and memory tuning in Confluence under Sun
JRE, please read Garbage Collector Performance Issues
In the general case, both JIRA & Confluence users will benefit from setting the minimum and maximum values
identical. In larger installations, there is benefit to memory tuning, if there is a perceived performance issue. If
you are experiencing Out of Memory Heap errors, try increasing the -Xmx and -Xms values for your installation
to see if this resolves or helps resolve your issue. It's best to increase in small increments (eg 512mb at a time),
to avoid having too large a heap, which can cause different problems. If increasing the memory does not help,
please lodge a support ticket as there may be other factors contributing.
Memory usage is most likely to be maximized under peak load, and when creating a site XML backup. In many
cases, the backup can be the cause of the OOM, so increase -Xmx values and verify if a backup was occurring
at the time of OOM. A quick rule of thumb for gauging the success of a memory adjustment is using simple
anecdotal evidence from users. Is it snappier? The same? How does it handle while a backup is occurring?
Atlassian recommends in normal use, to disable the XML backup and use a Production Backup Strategy
.
If you normally perform manual XML site backups on your server, test your maximum memory
requirements by performing a site XML backup while the server is under maximum load
If you do not create manual XML site backups, simply monitor the server while under maximum load
Related Topics
Apache Tomcat is the only application server supported for Confluence. To move Confluence from an
application server (e.g. WebSphere) to Tomcat using the same database, follow the instructions below.
Follow these instructions:
1. Before You Start
2. Backing Up
3. Switching Application Servers
4. Applying Customizations
Confluence Server
Plugins
Look and Feel
Performance
Advanced Customizations
5. Testing Confluence
1. The following instructions will only work if you are running the same major version of Confluence on both
application servers. If you are running different major versions of Confluence, you will need to upgrade
Confluence before you can switch to Tomcat.
2.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 629
2. Note that you need current software maintenance, as the process for changing application servers
involves installing Confluence.
3. If the environment (e.g. the database system, the operating system and so on) that you are running
Confluence in has changed, please ensure it still complies with the Confluence System Requirements.
4. If you are using an external database, familiarize yourself with all known issues for your specific
database. Also make sure the Confluence database connector principal (the database user login) has
sufficient permissions to modify the database schema.
5. Note any customizations that you have made to Confluence, e.g. enabled/installed plugins, modified
layouts, custom themes, etc. You will need to reapply these after you have switched to Tomcat. You can
view the list of customizations in the Reapplying Customizations section below.
6. We recommend that you do not run any other applications in your Tomcat application server that is
running Confluence, to prevent performance issues.
2. Backing Up
1. Install Confluence on your new application server. We recommend that you download Confluence as a
stand alone archive (rather than using the installer).
Important: At this stage, just unzip the standalone file to a location of your choice - this will be your
new installation directory. You should not start Confluence until directed to in step 3 below.
2. Copy the following files from your old Confluence installation to your new one:
<CONFLUENCE_INSTALL>\confluence\WEB-INF\classes\confluence-init.properti
es
<CONFLUENCE_INSTALL>\confluence\WEB-INF\classes\atlassian-user.xml
<CONFLUENCE_INSTALL>\confluence\WEB-INF\classes\osuser.xml (copy this over if
you are using JIRA user management)
<CONFLUENCE_INSTALL>\confluence\WEB-INF\classes\seraph-config.xml (copy this
over if you using custom SSO)
<CONFLUENCE_INSTALL>\confluence\WEB-INF\web.xml (copy this over if you have
previously modified it, e.g. to configure a datasource)
3. Start Confluence (make sure you shutdown the old server before you start up the new one)
4. If you are running the new application server on a different machine to the old one, carry out the following
actions as soon as you start the new server:
Re-index your data.
Make sure that the attachments location is valid for the new server.
5. If you have applied special settings to their Confluence server and/or Confluence look and feel, you will
need to reapply these customizations as described in below.
4. Applying Customizations
After switching to Tomcat, you need to review any customizations and other special configurations you
previously used for your Confluence instance, and re-apply if necessary. This section also contains some
Tomcat-specific customizations that you may wish to considering applying, if you haven't used Confluence with
Tomcat before.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 630
Confluence Server
For long-term use, we recommend that you configure Confluence to start automatically when the
operating system restarts. For Windows servers, this means configuring Confluence to run as a Windows
service.
If you are using the Confluence edition and you have previously defined a CATALINA_HOME
environment variable, please check that it points to the correct path for the new Confluence Tomcat
server.
If you were previously running Confluence on a non-standard port, edit your new <Installation-Di
rectory>\conf\server.xml file as described in Change listen port for Confluence.
Plugins
If you were previously using any plugins, install the latest compatible version and disable any plugins that
are incompatible with your new instance of Confluence. The easiest way to do this is to use the Universal
Plugin Manager in the Confluence Administration Console.
If you are using any customized themes, please check that they are displaying as expected. Some
further customization may be required to ensure compatibility with your new version of Confluence.
If you had previously customized the default site or space layouts, you will need to reapply your
changes to the new defaults as described here. Please do not just copy your VM (velocity) files across.
Ensure that Confluence works without your custom layouts then apply the layout via the Confluence
Administration console.
Performance
If the load on your Confluence instance is high, you may need more simultaneous connections to the
database. Read more about this in the Performance Tuning guide.
If you had previously modified the memory flags (Xms and Xmx) in either the <Installation-Direct
ory>\bin\setenv.sh or the setenv.bat file, you may want to make the modifications in your new
installation. The parameters are specified in the CATALINA_OPTS variable. See How to fix out of memory
errors by increasing available memory for more information.
Advanced Customizations
If you were previously running Confluence over SSL, you will need to reapply your configuration as
described in Running Confluence Over SSL or HTTPS.
If you were using a custom SSO authenticator, change seraph-config.xml to the correct authenticator.
If you had changed the Confluence interface text, you will need to copy over the
ConfluenceActionSupport.properties file.
If you had previously modified the Confluence source code, you will need to reapply your changes to the
new version.
5. Testing Confluence
Make sure you test Confluence on the new server before deploying it in production.
The Working with Confluence Logs document contains the locations for the application logs, if you need to refer
to them.
Java Policy Settings for Enterprise or Webhosting Environments
Confluence relies on a number of Java libraries. Some of these libraries make use of features of the Java
language that may be restricted by Java security policies.
This does not normally cause any problems. The default security configuration of most application servers will
happily run Confluence. However, in some shared-hosting or enterprise environments, security settings may be
such that Confluence cannot function.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 631
Related pages:
Application Server Configuration
Confluence Administrator's Guide
When you attempt to run Confluence, you may get the following error:
The permissions required by Confluence to run are detailed in the sample policy file below. You may need to
give this information to your systems administrator so that they can be deployed with the Confluence application.
grant {
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission java.lang.RuntimePermission "defineCGLIBClassInJavaPackage";
};
The content on this page relates to platforms which are not supported. Consequently, Atlassian Support
cannot guarantee providing any support for it. Please be aware that this material is provided for your
information only and using it is done so at your own risk.
Some of Confluence's macros, such as {rss} and {jiraissues} need to make web requests to remote servers in
order to retrieve data. If Confluence is deployed within a data centre or DMZ, it may not be able to access the
Internet directly to make these requests. If you find that the {rss} macro does not work, ask your network
administrator if Confluence needs to access the Internet through a web proxy.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 632
Proxy support is configured by passing certain system properties to the Java Virtual Machine on startup.
http.proxyHost
http.proxyPort (default: 80)
http.nonProxyHosts (default: <none>)
https.proxyHost
https.proxyPort
At a minimum, you need to define http.proxyHost to configure an HTTP proxy, and https.proxyHost to
configure an HTTPS proxy. System property configuration is described in the Configuring System Properties.
Properties http.proxyHost and http.proxyPort indicate the proxy server and port that the http protocol
handler will use, and https.proxyHost and https.proxyPort indicate the same for the https protocol
handler.
-Dhttp.proxyHost=proxy.example.org -Dhttp.proxyPort=8080
-Dhttps.proxyHost=proxy.example.org -Dhttps.proxyPort=8080
Property http.nonProxyHosts indicates the hosts which should be connected to directly and not through the
proxy server. The value can be a list of hosts, each separated by a pipe character | . In addition, a wildcard
character (asterisk) * can be used for matching. For example:
-Dhttp.nonProxyHosts=*.foo.com|localhost
If you're using Confluence 6.0 or later with Synchrony, you'll need to pass the following to ensure Confluence
can connect directly to Synchrony. Replace localhost|127.0.0.1 with your Synchrony IP if you have used
the synchrony.host system property to change the IP Synchrony uses.
-Dhttp.nonProxyHosts=localhost|127.0.0.1
-Dhttps.nonProxyHosts=localhost|127.0.0.1
Note: You may need to escape the pipe character | in some command-line environments.
If the http.nonProxyHosts property is not configured, all web requests will be sent to the proxy.
Please note that any command line parameters set are visible from the process list, and thus anyone who has
the approriate access to view the process list will see the proxy information in the clear. To avoid this, you can
set these properties in the catalina.properties file, located in confluence-install/conf/. Add this to the
end of the file:
http.proxyHost=yourProxyURL
http.proxyPort=yourProxyPort
http.proxyUser=yourUserName
http.proxyPassword=yourPassword
https.proxyHost=yourProxyURL
https.proxyPort=yourProxyPort
https.proxyUser=yourUserName
https.proxyPassword=yourPassword
Proxy authentication is also configured by providing system properties to Java in your application server's
configuration file. Specifically, the following two properties:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 633
http.proxyUser username
http.proxyPassword secret
Confluence supports NTLM authentication for outbound HTTP proxies when Confluence is running on a
Windows server.
This means that the {rss} and {jiraissues} macro will be able to contact external websites if requests have to go
through a proxy that requires Windows authentication. This support is not related to logging in Confluence users
automatically with NTLM, for which there is a user-contributed authenticator available.
To configure NTLM authentication for your HTTP proxy, you need to define a domain system property, http.au
th.ntlm.domain, in addition to the properties for host, port and username mentioned above:
-Dhttp.auth.ntlm.domain=MYDOMAIN
Sometimes multiple authentication mechanisms are provided by an HTTP proxy. If you have proxy
authentication failure messages, you should first check your username and password, then you can check for
this problem by examining the HTTP headers in the proxy failure with a packet sniffer on the Confluence server.
(Describing this is outside the scope of this document.)
To set the order for multiple authentication methods, you can set the system property http.proxyAuth to a
comma-separated list of authentication methods. The available methods are: ntlm, digest and basic; this is also
the default order for these methods.
For example, to attempt Basic authentication before NTLM authentication, and avoid Digest authentication
entirely, you can set the http.proxyAuth property to this value:
-Dhttp.proxyAuth=basic,ntlm -Dhttps.proxyAuth=basic,ntlm
Troubleshooting
1. There's a diagnostic jsp file in CONF-9719 for assessing the connection parameters.
2. 'Status Code [407]' errors are described in APR-160.
3. Autoproxies are not supported. See CONF-16941.
Running Confluence behind Apache
This page documents a configuration of Apache, rather than of Confluence itself. Atlassian will support
Confluence with this configuration, but we cannot guarantee to help you debug problems with Apache.
Please be aware that this material is provided for your information only, and that you use it at your own
risk.
Introduction
For improved performance in high-load environments, you should run Confluence behind a web server. In
general, web server caching and thread management is far superior to that provided by your application server's
HTTP interface.
To run Confluence behind the Apache httpd web server, there are two main configuration options: mod_jk or m
od_proxy.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 634
Configuration Guides
Please choose one configuration. Trying to configure for both mod_proxy and mod_jk will only lead to
confusion and tears.
The misleadingly-named mod_jk2 is an older method of connecting to Tomcat from Apache. Since mod_jk2 is n
o longer supported by the Apache Foundation, we do not support this configuration, and are not updating our mo
d_jk2 documentation. Mod_jk2 also has unresolved problems with Unicode URLs; you need to use either
mod_proxy or mod_jk for international characters to work correctly in Confluence.
To improve performance of a large Confluence site, we recommend that you move the caching of static content
from the JVM into Apache. This will prevent the JVM from having a number of long running threads serving up
static content. See Configuring Apache to Cache Static Content via mod_disk_cache.
On this page:
Prefer Apache mod_deflate to Confluence's built-in gzip implementation
Ensure keepalive is enabled
Enable keepalive for recent MSIE user agents
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 635
KeepAlive On
The standard Apache SSL configuration is very conservative when it comes to MSIE and SSL. By default all
keepalives are disabled when using HTTPS with MSIE. While MSIE will always be special, the issues with SSL
and MSIE have been solved since Service Pack 2 for Windows XP, released over 4 years go. For anyone using
an XP machine SP2 or above, it is safe to allow keepalive for MSIE 6 and above.
Remove the following lines:
RELATED TOPICS
Running Confluence behind Apache
Configuring Tomcat's URI encoding
Running Confluence Over SSL or HTTPS
Using Apache with mod_proxy
Atlassian applications allow the use of reverse-proxies, however Atlassian Support does not provide
assistance for configuring them. Consequently, Atlassian can not guarantee providing any
support for them.
If assistance with configuration is required, please raise a question on Atlassian Answers.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 636
Base configuration
If you want to access Confluence without a context path, such as www.example.com, skip this step.
Set your Confluence application path (the part after hostname and port) in Tomcat. In this example the
context path will be /confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 637
Next, set the URL for redirection. In the same <installation-directory>conf/server.xml file,
locate this code segment:
And add proxyName, proxyPort and Scheme as shown in the last line below:
proxyName="www.example.com" proxyPort="80"
scheme="http"/>
3 Configure mod_proxy
Use one of the examples below to edit your Apache http.conf file to proxy requests to the application
server.
You will need to enable the following required Apache modules if they are not already enabled:
mod_proxy
mod_proxy_http
proxy_wstunnel
mod_rewrite
(proxy_wstunnel and mod_rewrite are new requirements in Confluence 6.0)
The format of the http.conf file, and location of the modules may differ on your operating system. We
recommend Windows users specify the absolute path to the module files.
Example 1: Configuration with context path
Use this example if you set a context path in step 1, and will access Confluence with a context path like this h
ttp://www.example.com/confluence.
In this example, users will connect to Synchrony, which is required for collaborative editing, directly via
WebSockets.
The order of directives in the config is important.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 638
<Proxy *>
Require all granted
</Proxy>
<Location /confluence>
Require all granted
</Location>
Note: It's not possible to use Apache HTTP Server 2.2 with Confluence 6.0 or later. If you plan to use SSL,
you will need version 2.4.10 or later.
Example 2: Configuration without context path
Use this example if you skipped step 1, and will access Confluence without a context path like this http://ww
w.example.com.
As in the previous example, users will connect to Synchrony, which is required for collaborative editing,
directly via WebSockets.
The order of directives in the config is important.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 639
ProxyRequests Off
ProxyPreserveHost On
RewriteEngine On
RewriteCond %{REQUEST_URI} !^/synchrony
RewriteRule ^/(.*) http://<domain>:8090/$1 [P]
<Proxy *>
Require all granted
</Proxy>
<Location /synchrony>
Require all granted
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} Upgrade$ [NC]
RewriteRule .* ws://<domain>:8091%{REQUEST_URI} [P]
</Location>
ProxyPass / http://<domain>:8090
ProxyPassReverse / http://<domain>:8090
<Location />
Require all granted
</Location>
Note: It's not possible to use Apache HTTP Server 2.2 with Confluence 6.0 or later. If you plan to use SSL,
you will need version 2.4.10 or later.
4 Restart Apache
This is needed to pick up on the new configuration. To restart Apache, run the following command:
Having compression run on both the proxy and Tomcat can cause problems integrating with other Atlassian
applications, such as JIRA. Please disable HTTP compression as per our Compressing an HTTP Response
within Confluence docs.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 640
The last stage is to set the Base URL to the address you're using within the proxy, for example http://www.e
xample.com/confluence.
Adding SSL
We've created a much better guide for Securing your Atlassian applications with Apache using SSL.
You may also be interested in our other Reverse Proxy Setup Guides:
Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http)
Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_ajp)
Reverse Proxy and Application Link Troubleshooting Guide
More information
The mod_proxy_html site has documentation and examples on the use of this module in the complex
configuration.
Apache Week has a tutorial that deals with a complex situation involving two applications and
ProxyHTMLURLMap.
It's not possible to use only mod_jk to proxy Confluence 6.0 or later. This is because Synchrony,
which is required for collaborative editing, cannot accept AJP connections. The preferred
configuration is Using Apache with mod_proxy.
If you are unable to switch to mod_proxy, see How to configure Apache mod_jk to proxy
Confluence 6.x or later for a workaround.
Note: This page documents a configuration of Apache, rather than of Confluence itself. Atlassian will support
Confluence with this configuration, but we cannot guarantee to help you debug problems with Apache. Please
be aware that this material is provided for your information only, and that you use it at your own risk.
Confluence requires URL rewriting for proper functionality, if Confluence is accessible via different domain
names. If Confluence is configured for multiple domains without URL rewriting, you will experience an array of
problems. See Various Issues Caused when Server Base URL Does Not Match the URL Used to Access
Confluence.
An example of why you may want to access Confluence from different domains:
From an internal network:
http://wiki
The externally visible domain:
http://wiki.domain.com
Further information
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 641
You may be interested in the UrlRewriteFilter that is Java web filter that works in a similar way of the Apache's
mod_rewrite.
Configuring Apache to Cache Static Content via mod_disk_cache
Redirection Notice
This page will redirect to KB:Proxying Atlassian Server applications.
To improve performance of a large Confluence site, we recommend that you move the caching of static content
from the JVM into Apache. This will prevent the JVM from having a number of long running threads serving up
static content.
Static content in Confluence includes most JavaScript, CSS and image files which are included with the
application or an installed plugin. This content will be cached by Apache in this configuration. User-provided
content like space logos, attachments or embedded images are not considered static content and will not be
cached.
Note: This page documents a configuration of Apache, rather than of Confluence itself. Atlassian will support
Confluence with this configuration, but we cannot guarantee to help you debug problems with Apache. Please
be aware that this material is provided for your information only, and that you use it at your own risk.
<IfModule mod_disk_cache.c>
# "/s" is where Confluence serves "static" stuff. Instruct Apache
to cache it:
CacheEnable disk /s
CacheIgnoreHeaders Set-Cookie
CacheRoot "/var/cache/mod_proxy"
</IfModule>
2. Configure Apache to load mod_disk_cache. For example, in our server configuration this is done in /et
c/httpd/conf/httpd.conf:
Notes
This will purge content once the cache reaches 512M every 30 minutes. See the Apache documentation
for htcacheclean for details of the options.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 642
You can configure Confluence to start automatically on system startup, allowing it to recover automatically after
a reboot.
Start Confluence Automatically on Linux
Start Confluence Automatically on Windows as a Service
On Linux/Solaris, the best practice is to install, configure and run each service (including Confluence) as a
dedicated user with only the permissions they require.
To install, configure and run Confluence automatically on Linux/Solaris:
1. Create a confluence user for instance, using the following command:
2. Create a directory to install Confluence into. In this example we're using /usr/local/confluence.
sudo su - confluence
cd /usr/local/confluence/
tar zxvf /tmp/confluence-5.6.4.tar.gz
ln -s confluence-5.6.4/ current
4. Edit
<<CONFLUENCE_INSTALL_DIRECTORY>>/confluence/WEB-INF/classes/confluence-init.properties file,
and set confluence.home=/usr/local/confluence/<Confluence_Data_Home> (ensure you have removed
the comment '#')
5. Then back as root, create the file /etc/init.d/confluence (code shown below), which will be
responsible for starting up Confluence after a reboot (or when manually invoked).
If you are running Ubuntu Jaunty (or later) do not perform this step. Please use the instructions further
down this page.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 643
#!/bin/sh -e
# Confluence startup script
#chkconfig: 2345 80 05
#description: Confluence
case "$1" in
# Start command
start)
echo "Starting $APP"
/bin/su -m $USER -c "$CATALINA_HOME/bin/start-confluence.sh &>
/dev/null"
;;
# Stop command
stop)
echo "Stopping $APP"
/bin/su -m $USER -c "$CATALINA_HOME/bin/stop-confluence.sh &>
/dev/null"
echo "$APP stopped successfully"
;;
# Restart command
restart)
$0 stop
sleep 5
$0 start
;;
*)
echo "Usage: /etc/init.d/$APP {start|restart|stop}"
exit 1
;;
esac
exit 0
7. Set this file to run at the appropriate runlevel. For example, use sudo chkconfig --add confluence
on Redhat-based systems, sudo update-rc.d confluence defaults or rcconf on Debian-based
systems.
8. You should now be able to start Confluence with the init script. A successful startup output typically looks
like this:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
8.
Confluence 6.4 documentation 644
To continue configuring Confluence to start automatically as a service on Ubuntu Jaunty (or later):
1. After logging in as the confluence user to install Confluence, create start and stop scripts in /usr/l
ocal/confluence:
Example startscript:
#!/bin/bash
export JAVA_HOME=/usr/lib/jvm/java-7-oracle-1.7.0.71/
export JDK_HOME=/usr/lib/jvm/java-7-oracle-1.7.0.71/
cd /usr/local/confluence/current/bin
./startup.sh
Example stopscript:
#!/bin/bash
export JAVA_HOME=/usr/lib/jvm/java-7-oracle-1.7.0.71/
export JDK_HOME=/usr/lib/jvm/java-7-oracle-1.6.0.71/
cd /usr/local/confluence/current/bin
./shutdown.sh
2. Make both of these scripts executable. For example, by issuing the command: sudo chmod a+x
/usr/local/confluence/start /usr/local/confluence/stop.
3. Karmic and later: Create two text files in /etc/init/ called confluence-up.conf and confluence-
down.conf:
confluence-up:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 645
script
end script
confluence-down:
expect fork
respawn
1. Jaunty, Intrepid: Create two text files in /etc/event.d/ called confluence-up and confluence-do
wn:
confluence-up:
start on runlevel 2
start on runlevel 3
start on runlevel 4
start on runlevel 5
confluence-down:
start on runlevel 1
start on runlevel 6
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 646
For long-term use, we recommend that you configure Confluence to start automatically when the operating
system restarts. For Windows servers, this means configuring Confluence to run as a Windows service.
There are two ways to install the Confluence distribution as a service: using the Confluence installer or manually
as described below.
On this page:
Reasons for Starting Confluence as a Service
Changing the User Running the Service
Manually Installing the Confluence Distribution as a Service
Managing Confluence as a Service
Upgrading Confluence
Troubleshooting Confluence while Running as a Windows Service
Requesting Support
If you wish to run the service as a non-administrator user for security, or if you are using network drives for
backups, attachments or indexes, you can run the service as another user. To change users, open the Apache
Tomcat Confluence properties, go to the 'Log On' tab and enter the required username and password. Go to
your Windows Control Panel -> User Accounts and confirm that the user has write permissions for the <CONFLU
ENCE-INSTALL> and <CONFLUENCE-HOME> directories, and all subfolders. Note that any network drives must
be specified by UNC and not letter mappings (eg. \\backupserver\confluence not z:\confluence).
For more detail, see Creating a Dedicated User Account on the Operating System to Run Confluence.
In Windows:
1. Open a command prompt and change directory to the <CONFLUENCE-INSTALL>/bin directory.
You'll need to run the command prompt using 'Run as administrator' so that you can complete some of
these steps.
2. Confirm that the JAVA_HOME variable is set to the JDK base directory with the command:
echo %JAVA_HOME%
If you installed the Java Runtime Environment (JRE) or used the Confluence installer, replace JAVA_HOM
E with JRE_HOME. See Setting the JAVA_HOME Variable in Windows for more info.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 647
Note that any directory in the path with spaces (eg. C:\Program Files must be converted to its
eight-character equivalent (e.g. C:\Progra~1).
3. Use the following command to install the service with default settings:
The service will be called Atlassian Confluence and will be configured to start automatically by default,
but will not automatically start up until the next server reboot.
4. If you have a large Confluence installation, you can increase the maximum memory Confluence can use
(the default is 1024MB). For example, you can set the maximum memory to 2048MB using:
5. If you don't have any JVM parameters that you pass to your distribution of Confluence, you can skip this
step. If you do, add them to the service using:
Alternatively you can use the following command to launch the service properties dialog then navigate to
the Java tab to add more JVM parameters.
tomcat8w //ES//Confluence
For further configuration options, please refer to the Tomcat Windows Service How-To guide.
6. Go to Control Panel > Administrative Tools > Services > Atlassian Confluence and right-click Proper
ties to verify the settings are correct. Start the Confluence service with the command:
7. Finally, start the Confluence service. From now on this will happen automatically after the a server
reboot.
You can manage the Confluence service from the command prompt.
Stop Confluence with:
Upgrading Confluence
After upgrading Confluence, you can either uninstall and reinstall the Windows service or change the StartPath
parameter to your new folder. Refer to the Tomcat documentation for help.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 648
Note
We do not recommend that you run this tool for too long as it may disrupt other Atlassian
applications. Once you have captured the required information you will need to press Ctrl + E t
o stop capturing.
Requesting Support
If, after following the troubleshooting guide above, you still cannot make Confluence run as a Windows Service
or if there is an error when setting the JVM configuration for the service, you can create a support request.
Please provide the following information when creating your support request, because we will need it to assist
you:
Give us the result of running java -version from Windows command line console.
A screen shot of your Windows Registry setting for Tomcat.
If you have modified service.bat, please give us a copy of this file for review.
Your atlassian-confluence.log file.
Configuring Confluence
This section focuses on settings and configurations Related pages:
within the Confluence application.
Customizing your Confluence Site
For guidelines on external configuration, see Config Confluence administrator's guide
uring a Confluence Environment.
Viewing System Information
Configuring the Server Base URL
Configuring the Confluence Search and Index
Configuring Mail
Configuring Character Encoding
Other Settings
Configuring System Properties
Working with Confluence Logs
Configuring Confluence Security
Scheduled Jobs
Configuring the Whitelist
Configuring the Time Interval at which Drafts
are Saved
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 649
JMX (Java Management Extensions API) allows you to monitor the status of your Confluence instance in real
time. JMX uses objects called MBeans (Managed Beans) to expose data and resources from your application,
providing useful data such as the resource usage of your instance and its database latency, allowing you to
diagnose problems or performance issues.
In this page we'll guide you through how to use JConsole to monitor Confluence locally and remotely. JConsole
is included in the Java Development Kit (JDK), but you can use any JMX client.
If you are troubleshooting a particular issue, or only need to monitor Confluence for a short time, you can use
local monitoring. Local monitoring can have a performance impact on your server, so its not recommended for
long term monitoring of your production system.
To monitor locally:
1. Start JConsole (you'll find it in the bin directory of the JDK installation directory)
2. Select Local Process.
3. Select the Confluence process. It will be called something like org.apache.catalina.startup.Boo
tstrap start
See Using JConsole for more information on local monitoring.
Remote monitoring is recommended for production systems, as it does not consume resources on your
Confluence server.
To monitor remotely:
1. Add the following properties to your setenv.sh / setenv.bat file. The port can be any port that is not
in use.
2. Decide how you will secure your remote connection. See Remote Monitoring and Management for more
information.
Although it is possible to disable authentication, we do not recommend doing this on a production system.
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 650
3. Start JConsole (you'll find it in the bin directory of the JDK installation directory).
4. Select Remote Process.
5. Enter your hostname and port (this is the port you specified earlier, not the Confluence port).
6. Click Connect.
See Using JConsole for more information on remote monitoring.
Confluence MBeans
You can use the following Confluence MBeans to see live information about your Confluence instance.
CacheStatistics
This MBean shows information about Confluence caches. This info can also be found on the Cache Statistics pa
ge.
IndexingStatistics
This MBean shows information related to search indexing. Here's some useful attributes.
SystemInformation
This MBean shows information such as the Confluence version and uptime. This info can also be found on the S
ystem Information page.
DatabaseExampleLatency Shows the latency of an example query performed against the Milliseconds
database
RequestMetrics
This MBean shows information related to system load and error pages served.
AverageExecutionTimeForLastTenRequests Average execution time for the last ten requests. Milliseconds
MailServer-SMTPServer
This MBean shows information related to email dispatch attempts and failures. There will be an MBean for every
SMTP Mailserver that has been configured in the Confluence instance.
EmailsAttempted The number of email messages Confluence has tried to send. Integer
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 651
MailTaskQueue
SchedulingStatistics
This MBean shows information related to current jobs, scheduled tasks and the time that they were last run.
AllJobNames Shows information on current scheduled jobs including the time they String
were last run
CurrentlyRunningJobNames Lists the scheduled jobs that are currently running List
Additional MBeans
To also monitor Hibernate and Hazelcast (Confluence Data Center only) you will need to add the following
properties to your setenv.sh / setenv.bat file first.
This will make the Hibernate and Hazelcast MBeans available in your JMX client.
The Top Threads Plugin for JConsole is useful for monitoring whether the CPU is spiking. Use the following
command to start JConsole with this plugin:
The 'Modification' section of the Confluence 'System Information' screen lists the files that have been
changed since your Confluence application was installed. You will find this information particularly useful when
upgrading Confluence to a new version, because you will need to re-apply all customizations after the upgrade.
To see the modifications made to files in your Confluence installation:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 652
Notes
The modification tracker does not detect changes to class files from the confluence.jar or other JAR
files. If you modify classes, the Confluence modification detection does not report the modification.
View Space Activity
Space activity information is disabled by default, and the 'Activity' tab won't
be visible unless the Confluence Usage Stats plugin is enabled. See notes b Related pages:
elow. Page
If enabled, the space activity screen displays statistics on the activity in each History
space. These include: and Page
Compariso
How many pages and blog posts have been viewed, added or n Views
updated over a given period. Watch
Which content is the most popular (most frequently viewed). Pages,
Which content is the most active (most frequently edited). Spaces
Which people are the most active contributors/editors of content. and Blogs
How do I
To view the activity in a space:
get more
1. Go to the space and choose Space Tools at the bottom of the statistics
sidebar from
2. Choose Activity Confluenc
e?
You'll see a graphic display of the number of pages and blog posts that have been viewed, added, and
edited, showing trends over a period of time.
Screenshot: The Space Activity tab
In addition to the graphical representation of Views and Edits, the top ten most popular and most active
pages and/or blog posts will be listed, with a link to each.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 653
Notes
To view Space Activity the Confluence Usage Stats system plugin must be enabled. This plugin is
known to cause performance problems on large installations and in Confluence Cloud, and is disable
d by default. System administrators can enable this plugin (go to add-ons, select System add-ons a
nd search for 'Confluence Usage Stats').
The plugin collects data only when it's activated.
If you're using Confluence Data Center, space activity information isn't available.
Page hits aren't unique - the graph on the Space Activity screen includes all page hits, including
multiple visits by the same user.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 654
The top ten most popular and most active pages and/or blog posts will be listed, with a link to each.
Notes
The Confluence Usage Stats plugin, which provides the 'Global Activity' screen, is known to cause
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 655
performance problems on large installations. This plugin is disabled by default. A status report on the
progress of the performance issues with this plugin is available in this issue:
After adding memory, setting a proxy, or changing other Java options, it can be difficult to diagnose whether the
system has picked them up. This page tells you how to view the system properties that your Confluence site is
using.
You can see the expanded system properties on the 'System Information' screen of the Confluence
Administration Console. You do not need to restart Confluence before viewing the information.
To see the system properties recognized by your Confluence installation:
1. Choose the cog icon
The Server Base URL is the URL via which users access Confluence. The base URL must be set to the same
URL by which browsers will be viewing your Confluence site.
Confluence will automatically detect the base URL during setup, but you may need to set it manually if your site's
URL changes or if you set up Confluence from a different URL to the one that will be used to access it publicly.
You need to have System Administrator permissions in order to perform this function.
To configure the Server Base URL:
1. Choose the cog icon
Example
If Confluence is installed to run in a non-root context path (that is, it has a context path), then the server base
URL should include this context path. For example, if Confluence is running at:
http://www.foobar.com/confluence
http://www.foobar.com/confluence
Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 656
Using different URLs. If you configure a different base URL or if visitors use some other URL to access
Confluence, it is possible that you may encounter errors while viewing some pages.
Changing the context path. If you change the context path of your base URL, you also need to make
these changes:
1. Stop Confluence.
2. Go to the Confluence installation directory and edit <installation-directory>\conf\serve
r.xml.
3. Change the value of the path attribute in the Context element to reflect the context path. For
example, if Confluence is running at http://www.foobar.com/confluence, then your path a
ttribute should look like this:
Change the value of the confluence.webapp.context.path to reflect the new context path.
For example if Confluence is running at http://www.foobar.com/confluence your property
would look like this:
<property
name="confluence.webapp.context.path">/confluence</property>
Related pages:
Search
Confluence Administrator's Guide
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 657
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 658
1.
The search index is maintained automatically, but you may need to rebuild it manually if your searching and
mail threading are malfunctioning, or if directed to in the upgrade notes for a new version.
To rebuild the search index:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 659
The 'Did You Mean' feature is no longer available in Confluence. This index is therefore redundant, and will
be removed at some time in the future.
Slow reindexing
Does the reindexing take a long time to complete? The length of time depends on the following factors:
Number of pages in your Confluence instance.
Number, type and size of attachments.
Amount of memory allocated to Confluence.
Disk throughput.
It may help to increase the heap memory allocation of Confluence by following the instructions here Increasin
g JIRA application memory. The process is basically the same for Confluence or JIRA applications.
If you are running an older version of Confluence and find that the index rebuild is not progressing, you may
need to shut down Confluence, and restart it with the following Java system property set: bucket.indexin
g.threads.fixed=1. This will cause the re-indexing to happen in a single thread and be much more stable
(but slower).
Confluence uses a search engine called Lucene. If you need to see more details of the indexed pages in
your Confluence site, you can download and run Luke. Luke is a development and diagnostic tool that
accesses existing Lucene indexes and allows you to display and modify their content in several ways.
Start Luke and use it to open the index directory, located in your Confluence Home directory. For example:
c:\confluence\data\confluence-home\index.
Note: Confluence 5.2 (and later) use Lucene 4.3 (or later). If the Luke library has not been updated to
support the latest version of Lucene, you can compile Luke yourself, from the fork on Github please read
the warnings and notes in the README file of that repository.
If you are still experiencing problems after performing the above rebuild, the next step might be to rem
ove the index and rebuild it from scratch.
The space activity feature uses the index to store data. If you remove the index file, the existing
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 660
Enabling OpenSearch
With OpenSearch autodiscovery, you can add Confluence search to your Related pages:
Firefox or IE7 search box (see Searching Confluence from your Browser's
Search Box). By default, OpenSearch autodiscovery is enabled. This feature Search
can be enabled or disabled as described below. Confluenc
e
To enable or disable OpenSearch autodiscovery: Administra
tor's Guide
1. Choose the cog icon
http://yoursite/admin/permissions/pagepermsad
min.action
After rebuilding the ancestor table, you'll need to flush the "Inherited Content
Permissions" cache in Cache Statistics , otherwise the inherited permissions
may not be applied immediately to all pages. You may also need to rebuild
the content index so that the permissions take effect in search results.
Screenshot: Page level permissions
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 661
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.
Use your own programmer resources to replace Confluence's internal search with a crawler that indexes both
Confluence and external sites. This advanced option is easier than modifying the internal search engine. It
requires removing Confluence internal search from all pages and replacing the internal results page with your
own crawler front-end.
1. Setup a replacement federated search engine to index the Confluence site, as well as your other sites,
and provide the results that way. You would need to host a web crawler, such as these open-source
crawlers. Note that you can perform a search in Confluence via the Confluence API.
2. Replace references to the internal search by modifying the site layout so that it links to your search
front-end
3. Host another site containing the search front-end. You may wish to insert it into a suitable context path
in your application server so that it appears to be from a path under Confluence. Tomcat sets
Confluence's paths from the Confluence install\confluence\WEBINF\web.xml file.
Configuring Mail
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 662
On this page:
Configuring Confluence to send email messages
Testing the email settings
Related pages:
The Mail Queue
Setting Up a Mail Session for the Confluence
Distribution
Variable Description
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 663
The simplest way to set up a mail server through the Confluence Administration console. See Configuring a
Server for Outgoing Mail.
If you want to add different options or parameters you can also set up a mail session for the Confluence
distribution. In the example below we'll set up Gmail.
To set up a mail session for the Confluence distribution:
1. Stop Confluence.
2. Move (don't copy) mail-x.x.x.jar from <confluence-install>\confluence\WEB-INF\lib to
<confluence-install>\lib (x.x.x. represents the version numbers on the jar files in your
installation).
Don't leave a renamed backup of the jar files in \confluence\WEB-INF\lib. Even with a different file
name, the files will still be loaded as long as it remains in the directory.
3. Edit the <confluence-install>\conf\server.xml file and add the following at the end of the
Confluence <context> tag, just before </Context>.
Note: you're editing the <context> tag that contains the Confluence context path, not the one that contains
the Synchrony context path.
<Resource name="mail/GmailSMTPServer"
auth="Container"
type="javax.mail.Session"
mail.smtp.host="smtp.gmail.com"
mail.smtp.port="465"
mail.smtp.auth="true"
mail.smtp.user="yourEmailAddress@gmail.com"
password="yourPassword"
mail.smtp.starttls.enable="true"
mail.transport.protocol="smtps"
mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"
/>
4. Restart Confluence.
5. Go to
java:comp/env/mail/GmailSMTPServer
Note that the JNDI Location is case sensitive and must match the resource name specified in server.xml.
8. Save your changes and send a test email.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 664
content that is relevant to the person receiving the message, from spaces On this page:
they have permission to view. This is called the 'Recommended Updates'
notification. Initial
settings of
If you have Confluence Administrator or System Administrator permissions, the
you can configure the default settings that determine how often the defaults
Recommended Updates notification is sent. When new users are added to Configurin
Confluence, the default settings will be applied to their user profiles. g the
Recomme
Confluence users can choose their personal settings, which will override the
nded
defaults. See Email Notifications.
Updates
notification
Initial settings of the defaults
Disabling
When you install Confluence, the initial values of the default settings are as the
follows: Recomme
nded
The default frequency is weekly. Updates
If your Confluence site has public signup enabled, the Recommended notification
Updates notification is disabled by default. If public signup is not for the
enabled, the notification is enabled by default. entire site
You can change the above settings, specifying a different default value for Related pages:
the site.
Email
Notes: Notification
s
The Recommended Updates notification is sent only to people who
have a user profile in Confluence. If your Confluence site uses
external user management, such as LDAP, then people will receive
the report only after they have logged in for the first time. (The first
login creates their user profile.)
The daily email message is sent at 1 p.m. in the user's configured
time zone.
The weekly email message is sent at 1 p.m. on Thursdays in the
user's configured time zone.
Configuring the Recommended Updates notification
You can set the default send option (send / do not send) and the default schedule (daily or weekly).
To configure the Recommended Updates email notification:
1. Choose the cog icon
You can also turn off the recommended updates notification for the entire site, by disabling the 'Confluence
daily summary email' plugin. See Disabling and enabling add-ons.
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 665
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 666
1. Database encoding - usually the most important; it is where almost all user data is stored.
2. Filesystem encoding - important for attachment storage (pre-2.2), reading Velocity templates and
writing exported files.
3. HTTP request and response encoding - important for form parsing, correct rendering by the browser
and browser interpretation of encoded URLs.
Problems generally arise when Confluence thinks one of the above encoding is different to what it actually is.
For example, Confluence might believe the database is using ISO-8859-1 encoding, when in fact it is UTF-8
encoded.
In certain cases (for example, Microsoft Windows), it might not be possible to use a fully Unicode filesystem
(that is, a default Windows installation does not support Unicode filenames properly). If so, keep UTF-8 for
the other two and be aware that your operating system might have limitations around international
attachments (pre-2.2), backup and restore of international data, etc.
Java always uses the multibyte UTF-16 character encoding for all String data*. This means that each of
the encodings above defines how, at that particular point, characters are converted to and from Java's native
UTF-16 format into some other format that the browser, filesystem or database might understand.
So when a request comes in to Confluence, we convert it from the request encoding to UTF-16. Then we
store that data into the database, converting from UTF-16 to the database's encoding. Retrieving information
from the database and sending it back to the browser is the same process in the opposite direction.
*A char represents single Unicode code point from the Base Multilingual Plane (BMP), encoded as UTF-16.
Multiple chars are used as surrogate pairs for characters beyond U+FFFF.
The Confluence character encoding is used in the following parts of the system:
ConfluenceWebWorkConfiguration sets webwork.i18n.encoding to the this encoding, which
WebWork uses in the response Content-Type header.
AbstractEncodingFilter sets the HTTP request encoding to this encoding. This seems unnecessary,
since the Content-Type header from the client should include the encoding used. This affects form
submissions and file uploads.
VelocityUtils reads in Velocity templates using this encoding when reading templates from disk.
AbstractXmlExporter creates its output using this encoding.
GeneralUtil uses this encoding when doing URLEncode and URLDecode. Different browsers have
different support for character sets in URLs, so it's uncertain how much benefit this provides.
See Configuring Confluence Character Encoding (described above.)
Database encoding
The database encoding is the responsibility of your JDBC drivers. The drivers are responsible for reading
and writing from the database in its native encoding and translating this data to and from Java Strings (which
are UTF-16). For some drivers, such as MySQL, you must set Unicode encoding explicitly in the JDBC URL.
For others, the driver is smart enough to determine the database encoding automatically.
Ideally, your database itself should be in a Unicode encoding (and we recommend doing this for the simplest
configuration), but that is not necessary as long as:
the database encoding supports all the characters you want to store in Confluence
your JDBC drivers can properly convert from the database encoding to UTF-16 and vice-versa.
See Configuring Database Character Encoding.
Filesystem encoding
The filesystem encoding is mostly ignored by Confluence, except for the cases where the above
configuration setting above plays a part (exports, velocity). When attachments are uploaded, they are written
as a stream of bytes directly to the filesystem. It is the same when they are downloaded: the bytes from the
file InputStream are written directly to the HTTP response.
In some places in Confluence, we use the default filesystem encoding as determined by the JVM and stored
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 667
in the file.encoding system property (it can be overridden by setting this property at startup). This
encoding is used by the Java InputStreamReader and InputStreamWriter classes by default. This encoding
should probably never be used; for consistent results across all filesystem access we should be using the
encoding set in the General Configuration.
In certain cases we explicitly hard-code the encoding used to read or write data to the filesystem. Two
important examples are:
importing Mbox mailboxes which are known to be ISO-8859-1
Confluence Bandana config files are always stored as UTF-8.
Some application servers, Tomcat for example, have an encoding setting that modifies Confluence URLs
before they reach the application. This can prevent access to international pages and attachments (really
anything with international characters in the URL). See configuring your Application Server URL encoding.
If Confluence has the wrong idea about encoding for one of the above, it manifests itself in different ways:
1. Incorrect database encoding - user data is corrupted between saving and restoring from the database.
This often happens after a delay, as we cache data as it is written to the database and only later
retrieve the corrupted copy from the database.
2. Incorrect/non-Unicode filesystem encoding - international filenames break attachment
download/upload/removal (pre-2.2); exports break with international content or attachments.
3. Incorrect HTTP encoding - incorrect encoding selected by browser, resulting in incorrect rendering of
characters. Changing browser encoding causes page to render properly. Broken URLs when linking to
pages or attachments with non-ASCII characters.
See Troubleshooting Character Encodings.
Notes
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.
This is a good article by Joel Spolsky: The Absolute Minimum Every Software Developer Absolutely,
Positively Must Know About Unicode and Character Sets (No Excuses!)
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.
Confluence includes an encoding test that can reveal problems with your configuration.
To perform the test, access the Encoding Test page via the <confluence
base-url>/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.
You should also test pasting some sample text (Japanese for example) if you are experiencing problems with a
specific language.
Example:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 668
http://confluence.atlassian.com/admin/encodingtest.action
or
http://<host address>:<port>/admin/encodingtest.action
If the text displayed in the encoding test is different to what was entered, then there are problems with
your character encoding settings.
MySQL 3.x
MySQL 3.x is known to have some problems with the upper- and lower-casing of some characters, and
may fail the last two tests. For more information, see MySQL 3.x Character Encoding Problems.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 669
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
"" Euro character not displaying properly
The (euro) symbol is a three byte character, with byte values in file (UTF-8) of 0xE2, 0x82, 0xAC.
Sometimes, if the character encoding is not set consistently among all participating entities of the system,
Confluence, server and the database, one may experience strange behavior.
...
I write a page with a Euro sign in it (). All is well, the Euro sign shows up in the wiki markup
text-box, and the preview, and the display of the saved page.
One day later, the Euro sign has changed into a question mark upside down!
...
What is going on? Why does the Euro sign mysteriously change? How do I prevent it?
Interestingly enough the character encoding test passes with no problems, demonstrating that Confluence and
the connected Database both recognize the symbol.
There are two potential reasons for this behavior:
Database and Confluence is using utf-8 encoding. The connection is not.
When data transferred to it via the connection which does not use utf-8 encoding gets encoded incorrectly.
Hence, updating the connection encoding may resolve this problem from now on, yet it probably would not affect
already existing data.
Database is not using utf-8. Confluence and your connection are.
If your Database encoding is not set to UTF-8, yet is using some other encoding such as latin1, it could be one
of the potential reasons why you lose the "" characters at some stage. It could be occurring due to caching.
When Confluence saves data to the database, it may also keep a local cached copy. If the database encoding is
set incorrectly, the Euro character may not be correctly recorded in the database, but Confluence will continue to
use its cached copy of that data (which is encoded correctly). The encoding error will only be noticed when the
cache expires, and the incorrectly encoded data is fetched from the database.
For instance the latin1 encoding would store and display all 2-byte UTF8 characters correctly except
for the euro character which is replaced by '?' before being stored. As Confluence's encoding was set
to UTF-8, the 2-byte UTF-8 characters were stored in latin1 database assuming that they were two la
tin1 different characters, instead of one utf8 character. Nevertheless, this is not the case for 3-byte
utf8 characters, such as the Euro symbol.
Please ensure that you set the character encoding to UTF-8 for all the entities of your system as advised in this
guide.
MySQL 3.x Character Encoding Problems
MySQL 3.x is known to have some problems upper- and lower-casing certain (non-ASCII) characters.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 670
Solution
Upgrade to a newer version of MySQL. (4.1 is confirmed to work.)
Other Settings
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 671
(regex)
Disable or enable strict path checking
Enable or disable access to specific virtual files/folders
Note:
The 'WebDav Configuration' page is only available if the WebDAV plugin has been enabled. This
plugin is bundled with Confluence, and can be enabled or disabled by the System Administrator.
The settings on the 'WebDav Configuration' page do not apply to external attachment storage
configuration.
The following sections tell you how to set up a WebDAV client natively for a range of different operating
systems. WebDAV clients typically appear as drives in your operating system's file browser application, such
as Windows Explorer in Microsoft Windows, or Konqueror in Linux.
You can successfully connect but you can't see content when using HTTPS, so this technique won't
work for Confluence Cloud. Use a third-party WebDAV client instead.
http://<confluenceURL>/plugins/servlet/confluence/default
http://ourconfluence.atlassian.net/wiki/plugins/servlet/confluen
ce/default
Use your username (jsmith), not your email address, unless your email address is your
username.
Confluence will appear as a shared drive in Finder. You can use the same URL to connect using a third party
WebDav client, like CyberDuck.
This section covers the two methods for configuring a WebDAV client natively in Microsoft Windows:
As a network drive
As a web folder
If possible, use the network drive method as this will enable more comprehensive WebDAV client interaction
with Confluence than that provided by a web folder. However, your Confluence instance must meet several
environmental constraints if you use this method. If you cannot configure your instance to meet these
requirements, then use the web folder method or third-party WebDAV client software.
If you're using SSL you may need to add @SSL to the end of your server URL, for example:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 672
http://<confluence server
url>@SSL/confluence/plugins/servlet/confluence/default
If you run into any problems with the procedures in this section, please refer to the WebDAV Troubleshooting
page.
To map a Confluence WebDAV client network drive, your Confluence instance must be configured so that all
of the following criteria is met:
Has no context root
There's an issue that can prevent Network Drives from being mapped. Please use the Network
Folders steps below as a workaround.
The reason for these restrictions results from limitations in Microsoft's Mini-Redirector component. For more
information, please refer to Microsoft's server discovery issue.
To map a Confluence WebDAV client network drive in Microsoft Windows:
1. In Windows XP, go to My Computer->Tools menu->Map Network Drive
In Windows Vista, go to Computer->Map Network Drive
2. Specify the following input to map the WebDAV client as a network drive:
Drive:<Any drive letter> (for example, Z:)
Folder:\\<hostname>\webdav (for example, \\localhost\webdav)
3. Click Finish
When prompted for login credentials, specify your Confluence username and password.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 673
There are many tools and mechanisms available for configuring WebDAV clients in these operating systems.
Therefore, we have chosen to demonstrate this using the file manager Konqueror, which is part of the Linux
K Desktop Environment.
To set up a Confluence WebDAV client in Konqueror:
1. Open Konqueror
2. In the 'Location' field, enter the URL for the Confluence WebDAV location using the 'protocol' webdav
s (for example, webdavs://<confluence server
url>/confluence/plugins/servlet/confluence/default or webdavs://<confluence
server url>/plugins/servlet/confluence/default) and press Enter.
You should be able to click to load many, but not all files. In practice, you would normally save a modified file
locally, then drag it to the Konqueror window to upload it to Confluence.
In earlier versions of the WebDAV plugin, separate options for restricting a WebDAV client's write
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 674
permissions (that is, create/move, edit and delete actions), were available. However, in the current version of
this plugin, they have been simplified and combined into a general write permission restriction that covers all
of these actions.
WebDAV clients are now denied write permission to your Confluence installation by setting a regex that
matches specific content within the WebDAV client's user agent header. Upon setting a regex, it will be
added to a list of restricted WebDAV clients. Any WebDAV clients whose user agent header matches a regex
in this list will be denied write permission to your Confluence installation.
Example: A PROPFIND method header generated by a Microsoft Web Folder WebDAV client, showing the
user agent header field:
Unlike earlier versions of the WebDAV plugin, which could only restrict write permissions for all Web
DAV clients, the current version of this plugin allows you to restrict write permissions to specific
WebDAV clients.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 675
If you observe any idiosyncrasies with your WebDAV client, such as a folder that does exist on your
Confluence site but is missing from the client, you can disable the WebDAV plugin's strict path checking
option, which may minimize these problems.
To disable the WebDAV plugin's strict path checking option:
1. Choose the cog icon
In the unlikely event that you have problems with the WebDAV client's performance or stability, you can
enable access to automatically generated (that is, virtual) files and folders.
Note:
By default, these options are hidden on the 'WebDAV Configuration' page. To make them visible, append the
parameter ?hiddenOptionsEnabled=true to the end of your URL and reload the page. For example:
<Confluence base
URL>/admin/plugins/webdav/config.action?hiddenOptionsEnabled=true
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 676
When macros such as the RSS Macro make HTTP requests to servers which are down, a long timeout value is
used. You can set this timeout value through a system parameter to avoid this.
To configure the HTTP Timeout Settings:
1. Choose the cog icon
Confluence uses the guidelines in this Java document from Oracle: Class NumberFormat.
To change the number formats in Confluence:
1. Choose
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 677
Shortcut links are added and maintained by Confluence administrators from the Administration Console.
Enter a shortcut link on the Advanced tab of the Insert Link dialog. See Links for details.
Specify in the link what should be appended to the end of the shortcut URL, followed by an at-sign (@) and
the key of the shortcut. Shortcut names are case-insensitive. So, for example, using the keys shown in the
above screenshot:
a Atlassian http://www.google.com/search?q=Atlassian+Confluence
Google Confluence@Google
search
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 678
Shortcut links are listed on the Shortcut Links tab of the Administration Console. Click Remove to delete
the shortcut.
XML-RPC and SOAP remote APIs were deprecated in Confluence 5.5. We recommend using the fully
supported Confluence Server REST API wherever possible.
To use the XML-RPC and SOAP remote APIs you need to enable the APIs from the Administration Console.
You'll need System Administrator permissions to do this.
To enable the remote API:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 679
To install a language pack manually, you will need to upload the language pack plugin as described below.
The language pack plugin will be enabled by default once you have installed it.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 680
Plugins are distributed as JAR or OBR (OSGi Bundle Repository) files. To install a plugin:
1. Choose the cog icon
You can download official language packs from the Atlassian Marketplace. You can also download
language packs developed by the Confluence user community from https://translations.atlassian.com.
This feature is useful if you are working on creating translations of the Confluence user interface. After
opening the Confluence dashboard, you can add the following action to the end of your Confluence URL:
?i18ntranslate=on
This will cause each element of the user interface to display its special key name. This makes it easier to
find the context for each key within the user interface. You can then search for the key on http://translations.a
tlassian.com where you can enter an appropriate translation for your custom language pack.
The key names are displayed with a 'lightning bolt' graphic. For example:
To turn off the translation view, add the following to the end of the Confluence URL:
?i18ntranslate=off
Atlassian support or the Atlassian bug-fixing team may occasionally provide patches for critical issues that have
been resolved but have not yet made it into a release. Those patches will be class files which are attached to the
relevant issue in our JIRA bug-tracking system.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 681
will need to create them before copying the class files. Some issues will contain the patch in the
form of a ZIP file which will contain the desired directory structure.
3. Restart your Confluence instance for the changes to become effective.
Class files in the /WEB-INF/classes directory of a web application will be loaded before classes located in
JAR files in the /WEB-INF/lib directory. Therefore, classes in the first directory will effectively replace classes
of the same name and package which would otherwise be loaded from the JAR files.
To revert the patch, simply remove the class files from the <installation-directory>/confluence/WEB
-INF/classes/ folder (taking care to only remove those that apply to the patch you wish to revert), then restart
the instance.
Once the issue that the patch relates to is resolved, you should upgrade to the version of Confluence
that contains the fix, and revert the patch. Patches are often naive and untested and may not solve the
problem in the most efficient way. As such, an official fix should be preferred in all cases.
To Configure System Properties in Windows Installations When Starting from the .bat File:
1. Edit the <installation-directory>/bin/setenv.bat file.
2. Find the section set CATALINA_OPTS=%CATALINA_OPTS%
(this is JAVA_OPTS=%JAVA_OPTS% in Confluence 5.5 and earlier)
3. Refer to the list of parameters below.
Add all parameters in a space-separated list. Make sure to keep the string %CATALINA_OPTS% in
place.
Windows Service
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 682
There are two ways to configure system properties when you Start Confluence Automatically on Windows as
a Service, either via command line or in the Windows Registry
tomcat8w //ES//<SERVICENAME>
5. Append any new option on its own new line by adding to the end of the existing Java Options. Refer to
the list of parameters below.
In some versions of Windows, there is no option to add Java variables to the service. In these cases, you
must add the properties by viewing the option list in the registry.
1. Go to the Registry Editor (Start > regedit.exe).
2. Find the Services entry:
HKEY_LOCAL_MACHINE >> SOFTWARE >> Apache Software Foundation >> Procrun 2.0
>> Confluence service name
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
2.
Confluence 6.4 documentation 683
If you've used the Quick Start or CloudFormation template to deploy Confluence Data Center in AWS, you
will pass system properties via the Cloud Formation Template, and not using the methods described above.
1. In the AWS Console, choose Update Stack
2. Under Advanced, enter system properties in the Catalina Properties field as follows:
atlassian.forceSchemaUpdate
1.0 false atlassian-config By default, Confluence will only run its database
schema update when it detects that it has been
upgraded. This flag will force Confluence to perform
the schema update on system startup.
confluence.home
1.0 Any Confluence and If this system property is set, Confluence will ignore
filesystem atlassian-config the contents of the confluence-init.properti
path es file, and use this property as the setting for the
Confluence Home directory.
confluence.dev.mode
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 684
confluence.disable.mailpolling
confluence.i18n.reloadbundles
1.0 true Confluence Setting this property will cause Confluence to reload
its i18n resource bundles every time an
internationalized string is looked up. This can be
useful when testing translations, but will make
Confluence run insanely slowly.
confluence.ignore.debug.logging
confluence.jmx.disabled
confluence.optimize.index.modulo
confluence.plugins.bundled.disable
atlassian.indexing.contentbody.maxsize
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 685
3.0 1048576 atlassian When a file is uploaded, its text is extracted and
indexed. This allows people to search for the
content of a file, not just the filename.
If the amount of content extracted from the file
exceeds the limit set by this property (default is
1MB, in bytes), the file's contents will still be indexed
and searchable, but will not appear when the file is
returned in search results. Increasing this limit may
make displaying search results slower. See Configu
ring Attachment Size for more info.
atlassian.mail.fetchdisabled
3.5 false Confluence Disables mail fetching services for IMAP and POP
atlassian.mail.senddisabled
atlassian.disable.caches
2.4 true atlassian-plugins, Setting this property will disable conditional get and
atlassian-cache-servlet expires: headers on some web resources. This will
significantly slow down the user experience, but is
useful in devlopment if you are frequently changing
static resources and don't want to continually flush
your browser cache.
confluence.html.encode.automatic
org.osgi.framework.bootdelegation
confluence.diff.pool.size
confluence.diff.timeout
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 686
confluence.html.diff.timeout
atlassian.user.experimentalMapping
confluence.import.use-experimental-importer
3.2 false Confluence Setting this property changes Confluence to use the
Experimental XML Importer. It is designed to be a
more stable implementation but, at the time of the
release of 3.2, the importer is largely untested and
thus not supported.
atlassian.webresource.disable.minification
index.queue.thread.count
3.3 See "Effect" Confluence Sets the number of threads to be used for the
reindex job. The value has to be in the range of 1 to
50 (inclusive), i.e. at least one thread but no more
than 50 threads will be used. There is no default
value, i.e.
If you don't set index.queue.thread.count,
the number of threads to be used are calculated
based on the number of objects that need to be
reindexed and the number of processors
available (a maximum of 50 threads will be
used).
If you set index.queue.thread.count=2,
then two threads will be used to reindex the
content (regardless of the number of objects to
be reindexed or the number of processors
available)
If you set index.queue.thread.count=200,
then ten threads (the maximum allowed) will be
used to reindex the content.
Note: For Confluence versions from 3.3 to 5.6 the
maximum threads is 10.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 687
index.queue.batch.size
3.3 1500 Confluence Size of batches used by the indexer. Reducing this
value will reduce the load that the indexer puts on
the system, but indexing takes longer. Increasing
this value will cause indexing to be completed
faster, but puts a higher load on the system.
Normally this setting does not need tuning.
password.confirmation.disabled
confluence.browser.language.enabled
3.5 true Confluence Setting this property to "false" disables the detection
of browser language headers, effectively restoring
Confluence behavior to that of earlier releases.
Setting this property to "true" enables the detection
of the language headers sent by the browser.
Confluenc will change the UI language based on the
browser headers. See documentation on how users
can choose a language preference.
upm.pac.disable
Universal false Universal Plugin When this property is set to true, then UPM will not
Plugin Manager (UPM) try to access the The Atlassian Marketplace. This is
Manager useful for application servers that do not have
1.5 access to the Internet. See the UPM documentation.
confluence.reindex.documents.to.pop
confluence.reindex.attachments.to.pop
confluence.upgrade.active.directory
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 688
confluence.context.batching.disable
com.atlassian.logout.disable.session.invalidation
officeconnector.spreadsheet.xlsxmaxsize
4.0.5 2097152 Office Connector Indicates the maximum size in bytes of an Excel file
that can be viewed using the viewxls macro. If
empty, the maximum size defaults to 2Mb. See CO
NF-21043 for more details.
com.atlassian.confluence.extra.calendar3.display.events.calendar.maxpercalendar
com.atlassian.confluence.allow.downgrade
confluence.skip.reindex
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 689
reindex.thread.count
reindex.attachments.thread.count
confluence.mbox.directory
confluence.search.max.results
5.5 1000 Confluence Setting this property changes the maximum number
of items Confluence Search will return.
confluence.upgrade.recovery.file.enabled
confluence.junit.report.directory
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 690
officeconnector.textextract.word.docxmaxsize
5.5.3 16777216 Confluence When a file is uploaded, its text is extracted and
indexed. This allows people to search for the
content of a file, not just the filename.
Confluence will only extract content from a Word
document up to the limit set by this property
(defaults to 16MB, in bytes), before proceeding to
index it. This will mean that only part of file's
contents are searchable. See Configuring
Attachment Size for more info.
cluster.login.rememberme.enabled
confluence.cluster.hazelcast.listenPort
confluence.document.conversion.threads
confluence.document.conversion.threads.wait
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 691
5.7 1000 Confluence Set this property to change the maximum number of
items that can be queued for conversion.Any file
conversion requests that are made when this
maximum limit has been reached are aborted.
confluence.cluster.node.name
5.7 Confluence Set this property to give each node in your Data
Center cluster a human readable name (displayed
in email notifications and in the footer). If left unset,
Confluence will assign a node identifier to each
node.
confluence.document.conversion.fontpath
5.8.7 Confluence Set this property to define a directory where you can
add additional fonts to be used when rendering files
(in previews and thumbnails).
This is useful if you need to support previewing files
with specific fonts, or fonts with multibtye characters
(such as Japanese).
confluence.document.conversion.words.defaultfontname
5.8.7 Confluence Set this property to change the default font for
rendering Word (.doc and .docx) files in
Confluence.
Specify just the name of the font (not the path).
confluence.document.conversion.slides.defaultfontname.regular
5.8.7 Confluence Set this property to change the default font for
rendering regular fonts in Powerpoint (.ppt and .p
ptx) files in Confluence.
confluence.document.conversion.slides.defaultfontname.asian
5.8.7 TakaoPGothic Confluence Set this property to change the default font for
rendering asian fonts in Powerpoint (.ppt and .pp
tx) files in Confluence.
confluence.document.conversion.slides.defaultfontname.symbol
5.8.7 Confluence Set this property to change the default font for
rendering symbols in Powerpoint (.ppt and .pptx)
files in Confluence.
This is the font that will be used for bullets and other
symbols when the font Symbol is not found.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 692
confluence.clickjacking.protection.disable
confluence.cluster.index.recovery.query.timeout
confluence.cluster.index.recovery.generation.timeout
confluence.cluster.index.recovery.num.attempts
com.atlassian.confluence.officeconnector.canary.memory_value
5.9.1 1024 Confluence Sets the memory (in megabytes) available to the
Office Connector Canary process, which is a
workaround for a known issue with the Import from
Word option. See JVM crashes during Import from
Word in Confluence for more information.
com.atlassian.confluence.officeconnector.canary.timeout
5.9.1 120000 Confluence Sets the maximum timeout (in milliseconds) for the
Office Connector Canary process, which is a
workaround for a known issue with the Import from
Word option. See JVM crashes during Import from
Word in Confluence for more information.
atlassian.plugins.enable.wait
5.9.5 300 Set this property to increase the default time to wait
for plugins to start up. This is useful if you have
problems with plugins not starting up in time,
causing Confluence to fail to start.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 693
confluence.cluster.hazelcast.max.no.heartbeat.seconds
5.9.7 30 Confluence In Confluence Data Center, this sets how long (in
seconds) a node can be out of communication with
the cluster before it's removed from the cluster. See
balancing uptime and data integrity for more info on
when you may want to change this setting.
confluence.startup.remigration.disable
cluster.safety.time.to.live.split.ms
confluence.cph.max.entries
6.0.0 2000 Confluence This is the maximum number of pages that can be
copied when you copy a page and its child pages.
Increase this if you need to copy a page with more
than the default number of child pages.
confluence.cph.batch.size
6.0.0 8091 This is the port that Synchrony, the service that
powers collaborative editing, runs on. You should
only need to change this if port 8091 is not
available. For Confluence Data Center system
properties see Configuring Synchrony for Data
Center.
From 6.0.4, Confluence Server will accept either re
za.port or synchrony.port.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 694
synchrony.stack.space
6.0.0 2048k This sets the stack size (Xss) of the Synchrony
JVM. Increase if you experience stack overflow
errors, or decrease if you experience out of memory
errors from Synchrony.
synchrony.enable.xhr.fallback
synchrony.database.test.connection.on.checkin
synchrony.proxy.enabled
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 695
synchrony.context.path
6.0.0 /synchrony This is the context path for Synchrony. There should
be no need to change this in Confluence Server.
confluence.flyingpdf.default.characters.per.line
synchrony.host
synchrony.proxy.healthcheck.disabled
page.index.macro.max.pages
6.1.4 5000 Sets the maximum number of pages that the Page
Index macro can display. The Page Index macro
can significantly slow down your Confluence
instance and cause out of memory errors when
used in a space with a large number of pages. If the
number of pages in the space exceeds this limit, the
Page Index macro will show a page count, and a
message that there are too many pages to display.
atlassian.indexing.attachment.maxsize
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 696
officeconnector.excel.extractor.maxlength
confluence.collab.edit.user.limit
Confluence supports some configuration and debugging settings that can be enabled through Java system
properties. System properties are usually set by passing the -D flag to the Java virtual machine in which
Confluence is running. See the full instructions: Configuring System Properties.
atlassian.forceSchemaUpdate
1.0 false atlassian-config By default, Confluence will only run its database
schema update when it detects that it has been
upgraded. This flag will force Confluence to perform the
schema update on system startup.
confluence.home
1.0 Any Confluence and If this system property is set, Confluence will ignore the
filesystem atlassian-config contents of the confluence-init.properties file,
path and use this property as the setting for the Confluence
Home directory.
confluence.dev.mode
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 697
confluence.disable.mailpolling
2.4 false Confluence If set to "true", will prevent Confluence from retrieving
mail for archiving within spaces. Manually triggering
"check for new mail" via the web UI will still work. This
property has no effect on outgoing mail
confluence.i18n.reloadbundles
1.0 true Confluence Setting this property will cause Confluence to reload its
i18n resource bundles every time an internationalized
string is looked up. This can be useful when testing
translations, but will make Confluence run insanely
slowly.
confluence.ignore.debug.logging
1.0 true Confluence Confluence will normally log a severe error message if
it detects that DEBUG level logging is enabled (as
DEBUG logging generally causes a significant
degradation in system performance). Setting this
property will suppress the error message.
confluence.jmx.disabled
confluence.optimize.index.modulo
confluence.plugins.bundled.disable
atlassian.indexing.contentbody.maxsize
3.0 1048576 atlassian When a file is uploaded, its text is extracted and
indexed. This allows people to search for the content of
a file, not just the filename.
If the amount of content extracted from the file exceeds
the limit set by this property (default is 1MB, in bytes),
the file's contents will still be indexed and searchable,
but will not appear when the file is returned in search
results. Increasing this limit may make displaying
search results slower. See Configuring Attachment Size
for more info.
atlassian.mail.fetchdisabled
3.5 false Confluence Disables mail fetching services for IMAP and POP
atlassian.mail.senddisabled
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 698
atlassian.disable.caches
2.4 true atlassian-plugins, Setting this property will disable conditional get and
atlassian-cache-servlet expires: headers on some web resources. This will
significantly slow down the user experience, but is
useful in devlopment if you are frequently changing
static resources and don't want to continually flush your
browser cache.
confluence.html.encode.automatic
org.osgi.framework.bootdelegation
confluence.diff.pool.size
confluence.diff.timeout
confluence.html.diff.timeout
atlassian.user.experimentalMapping
2.10 false Confluence Setting this property changes the relationship between
local users and local groups to reduce performance
degradation when adding a local user to a local group
with a large number of users. Please note, setting this
property can slow down other user management
functions. We recommend that you set it only if you are
experiencing performance problems when adding local
users to large local groups. Please refer to CONF-1231
9, fixed in Confluence 3.1.1.
confluence.import.use-experimental-importer
3.2 false Confluence Setting this property changes Confluence to use the
Experimental XML Importer. It is designed to be a more
stable implementation but, at the time of the release of
3.2, the importer is largely untested and thus not
supported.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 699
atlassian.webresource.disable.minification
index.queue.thread.count
3.3 See "Effect" Confluence Sets the number of threads to be used for the reindex
job. The value has to be in the range of 1 to 50
(inclusive), i.e. at least one thread but no more than 50
threads will be used. There is no default value, i.e.
If you don't set index.queue.thread.count,
the number of threads to be used are calculated
based on the number of objects that need to be
reindexed and the number of processors available
(a maximum of 50 threads will be used).
If you set index.queue.thread.count=2, then
two threads will be used to reindex the content
(regardless of the number of objects to be
reindexed or the number of processors available)
If you set index.queue.thread.count=200,
then ten threads (the maximum allowed) will be
used to reindex the content.
Note: For Confluence versions from 3.3 to 5.6 the
maximum threads is 10.
index.queue.batch.size
3.3 1500 Confluence Size of batches used by the indexer. Reducing this
value will reduce the load that the indexer puts on the
system, but indexing takes longer. Increasing this value
will cause indexing to be completed faster, but puts a
higher load on the system. Normally this setting does
not need tuning.
password.confirmation.disabled
confluence.browser.language.enabled
3.5 true Confluence Setting this property to "false" disables the detection of
browser language headers, effectively restoring
Confluence behavior to that of earlier releases. Setting
this property to "true" enables the detection of the
language headers sent by the browser. Confluenc will
change the UI language based on the browser headers.
See documentation on how users can choose a
language preference.
upm.pac.disable
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 700
Universal false Universal Plugin When this property is set to true, then UPM will not try
Plugin Manager (UPM) to access the The Atlassian Marketplace. This is useful
Manager for application servers that do not have access to the
1.5 Internet. See the UPM documentation.
confluence.reindex.documents.to.pop
confluence.reindex.attachments.to.pop
confluence.upgrade.active.directory
confluence.context.batching.disable
4.0 false Confluence Disables batching for web resources in contexts (e.g.
editor, main, admin). Useful for diagnosing the source
of javascript or CSS errors.
com.atlassian.logout.disable.session.invalidation
4.0 false Confluence Disables the session invalidation on log out. As of 4.0
the default behavior is to invalidate the JSession
assigned to a client when they log out. If this is set to
true the session is kept active (but the user logged out).
This may be valuable when using external
authentication systems, but should generally not be
needed.
officeconnector.spreadsheet.xlsxmaxsize
4.0.5 2097152 Office Connector Indicates the maximum size in bytes of an Excel file
that can be viewed using the viewxls macro. If empty,
the maximum size defaults to 2Mb. See CONF-21043 f
or more details.
com.atlassian.confluence.extra.calendar3.display.events.calendar.maxpercalendar
200 Team Calendars Specifies the maximum number of events per calendar.
This property is effective only if the Team Calendars plu
gin is installed on your Confluence site.
com.atlassian.confluence.allow.downgrade
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 701
confluence.skip.reindex
reindex.thread.count
reindex.attachments.thread.count
confluence.mbox.directory
confluence.search.max.results
5.5 1000 Confluence Setting this property changes the maximum number of
items Confluence Search will return.
confluence.upgrade.recovery.file.enabled
confluence.junit.report.directory
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 702
officeconnector.textextract.word.docxmaxsize
5.5.3 16777216 Confluence When a file is uploaded, its text is extracted and
indexed. This allows people to search for the content of
a file, not just the filename.
Confluence will only extract content from a Word
document up to the limit set by this property (defaults to
16MB, in bytes), before proceeding to index it. This will
mean that only part of file's contents are searchable. Se
e Configuring Attachment Size for more info.
cluster.login.rememberme.enabled
5.6 False In a cluster, setting this property to True will enable the
'Remember Me' checkbox on the login page. This is not
recommended in a cluster, and is disabled by default
(i.e. 'Remember me' is always on and users can move
seamlessly between nodes).
This system property has no effect in standalone
Confluence.
confluence.cluster.hazelcast.listenPort
confluence.document.conversion.threads
confluence.document.conversion.threads.wait
5.7 1000 Confluence Set this property to change the maximum number of
items that can be queued for conversion.Any file
conversion requests that are made when this maximum
limit has been reached are aborted.
confluence.cluster.node.name
5.7 Confluence Set this property to give each node in your Data Center
cluster a human readable name (displayed in email
notifications and in the footer). If left unset, Confluence
will assign a node identifier to each node.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 703
confluence.document.conversion.fontpath
5.8.7 Confluence Set this property to define a directory where you can
add additional fonts to be used when rendering files (in
previews and thumbnails).
This is useful if you need to support previewing files
with specific fonts, or fonts with multibtye characters
(such as Japanese).
confluence.document.conversion.words.defaultfontname
5.8.7 Confluence Set this property to change the default font for
rendering Word (.doc and .docx) files in Confluence.
confluence.document.conversion.slides.defaultfontname.regular
5.8.7 Confluence Set this property to change the default font for
rendering regular fonts in Powerpoint (.ppt and .pptx
) files in Confluence.
Specify just the name of the font (not the path).
confluence.document.conversion.slides.defaultfontname.asian
5.8.7 TakaoPGothic Confluence Set this property to change the default font for
rendering asian fonts in Powerpoint (.ppt and .pptx)
files in Confluence.
Specify just the name of the font (not the path).
confluence.document.conversion.slides.defaultfontname.symbol
5.8.7 Confluence Set this property to change the default font for
rendering symbols in Powerpoint (.ppt and .pptx) file
s in Confluence.
This is the font that will be used for bullets and other
symbols when the font Symbol is not found.
confluence.clickjacking.protection.disable
confluence.cluster.index.recovery.query.timeout
confluence.cluster.index.recovery.generation.timeout
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 704
confluence.cluster.index.recovery.num.attempts
com.atlassian.confluence.officeconnector.canary.memory_value
5.9.1 1024 Confluence Sets the memory (in megabytes) available to the Office
Connector Canary process, which is a workaround for a
known issue with the Import from Word option. See JV
M crashes during Import from Word in Confluence for
more information.
com.atlassian.confluence.officeconnector.canary.timeout
5.9.1 120000 Confluence Sets the maximum timeout (in milliseconds) for the
Office Connector Canary process, which is a
workaround for a known issue with the Import from
Word option. See JVM crashes during Import from
Word in Confluence for more information.
atlassian.plugins.enable.wait
5.9.5 300 Set this property to increase the default time to wait for
plugins to start up. This is useful if you have problems
with plugins not starting up in time, causing Confluence
to fail to start.
confluence.cluster.hazelcast.max.no.heartbeat.seconds
5.9.7 30 Confluence In Confluence Data Center, this sets how long (in
seconds) a node can be out of communication with the
cluster before it's removed from the cluster. See balanci
ng uptime and data integrity for more info on when you
may want to change this setting.
confluence.startup.remigration.disable
cluster.safety.time.to.live.split.ms
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 705
confluence.cph.max.entries
6.0.0 2000 Confluence This is the maximum number of pages that can be
copied when you copy a page and its child pages.
Increase this if you need to copy a page with more than
the default number of child pages.
confluence.cph.batch.size
6.0.0 10 Confluence This is the number of pages copied in each batch when
you copy a page and its children. Increase or reduce
this number if you experience problems copying a page
with many child pages.
6.0.0 8091 This is the port that Synchrony, the service that powers
collaborative editing, runs on. You should only need to
change this if port 8091 is not available. For Confluence
Data Center system properties see Configuring
Synchrony for Data Center.
From 6.0.4, Confluence Server will accept either reza.
port or synchrony.port.
synchrony.stack.space
6.0.0 2048k This sets the stack size (Xss) of the Synchrony JVM.
Increase if you experience stack overflow errors, or
decrease if you experience out of memory errors from
Synchrony.
synchrony.enable.xhr.fallback
6.0.0 True XML HTTP Request (XHR) fallback allows a user, who
cannot connect to Synchrony via a WebSocket, to use
the Confluence Editor. From Confluence 6.1 this is
enabled by default, and only used when a WebSocket
connection is not available. You should not need to
disable this, unless directed by our support team.
synchrony.database.test.connection.on.checkin
synchrony.proxy.enabled
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 706
synchrony.context.path
6.0.0 /synchrony This is the context path for Synchrony. There should be
no need to change this in Confluence Server.
confluence.flyingpdf.default.characters.per.line
synchrony.host
synchrony.proxy.healthcheck.disabled
page.index.macro.max.pages
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 707
6.1.4 5000 Sets the maximum number of pages that the Page
Index macro can display. The Page Index macro can
significantly slow down your Confluence instance and
cause out of memory errors when used in a space with
a large number of pages. If the number of pages in the
space exceeds this limit, the Page Index macro will
show a page count, and a message that there are too
many pages to display.
atlassian.indexing.attachment.maxsize
officeconnector.excel.extractor.maxlength
confluence.collab.edit.user.limit
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 708
This section describes Confluence's default logging behavior, assuming that you have not changed the
destination of the logs. In order to unify logging across different application servers, Confluence uses the atl
assian-confluence.log as its primary log, not the application server log.
When you start Confluence, log entries will be sent to the application server logs until Confluence has
completed its initial bootstrap. Any log entries written to the console will be repeated into the log in the
Confluence home directory as described below.
Once the initial startup sequence is complete, all logging will be to <confluence-home>/logs/atl
assian-confluence.log. For example: c:/confluence/data/logs/atlassian-confluenc
e.log.
Note that the default location is the Confluence home directory, not the application server's log file. The
home directory is specified in <confluence-installation>/confluence/WEB-INF/classes/confl
uence-init.properties.
The logging behavior for Confluence and Synchrony is defined in the following properties file:
<CONFLUENCE-INSTALL>/confluence/WEB-INF/classes/log4j.properties
This file is a standard log4j configuration file, as described in the Apache log4j documentation.
In log4j, an output destination is called an 'appender'. To change the destination of the log files, you need to
stop Confluence and then change the settings in the 'Logging Location and Appender' section of the log4
j.properties file. The location of this file is described above.
In the standard properties file, you will find entries for two appenders:
com.atlassian.confluence.logging.ConfluenceHomeLogAppender This is a custom
appender which controls the default logging destination described above. This appender allows the
following settings:
MaxFileSize
MaxBackupIndex
org.apache.log4j.RollingFileAppender If you want to log to a different location,
uncomment the RollingFileAppender line and change the destination file in the line below it.
Comment out the previous lines referring to the ConfluenceHomeLogAppender.
The Synchrony log destination can also be changed in the same way in file.
Confluence ships with the full suite of appenders offered by log4j. Read more about appenders in the log4j
documentation.
By default, Confluence keeps 5 log files, which are overwritten as they reach 20 MB.
You can change the default log size and the number of log files to keep by editing the following values in <CO
NFLUENCE-INSTALL>/confluence/WEB-INF/classes/log4j.properties file.
log4j.appender.confluencelog.MaxFileSize=20480KB
log4j.appender.confluencelog.MaxBackupIndex=5
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 709
See Configuring Logging for instructions on how to change the logging configuration of Confluence.
This section contains some pointers to specific log configurations you may need.
You may want to increase Confluence's logging so that it records individual SQL requests sent to the
database. This is useful for troubleshooting specific problems.
You can enable detailed SQL logging in two ways:
At runtime see instructions above.
Via the logging properties file see the detailed instructions.
You can configure the log to show which users are accessing which pages in Confluence. This can only be
done via the logging properties file see the detailed instructions.
Confluence provides an inbuilt log scanner that will check your Confluence logs for errors and attempt to
match them against known issues in our knowledge base and bug tracker. See Troubleshooting Problems
and Requesting Technical Support.
Notes
Finding the thread dumps. Thread dumps are logged to the application server log file.
Configuring Logging
We recommend that you configure Confluence's logging to your own requirements. You can change the log
settings in two ways:
Configure logging in Confluence Administration Your changes will be in effect only until you next restart
Confluence.
Edit the properties file Your changes will take effect next time you start Confluence, and for all
subsequent sessions.
Both methods are described below. In some rare circumstances you may also need to configure the logging.pro
perties file.
Terminology: In log4j, a 'logger' is a named entity. Logger names are case-sensitive and they follow a
hierarchical naming standard. For example, the logger named com.foo is a parent of the logger named com.fo
o.Bar.
You can change some of Confluence's logging behavior via the Administration Console while Confluence is
running. Any changes made in this way will apply only to the currently-running Confluence lifetime. The changes
are not written to the log4j.properties file and are therefore discarded when you next stop Confluence.
Not all logging behavior can be changed via the Administration Console. For logging configuration not mentioned
below, you will need to stop Confluence and then edit the logging properties file instead.
The 'Logging and Profiling' screen shows a list of all currently defined loggers. On this screen you can:
Turn page profiling on or off.
Turn detailed SQL logging on or off.
Add a new logger for a class/package name.
Remove a logger for a class/package name.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 710
Set the logging level (INFO, WARN, FATAL, ERROR or DEBUG) for each class or package name.
Reset all logging levels to a predefined profile.
Changing the logging configuration
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 711
To configure the logging levels and other settings on a permanent basis, you need to stop Confluence and then
change the settings in the log4j.properties file, described above.
The properties file contains a number of entries for different loggers that can be uncommented if you are
interested in logging from particular components. Read more in the Apache log4j documentation.
See Working with Confluence Logs for some guidelines on specific configuration options you may find useful.
A few libraries used by Confluence use java.util.logging rather than log4j or slf4j. These libraries include:
com.sun.jersey
org.apache.shindig
net.sf.ehcache
Confluence's logging.properties file is set to redirect java.util.logging at specific levels to log4j via slf4j.
To increase logging levels for these libraries you must first configure the logging.properties file in <CONFL
UENCE-INSTALL>/confluence/WEB-INF/classes/. The logging levels are different from log4j and are
listed here.
For example, to increase logging for shindig change the following line in the logging.properties file:
org.apache.shindig.level = INFO
to
org.apache.shindig.level = FINE
And then use one of the methods above as well to configure the log4j level.
log4j Logging Levels
Logging Levels
DEBUG - designates fine-grained informational events that are most useful to debug an application (what
is going on)
INFO - announcements about the normal operation of the system - scheduled jobs running, services
starting and stopping, user-triggered processes and actions
WARN - any condition that, while not an error in itself, may indicate that the system is running
sub-optimally
ERROR - a condition that indicates something has gone wrong with the system
FATAL - a condition that indicates something has gone wrong so badly that the system can not recover
TRACE - n/a within confluence
There are two ways to modify the logging levels, as described in Working with Confluence Logs.
1. Modifying the runtime log levels via the Administration Console (changes made here will not
persist across restarts).
2. Manually modifying the <Confluence-Install>\confluence\WEB-INF\classes\log4j.
properties file.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 712
The standard Confluence log level WARN is a way for Confluence to communicate with the server administrator.
Logging at WARN level and higher should be reserved for situations that require some kind of attention from the
server administrator, and for which corrective action is possible.
See log4j manual for more information.
Troubleshooting SQL Exceptions
If you get an exception similar to those shown below, it is a good idea to increase the logging levels of your
Confluence instance. If you request Atlassian support, this additional logging will help us work out the cause of
the error.
Increased logging levels will enable us to diagnose errors like these:
org.springframework.dao.DataIntegrityViolationException:
(HibernateTemplate): data integrity violated by SQL ''; nested exception
is java.sql.BatchUpdateException: Duplicate entry '1234' for key 1
at
org.springframework.jdbc.support.SQLStateSQLExceptionTranslator.translat
e(SQLStateSQLExceptionTranslator.java:88)
caused by: java.sql.BatchUpdateException: Duplicate entry '1234' for key
1
at
com.mysql.jdbc.ServerPreparedStatement.executeBatch(ServerPreparedStatem
ent.java:647)
or
This document outlines the steps to take to increasing logging on your system.
If you can not locate these lines in your log4j.properties file, please add them to the end of it.
2. Restart Confluence.
3. Redo the steps that led to the error.
4. Zip up your logs directory and attach it your support ticket.
5. If you are using Oracle and received a constraint error, please ask your database administrator which ta
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 713
5.
ble and column the constraint (that is, CONFLUENCE.SYS_C0012345) refers to and add that information
to your support ticket.
6. Open confluence/WEB-INF/classes/log4j.properties again and remove the 4 lines you added
in step 1. (The additional logging will impact performance and should be disabled once you have
completed this procedure.)
RELATED TOPICS
Enabling Detailed SQL Logging
Working with Confluence Logs
Troubleshooting failed XML site backups
Configuring Confluence Security
This section gives guidelines on configuring the
security of your Confluence site: Related pages:
Password Storage
When Confluence's internal user management is used, since version 3.5 of Confluence passwords are hashed
through the salted PKCS5S2 implementation provided by Embedded Crowd before being stored in the
database. There is no mechanism within Confluence to retrieve a user's password when password recovery is
performed, a reset password link is generated and mailed to the user's registered address.
When external user management is enabled, password storage is delegated to the external system.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 714
On this page:
Application Security Overview
Finding and Reporting a Security Vulnerability
Publication of Confluence Security Advisories
Severity Levels
Our Security Bugfix Policy
Published Security Advisories
Buffer Overflows
Confluence is a 100% pure Java application with no native components. As such it is highly resistant to buffer
overflow vulnerabilities possible buffer overruns are limited to those that are bugs in the Java Runtime
Environment itself.
SQL Injection
Confluence interacts with the database through the Hibernate Object-Relational mapper. Database queries are
generated using standard APIs for parameter replacement rather than string concatenation. As such,
Confluence is highly resistant to SQL injection attacks.
Script Injection
Confluence is a self-contained Java application and does not launch external processes. As such, it is highly
resistant to script injection attacks.
Cross-Site Scripting
As a content-management system that allows user-generated content to be posted on the web, precautions
have been taken within the application to prevent cross-site scripting attacks:
The wiki markup language in Confluence does not support dangerous HTML markup
Macros allowing the insertion of raw HTML are disabled by default
HTML uploaded as a file attachment is served with a content-type requesting the file be downloaded,
rather than being displayed inline
Only system administrators can make HTML-level customizations of the application
When cross-site scripting vulnerabilities are found in the Confluence web application, we endeavor to fix them as
quickly as possible.
Confluence does not directly support SSL/TLS. Administrators who are concerned about transport-layer security
should set up SSL/TLS at the level of the Java web application server, or the HTTP proxy in front of the
Confluence application.
For more information on configuring Confluence for SSL, see: Running Confluence Over SSL or HTTPS
Session Management
Confluence delegates session management to the Java application server in which it is deployed. We are not
aware of any viable session-hijacking attacks against the Tomcat application server shipped with Confluence. If
you are deploying Confluence in some other application server, you should ensure that it is not vulnerable to
session hijacking.
Plugin Security
Administrators install third party plugins at their own risk. Plugins run in the same virtual machine as the
Confluence server, and have access to the Java runtime environment, and the Confluence server API.
Administrators should always be aware of the source of the plugins they are installing, and whether they trust
those plugins.
Confluence is written under the assumption that anyone given System Administrator privileges is trusted.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 715
System administrators are able, either directly or by installing plugins, to perform any operation that the
Confluence application is capable of.
As with any application, you should not run Confluence as the root/Administrator user. If you want Confluence to
listen on a privileged network port, you should set up port forwarding or proxying rather than run Confluence with
additional privileges. The extra-careful may consider running Confluence inside a chroot jail.
Stack Traces
To help debug support cases and provide legendary support, Confluence provides stack traces through the web
interface when an error occurs. These stack traces include information about what Confluence was doing at the
time, and some information about your deployment server.
Only non-personal information is supplied such as operating system and version and Java version. With proper
network security, this is not enough information to be considered dangerous. No usernames or passwords are
included.
Atlassian's approach to reporting security vulnerabilities is detailed in How to Report a Security Issue.
Atlassian's approach to releasing security advisories is detailed in Security Advisory Publishing Policy.
Severity Levels
Atlassian's approach to ranking security issues is detailed in Severity Levels for Security Issues.
Our approach to releasing patches for security issues is detailed in our Security Bugfix Policy.
Confluence Cookies
This page lists cookies stored in Confluence users' browsers which are On this page:
generated by Confluence itself. This page does not list cookies that may
originate from 3rd-party Confluence plugins. Authentica
tion
Authentication cookies cookies
Other
Confluence uses Seraph, an open source framework, for HTTP cookie Confluenc
authentication. Confluence uses two types of cookies for user e cookies
authentication: Notes
The JSESSIONID cookie is created by the application server and
used for session tracking purposes. This cookie contains a random
string and the cookie expires at the end of every session or when the
browser is closed.
The 'remember me' cookie, seraph.confluence, is generated by
Confluence when the user selects the Remember me check box on
the login page.
You can read about cookies on the Wikipedia page about HTTP cookies.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 716
The 'remember me' cookie, seraph.confluence, is a long-lived HTTP cookie. This cookie can be used to
authenticate an unauthenticated session. Confluence generates this cookie when the user selects the Reme
mber me check box on the login page.
Cookie key and contents
By default, the cookie key is seraph.confluence, which is defined by the login.cookie.key parameter
in the CONFLUENCE-INSTALLATION/confluence/WEB-INF/classes/seraph-config.xml file.
The cookie contains a unique identifier plus a securely-generated random string (i.e. token). This token is
generated by Confluence and is also stored for the user in the Confluence database.
Use of cookie for authentication
When a user requests a web page, if the request is not already authenticated via session-based
authentication or otherwise, Confluence will match the 'remember me' cookie (if present) against the token
(also if present), which is stored for the user in the Confluence database.
If the token in the cookie matches the token stored in the database and the cookie has not expired, the user
is authenticated.
Life of 'remember me' cookies
You can configure the maximum age of the cookie. To do that you will need to modify the CONFLUENCE-INS
TALLATION/confluence/WEB-INF/classes/seraph-config.xml file and insert the following lines
below the other init-param elements:
<init-param>
<param-name>autologin.cookie.age</param-name>
<param-value>2592000</param-value><!-- 30 days in seconds -->
</init-param>
Note: The only purpose of this job is to prevent the database table from growing too big. For authentication
purposes, Confluence will ignore expired tokens even if they still exist in the database.
Is it possible to disable the 'remember me' feature?
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 717
Confluence does not offer an option for disabling the 'Remember Me' feature. See the workaround.
There are several cookies that Confluence uses to store basic 'product presentation' states. Confluence
users' authentication details are not stored by these cookies.
confluence.list.pages.cookie Remembers the user's last chosen tab The name of the One
in the "list pages" section. last selected year
tab. For from the
example, date it
list-content-tree was set
or was
last
updated.
confluence.browse.space.cookie Remembers the user's last chosen tab The name of the One
in the "browse space" section last selected year
tab. For from the
example, date it
space-pages was set
or was
last
updated.
AJS.conglomerate.cookie Tracks which general tabs were last One or more One
used or expansion elements were last key-value year
opened or closed. strings which from the
indicate the date it is
states of your set or
last general tab was last
views or updated.
expansion
elements.
Notes
The autocomplete feature in browser text fields (which are typically noticeable when a user logs in to
Confluence) is a browser-specific feature, not a Confluence one. Confluence cannot enable or disable
this autocompletion, which is typically set through a browser's settings.
Confluence protects access to its administrative functions by requiring a secure administration session to use
the Confluence administration console or administer a space. When a Confluence administrator (who is logged
into Confluence) attempts to access an administration function, they are prompted to log in again. This logs the
administrator into a temporary secure session that grants access to the Confluence/space administration
console.
The temporary secure session has a rolling timeout (defaulted to 10 minutes). If there is no activity by the
administrator in the Confluence/space administration console for a period of time that exceeds the timeout, then
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 718
the administrator will be logged out of the secure administrator session (note, they will remain logged into
Confluence). If the administrator does click an administration function, the timeout will reset.
To configure secure administrator sessions:
1. Choose the cog icon
Notes
Note for developers. Secure administrator sessions can cause exceptions when developing against
Confluence or deploying a plugin. Please read this FAQ: How do I develop against Confluence with
Secure Administrator Sessions? Note: The Confluence XML-RPC and REST APIs are not affected by
secure administration sessions.
Using Fail2Ban to limit login attempts
What is Fail2Ban?
We need a means of defending sites against brute-force login attempts. Fail2Ban is a Python application which
trails logfiles, looks for regular expressions and works with Shorewall (or directly with iptables) to apply
temporary blacklists against addresses that match a pattern too often. This can be used to limit the rate at which
a given machine hits login URLs for Confluence.
Prerequisites
How to set it up
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 719
Running Fail2Ban
Common Configuration
jail.local
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 720
[DEFAULT]
[ssh-iptables]
enabled = false
[apache-shorewall]
enabled = true
filter = cac-login
action = shorewall
logpath = /var/log/httpd/confluence-access.log
bantime = 600
maxretry = 3
findtime = 60
backend = polling
The following is an example only, and you should adjust it for your site.
filter.d/confluence-login.conf
[Definition]
ignoreregex =
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 721
The following outlines some basic techniques to secure a Confluence instance using Apache. These instructions
are basic to-do lists and should not be considered comprehensive. For more advanced security topics see the
"Further Information" section below.
Using Apache to limit access to the Confluence administration interface
Using Fail2Ban to limit login attempts
Further Information
The Confluence administration interface is a critical part of the application; anyone with access to it can
potentially compromise not only the Confluence instance but the entire machine. As well as limiting access to
users who really need it, and using strong passwords, you should consider limiting access to it to certain
machines on the network or internet. If you are using an Apache web server, this can be done with Apache's Lo
cation functionality as follows:
1. Create a file that defines permission settings
This file can be in the Apache configuration directory or in a system-wide directory. For this example we'll call it
"sysadmin_ips_only.conf". The file should contain the following:
Order Deny,Allow
Deny from All
This configuration assumes you've installed Confluence under '/confluence'. If you have installed under
'/' or elsewhere, adjust the paths accordingly.
<Location /confluence/admin>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/consumers/list>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/view-consumer-info>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/service-providers/list>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/service-providers/add>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/consumers/add>
Include sysadmin_ips_only.conf
</Location>
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 722
<Location /confluence/plugins/servlet/oauth/consumers/add-manually>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/oauth/update-consumer-info>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/pages/templates/listpagetemplates.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/pages/templates/createpagetemplate.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/spacepermissions.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/pages/listpermissionpages.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/removespace.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/importmbox.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/viewmailaccounts.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/addmailaccount.action?>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/importpages.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/flyingpdf/flyingpdf.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/exportspacehtml.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/spaces/exportspacexml.action>
Include sysadmin_ips_only.conf
</Location>
<Location /confluence/plugins/servlet/embedded-crowd>
Include sysadmin_ips_only.conf
</Location>
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 723
<Location /confluence/plugins/servlet/upm>
Include sysadmin_ips_only.conf
</Location>
External referrers
An external referrer is any site that links to your Confluence instance. Each time someone clicks on the
external link, your Confluence site can record the click as a referral.
By default, external referrers for a page are listed under 'Hot Referrers' on the 'Info' screen of the page.
Confluence shows a maximum of 10 referrers. If there are more than 10, confluence shows the 10 with the
highest number of hits.
Note that you do not need to enable trackback in order to have external referrers enabled.
Screenshot: hot referrers on the page information screen.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 724
Confluence Administrators can exclude external referrers to prevent them from being recorded or displayed
anywhere on your site. Once you have specified your list of blocked URLs, any incoming links from URLs
that match the list will no longer be recorded.
Referrer URLs are blocked if they start with any of the URLs in the exclusion list. So http://evilspamsite.blogs
pot.com will also match http://evilspamsite.blogspot.com/nastypage.html
You might want to do this if:
1. You're running a Confluence installation that is open to public
In a site that is open to public, one unfortunate problem is that malicious sites can spam the display of
a page's incoming links statistics. This is usually done to get the site's URL to appear in the sidebar.
By adding these sites to the 'excluded referrers' list, you can prevent them from being listed on your
site.
2. Confluence is installed on a server with multiple domain names or IP addresses
Confluence will consider any URL originating from the domain name where Confluence is installed as
an internal link. However, if Confluence is installed on a server with multiple domain names or IP
addresses, you will need to add the other domain name prefixes to this list to let Confluence know that
any links from these domains should not be considered external links.
To add a URL to the excluded referrers list:
1. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 725
By default, Confluence lists the external referrers as 'Hot Referrers' on the page information screen for a
page. If you turn this option off, external referrers will not be listed on the page.
To hide external referrers:
1. Go to
An external referrer is any site that links to your Confluence instance. Each time someone clicks on the
external link, your Confluence site can record the click as a referral. By default, Confluence records the
number of hits made to a page from any link on an external site. If you turn this option off, Confluence will not
record the hits.
To ignore external referrers:
1. Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 726
The best way to harden a system is to look at each of the involved systems individually. Contact your company's
security officer or department to find out what security policies you should be using. There are many things to
consider, such as the configuration of your underlying operating systems, application servers, database servers,
network, firewall, routers, etc. It would be impossible to outline all of them here.
This page contains guidelines on good security practices, to the best of our knowledge.
See the following system administrator guide for general hints on the application server level:
Tomcat security best practices
The way you set up Confluence roles, permissions and processes makes a big difference in the security of your
Confluence site.
Below are some more Confluence-specific items to consider. None of these provides 100% security. They are
measures to reduce impact and to slow down an intruder in case your system does become compromised.
Keep the number of Confluence administrators extremely low. For example, 3 system administrator
accounts should be the maximum.
Similarly, restrict the number of users with powerful roles or group memberships. If only one department
should have access to particularly sensitive data, then do restrict access to the data to those users. Do
not let convenience over-rule security. Do not give all staff access to sensitive data when there is no
need.
The administrators should have separate Confluence accounts for their administrative roles and for their
day to day roles. If John Doe is an administrator, he should have a regular user account without
administrator access to do his day to day work (such as writing pages in the wiki). This could be a
'john.doe' account. In addition, he should have an entirely separate account (that cannot be guessed by
an outsider and that does not even use his proper name) for administrative work. This account could be
'jane smith' using a username that is so obscure or fake that no outsider could guess it. This way, even
if an attacker singles out the actual person John Doe and gets hold of his password, the stolen account
would most likely be John's regular user account, and the attacker cannot perform administrative actions
with that account.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 727
Lock down administrative actions as much as you can. If there is no need for your administrators to
perform administrative actions from outside the office, then lock down access to those actions to known
IP adresses, for example. See Using Apache to limit access to the Confluence administration interface.
Put documented procedures in place for the case of employees leaving the company.
Perform security audits regularly. Know who can help in case a security breach occurs. Perform 'what if'
planning exercises. ('What is the worst thing that could happen if a privileged user's password were stolen
while he's on vacation? What can we do to minimize damage?').
Make sure the Confluence database user (and all datasource database users) only has the amount of
database privileges it really needs.
Monitor your binaries. If an attacker compromises an account on your system, he will usually try to gain
access to more accounts. This is sometimes done by adding malicious code, such as by modifying files
on the system. Run routine scripts that regularly verify that no malicious change has been made.
As another precaution:
Regularly monitor the above requirements. There are many things that could start out well, but deteriorate
over time:
A system may start out with just 3 administrators, but over the course of a year this could grow to
30 administrators if no one prevents expansion.
Apache administration restrictions may be in place at the start of the year, but when the application
server is migrated after a few months, people may forget to apply the rules to the new system.
Again, keep in mind that the above steps may only be a fraction of what could apply to you, depending on your
security requirements. Also, keep in mind that none of the above rules can guarantee anything. They just make it
harder for an intruder to move quickly.
Hiding the People Directory
The People Directory provides a list of all users in your Confluence system.
If you need to disable the People Directory set the following system properties on your application server
command line:
To disable the People Directory for anonymous users:
-Dconfluence.disable.peopledirectory.anonymous=true
-Dconfluence.disable.peopledirectory.all=true
This workaround will prevent the People directory from appearing on the dashboard, but if you navigate to the
profile of a user, and then click on the "People" in the breadcrumb link (Dashboard >> People >> FullName >>
Profile) or you go to the URL directly <CONFLUENCE_INSTALL>/browsepeople.action, you will be able to
access the people directory.
To workaround this, set up your Apache webserver in front of Confluence and redirect requests to this URL.
Configuring Captcha for Spam Prevention
If your Confluence site is open to the public (you
allow anonymous users to add comments, create Related pages:
pages etc) you may find that automated spam is Configuring Confluence Security
being added, in the form of comments or new pages.
You can configure Confluence to deter automated
spam by asking users to prove that they are human
before they are allowed to:
Sign up for an account.
Add a comment.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 728
Create a page.
Edit a page.
Send a request to the Confluence
administrators.
Captcha is a test that can distinguish a human being from an automated agent such as a web spider or
robot. When Captcha is switched on, users will see a distorted picture of a word, and must enter it in a text
field before they can proceed.
Screenshot: Example of a Captcha test
By default, Captcha is disabled. When enabled, the default is that only anonymous users will have to
perform the Captcha test when creating comments or editing pages. You can also choose to enforce
Captcha for all users or members of particular groups.
You need System Administrator permissions to configure Captcha for spam prevention in Confluence.
To enable Captcha for spam prevention in Confluence:
1. Choose the cog icon
Hiding external links from search engines helps to discourage spammers from posting links on your site. If you
turn this option on, any URLs inserted in pages and comments will be given the 'nofollow' attribute, which
prevents search engines from following them.
Shortcut links (e.g. CONF-2622@JIRA) and internal links to other pages within Confluence are not tagged.
To hide external links from search engines:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 729
By default, Captcha for failed logins is enabled and the number of failed login attempts is set to three.
To enable, disable and configure Captcha for failed logins:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 730
Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 731
Administrators may wish to disable anonymous access to the Confluence remote API. to make it harder for
malicious users to write 'bots' that perform bulk changes to the site.
To disable anonymous access to the remote API:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 732
Notes
This page is about access to the remote API. If you are looking for information about preventing anonymous
users from accessing Confluence, see Global Permissions Overview.
Running Confluence Over SSL or HTTPS
Atlassian applications allow the use of SSL within our products, however Atlassian Support does not
provide assistance for configuring it. Consequently, Atlassian cannot guarantee providing any
support for it.
If assistance with conversions of certificates is required, please consult with the vendor who
provided the certificate.
If assistance with configuration is required, please raise a question on Atlassian Answers.
You will need a valid SSL certificate before you can enable HTTPS. If you already have a certificate
prepared, skip to step 2 below.
You can choose to create a self-signed certificate or to use a certificate issued by a certificate authority (CA,
sometimes also called a 'certification authority'). We described both options below.
If you're not comfortable using command line utilities KeyStore Explorer is a useful GUI replacement for the
Java Keytool command line.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 733
Self-signed certificates are useful if you require encryption but do not need to verify the identity of the
requesting website. In general, you might use a self-signed certificate on a test environment and on internal
corporate networks (intranets).
Because the certificate is not signed by a certificate authority (CA), users may receive a message that the
site is not trusted and may have to perform several steps to accept the certificate before they can access the
site. This usually will only occur the first time they access the site.
Follow the steps below to generate a certificate using Java's keytool utility. This tool is included in the JDK.
Many SSL issuers (including but not limited to GoDaddy and RapidSSL) are now requiring a
2048-bit key size. To generate a key with 2048-bit encryption, add '-keysize 2048' to these
queries.
Tomcat has a known issue with passwords containing special characters. You should
use a password that only contains alphanumeric characters.
3. Follow the prompts to specify your name, organization and location. This information is used to
construct the X.500 Distinguished Name (DN) of the entity. The CN ("What is your first and last
name?") must match the fully-qualified hostname of the server running Confluence, otherwise Tomcat
will not be able to use the certificate for SSL. For example for a Confluence running on a server
named "confluence.example.com":
CN=confluence.example.com, OU=Java Software Division, O=Sun Microsystems
Inc, C=US
4. Enter 'y' to confirm the details.
5. When asked for the password for 'tomcat' (the alias you entered in the keytool command above),
press the 'Enter' key. This specifies that your keystore entry will have the same password as your
private key. You MUST use the same password here as was used for the keystore password itself.
This is a restriction of the Tomcat implementation.
6. You certificate is now ready. Go to step 2 below.
When running Confluence in a production environment, you will need a certificate issued by a certificate
authority (CA, sometimes also called a 'certification authority') such as VeriSign, Thawte or digicert. The
instructions below are adapted from the Tomcat documentation.
First you will generate a local certificate and create a 'certificate signing request' (CSR) based on that
certificate. You will submit the CSR to your chosen certificate authority. The CA will use that CSR to generate
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 734
3. Submit the generated file called certreq.csr to your chosen certificate authority. Refer to the
documentation on the CA's website to find out how to do this.
4. The CA will send you a certificate.
5. Import the new certificate into your local keystore:
Please note that some CAs require you to install an intermediate certificate before importing
your certificate. Please refer to your CA documentation to successfully install your certificate.
If you receive an error, and you use Verisign or GoDaddy, you may need to export the certificate to
PKCS12 format along with the private key.
1. First, remove the certificate added above from the keystore:
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 735
3. Replace the text <MY_CERTIFICATE_PASSWORD> with the password you specified for your
certificate.
4. Make sure that the attribute-value pair SSLEnabled="true" is part of the Connector element, as
shown above. If this attribute is not present, attempts to access Confluence will time out.
5. Save the server configuration file.
Avoid removing the http connector, as the Synchrony proxy health check, still requires HTTP. If you do
not want to include the http connector, you can use the synchrony.proxy.healthcheck.disabled sy
stem property to disable the health check.
You should also not disable the internal Synchrony proxy (by setting the synchrony.proxy.enabled syst
em property to false) as this is known to cause problems when you're terminating SSL at Tomcat.
By default, Tomcat expects the keystore file to be named .keystore and to be located in the user home
directory under which Tomcat is running (which may or may not be the same as your own home directory).
This means that, by default, Tomcat will look for your SSL certificates in the following location:
On Windows: C:\users\#CURRENT_USER#\.keystore
On OS X and UNIX-based systems: ~/.keystore
Don't store your keystore file in your Confluence installation directory as the contents of that directory
are removed when you upgrade Confluence.
You may decide to move the certificate to a custom location. If your certificate is not in the default location,
you will need to update your server configuration file as outlined below, so that Tomcat can find the
certificate.
1. Edit the server configuration file at this location: <CONFLUENCE_INSTALLATION>/conf/server.xm
l
2. Add the attribute keystoreFile="<MY_CERTIFICATE_LOCATION>" to the Connectorelement, so
that the element looks like this:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 736
3. Replace the text <MY_CERTIFICATE_LOCATION> with the path to your certificate, including the path
and the name of the .keystore file.
4. Save the server configuration file.
Although HTTPS is now activated and available, the old HTTP URLs (http://localhost:8090) are still available.
Now you need to redirect the URLs to their HTTPS equivalent. You will do this by adding a security constraint
in web.xml. This will cause Tomcat to redirect requests that come in on a non-SSL port.
1. Check whether your Confluence site uses the RSS macro. If your site has the RSS macro enabled,
you may need to configure the URL redirection with a firewall rule, rather than by editing the web.xml
file. Skip the steps below and follow the steps on the RSS Feed Macro page instead.
2. Otherwise, Edit the file at <CONFLUENCE_INSTALLATION>/confluence/WEB-INF/web.xml.
3. Add the following declaration to the end of the file, before the </web-app>tag:
<security-constraint>
<web-resource-collection>
<web-resource-name>Restricted URLs</web-resource-name>
<url-pattern>/</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 737
keystore. The command packages the public key into an X.509 v3 self-signed certificate, which is
stored as a single-element certificate chain. This certificate chain and the private key are stored in a
new keystore entry, identified by the alias that you specify in the command. The Java SE
documentation has a good overview of the utility.
Custom SSL port: If you have changed the port that the SSL connector is running on from the default
value of 8443, you must update the redirectPort attribute of the standard HTTP connector to
reflect the new SSL port. Tomcat needs this information to know which port to redirect to when an
incoming request needs to be secure.
Multiple instances on the same host: When running more than one instance on the same host, it is
important to specify the address attribute in the <CONFLUENCE_INSTALLATION>/conf/server.xm
l file because by default the connector will listen on all available network interfaces, so specifying
the address will prevent conflicts with connectors running on the same default port. See the Tomcat
Connector documentation for more about setting the address attribute: https://tomcat.apache.org/tomc
at-8.0-doc/config/http.html
Protection for logins only or for individual spaces: As of Confluence 3.0, Atlassian does not
support HTTPS for logins only or for specific pages. We support only site-wide HTTPS. To see the
reasoning behind this decision, please see CONF-18120 and CONF-4116.
Troubleshooting
<Valve
className="org.apache.catalina.authenticator.NonLoginAuthenticat
or"
disableProxyCaching="true" securePagesWithPragma="false"
/>
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 738
This page describes how to get Confluence connecting to external servers over SSL, via the various
SSL-wrapped protocols.
Here are some examples of when you may need to connect to an external server over SSL/HTTPS:
You need to connect to an LDAP server, such as Active Directory, if the LDAP server is running over
SSL.
For specific instructions for Active Directory, see Configuring an SSL Connection to Active
Directory.
You want to set up your JIRA application as a trusted application in Confluence, when JIRA is running
over SSL.
You want to refer to an https://... URL in a Confluence macro.
If you want to run Confluence itself over SSL, see Running Confluence Over SSL or HTTPS.
2. Import your LDAP or JIRA server's public certificate into the JVM Keystore. This is the certificate that
the LDAP server will use to set up the SSL encryption. You can use any alias of your choosing in
place of "JIRAorLDAPServer.crt".
3. Verify that the certificate has been added successfully by entering the following command:
4. Ensure that you have updated CATALINA_OPTS to specify the path to the keystore, as specified in C
onnecting to SSL services before restarting Confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 739
4.
There is no need to specify an alias for Confluence to use. On connecting to the LDAP server, it will
search through the keystore to find a certificate to match the key being presented by the server.
Troubleshooting
Notes
When using the RSS Feed Builder, a user could potentially enter such a large value for the number of
feed items returned that Confluence would eventually run out of memory.
When using the Feed Builder, if a users a value greater than this setting (or less than 0) they will get a
validation error.
If any pre-existing feeds are set to request more than the configured maximum, they will be supplied
with only the configured maximum number of items. This is done silently - there is no logging and no
message is returned to the RSS reader.
If Confluence times out when responding to an RSS feed request, any items already rendered are
returned.
Stopping Spammers
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 740
To prevent spammers:
1. Enable Captcha. See Configuring Captcha for Spam Prevention.
2. Run Confluence behind an Apache webserver and create rules to block the spammer's IP address.
If a spam bot is attacking your Confluence site, they are probably coming from one IP address or a small range
of IP addresses. To find the attacker's IP address, follow the Apache access logs in real time and filter for a
page that they are attacking.
For example, if the spammers are creating users, you can look for signup.action:
Compare the actual spam users being created with the log entries to make sure you do not block legitimate
users. By default, Apache logs the client's IP address in the first field of the log line.
Once you have the offender's IP address or IP range, you can add it to your firewall's blacklist. For example,
using the popular Shorewall firewall for Linux you can simply do this:
To block an IP address at the Apache level, add this line to your Apache vhost config:
You can restart Apache with a "graceful" command which will apply the changes without dropping any current
sessions.
If this still does not stop the spam, then consider turning off public signup.
Deleting Spam
Profile Spam
By 'profile spam', we mean spammers who create accounts on Confluence and post links to their profile page.
If you have had many such spam profiles created, the easiest way to delete them is via SQL.
To delete a spam profile:
1. Shut down Confluence and back up your database.
Note: This step is essential before you run any SQL commands on your database.
2. Find the last real profile:
3. Look through the bodies of the profile pages until you find where the spammer starts. You may have to
identify an number of ranges.
4. Find the killset:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
4. 6.4 documentation 741
If you're using Confluence 5.6 or earlier use the SQL commands below:
For Confluence 5.6 and earlier...
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 742
5. Once the spam has been deleted, restart Confluence and rebuild the index. This will remove any
references to the spam from the search index.
Running Confluence behind NGINX with SSL
This page describes how to set up NGINX as a rever On this page
se proxy for Confluence. Step 1: Set the context path
Step 2: Configure the Tomcat
The configuration described on this page results in a
connector
scenario where:
Step 3: Configure NGINX
External client connections with NGINX are Step 4: Restart Confluence and
secured using SSL. Connections between NGINX
NGINX and Confluence Server are
unsecured.
Confluence Server and NGINX run on the
same machine.
We assume that you already have a running instance of NGINX. If not, refer to the NGINX documentation for
instructions on downloading and installing NGINX. SSL certificates must be installed on the server machine.
You'll an NGINX version that supports WebSockets (1.3 or later).
Note that the Atlassian Support does not cover NGINX integration. Assistance with NGINX may be obtained
through the Atlassian community from answers.atlassian.com or from an Atlassian Expert.
If you want to access Confluence without a context path (www.example.com), or via a sub-domain
(confluence.example.com) skip this step.
Set your Confluence application path (the part after hostname and port) in Tomcat. Edit <installation-d
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 743
protocol="org.apache.coyote.http11.Http11NioProtocol"/>
proxyName="www.example.com" proxyPort="443"
scheme="https"/>
Note: don't include secure="true" in this connector. Make sure you've included correct values for proto
col and proxyName.
You will need to specify a listening server in NGINX, as in the example below. Add the following to your
NGINX configuration.
Replace your server name and the location of your SSL certificate and key.
In this example, users will connect to Synchrony, which is required for collaborative editing, directly.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 744
server {
listen www.example.com:80;
server_name www.example.com;
ssl_session_timeout 5m;
location /confluence {
client_max_body_size 100m;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8090/confluence;
}
location /synchrony {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8091/synchrony;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
}
}
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 745
server {
listen confluence.example.com:80;
server_name confluence.example.com;
ssl_session_timeout 5m;
location / {
client_max_body_size 100m;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For
$proxy_add_x_forwarded_for;
proxy_pass http://localhost:8090;
}
location /synchrony {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For
$proxy_add_x_forwarded_for;
proxy_pass http://localhost:8091/synchrony;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
}
}
1. Restart Confluence and NGINX for all the changes to take affect.
2. Update Confluence's base URL to include the context path you set earlier - see Configuring the Server
Base URL.
Scheduled Jobs
The administration console allows you to schedule
various administrative jobs in Confluence, so that
they are executed at regular time intervals. The
types of jobs which can be scheduled cover:
Confluence site backups
Storage optimization jobs to clear
Confluence's temporary files and caches
Index optimization jobs to ensure
Confluence's search index is up to date
Mail queue optimization jobs to ensure
Confluence's mail queue is maintained and
notifications have been sent.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 746
To run a job manually head to the Scheduled Jobs list and choose Run next to the job. It will
run immediately.
Not all jobs can be run manually.
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 747
To see when a job was last run, and how long the job took to run, click the History link beside the job.
If a job has not run at least once the History link won't appear.
Screenshot: Job Execution History
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 748
Types of jobs
Here's a summary of some of the scheduled jobs that you may want to adjust.
Back Up Performs a backup of your entire Confluence site. Per cluster At 2am
Confluence every day
Check Cluster For clustered Confluence installations, this job ensures that Per cluster Every 30
Safety only one Confluence instance in the cluster writes to the seconds
database at a time.
For standard (non-clustered) editions of Confluence, this job is
useful for alerting customers who have accidentally connected
a second Confluence instance to a Confluence database which
is already in use.
Clean Journal Periodically clears journal entries that have already been Per node At 2am
Entries processed to ensure that its size does not grow indefinitely. every day
Clean Cleans up temporary files generated in the <confluence-ho Per node At 4am
Temporary me>/temp directory. This temp directory is created by exports every day
Directory etc.
This doesn't include the temp directory located in the
confluence install directory.
Clear Expired Clears notification errors in the mail error queue. A notification Per cluster At 3am
Mail Errors error is sent to the mail error queue whenever the notification every day
fails to be sent due to an error.
Clear Expired Clears all expired 'Remember Me' tokens from the Confluence Per cluster On the
Remember Me site. Remember Me tokens expire after two weeks. 20th of
Tokens each
month
Email Daily Emails a daily summary report of all Confluence changes to all Per cluster At 12am
Reports subscribers. every day
Since each email report only records changes from the last
24-hour period, it is recommended that you only change the
time of this job while keeping the job's frequency to 24 hours.
Flush Edge Flushes the Edge Index Queue so Confluence's search results Per node Every 30
Index Queue stay up to date. seconds
Flush Local Flushes the local task queue. (These are internal Confluence Per node Every
Task Queue tasks that are typically flushed at a high frequency.) minute
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 749
Flush Mail Sends notifications that have been queued up in the mail Per cluster Every
Queue queue. This doesn't include batched notifications. Edit the Sen minute
d batched notifications job if you also want to change how
often notifications are sent for changes to a page or blog post.
Send batched Sends email notifications containing all changes to a page or Per cluster Every 10
notifications blog post since the last time the job ran. Increase the time for minutes
fewer emails or reduce the time if more immediate notifications
are important in your site.
Flush Task Flushes the task queue. (These are internal Confluence tasks Per node Every
Queue that are typically flushed at a high frequency.) minute
Send Triggers sending recommended update emails to users. The Per cluster Hourly
Recommended job runs hourly, but users will receive the notification weekly or
Updates Email daily, depending on the setting in their profile, at a time that
matches their timezone.
Cron expressions
A cron expression is a string of 6-7 'time interval' fields that defines the frequency with which a job is
executed. Each of these fields can be expressed as either a numerical value or a special character and each
field is separated by at least one space or tab character.
The table below is shows the order of time interval fields in a cron expression and each field's permitted
numerical values.
You can specify a special character instead of a numerical value for any field in the cron expression to
provide flexibility in defining a job's frequency. Common special characters include:
'*' a 'wild card' that indicates 'all permitted values'.
'?' indicates 'ignore this time interval' in the cron expression. That is, the cron expression will not be
bound by the time interval (such as 'Month', 'Day of week' or 'Year') to which this character is
specified.
For more information about cron expressions, please refer to the Cron Trigger tutorial on the Quartz website.
7 Year 1970-2099 No
Confluence administrators can choose to allow incoming and outgoing connections and content from specified
sources for use in the RSS macro, HTML Include macro and gadgets, by adding URLs to the whitelist.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 750
Confluence will display an error if content has been added that is not from an allowed source, and prompt the
user to add the URL to the whitelist.
Application links are automatically added to the whitelist. You don't need to manually add them.
Note: The HTML Include macro is disabled by default.
Expression Types
When adding a URL to the whitelist, you can choose from a number of expression types.
Allow Incoming
Allow Incoming enables CORS requests from the specified origin. The URL must match the format scheme:/
/host[:port], with no trailing slashes (:port is optional). So http://example.com/ would not
allow CORS requests from the domain example.com.
The whitelist is enabled by default. You can choose to disable the whitelist however this will allow all URLs,
including malicious content, and is not recommended.
To disable the whitelist:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 751
All URLs will now be allowed. We strongly recommend not disabling the whitelist.
Configuring the Time Interval at which Drafts are Saved
Related pages:
This setting only applies to Confluence 6.0 or later if you've chosen
to disable collaborative editing. Drafts
When collaborative editing is enabled we're saving all the time!
Performance Tuning
This document describes tuning your application for On this page:
improved performance. It is not a guide to
troubleshooting Confluence outages. Check Trouble Use the latest version of your tools
shooting Confluence hanging or crashing for help if Avoid swapping due to not enough
Confluence is crashing. RAM
Being aware of other systems
Like any server application, Confluence may require using the same infrastructure
some tuning as it is put under heavier use. We do Choice of database
our best to make sure Confluence performs well Database connection pool
under a wide variety of circumstances, but there's no Database in general
single configuration that is best for everyone's Database statistics and query
environment and usage patterns. analyzers
Cache tuning in Confluence and
If you are having problems with the performance of
Apache
Confluence and need our help resolving them, you
Antivirus software
should read Requesting Performance Support.
Enabling HTTP compression
Performance testing
Use the latest version of your tools Access logs
Built-in profiler
Use the latest versions of your application servers Application server memory
and Java runtime environments. Newer versions are settings
usually better optimized for performance. Web server configuration
Troubleshooting possible memory
leaks
Always watch the swapping activity of your server. If there is not enough RAM available, your server may
start swapping out some of Confluence's heap data to your hard disk. This will slow down the JVM's garbage
collection considerably and affect Confluence's performance. In clustered installations, swapping can lead to
a Cluster Panic due to Performance Problems. This is because swapping causes the JVM to pause during G
arbage Collection, which in turn can break the inter-node communication required to keep the clustered
nodes in sync.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 752
It may sound tempting: Just have one powerful server hosting your database and/or application server, and
run all your crucial programs on that server. If the system is set up perfectly, then you might be fine.
Chances are however that you are missing something, and then one application's bug might start affecting
other applications. So if Confluence is slow every day around noon, then maybe this is because another
application is using the shared database to generate complicated reports at that time? Either make sure
applications can't harm each other despite sharing the same infrastructure, or get these systems untangled,
for example by moving them to separate instances that can be controlled better.
Choice of database
The embedded H2 database is provided for evaluating Confluence, not for production Confluence sites.
After the evaluation finishes, you must switch to a supported external database. We recommend using what
you are familiar with, because your ability to maintain the database will probably make far more difference to
what you get out of it than the choice of database itself.
If load on Confluence is high, you may need more simultaneous connections to the database.
If you are using JNDI data-sources, you will do this in your application server's configuration files.
If you have configured Confluence to access the database directly, you will need to manually edit the
hibernate.c3p0.max_size property in the confluence.cfg.xml file in your confluence.home directory.
After you have changed the URL in this file, restart Confluence.
To assess whether you need to tune your database connection pool, take thread dumps during different
times (including peak usage). Inspect how many threads have concurrent database connections.
Database in general
If Confluence is running slowly, one of the most likely cause is that there is some kind of bottleneck in (or
around) the database.
The first item you should check is the "Database Latency" field in the System Information tab in the admin
console.
The latency is calculated by sending a trivial request to the database, querying a table which is known to
have only one column and one row. ("select * from CLUSTERSAFETY"). Obviously this query should be
blazing fast, and return within 1 or 2 milliseconds. If the value displayed is between 3 and 5 milliseconds, you
might already have an issue. If the value is above 10ms, then you definitely need to investigate and improve
something! A few milliseconds may not sound so bad, but consider that Confluence sends quite a few
database queries per page request, and those queries are a lot more complex too! High latency might stem
from all sorts of problems (slow network, slow database, connection-pool contention, etc), so it's up to you to
investigate. Don't stop improving until latency is below 2ms on average.
Obviously, latency is just the very first thing to look at. You may get zero latency and still have massive
database problems, e.g. if your tables are poorly indexed. So don't let a low latency fool you either.
Modern databases have query optimizers based on collecting statistics on the current data. Using the SQL
EXPLAIN statement will provide you information on how well the query optimizer is performing. If the cost
estimate is wildly inaccurate then you will need to run statistics collection on the database. The exact
command will depend on your database and version. In most cases you can run statistics collection while
Confluence is running, but due to the increased load on the database it's best to do this after normal hours or
on a week-end.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 753
To reduce the load on the database, and speed up many operations, Confluence keeps its own cache of
data. Tuning the size of this cache may speed up Confluence (if the caches are too small), or reduce memory
(if the caches are too big).
Please have a look at our documentation on Cache Performance Tuning for information on how to tune
Confluence caches.
To improve performance of a large Confluence site, we recommend that you move the caching of static
content from the JVM into Apache. This will prevent the JVM from having a number of long running threads
serving up static content. See Configuring Apache to Cache Static Content via mod_disk_cache.
Antivirus software
Antivirus software greatly decreases the performance of Confluence. Antivirus software that intercepts
access to the hard disk is particularly detrimental, and may even cause errors with Confluence. You should
configure your antivirus software to ignore the Confluence home directory, its index directory and any
database-related directories.
If bandwidth is responsible for bottlenecking in your Confluence installation, you should consider enabling
HTTP compression. This may also be useful when running an external facing instance to reduce your
bandwidth costs.
Take note of the known issues with HTTP compression in versions of Confluence prior to 2.8, which may
result in high memory consumption.
Performance testing
You should try out all configuration changes on a demo system. Ideally, you should run and customize
loadtests that simulate user behavior.
Access logs
You can find out which pages are slow and which users are accessing them by enabling Confluence's built-in
access logging.
Built-in profiler
You can identify the cause of page delays using Confluence's built-in profiler according to Troubleshooting
Slow Performance Using Page Request Profiling.
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.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 754
Some external plugins, usually ones that have been written a long time ago and that are not actively
maintained anymore, have been reported to consume memory and never return it. Ultimately this can lead to
a crash, but first this manifests as reduced performance. The Troubleshooting Confluence hanging or
crashing guide is a good place to start. Some of the known causes listed there could result in performance
issues short of a crash or hang.
As an example of how to tune Confluence's caches, let's have a look at the following table:
The maximum size of the caches above is 1000 (meaning that it can contain up to 1000 objects). You can tell
when a cache size needs to be increased because the cache has both:
a high usage percentage (above 75%)
a low effectiveness percentage.
Check the 'effectiveness' versus the 'percent used'. A cache with a low percent used need not have its size
lowered; it does not use more memory until the cache is filled.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 755
Based on this, the sizes of the "Attachments", "Database Queries", and "Users" caches should be increased
to improve their effectiveness.
As the stored information gets older or unused it will expire and be eliminated from the cache. Cache expiry
may be based on time or on frequency of use.
There is not much that you can do with a cache that has both a low percentage of usage and
effectiveness. Over time, as the cache is populated with more objects and repeat requests for them are
made, the cache's effectiveness will increase.
The cache configuration file configures caches by their keys. To find out a cache key hover your mouse over
the cache name in the Cache Management screen.
In Confluence Data Center (clustered) you have a distributed cache and a cluster node-local cache. The
Cluster Management page will indicate cluster distributed cache and cluster node-local cache.
The cache configuration file is stored in the shared home directory for the cluster.
Important caches
The following suggestions are general guidelines. In cases of large databases, 20-30% of the size of
the table may be unnecessarily large. Check the effectiveness and percent used categories in the
cache for more specific assessments.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 756
SELECT
COUNT(*)
FROM
cwd_user u
JOIN
cwd_directory d
ON
u.directory_id = d.id
AND d.directory_name = 'Confluence Internal Directory';
SELECT
COUNT(*)
FROM
cwd_user u;
Cache Statistics
Confluence provides statistics about its internal caches that allow you to track the size and hit ratio of each
cache and tune it for better performance (if necessary). See Performance Tuning for more information.
Configurable Caches
System administrators can change the sizes of Confluence's internal caches through the Administration Console
and these changes will take effect without the need to first shut down and then restart Confluence. The
maximum number of units for any of the defined cache regions can be adjusted individually.
Note that larger cache sizes will require more memory at runtime, so you should review the memory allocation of
the Confluence Java process and the physical memory available on your server.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 757
Capacity =(Objects)/(Size)
Utilization
For example Percent Used = 4023 / 5000 = 80%
Current / Max The number of entries in the cache / the number of total possible entries allowed (this is the
Entries size of the cache).
Current Heap Heap memory (in MB) allocated to this cache (if applicable)
Size
Hit / Miss / The number of reads accessing cache where required content was found / the number of
Evicted reads accessing cache where required content was not found / the number of objects evicted
from the cache.
Adjust Size Use this option to specify a different maximum cache size.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 758
Caching
By default, Confluence keeps large in-memory caches of data to improve its responsiveness and the user
experience. The trade off is an increase in memory requirements to support the cache. Administrators of
larger Confluence sites may need to configure the size of their caches to improve performance.
To customize Confluence's cache to meet your needs, see cache tuning.
To increase the amount of memory available to Confluence, see How to fix out of memory errors by
increasing available memory.
Confluence keeps a copy of all emails that it failed to send within an internal error queue. In the event of
intermittent failures such as network connectivity issues, the emails in this queue can be manually resent
when the problem is fixed. Under certain circumstances, the mail queue can fill up with large objects. The
queue is regularly flushed, but if you get a lot of mail errors, you might get a spike in memory usage.
Attachments
The indexing of large attachments requires that the attachment be loaded into memory. In the case of large
attachments, this can cause a temporary strain on the systems resources, and may result in indexing failing
because the attachment could not be fully loaded into memory.
The Confluence backup and restore process scales linearly with the size of data. This can have a significant
impact on large Confluence instances where the amount of data exceeds the amount of available memory. If
you are experiencing an OutOfMemoryError during either a backup or restore processes, then we strongly
recommend that you choose and Production Backup Strategy.
If you encounter an OutOfMemoryError while restoring a backup and wish to overcome this issue by
increasing memory, how much more will you need to make this process work? A good rule of thumb is to
have a look at the size of the entities.xml file in your backup. This file contains all of the data Confluence
will be loading, so at least that much is required. Add another 64-128Mb to ensure that Confluence has
enough memory to load and function and that should be enough. To increase the amount of memory
available to Confluence, see How to fix out of memory errors by increasing available memory.
There are also some memory issues we don't have any control over. For example,
There's a memory leak in the Oracle 10g JDBC drivers. Not much we can do about that.
One customer found a rather nasty memory leak that appeared to originate inside Tomcat 5, but only
using the IBM JDK on PowerPC.
If you are having problems that appear to result from a memory leak, log an issue on http://support.atlassian.
com. Our memory profiler of choice is YourKit. It would be helpful to us if you can provide us with a memory
dump from that tool showing the leak.
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.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 759
To enable gc (garbage collection) logging, start Confluence with the option -XX:+PrintGCDetails
-XX:+PrintGCTimeStamps -verbose:gc -Xloggc:gc.log. Replace gc.log with an absolute path to
a gc.log file.
or in bin/setenv.sh, set:
If you modify bin/setenv.sh, you will need to restart Confluence for the changes to take effect.
What can you do to minimize the time taken to handle the garbage collection? See http://java.sun.com/docs/
hotspot/gc1.4.2/ for details on tuning the JVM to minimize the impact that garbage collection has on the
running application.
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
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 760
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
The database
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
Monitoring data
Before drilling down into individual problems, helps a lot to understand the nature of the performance
problem. Do we deal with sudden spikes of load, or is it a slowly growing load, or maybe a load that follows a
certain pattern (daily, weekly, maybe even monthly) that only on certain occasions exceeds critical
thresholds? It helps a lot to have access to continuous monitoring data available to get a rough overview.
Here are sample graphs from the confluence.atlassian.com system, showing
Load
This graph shows the load for two consecutive days. The obvious pattern is that the machine is under decent
load, which corresponds to the user activity, and there is no major problem.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 761
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 762
The database connection pool size peaked over 112, which happened to be more than the maximum number
of connections the database was configured for (100). So it was no surprise that some requests to
Confluence failed and many users thought it had crashed, since many requests could not obtain the crucial
database connections.
We were able to identify this configuration problem quite easily just by looking at those charts. The next
spikes were uncritical because more database connections were enabled.
The bottom line being: it helps a lot to monitor your Confluence systems continuously (we use Hyperic, for
example), and it helps even more if you are able to send us graphs when you encounter problems.
Access logs
How to Enable User Access Logging, including redirecting the logs to a separate file
You can run this file through a log file analyzer such as AWStats, or manually look through for
pages which are slow to load.
Enable Confluence's built-in profiling for long enough to demonstrate the performance problem using T
roubleshooting Slow Performance Using Page Request Profiling.
If a single page is reliably slow, you should make several requests to that page
If the performance problem is intermittent, or is just a general slowness, leave profiling enabled
for thirty minutes to an hour to get a good sample of profiling times
Find Confluence's standard output logs (which will include the profiling data above). Take a zip of the
entire logs directory.
Take a thread dump during times of poor performance
CPU load
If you are experiencing high CPU load, please install the YourKit profile and attach two profiler dumps
taken during a CPU spike. If the CPU spikes are long enough, please take the profiles 30-60 seconds
apart. The most common cause for CPU spikes is a virtual machine operating system.
If the CPU is spiking to 100%, try Live Monitoring Using the JMX Interface, in particular with the Top
threads plugin.
It is essential to understand the user access and usage of your instance. Please use the access log
scripts and sql scripts to generate Usage statistics for your instance.
Next step
Open a ticket on https://support.atlassian.com and attach all the data you have collected. This should give us
the information we need to track down the source of your performance problems and suggest a solution.
Please follow the progress of your enquiry on the support ticket you have created.
The access log scripts are attached to this page. To use the scripts:
1. Unzip the 7z file.
2. Copy all the daily access logs to a folder called logs.
3. Run Atlassian-processDailyLog.rb. This will generate a csv file called summary.csv and
several directories which contain the access logs of each defined user action.
4. Run the appropriate script Atlassian-processDailyLog-hourly.rb
<admin/comment/create/edit/search/rss>. Each script will generate a different csv file. For
example, Atlassian-processDailyLog-hourly.rb admin will process the admin logs extracted in
step 3.
5. Import the csv files to www-log-Analysis.xls (summary.csv to 'raw stats - daily' sheet and admin.
csv to 'admin -hours' sheet, etc) to generate the load profiles and graphs. You may need to modify the
number of rows in each sheet depending on the number of logs.
Note
All scripts are written in Ruby and assume the log file name contains the string
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 763
Confluence supports HTTP GZip transfer encoding. This means that Confluence will compress the data it sends
to the user, which can speed up Confluence over slow or congested Internet links, and reduce the amount of
bandwidth consumed by a Confluence server.
Turn on Confluence's GZip encoding if:
Users are accessing Confluence over the Internet, or a WAN connection with limited bandwidth.
You wish to reduce the amount of data transfer between the Confluence server and client.
If you are accessing Confluence over a Local Area Network or over a particularly fast WAN, you may wish to
leave GZip encoding disabled. If the network is fast enough that transferring data from Confluence to the user
isn't a limiting factor, the additional CPU load caused by compressing each HTTP response may slow
Confluence down.
This document relates broadly to memory management with Oracle's Hotspot JVM. These
recommendations are based on Support's successful experiences with customers with large Confluence
instances.
Please do not use the Concurrent Mark Sweep (CMS) Collector with Confluence, unless otherwise
advised by Atlassian Support. It requires extensive manual tuning and testing, and is likely to result in
degraded performance.
Keep your heap as small as possible, without the instance experiencing OutOfMemory errors. If you experience
OutOfMemory errors and need to increase this, we recommend you do it in 512mb or 1gb allotments, and
monitor the instance. If you continue to receive OutOfMemory errors, increase the heap by another 512mb or
1gb, and continue this process until you are operating stably with no OutOfMemory errors. Do not increase the
heap further than required, as this will result in longer garbage collections.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 764
On every full GC, the JVM will resize the allocations of Eden, Survivor etc based on the throughput it is actually
seeing. It will tune itself based on the real world data of the objects that are being created and collected. Most of
the time simply allowing JVM to tune itself will give you better performance.
If you have added JVM parameters in the past and are experiencing difficulties with GC now, we'd recommend
you remove all GC related parameters, unless you added them to solve a specific problem, and they did in fact
solve that problem. You should also consider re-benchmarking now to ensure that they are still solving that
problem, and are not causing you any other issues.
If you run Confluence on a VM, check that is it not using the swap file. If it does, when the JVM garbage collects
it has to load the objects from the swap file into memory to clean them, and this can cause significantly longer
GC pauses. Instead of using swapping, ballooning and bursting, allocate adequate memory to the VM.
Manual Tuning
If you find you are still experiencing difficulties with GC after following these recommendations and you would
like to see if you can tune the JVM better to improve performance, we recommend following the instructions in
our Garbage Collection (GC) Tuning Guide. This document will take you through the process of choosing
performance goals (throughput/footprint/latency), and how to tune for those goals.
How to Enable Garbage Collection (GC) Logging, and use a tool like Chewiebug's GCViewer to view the
resulting logs.
Troubleshooting Slow Performance Using Page Request Profiling
This page tells you how to enable page-request On this page:
profiling. With profiling turned on, you will see a
record of the time it takes (in milliseconds) to Enabling Page-Request Profiling
complete each action made on any Confluence Profiling an Activity
page. If Confluence is responding slowly, an internal Example of a Profile
timing trace of the slow page request can help to Start Confluence with Profiling
identify the cause of the delay. Enabled
You need to have System Administrator permissions in order to enable or disable profiling.
To enable page profiling:
1. Choose the cog icon
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
1. 6.4 documentation
Confluence 765
Profiling an Activity
Example of a Profile
Below are the first few lines of a normal profile for accessing a page called Confluence Overview.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 766
[344ms] - /display/ds/Confluence+Overview
[313ms] - SiteMesh: parsePage:
http://localhost:8080/display/ds/Confluence+Overview
[313ms] - XW Interceptor: Before defaultStack:
/pages/viewpage.action (ViewPageAction.execute())
[0ms] - SpaceAwareInterceptor.intercept()
[16ms] - PageAwareInterceptor.intercept()
[0ms] - AOP: PageManager.getPage()
[16ms] - AOP: PermissionManager.hasPermission()
[0ms] - AOP: SpacePermissionManager.hasPermission()
[16ms] - AOP: SpacePermissionManager.hasPermission()
[0ms] - AOP: SpacePermissionManager.hasPermission()
[0ms] - AOP: SpacePermissionManager.hasPermission()
[281ms] - XW Interceptor: After defaultStack:
/pages/viewpage.action (ViewPageAction.execute())
[281ms] - XW Interceptor: After validatingStack:
/pages/viewpage.action (ViewPageAction.execute())
...
Notice that each indented line is a recursive call that rolls up into the parent line. In the example above,
the Confluence Overview page takes 344ms. Part of that, 313ms, is spent in sitemesh.
There may be some situations where you may wish to have Confluence profiling enabled during startup. This
may be useful if you restart often and may forget to enable profiling for Support/Trouble-shooting purposes.
Edit the file CONFLUENCE_HOME\confluence\WEB-INF\web.xml. You should see a section similar to the
one below. Set the parameter value for autostart to true:
<filter>
<filter-name>profiling</filter-name>
<filter-class>com.atlassian.confluence.util.profiling.ConfluenceProfi
lingFilter</filter-class>
<init-param>
<!-- specify the which HTTP parameter to use to turn the
filter on or off -->
<!-- if not specified - defaults to "profile.filter" -->
<param-name>activate.param</param-name>
<param-value>profile</param-value>
</init-param>
<init-param>
<!-- specify the whether to start the filter
automatically -->
<!-- if not specified - defaults to "true" -->
<param-name>autostart</param-name>
<param-value>true</param-value>
</init-param>
</filter>
Remember to turn it back to false or your logs will grow very large.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 767
Page Profiling gives good detail on what operations are slow in a page load. In addition, you can add debug
level logging:
Version 3.1 and Later
Set the package name com.atlassian.renderer.v2.components.MacroRendererComponent to
DEBUG in Administration >> Logging and Profiling.
Prior to version 3.1
Download WikiMarkupParser.class, available from the attachments to this page. This will result in logs like:
Resolution
Experiment with the tips from the performance tuning page, or open an enhancement request about the specific
macro. In some instances there is no resolution - you'll just be aware of the overhead of various macros.
We're proud that Confluence is one of the most versatile collaboration tools on the planet, and we will continue
to deliver innovative new features as quickly as we can. In order to prioritize the features we deliver, we need to
understand how our customers use Confluence, what's important, what's not, and what doesn't work well. The
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 768
collection of usage data allows us to measure the user experience across many thousands of users and deliver
features that matter.
The type of data we collect is covered in our Privacy Policy. Please read it - we've tried to avoid legal jargon and
made it as straightforward as possible.
To view a sample of data that might be collected from your specific installation, go to
Older versions of Confluence (prior to Confluence 5.6 or Confluence Questions 1.0.618) didn't collect usage
data. Analytics are collected using the Atlassian Analytics add-on. The add-on collects analytics events in a log
file which is located in <confluence-home>/analytics-logs. The logs are periodically uploaded using an
encrypted session and then deleted. If Confluence is unable to connect to the Internet, no logs are ever
uploaded.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 769
The editing mode determines the editing experience for all users in your site. This is how you turn
collaborative editing on or off.
To change the editing mode:
1. Go to
Mode Implications
On This mode allows your team to edit a shared draft of a page at the same time, and see each
others' changes in real time.
This the recommended editing mode.
Limited This mode protects your users' shared drafts if you need to troubleshoot Synchrony. You would
only switch to this mode if your users are experiencing problems editing and publishing.
The editing experience will be very limited for your users:
Only one person can edit a shared draft at one time.
You can't revert to an earlier version of the page in the page history.
You can't move pages.
You can't make inline comments on pages.
As soon as Synchrony is running again, we recommend turning collaborative editing back on.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 770
Off This mode means that your team can only edit their own personal draft of a page. Confluence
will attempt to merge any conflicts on save. This mode replicates the Confluence 5 editing
experience.
This mode is useful if you are unable to run Synchrony successfully in your environment, or if
you have decided that collaborative editing is not for you (for example if you have auditing
requirements that would prohibit using collaborative editing just yet).
All existing shared drafts are lost when you switch to this mode, so make sure your users have
published any work they want to keep before you make the change.
A maximum of 12 people can edit a page at the same time. This means that people can't enter the editor if
there are already 12 other people editing the page, and will need to wait until someone leaves.
Administrators can increase or decrease this limit using a system property. If you experience performance
issues when many people are editing, you might want to decrease this limit.
Auditing considerations
We know that auditing is a major consideration for some customers. We don't yet have very granular auditing
capabilities with collaborative editing. All page changes are currently attributed to the person that publishes
the page, rather than the people who made each specific change.
If this is going to be a problem in your site, we recommend turning collaborative editing off in your site for
now.
We're saving all the time in collaborative editing, but we don't save versions of unpublished changes. When
restoring an earlier page version, you can only roll back to an existing published version. Any unpublished
changes will be lost when you restore a previous version.
There are some additional things to be aware of if you have granted the Add page permission (and Can use
global permission) to anonymous users.
You won't be alerted, when closing the editor or publishing a page, if the only unpublished changes on the
page were made by anonymous users. This means a logged in user may inadvertently publish changes they
were not aware had been made to the page.
The changes themselves are visible in the page, but the usual warning dialog will not appear if the only
people to have made changes were not logged in.
If there are unpublished changes from both logged in users and anonymous users, the warning dialog will
appear, but only the logged in users will be listed in the dialog. Changes made by all users (including
anonymous) will be included if you view the changes from that dialog.
The content of any unpublished shared drafts are not included when you export a space or site to XML. This
is particularly important to know if you use an XML site backup as part of your backup strategy. See Producti
on Backup Strategy for our recommendations, which do not rely on the XML export.
If you do need to do a space or site export, you should ask your users to publish any work they want to keep
before you begin the export.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 771
You can't change your Synchrony configuration through the Confluence UI. Configuration changes are made
via system properties. In most cases you will not need to make changes to the default configuration.
If you're Confluence 6.0.3 or earlier you'll need to use reza.port instead of synchrony.port.
If you're Confluence 6.0.3 or earlier you'll need to use reza.memory.max instead of synchrony.memor
y.max.
See Recognized System Properties for the full list of Synchrony system properties.
If you need to pass additional arguments to Synchrony's JVM directly, create a file called synchrony-args
.properties in the Confluence home directory and include the arguments you want to pass to Synchrony,
one per line, as follows.
property1=value1
property2=value2
This will add -Dproperty1=value1 -Dproperty2=value2 to the Synchrony command. This is only
available in Confluence 6.0.2 and later.
You can't use this method for passing any value that is already handled by a system property, such port, Xmx
or Xss etc. See Configuring System Properties for a full list of system properties.
How you connect to Synchrony will depend on your environment. We know that most Confluence sites run
behind a reverse proxy, often with SSL. Here's some information to help you identify the right configuration
for your environment, and any changes you might need to make to your environment to use collaborative
editing in your site.
SSL
Synchrony runs in a seperate JVM, and does not support direct HTTPS connections. If you are not using a
reverse proxy, SSL should be terminated at Tomcat. If you are using a reverse proxy or load balancer, SSL
should be terminated at your reverse proxy or load balancer.
Proxies
In the diagrams below we've used a common implementation where Confluence is running under the
/confluence context path (e.g. www.mysite.com/confluence). The concepts are the same if you use
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 772
No reverse proxy
If you don't run Confluence behind a reverse proxy, you'll connect to Synchrony via Confluence's internal
Synchrony proxy. SSL, if used, is terminated at Tomcat. This is the default configuration, and you shouldn't
need to make any additional changes to use collaborative editing.
If you run Confluence behind a reverse proxy, you will connect to Synchrony via Confluence's internal
Synchrony proxy. This is the default configuration with a reverse proxy, and a good choice if you do not want
to open port 8091. SSL should be terminated at your reverse proxy.
You do not need to make any additional changes to your reverse proxy configuration for Synchrony, but for
best results your reverse proxy must support WebSocket connections (you may need to manually enable this
in your proxy).
To tell Confluence that you want to use the internal proxy, set the synchrony.proxy.enabled system
property to true. (This is optional, but will prevent Confluence from trying to reach Synchrony via /synchrony
first, before retrying via the internal proxy).
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 773
If you run Confluence behind a reverse proxy, and experience latency or other issues connecting to
Synchrony via Confluence's internal Synchrony proxy, you can choose to connect direct to Synchrony. This is
the optimal setup, but does require some changes to your environment. You will need to open port 8091 and
add /synchrony to your reverse proxy configuration. SSL will still be terminated at your reverse proxy, as
Synchrony does not accept direct HTTPS connections.
If Synchrony can't be reached via /synchrony we'll automatically try the internal Synchrony proxy via
/confluence/synchrony-proxy (where /confluence is your Confluence context path).
See the following guides for example reverse proxy configurations. The order of directives is important, so
check our examples.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 774
XHR fallback
When a user cannot connect to Confluence via a WebSocket, we'll fall back to a XML HTTP Request (XHR),
allowing them to edit pages successfully. For the best editing experience, we strongly recommend that your
environment allows WebSocket connections however.
XHR fallback is enabled by default, but can be disabled using a system property if necessary. You shouldn't
need to change this.
Restart Synchrony
Go to
> General Configuration > Collaborative editing and choose Restart Synchrony.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 775
Synchrony runs on port 8091 by default. If this port is already in use by another application on your server
you can use the the synchrony.port system property to change it to an available port.
(If you're using Confluence 6.0.3 or earlier you'll need to use reza.port instead of synchrony.port.)
If you have configured your reverse proxy, but can't edit pages, here's some things to check in your
configuration:
Go to installation-directory>/conf/server.xml and check the Connector directive. Make
sure that you have correct values for <protocol> and <proxyName>. See the examples in the
guides below for more information.
The http connector always needs to be present in the <installation-directory>/conf/serv
er.xml file, even if you're configuring SSL or using the AJP connector. The Synchrony health check
uses HTTP and will fail if this connector is not present. Alternatively, if you do not want to include the
http connector, you can use the synchrony.proxy.healthcheck.disabled system property to
disable the health check.
If you're using Apache, make sure you're using Apache 2.4 (with WebSockets support) and all
required modules have been enabled (mod-proxy, mod_rewrite, proxy_wstunnel).
If you're using Apache and want to connect directly to Synchrony, in your proxy config file, make sure
you've included /synchrony and that the order of the Confluence and Synchrony directives and
location blocks is correct. See the examples in the guides below for more information.
See Administering Collaborative Editing to find out more about possible proxy and SSL configurations then
check out the following guides for more information on how to include Synchrony in your reverse proxy
config, if you want to connect direct to Synchrony:
Using Apache with mod_proxy
Running Confluence behind NGINX with SSL
Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http)
Proxying Atlassian server applications with Microsoft Internet Information Services (IIS)
How to configure Amazon Web Service Elastic Load Balancer with Confluence 6.0
If you're using a forward or outbound proxy, you will need to add the IP that Synchrony listens on to your
config to ensure it is bypassed. See Configuring Web Proxy Support for Confluence for more info.
By default, the IP is 127.0.0.1, or it will be the value of the synchrony.host system property, if you've
customized the hostname or IP that Confluence uses to connect to Synchrony.
Websocket issues
Collaborative editing works best with a WebSocket connection. If one can't be established due to a timeout,
or a proxy server or firewall that doesn't allow WebSocket connections, the editor will attempt to connect via
an XML HTTP Request (XHR).
You can use http://websocket.org/echo.html to perform a quick HTML5 WebSocket test against an echo
server.
SSL issues
Synchrony cannot accept direct HTTPS connections, so you will need to terminate SSL at your reverse proxy
or load balancer, or at Tomcat if you are not using a reverse proxy.
Memory issues
If you experience out of memory errors related to Synchrony, you can change the heap size allocated to
Synchrony using the synchrony.memory.max system property.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 776
If you're Confluence 6.0.3 or earlier you'll need to use reza.memory.max instead of synchrony.memory.
max.
If you see an error immediatley in the editor, but Confluence reports that Synchrony is running, check to
make sure that you only have one Synchrony process running.
If you do have multiple Synchrony processes running, stop Confluence, kill the additional Synchrony
processes and then restart Confluence.
You can avoid this problem by always using stop-confluence.sh / stop-confluence.bat to stop
Confluence, rather than simply closing the Tomcat window.
Some third party browser extensions that interact with the editor, such as Grammarly, may not function
correctly with collaborative editing. See Confluence Collaborative Editing blocks Grammarly Extension to find
out how to disable Grammarly for just your Confluence site.
We've had a few reports of firewalls or anti-virus software blocking some requests to the server, resulting in
unexpected behavior in the editor. You may need to add Confluence to your whitelist / trusted URLs if you
experience issues. See Weird Page or Editor Behaviors with Kaspersky Internet Security for more
information.
We don't enforce a maximum number of people who can edit together, but we recommend you keep it to no
more than 12 people editing the same page at the same time. We may enforce a limit to the number people
who can enter the editor in a later release if necessary.
You can migrate from your Confluence Cloud to Confluence Server 6.0 or later only. You can't import Cloud
data (whole site or individual space exports) into any earlier versions of Confluence. We recommend
installing the latest version.
Confluence Cloud is typically ahead of Confluence Server, which means that some features may not be
available after you've moved to Confluence Server.
Migration steps
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation
2. 777
There's a known issue where the sysadmin user may not be created on import to Confluence
Server. Please try this workaround, and comment on the following issue if you're still having trouble.
Please note the following about your new Confluence Server site.
If you're unable to remove the JIRA cloud application link from your Confluence after the
import, you'll need to remove those references directly from the Confluence database as per t
his guide.
The User Management section might be missing due to
CONFSERVER-35177 - User and Group Links Missing from Admin Console After Migrating From Cloud
to Server OPEN
Follow the workaround notes on the issue to enable the feature again.
If your Confluence Cloud instance has macros that depend on the Application Links back to a
JIRA Cloud instance, and you are migrating JIRA as well, these references will need to be
updated to work properly as per
APL-1144 - Allow relocation of application links even if the target application is still accessible.
TRIAGE
You can address that by either editing the XML prior to import, or by bulk editing those
references in Confluence database as per this guide.
If you experience problems loading pages after the import, head to
> General Configuration to check your base URL as the port may have changed.
If you find that some of your users' favorites (pages saved for later) are missing due to
CONFSERVER-36348 - Favourites missing after importing
OPEN . See How to restore missing
favorites after import from XML for more information.
Confluence spaces are not automatically created when you create a new JIRA projects.
If you are unable to create or edit pages after migrating from Cloud to Confluence 5.10, follow
the workaround in this issue to disable the specified dark features
CONFSERVER-44335 - Edit/Create pages is not working when migrate from Cloud to Server
RESOLVED
. This issue doesn't affect Confluence 6.x versions.
Add-ons
After migrating your data you will need to install any compatible add-ons, such as Questions and Team
Calendars.
Some third party add-ons are only available for Cloud, and will no longer be available after you migrate. You
can check whether your essential add-ons are available for Confluence Server, Cloud or both on Atlassian
Marketplace.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 778
Database considerations
If you are uncertain about which database to choose for your new Confluence installation, we recommend
PostgreSQL - see Database Setup for PostgreSQL. The Confluence Cloud site runs on PostgreSQL, so
there should be no compatibility issues.
If you choose another supported database, Contact Support if you encounter any compatibility issues with
other supported databases.
Confluence license
You will need a new license to migrate to Confluence Server. Your existing Cloud license cannot be used.
You can get a new license at https://my.atlassian.com. You may also need new licenses for any paid
add-ons.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 779
System Requirements
Confluence can run on a wide range of operating On this page:
systems and databases, on physical or virtualized Software requirements
servers. Operating systems
Application server
See Supported Platforms for the full list of platforms Databases
that we support in this version of Confluence or Sup Java
ported Platforms FAQ for details on our support Antivirus considerations
handling procedures. Hardware requirements
Hosted solutions Confluence
Cloud
Software requirements
Operating systems
Application server
We only support running Confluence on the version of Apache Tomcat that is bundled with the Confluence
distribution.
Databases
You'll need an external database to run Confluence. See the Supported Platforms page for a list of all the
databases we support.
When evaluating Confluence, you can use the embedded H2 database included in the Confluence
installation, but you will need to migrate to a supported external database once you're ready to roll
Confluence out to your team.
Java
The Java Runtime Environment (JRE) is packed up and ready to go when you install Confluence using the
Windows or Linux installer. You don't need to install Java yourself.
If you choose to install Confluence from an archive file, you'll need a supported JRE or JDK, and your
JAVA_HOME variable set correctly. See Installing Java for Confluence for more information.
Antivirus considerations
Antivirus software on the operating system running Confluence can greatly decrease the performance of
Confluence. Antivirus software that intercepts access to the hard disk is particularly detrimental and may
even cause errors in Confluence. This is particularly important if you are running Confluence on Windows. No
matter how fast your hardware is, antivirus software will almost always have a negative impact on
Confluence's performance.
You should configure your antivirus software to ignore the following directories:
Confluence home directory
Confluence's index directory
All database-related directories
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 780
Hardware requirements
Please be aware that while some of our customers run Confluence on SPARC-based hardware, Atlassian
only officially supports Confluence running on x86 hardware and 64-bit derivatives of x86 hardware.
See Server Hardware Requirements Guide for more information.
You may also like to check out our tips on reducing out of memory errors, in particular the section on Perman
ent Generation Size.
If you do not have the resources to set up and maintain a Confluence installation locally, consider trying
Confluence Cloud. Atlassian can run and maintain your installation of Confluence, handling all the testing,
monitoring and upgrading processes for you.
Note: Please be aware that while some of our customers run Confluence on SPARC-based hardware, we
only officially support Confluence running on x86 hardware and 64-bit derivatives of x86 hardware.
Confluence typically will not perform well in a tightly constrained, shared environment - examples include an
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 781
AWS micro.t1 instance. Please be careful to ensure that your choice of hosting platform is capable of
supplying sustained processing and memory capacity for the server, particularly the processing-intense
startup process.
These are example hardware specifications for non-clustered Confluence instances. It is not recorded
whether the amount of RAM refers to either the total server memory or memory allocated to the JVM, while
blank settings indicate that the information was not provided.
85,000 100 12,500 4 2.6 4,096 3 machines total: application server, database
server, Apache HTTPD + LDAP tunnel server.
When planning server hardware requirements for your Confluence deployment, you will need to estimate the
server scalability based on peak visitors, the editor to viewer ratio and total content.
The editor to viewer ratio is how many visitors are performing updates versus those only viewing
content
Total content is best estimated by a count of total spaces
Confluence scales best with a steady flow of visitors rather than defined peak visitor times, few editors and
few spaces. Users should also take into account:
Total pages is not a major consideration for performance. For example, instances hosting 80K of
pages can consume under 512MB of memory
Always use an external database, and check out the performance tuning guides.
These values are largest customer instances reported to Atlassian or used for performance testing.
Clustering, database tuning and other performance tuning is recommended for instances exceeding these
values.
All page content is stored in the database, while attachments are stored in the file system. The more
attachments you have, the more disk space you will require.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 782
Private instances manage their users either internally or through a user repository such as LDAP, while
online instances have public signup enabled and must handle the additional load of anonymous internet
visitors. Please keep in mind that these are examples only, not recommendations:
Use Case Spaces User Editors Editor Pages Page Attachments Comments
Accounts To Revisions
Viewer
Ratio
Private Intranet 130 180 140 78% 8,000 84,000 3,800 500
Professional assistance
For large instances, it may be worthwhile contacting an Atlassian Expert for expertise on hardware sizing,
testing and performance tuning. Simply contact a local Expert directly or email our Experts team for a
recommendation.
Example site
Here is a breakdown of the disk usage and memory requirements a large documentation site as at April
2013:
Content bodies (incl. all versions of blogs, pages and bodycontent 517520 1354
comments) MB
Note: not all database tables or indexes are shown, and average row size may vary between instances.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 783
Note: not all files are shown, and average file size may vary between instances.
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.
Banking/Finance
Education
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 784
Engineering/Aerospace
Entertainment
Government
Technology
Telecommunications &
Media
Summary
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 785
Recommendations
The following recommendations come from our experience in running and testing Confluence in virtualized
environments like VMWare and KVM, and our experience in working with customers running on these
platforms.
Know your platform. Consult the documentation for your operating system and your chosen
virtualization technology, for details on setting up a reliable VM (virtual machine) image.
Allocate enough memory. As a Java web application, Confluence requires a relatively large memory
allocation, compared to some other web technologies. Ensure that your VM images have enough
physical memory allocated to run Confluence without swapping.
Handle high I/O. Under normal usage, Confluence requires a significant number of input/output (I/O)
operations to the database and home directory for each web request. Ensure that you use the correct
drivers and consider how you make storage available to your VMs to optimize this access.
Handle peak CPU and memory usage. For certain operations (including PDF export, Office
document processing, and displaying large pages) Confluence requires a significant amount of CPU
and memory. Ensure that your virtualization infrastructure has the flexibility and capacity to deal with
peak load, not just idle load.
Synchronize time correctly. Some customers have had problems with time synchronization between
the VM and the host system. This causes problems in Confluence due to irregularities in the execution
of scheduled tasks. We strongly recommend checking your VM time sync if you have issues with
scheduled tasks in a virtualized environment.
Further help
For further assistance in setting up a virtualized environment for running Confluence, you may want to
consult an Atlassian Expert. Several experts have experience with installation and performance tuning, and
can help you with your Confluence configuration.
Before installing Confluence, please check that you meet the minimum system requirements and Supported
Platforms.
If you're planning to run Confluence in a virtualized environment see Running Confluence in a Virtualized
Environment.
There are a number of ways to install Confluence. Choose the method that is best for your environment.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 786
Install a Confluence trial This is the fastest way to get a Confluence site up and running. If
you're evaluating Confluence, use this option or try Confluence
Windows, Linux or OS X Cloud free.
You don't need an external database to install a Confluence trial.
Install Confluence using an installer This option uses an installer, and is the most straightforward way
to get your production site up and running on a Windows or
Windows Linux server.
Linux
Install Confluence from a zip or archive This option requires you to manually install files and configure
file some system properties. It gives you the most control over the
install process. Use this option if there isn't an installer for your
Windows operating system.
Linux
Run Confluence in a Docker container This option gets Confluence Server up and running in no time
using a pre-configured Docker image. Head to https://docs.dock
Docker er.com/ to find out more about Docker.
Atlassian supports running Confluence in a Docker container, but
we cannot offer support for problems which are related to the
environment itself.
Install Confluence in a cluster Confluence Data Center is a clustered solution for large
enterprises.
Windows or Linux
AWS Quick Start Read the Confluence Data Center Technical Overview to find out
if Confluence Data Center is right for your organization.
Installing Confluence
There are a number of ways to install Confluence. Choose the method that is best for your environment.
Install a Confluence trial This is the fastest way to get a Confluence site up and running. If
you're evaluating Confluence, use this option or try Confluence
Windows, Linux or OS X Cloud free.
You don't need an external database to install a Confluence trial.
Install Confluence using an installer This option uses an installer, and is the most straightforward way
to get your production site up and running on a Windows or
Windows Linux server.
Linux
Install Confluence from a zip or archive This option requires you to manually install files and configure
file some system properties. It gives you the most control over the
install process. Use this option if there isn't an installer for your
Windows operating system.
Linux
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 787
Run Confluence in a Docker container This option gets Confluence Server up and running in no time
using a pre-configured Docker image. Head to https://docs.dock
Docker er.com/ to find out more about Docker.
Atlassian supports running Confluence in a Docker container, but
we cannot offer support for problems which are related to the
environment itself.
Install Confluence in a cluster Confluence Data Center is a clustered solution for large
enterprises.
Windows or Linux
AWS Quick Start Read the Confluence Data Center Technical Overview to find out
if Confluence Data Center is right for your organization.
If you're ready to set up a production Confluence site or you want more control, check out our full installation
guides.
Our installers come with all the bits and pieces you need to run the application, but there's a few things you'll
need to get up and running:
A computer or laptop with a supported operating system - you'll be installing Confluence so you'll need
admin rights.
2. Install Confluence
For Windows
1. Run the installer - we recommend running with a Windows administrator account.
If prompted, make sure you allow the installer to make changes to your computer. This will allow
you to install Confluence as a service.
2.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 788
$ sudo ./atlassian-confluence-X.X.X-x64.bin
3. Set up Confluence
The set up wizard is the last step in getting Confluence up and running. You'll need your email address to
generate your evaluation license.
1. Select Trial, and click Next.
This will allow Confluence to set up everything it needs to run, including an H2 database.
2. Select Get an evaluation license then follow the prompts to generate your license.
3. If you want to try some Confluence add-ons to give you more functionality, select the ones you want
and click Next.
It will take a few minutes to get everything connected and operational.
4. Select Manage users with Confluence, and click Next.
5. Enter and confirm the details you want to use for your administrator account, and click Done.
That's it! You're ready to team up with some colleagues and start using Confluence!
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 789
On this page:
Before you begin
Install Confluence
1. Download Confluence
Other ways to install Confluence: 2. Run the installer
Set up Confluence
Evaluation - get your free trial up and running 3. Choose installation type
in no time. 4. Enter your license
Zip install Confluence manually from a zip 5. Connect to your
file. database
Linux install Confluence on a Linux 6. Populate your new site
operating system with content
7. Choose where to
manage users
8. Create your administrator
account
9. Start using Confluence
Troubleshooting
Before you install Confluence, there's a few questions you need to answer.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 790
Install Confluence
1. Download Confluence
Set up Confluence
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 791
Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.
1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of
this page for details.
2. Choose My own database then select your particular database from the Database type dropdown
menu.
Choose whether you'd like Confluence to populate your site with content:
Demonstration space...
This option will create a space that you and your users can use to get to know Confluence. You can
delete this space at any time.
Import data from an existing site...
Use this option if you have a full site export of an existing Confluence site. This is useful when youre
migrating to another database or setting up a test site.
Good to know:
You can only import sites from the same or earlier Confluence version.
The system administrator account and all other user data and content will be imported from your
previous installation.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 792
Choose to manage Confluence's users and groups inside Confluence or in a JIRA application, such as JIRA
Software or JIRA Service Desk:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 793
That's it! Your Confluence site is accessible from a URL like this:
http://<computer_name_or_IP_address>:<port>
If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go
any further.
Here's a few things that will help you get your team up and running:
Set the server base URL this is the URL people will use to access Confluence.
Set up a mail server this allows Confluence to send people notification about content.
Add and invite users get your team on board!
Start and stop Confluence find out how to start and stop Confluence.
Troubleshooting
Running into problems installing Confluence?
Some anti-virus or other Internet security tools may interfere with the Confluence installation
process and prevent the process from completing successfully. If you experience or anticipate
experiencing such an issue with your anti-virus/Internet security tool, disable this tool first before
proceeding with the Confluence installation.
Can't start Confluence? See Confluence does not start due to Spring Application context has not
been set.
Collaborative editing errors? See Troubleshooting Collaborative Editing.
Head to Installation Troubleshooting in our Knowledge Base for more help.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 794
Before you install Confluence, there's a few questions you need to answer.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 795
If you see a path to your Java installation directory, the JAVA_Home environment
variable has been set correctly.
If nothing is displayed, or only %JAVA_HOME% is returned, you'll need to set the JAV
A_HOME environment variable manually. See Setting the JAVA_HOME Variable in
Windows for a step by step guide.
Install Confluence
1. Download Confluence
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 796
1. Create your installation directory (with full control permission) this is where Confluence will be
installed. Avoid using spaces or special characters in the path. We'll refer to this directory as your <in
stallation-directory>.
2. Extract the Confluence zip file to your <installation-directory>. We recommend using 7zip or
Winzip.
1. Create your home directory (with full control permission) this is where Confluence data like logs,
search indexes and files will be stored. This should be seperate to your installation directory. We'll
refer to this directory as your <home-directory>.
2. Edit <installation-directory>\confluence\WEB-INF\classes\confluence-init.pro
perties.
3. At the bottom of the file, enter the path to your <home directory>.
# confluence.home=c:/confluence/data
b. Remove the '#' and the space at the beginning of this line (so Confluence doesn't regard the
line as a comment)
confluence.home=c:/data/confluence-home
c. If you decide to use a different directory as the home directory you should:
Avoid spaces in the directory path or file name.
Use forward slashes '/' to define the path in this file.
By default Confluence listens on port 8090. If you have another application running on your server that uses
the same ports, you'll need to tell Confluence to use a different port.
In the example below we've changed the Server port to 5000 and the Connector port to 5050.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 797
5. Start Confluence
A command prompt will open. Closing this window will stop Confluence.
Set up Confluence
Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.
1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of
this page for details.
2. Choose My own database then select your particular database from the Database type dropdown
menu.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 798
l file.
Some servers will have JNDI names like jdbc/datasourcename; others will be like java
:comp/env/jdbc/datasourcename.
Choose whether you'd like Confluence to populate your site with content:
Demonstration space...
This option will create a space that you and your users can use to get to know Confluence. You can
delete this space at any time.
Import data from an existing site...
Use this option if you have a full site export of an existing Confluence site. This is useful when youre
migrating to another database or setting up a test site.
Good to know:
You can only import sites from the same or earlier Confluence version.
The system administrator account and all other user data and content will be imported from your
previous installation.
In the setup wizard:
Upload a backup file use this option if your site export file is small (25mb or less).
Restore a backup file from the file system use this option if your backup file is large. Drop the
file into your <confluence-home>/restore directory then follow the prompts to restore the
backup.
Build Index well need to build an index before your imported content is searchable. This can
take a long time for large sites, so deselect this option if you would rather build the index
later. Your content won't be searchable until the index is built.
Choose to manage Confluence's users and groups inside Confluence or in a JIRA application, such as JIRA
Software or JIRA Service Desk:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 799
JIRA System Administrator global permission in your JIRA application. Confluence will also use
this username and password to create a local administrator account which will let you access
Confluence if JIRA is unavailable. Note that this single account is stored in Confluence's internal
user directory, so if you change the password in JIRA, it will not automatically update in
Confluence.
Confluence Base URL this is the URL JIRA will use to access your Confluence server. The URL
you give here overrides the base URL specified in Confluence, for the purposes of connecting to
the JIRA application.
User Groups these are the JIRA groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in
your Confluence license. The default user group name differs depending on your JIRA version:
JIRA 6.4 and earlier: jira-users.
JIRA Software 7.x and later: jira-software-users
JIRA Core 7.x and later: jira-core-users
JIRA Service Desk 3.x and later: jira-servicedesk-users
Admin Groups provide one or more JIRA groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.
That's it! Your Confluence site is accessible from a URL like this:
http://<computer_name_or_IP_address>:<port>
If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go
any further.
Here's a few things that will help you get your team up and running:
Set the server base URL this is the URL people will use to access Confluence.
Set up a mail server this allows Confluence to send people notification about content.
Add and invite users get your team on board!
Start and stop Confluence find out how to start and stop Confluence.
Troubleshooting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 800
This page describes the procedure for uninstalling an instance of Confluence which has been installed using the
Windows Installer.
To uninstall Confluence from Windows:
1. Log in to Windows as the same user that was used to install Confluence with the Windows Installer.
2. Start the uninstaller by doing either of the following:
Click the Windows Start Menu > All Programs > Confluence > Uninstall Confluence
OR
Open the Windows Control Panel, choose Add or Remove Programs (on Windows XP) or Progr
ams and Features on (Windows 7, Vista) and then select Confluence X.Y from the list of
applications and click Uninstall/Change.
OR
Open the Windows command prompt and do the following:
a. Change directory to your Confluence installation directory
b. Run the uninstall.exe file
3. Follow the prompts to uninstall Confluence from your computer.
Please note:
The uninstaller will not delete the Confluence Home Directory.
All log files that were generated while Confluence was running will not be deleted.
All files within the Confluence Installation Directory will be deleted (with the exception of the Tomcat log f
older located in the Confluence Installation Directory).
The uninstaller can be made to operate in unattended mode by specifying the -q option at the Windows
command prompt i.e. uninstall -q
If you wish to re-install Confluence in 'unattended mode', do not uninstall your previous installation of
Confluence just yet. See Using the Silent Installation Feature for more information.
Installing Confluence on Linux
In this guide we'll run you through installing On this page:
Confluence in a production environment, with an
external database, using the Linux installer. Before you begin
Install Confluence
This is the most straightforward way to get your 1. Download Confluence
production site up and running on a Linux server. 2. Run the installer
Set up Confluence
3. Choose installation type
4. Enter your license
5. Connect to your
database
Other ways to install Confluence:
6. Populate your new site
Evaluation - get your free trial up and running with content
in no time. 7. Choose where to
TAR.GZ install Confluence manually from manage users
an archive file. 8. Create your administrator
Windows install Confluence on a Windows account
server. 9. Start using Confluence
Troubleshooting
Before you install Confluence, there are a few questions you need to answer.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 801
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 802
Install Confluence
1. Download Confluence
2. Run the installer we recommend using sudo to run the installer as this will create a dedicated
account to run Confluence and allow you to run Confluence as a service.
$ sudo ./atlassian-confluence-X.X.X-x64.bin
You can also choose to run the installer as with root user privileges.
3. Follow the prompts to install Confluence. You'll be asked for the following info:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 803
Set up Confluence
Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.
1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of
this page for details.
2. Choose My own database then select your particular database from the Database type dropdown
menu.
Choose whether you'd like Confluence to populate your site with content:
Demonstration space...
This option will create a space that you and your users can use to get to know Confluence. You can
delete this space at any time.
Import data from an existing site...
Use this option if you have a full site export of an existing Confluence site. This is useful when youre
migrating to another database or setting up a test site.
Good to know:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 804
You can only import sites from the same or earlier Confluence version.
The system administrator account and all other user data and content will be imported from your
previous installation.
In the setup wizard:
Upload a backup file use this option if your site export file is small (25mb or less).
Restore a backup file from the file system use this option if your backup file is large. Drop the
file into your <confluence-home>/restore directory then follow the prompts to restore the
backup.
Build Index well need to build an index before your imported content is searchable. This can
take a long time for large sites, so deselect this option if you would rather build the index
later. Your content won't be searchable until the index is built.
Choose to manage Confluence's users and groups inside Confluence or in a JIRA application, such as JIRA
Software or JIRA Service Desk:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 805
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.
That's it! Your Confluence site is accessible from a URL like this:
http://<computer_name_or_IP_address>:<port>
If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go
any further.
Here's a few things that will help you get your team up and running:
Set the server base URL this is the URL people will use to access Confluence.
Set up a mail server this allows Confluence to send people notification about content.
Add and invite users get your team on board!
Start and stop Confluence find out how to start and stop Confluence.
Troubleshooting
Running into problems installing Confluence?
Some anti-virus or other Internet security tools may interfere with the Confluence installation
process and prevent the process from completing successfully. If you experience or anticipate
experiencing such an issue with your anti-virus/Internet security tool, disable this tool first before
proceeding with the Confluence installation.
The Linux OOM Killer can sometimes kill Confluence processes when memory on the server
becomes too low. See How to Configure the Linux Out-of-Memory Killer.
Collaborative editing errors? See Troubleshooting Collaborative Editing.
Head to Installation Troubleshooting in our Knowledge Base for more help.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 806
Before you install Confluence, there are a few questions you need to answer.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 807
$ java -version
$ echo $JAVA_HOME
If you see a path to your Java installation directory, the JAVA_Home environment
variable has been set correctly. If a path is not returned you'll need to set your JAVA_H
OME environment variable manually before installing Confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 808
See Creating a Dedicated User Account on the Operating System to Run Confluence f
or more information.
Install Confluence
1. Download Confluence
1. Create your installation directory this is where Confluence will be installed. Avoid using spaces or
special characters in the path. We'll refer to this directory as your <installation-directory>.
$ mkdir confluence
Replace x.x.x with your Confluence version and <installation-directory> with the full
path to the directory you created in the last step.
3. Give your dedicated Confluence user read, write and execute permission to your <installation-d
irectory>.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 809
1. Create your home directory this is where Confluence application data like logs, search indexes and
files will be stored. This should be separate to your installation directory, with no spaces or special
characters in the path. We'll refer to this directory as your <home-directory>.
$ mkdir confluence-home
2. Give your dedicated Confluence user read, write and execute permissions to the <home-directory
>.
3. Edit <installation-directory>\confluence\WEB-INF\classes\confluence-init.pro
perties.
4. At the bottom of the file, enter the absolute path to your <home-directory>. This tells Confluence
where to find your <home-directory> when it starts up.
# confluence.home=c:/confluence/data
b. Remove the # and the space at the beginning of this line (so Confluence doesn't read the
line as a comment) and add the absolute path to your home directory (not a symlink). For
example:
confluence.home=/var/confluence-home
By default Confluence listens on port 8090. If you have another application running on your server that uses
the same ports, you'll need to tell Confluence to use a different port.
2.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 810
2. Change the Server port (8000) and the Connector port (8090) to free ports on your server.
In the example below we've changed the Server port to 5000 and the Connector port to 5050.
Linux won't allow you to bind to ports less than 1024. If you want to run Confluence on port 80, for
example, you could use a reverse proxy to redirect traffic from port 80. See Using Apache with
mod_proxy.
5. Start Confluence
$ su -u <user>
$ ./start-confluence.sh
$ sudo su <user>
$ ./start-confluence.sh
Set up Confluence
Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.
1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 811
1.
2. Choose My own database then select your particular database from the Database type dropdown
menu.
Choose whether you'd like Confluence to populate your site with content:
Demonstration space...
This option will create a space that you and your users can use to get to know Confluence. You can
delete this space at any time.
Import data from an existing site...
Use this option if you have a full site export of an existing Confluence site. This is useful when youre
migrating to another database or setting up a test site.
Good to know:
You can only import sites from the same or earlier Confluence version.
The system administrator account and all other user data and content will be imported from your
previous installation.
In the setup wizard:
Upload a backup file use this option if your site export file is small (25mb or less).
Restore a backup file from the file system use this option if your backup file is large. Drop the
file into your <confluence-home>/restore directory then follow the prompts to restore the
backup.
Build Index well need to build an index before your imported content is searchable. This can
take a long time for large sites, so deselect this option if you would rather build the index
later. Your content won't be searchable until the index is built.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 812
10. Choose where to manage users
Choose to manage Confluence's users and groups inside Confluence or in a JIRA application, such as JIRA
Software or JIRA Service Desk:
That's it! Your Confluence site is accessible from a URL like this:
http://<computer_name_or_IP_address>:<port>
If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go
any further.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 813
Here's a few things that will help you get your team up and running:
Set the server base URL this is the URL people will use to access Confluence.
Set up a mail server this allows Confluence to send people notification about content.
Add and invite users get your team on board!
Start and stop Confluence find out how to start and stop Confluence.
Troubleshooting
This page describes the procedure for uninstalling Confluence, which had been installed using the Linux Installer
.
To uninstall Confluence from Linux:
1. Open a Linux console.
2. Change directory (cd) to your Confluence installation directory.
3. Execute the command uninstall. This command must be executed as the same user account that was
used to install Confluence with the Linux Installer.
4. Follow the prompts to uninstall Confluence from your computer.
Please note:
The uninstaller will not delete the Confluence Home Directory.
All log files that were generated while Confluence was running will not be deleted.
All files within the Confluence Installation Directory will be deleted (with the exception of the Tomcat log f
older located in the Confluence Installation Directory).
The uninstaller can be made to operate in unattended mode by specifying the -q option i.e. uninstal
l -q
If you wish to re-install Confluence in 'unattended mode', do not uninstall your previous installation of
Confluence just yet. See Using the Silent Installation Feature for more information.
Unattended installation
If you've previously installed Confluence using the
Windows or Linux installer, you can use a
configuration file from your existing Confluence
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 814
Good to know
The response.varfile file contains the options specified during the installation wizard steps of
your previous Confluence installation. Don't uninstall your previous Confluence installation until after
you've copied this file to your new install location.
If you decide to modify the response.varfile file, make sure all directory paths specified are
absolute, for example, sys.installationDir=C\:\\Program
Files\\Atlassian\\Confluence
(Windows) or sys.installationDir=/opt/atlassian/confluence (Linux).
Unattended installations will fail the file contains relative directory paths.
3. In command prompt or terminal change directory (cd) to where you downloaded the installer.
Windows
> atlassian-confluence-X.X.X-x64.exe -q -varfile
response.varfile
Linux
$ atlassian-confluence-X.X.X-x64.bin -q -varfile
response.varfile
-q instructs the installer to run in unattended mode (quietly). -varfile specifies the location and
name of the configuration file containing the options used by the installer.
See the Set up Confluence section on Installing Confluence on Windows or Installing Confluence on Linux f
or more info.
Problem
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 815
This page tells you what to do if you get errors like the following when starting Confluence, when you can't
access Confluence on port 8090.
If you see this error:
This means you are running other software on Confluence's default port of 8090. This may be another other
process running on the same port. It may also be a previous instance of Confluence that hasn't been shut down
cleanly.
To find out what process is listening on that port, load a command prompt and type: netstat -an
-a : Displays all active TCP connections and the TCP and UDP ports on
which the computer is listening.
-n : Displays active TCP connections, however, addresses and port
numbers are expressed numerically and no attempt is made to determine
names.
There is also Process Explorer tool available to determine what is binding port 8090.
To change the ports for Confluence, open the file conf/server.xml under your Confluence Installation
directory. The first four lines of the file look like this:
Default conf/server.xml
<Server port="8000" shutdown="SHUTDOWN" debug="0">
<Service name="Tomcat-Standalone">
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8090" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443" acceptCount="10"
debug="0" connectionTimeout="20000" useURIValidationHack="false"/>
...
You need to modify both the server port (default is 8000) and the connector port (default is 8090) to ports that
are free on your machine. The server port is required by Tomcat but is not user facing in any way. The connector
port is what your users will use to access Confluence, eg in the snippet above, the URL would be http://exam
ple.com:8090.
Hint: You can use netstat to identify free ports on your machine. See more information on using netstat on
Windows or on Linux.
For example, here are the first four lines of a modified server.xml file, using ports '8020' and '8099':
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 816
Final Configuration
If this is the URL your users will use to access Confluence, update your Base URL to point to the new
URL.
You should also ensure at this point that if you are using a firewall, it is configured to allow http/https
traffic over the port you have chosen.
NOTES
[1] For more information on netstat, see using netstat on Windows, or netstat man page (Linux).
[2] The JIRA distribution runs on port 8080 by default. If you're looking to change the port of your JIRA
application's distribution, see Changing JIRA application TCP ports.
[3] You will need to restart Confluence after editing server.xml for the changes to take effect.
Start and Stop Confluence
How you start and stop Confluence depends on whether you are running Confluence as a Service.
To check whether Confluence is already running you can go to http://<base-url>/status.
Windows
When installed as a service...
If you installed Confluence as a service, you can Start Confluence Server and Stop Confluence Server fro
m the Windows Start menu.
You can't start or stop Confluence manually using the start-confluence.bat and stop-confluence.
bat file.
We recommend running Confluence with a dedicated user account. To do this, use use the runas command
to execute start-confluence.bat.
Where <DOMAIN> is your Windows domain or computer name and <confluence> is the name of your
dedicated user.
With add-ons disabled (for troubleshooting)...
It is possible to start Confluence Server with user installed add-ons temporarily disabled. This is useful if you
need to troubleshoot problems with your site, particularly if an add-on may be preventing Confluence from
starting up successfully.
To start Confluence with all user installed add-ons temporarily disabled:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 817
> cd <installation-directory>/bin
> start-confluence.bat /disablealladdons
> cd <installation-directory>/bin
> start-confluence.bat /disableaddon=com.atlassian.test.plugin
where com.atlassian.test.plugin is the add-on key. To disable multiple add-ons, use a colon
separated list. Regex/wildcards are not permitted, the full key of the plugin must be provided.
These parameters are applied at startup only, they do not persist. If you want to permanently disable an
add-on, go to
Linux
You can't start or stop Confluence manually using the start-confluence.sh and stop-confluence.s
h files.
$ su -u <user>
$ ./start-confluence.sh
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 818
$ sudo su <user>
$ ./start-confluence.sh
$ cd <installation-directory>/bin
$ ./start-confluence.sh --disable-all-addons
$ cd <installation-directory>/bin
$ ./start-confluence.sh --disable-addons=com.atlassian.test.plugin
To disable multiple add-ons, use a colon separated list, for example, com.atlassian.test.plugin:com
.atlassian.another.plugin. Regex/wildcards are not permitted, the full key of the plugin must be
provided.
These parameters are applied at startup only, they do not persist. If you want to permanently disable an
add-on, go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 819
Deploying in AWS?
We recommend using our Quick Start or Cloud Formation Template to deploy Confluence
Data Center in AWS, as it will automatically provision, configure and connect everything you
need.
If you do decide to do your own custom deployment, you can provide the following
information to allow Confluence to auto-discover cluster nodes:
Field Description
IAM This is your authentication method. You can choose to authenticate by IAM
Role or Role or Secret Key.
Secret
Key
Region This is the region your cluster nodes (EC2 instances) will be running in.
Host Optional. This is the AWS endpoint for Confluence to use (the address where
header the EC2 API can be found, for example ec2.amazonaws.com). Leave blank to
use the default endpoint.
Security Optional. Use to narrow the members of your cluster to only resources in a
group particular security group (specified in the EC2 console).
name
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 820
Tag key Optional. Use to narrow the members of your cluster to only resources with
and Tag particular tags (specified in the EC2 console).
value
2. Set up Synchrony
Collaborative editing requires Synchrony, which runs as a separate process. You can deploy Synchrony on
the same nodes as Confluence, or in its own cluster with as many nodes as you need. You'll need to
complete step one (including entering your Data Center license) before you start this step.
In this example, we assume you'll run Synchrony in its own cluster. When configuring your cluster nodes you
can either supply the IP address of each Synchrony cluster node, or a multicast address.
1. Create a Synchrony directory on your first node and copy synchrony-standalone.jar from your
Confluence <home-directory> to this directory.
2. Copy your database driver from your Confluence <install-directory>/confluence/web-inf/
lib to an appropriate location on your Synchrony node.
3. Change to your Synchrony directory and start Synchrony using the following command.
You need to pass all of the system properties listed, replacing the values where indicated.
java
-Xss2048k
-Xmx2g
-Dsynchrony.bind=<SERVER_IP>
-Dsynchrony.service.url=<SYNCHRONY_URL>
-Dsynchrony.database.url=<YOUR_DATABASE_URL>
-Dsynchrony.database.username=<DB_USERNAME>
-Dsynchrony.database.password=<DB_PASSWORD>
synchrony.core
sql
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 821
Remember to remove all commented lines completley before you execute this command, and
replace all new lines with white space. You may also need to change the name of the synchrony
-standalone.jar if the file you copied is different to our example.
Here's more information about each of the values you'll need to supply in the command above.
<JDBC_DRIVER_PATH> Yes This is the path to your database driver. For exam
-directory>/postgresql-9.2-1002.jdbc
<SYNCHRONY_URL> Yes This is the URL that the browser uses to contact
Generally this will be the full URL of the load bala
will run behind plus the Synchrony context path,
//yoursite.com:8091/synchrony. Note tha
with /v1, unlike the synchrony.service.url
passed to Confluence. If this URL doesn't match
from a users' browser, Synchrony will fail.
When you start Synchrony we also pass default values for a number of additional properties. You
can choose to override these values by specifying these optional properties when you start
Synchrony. See Configuring Synchrony for Data Center for more information.
4. To check that Synchrony is accessible, you can go to:
http://<SERVER_IP>:<SYNCHRONY_PORT>/synchrony/heartbeat
5. Repeat this process to start Synchrony on each node of your Synchrony cluster.
As each node joins you'll see something like this in your console.
Members [2] {
Member [172.22.52.12]:5701
Member [172.22.49.34]:5701
}
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 822
1. Start Confluence on node 1 and pass the following system property to Confluence to tell Confluence
where to find your Synchrony cluster.
-Dsynchrony.service.url=http://<LOAD_BALANCER_URL>:<PORT>/synchr
ony/v1
You may want to add this system property to your <install-directory>/bin/setenv.sh or set
env.bat so it is automatically passed every time you start Confluence. See Configuring System
Properties for more information on how to do this in your environment.
2. Head to
> General Configuration > Collaborative editing to check that this Confluence node can connect to
Synchrony.
Note: to test creating content you'll need to access Confluence via your load balancer. You can't
create or edit pages when accessing a node directly.
Configure your load balancer for Confluence. You can use the load balancer of your choice, but it needs to
support session affinity and WebSockets.
SSL connections must be terminated at your load balancer so that Synchrony can accept XHR requests from
the web browser.
You can verify that your load balancer is sending requests correctly to your existing Confluence server by
accessing Confluence through the load balancer and creating a page, then checking that this page can be
viewed/edited by another machine through the load balancer.
6. Start Confluence on the first node, wait, then start Confluence on second node
> General Configuration > Clustering) includes information about the active cluster.
When the cluster is running properly, this page displays the details of each node, including system usage and
uptime. Use the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 823
Remember, to test creating content you'll need to access Confluence via your load balancer. You can't
create or edit pages when accessing a node directly.
A simple process to ensure your cluster is working correctly is:
1. Access a node via your load balancer, and create a new document on this node
2. Ensure the new document is visible by accessing it directly on a different node
3. Search for the new document on the original node, and ensure it appears
4. Search for the new document on another node, and ensure it appears
If Confluence detects more than one instance accessing the database but not in a working cluster, it
will shut itself down in a cluster panic. This can be fixed by troubleshooting the network connectivity
of the cluster.
Security
Ensure that only permitted cluster nodes are allowed to connect to a Confluence Data Center instance's Haz
elcast port (which defaults to 5801) or Synchrony's Hazelcast port (which defaults to 5701) through the use of
a firewall and or network segregation.
Troubleshooting
If you have problems with the above procedure, please see our Cluster Troubleshooting guide.
If you're testing Confluence Data Center by running the cluster on a single machine, please refer to our
developer instructions on Starting a Confluence cluster on a single machine.
Upgrading a cluster
It's important that upgrades follow the procedure for Upgrading Confluence Data Center.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 824
Have a Data Center license (you can purchase a Data Center license or create an evaluation license
at my.atlassian.com)
Use an external database
Use a load balancer with session affinity in front of the cluster
Have a shared directory that's accessible by the same path to all cluster nodes (this will be your
shared home directory)
Use OAuth authentication if you have application links to other Atlassian products (like JIRA
applications).
If you need a Confluence Data Center evaluation license, get in touch with us.
In this guide we'll use the following terminology:
installation directory The directory where Confluence is installed.
local home directory The home or data directory on each node (in non-clustered Confluence this is
simply known as the home directory).
shared home directory The directory you created that is accessible to all nodes in the cluster via
the same path.
At the end of the installation process you'll have an installation directory and local home directory on each
node, and a single shared home directory (for example, in a two node cluster you'd have a total of 5
directories).
If you're switching to Confluence Data Center 5.9 or later follow the normal procedure for backing up
and upgrading Confluence first. See upgrading Confluence for information on upgrading and choosing the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 825
If you're switching to Confluence Data Center 5.8 the process for upgrading is a little different. Refer to our e
arlier documentation for more information.
1. Go to
1. Create a directory that's accessible to all cluster nodes via the same path. This will be your shared
home directory.
2. In your existing Confluence home directory, move the contents of <confluence
home>/shared-home to the new shared home directory you just created.
To prevent confusion, we recommend deleting the empty <confluence home>/shared-home direc
tory once you've moved its contents.
3. Move your attachments directory to the new shared home directory (skip this step if you currently store
attachments in the database).
4. Start Confluence
The setup wizard will prompt you to complete the migration, by entering:
A name for your cluster
The path to the shared home directory you created earlier
A multicast address (automatically generated or enter your own) or the IP addresses of each cluster
node
The network interface Confluence will use to communicate between nodes
Deploying in AWS?
We recommend using our Quick Start or Cloud Formation Template to deploy Confluence Data
Center in AWS, as it will automatically provision, configure and connect everything you need.
If you do decide to do your own custom deployment, you can provide the following information to
allow Confluence to auto-discover cluster nodes:
Field Description
IAM Role This is your authentication method. You can choose to authenticate by IAM Role or
or Secret Key.
Secret
Key
Region This is the region your cluster nodes (EC2 instances) will be running in.
Host Optional. This is the AWS endpoint for Confluence to use (the address where the
header EC2 API can be found, for example 'ec2.amazonaws.com'). Leave blank to use the
default endpoint.
Security Optional. Use to narrow the members of your cluster to only resources in a
group particular security group (specified in the EC2 console).
name
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 826
Tag key Optional. Use to narrow the members of your cluster to only resources with
and Tag particular tags (specified in the EC2 console).
value
2. Set up Synchrony
Collaborative editing requires Synchrony, which runs as a separate process. You can deploy Synchrony on
the same nodes as Confluence, or in its own cluster with as many nodes as you need. You'll need to
complete step one (including entering your Data Center license) before you start this step.
In this example, we assume you'll run Synchrony in its own cluster. When configuring your cluster nodes you
can either supply the IP address of each Synchrony cluster node, or a multicast address.
1. Create a Synchrony directory on your first node and copy synchrony-standalone.jar from your
Confluence <home-directory> to this directory.
2. Copy your database driver from your Confluence <install-directory>/confluence/web-inf/
lib to an appropriate location on your Synchrony node.
3. Change to your Synchrony directory and start Synchrony using the following command.
You need to pass all of the system properties listed, replacing the values where indicated.
java
-Xss2048k
-Xmx2g
-Dsynchrony.bind=<SERVER_IP>
-Dsynchrony.service.url=<SYNCHRONY_URL>
-Dsynchrony.database.url=<YOUR_DATABASE_URL>
-Dsynchrony.database.username=<DB_USERNAME>
-Dsynchrony.database.password=<DB_PASSWORD>
synchrony.core
sql
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 827
Remember to remove all commented lines completley before you execute this command, and
replace all new lines with white space. You may also need to change the name of the synchrony
-standalone.jar if the file you copied is different to our example.
Here's more information about each of the values you'll need to supply in the command above.
<JDBC_DRIVER_PATH> Yes This is the path to your database driver. For exam
-directory>/postgresql-9.2-1002.jdbc
<SYNCHRONY_URL> Yes This is the URL that the browser uses to contact
Generally this will be the full URL of the load bala
will run behind plus the Synchrony context path,
//yoursite.com:8091/synchrony. Note tha
with /v1, unlike the synchrony.service.url
passed to Confluence. If this URL doesn't match
from a users' browser, Synchrony will fail.
When you start Synchrony we also pass default values for a number of additional properties. You
can choose to override these values by specifying these optional properties when you start
Synchrony. See Configuring Synchrony for Data Center for more information.
4. To check that Synchrony is accessible, you can go to:
http://<SERVER_IP>:<SYNCHRONY_PORT>/synchrony/heartbeat
5. Repeat this process to start Synchrony on each node of your Synchrony cluster.
As each node joins you'll see something like this in your console.
Members [2] {
Member [172.22.52.12]:5701
Member [172.22.49.34]:5701
}
1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 828
1. Start Confluence on node 1 and pass the following system property to Confluence to tell Confluence
where to find your Synchrony cluster.
-Dsynchrony.service.url=http://<LOAD_BALANCER_URL>:<PORT>/synchr
ony/v1
You may want to add this system property to your <install-directory>/bin/setenv.sh or set
env.bat so it is automatically passed every time you start Confluence. See Configuring System
Properties for more information on how to do this in your environment.
2. Head to
> General Configuration > Collaborative editing to check that this Confluence node can connect to
Synchrony.
Note: to test creating content you'll need to access Confluence via your load balancer. You can't
create or edit pages when accessing a node directly.
Configure your load balancer for Confluence. You can use the load balancer of your choice, but it needs to
support session affinity and WebSockets.
SSL connections must be terminated at your load balancer so that Synchrony can accept XHR requests from
the web browser.
You can verify that your load balancer is sending requests correctly to your existing Confluence server by
accessing Confluence through the load balancer and creating a page, then checking that this page can be
viewed/edited by another machine through the load balancer.
6. Start Confluence on the first node, wait, then start Confluence on second node
> General Configuration > Clustering) includes information about the active cluster.
When the cluster is running properly, this page displays the details of each node, including system usage and
uptime. Use the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 829
Remember, to test creating content you'll need to access Confluence via your load balancer. You can't
create or edit pages when accessing a node directly.
A simple process to ensure your cluster is working correctly is:
1. Access a node via your load balancer, and create a new document on this node
2. Ensure the new document is visible by accessing it directly on a different node
3. Search for the new document on the original node, and ensure it appears
4. Search for the new document on another node, and ensure it appears
If Confluence detects more than one instance accessing the database but not in a working cluster, it
will shut itself down in a cluster panic. This can be fixed by troubleshooting the network connectivity
of the cluster.
Security
Ensure that only permitted cluster nodes are allowed to connect to a Confluence Data Center instance's Haz
elcast port (which defaults to 5801) or Synchrony's Hazelcast port (which defaults to 5701) through the use of
a firewall and or network segregation.
Troubleshooting
If you have problems with the above procedure, please see our Cluster Troubleshooting guide.
If you're testing Confluence Data Center by running the cluster on a single machine, please refer to our
developer instructions on Starting a Confluence cluster on a single machine.
If you need to move from Data Center (clustered) to Server (non-clustered), read on. In these instructions
we'll assume that you'll use one of your existing cluster nodes as your new, non-clustered installation.
You'll need a Confluence Server license to switch back to Server.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 830
1. Go to
Stop any cluster nodes that are still running before proceeding. We also recommend configuring your load
balancer to redirect traffic away from Confluence.
1. Create a directory called /shared-home in the <local home> directory on one node (if you
removed this directory when installing Data Center)
2. Move the entire config directory from your <shared home> directory to the <local
home>/shared-home directory
3. Move the remaining contents of your <shared home> directory to the root of your <local home> di
rectory
Your cluster's shared home directory should now be empty.
4. Start Confluence
The setup wizard will guide you through the migration process.
> General Configuration. The 'Cluster Configuration' page should not appear. Instead you'll see
information about Confluence Data Center.
Step 1 Back up
We strongly recommend that you backup your Confluence home and install directories and your database
before proceeding.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 831
More information on specific files and directories to backup can be found in Upgrading Confluence.
You must stop all the nodes in the cluster before upgrading.
We recommend configuring your load balancer to redirect traffic away from Confluence until the upgrade is
complete on all nodes.
If you are upgrading an existing Confluence Data Center instance (Confluence 5.6 or later), you can
skip this step, as you already have a Shared Home directory.
To set up your Shared Home directory:
1. Create a directory that is accessible to all cluster nodes via the same path. This will be your shared
home directory.
2. Edit confluence.cfg.xml in the home directory on the first node and add a new property called co
nfluence.cluster.home with the path of the shared home directory as the value. Example:
<property
name="confluence.cluster.home">/mnt/confluence-shared-home</prop
erty>
3. Move all the files/directories from the local home directory the first node to the new shared home
directory except for the following:
config
confluence.cfg.xml
index
temp
bundled-plugins
plugin-cache-*
plugins-cache
plugins-osgi-cache
plugins-temp
Remove the moved files/directories from the local home directories on all other nodes.
This step is only required the first time you upgrade to Confluence Data Center 6.0.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 832
In this example, we assume you'll run Synchrony in its own cluster. When configuring your cluster nodes you
can either supply the IP address of each Synchrony cluster node, or a multicast address.
1. Create a Synchrony directory on your first node and copy synchrony-standalone.jar from your
Confluence <home-directory> to this directory.
2. Copy your database driver from your Confluence <install-directory>/confluence/web-inf/
lib to an appropriate location on your Synchrony node.
3. Change to your Synchrony directory and start Synchrony using the following command.
You need to pass all of the system properties listed, replacing the values where indicated.
java
-Xss2048k
-Xmx2g
-Dsynchrony.bind=<SERVER_IP>
-Dsynchrony.service.url=<SYNCHRONY_URL>
-Dsynchrony.database.url=<YOUR_DATABASE_URL>
-Dsynchrony.database.username=<DB_USERNAME>
-Dsynchrony.database.password=<DB_PASSWORD>
synchrony.core
sql
Remember to remove all commented lines completley before you execute this command, and
replace all new lines with white space. You may also need to change the name of the synchrony
-standalone.jar if the file you copied is different to our example.
Here's more information about each of the values you'll need to supply in the command above.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 833
<JDBC_DRIVER_PATH> Yes This is the path to your database driver. For exam
-directory>/postgresql-9.2-1002.jdbc
<SYNCHRONY_URL> Yes This is the URL that the browser uses to contact
Generally this will be the full URL of the load bala
will run behind plus the Synchrony context path,
//yoursite.com:8091/synchrony. Note tha
with /v1, unlike the synchrony.service.url
passed to Confluence. If this URL doesn't match
from a users' browser, Synchrony will fail.
When you start Synchrony we also pass default values for a number of additional properties. You
can choose to override these values by specifying these optional properties when you start
Synchrony. See Configuring Synchrony for Data Center for more information.
4. To check that Synchrony is accessible, you can go to:
http://<SERVER_IP>:<SYNCHRONY_PORT>/synchrony/heartbeat
5. Repeat this process to start Synchrony on each node of your Synchrony cluster.
As each node joins you'll see something like this in your console.
Members [2] {
Member [172.22.52.12]:5701
Member [172.22.49.34]:5701
}
1. Start Confluence on node 1 and pass the following system property to tell Confluence where to find
your Synchrony cluster.
-Dsynchrony.service.url=http://<YOUR_LOAD_BALANCER>:<LOAD_BALANC
ER_PORT>/synchrony/v1
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 834
2. Head to
> General Configuration > Collaborative editing to check that this Confluence node can connect to
Synchrony.
Note: to test creating content you'll need to access Confluence via your load balancer. You can't
create or edit pages when accessing a node directly.
The next step is to replicate your upgraded Confluence directories to other nodes in the cluster.
1. Stop Confluence on the first node.
2. Copy the installation directory and local home directory from the first node to the next node.
If the path to the local home directory is different on this node, edit the confluence-init.propert
ies to point to the correct location.
3. Start Confluence, and and confirm that you can log in and view pages before continuing with the next
node.
Repeat this process for each remaining node.
Once all nodes have been upgraded you can start Confluence Data Center on each node, one at a time
(starting up multiple nodes simultaneously can lead to serious failures).
The Cluster monitoring console (
> General Configuration > Clustering) includes information about the active cluster nodes. When the
cluster is running properly, you should be able to see the details of each node.
Your Data Center license is based on the number of users in your cluster, rather than the number of nodes. This
means you can add and remove nodes from your Data Center cluster at any time.
If you deployed Confluence Data Center on AWS using the Quick Start, your Confluence and Synchrony nodes
will be in auto-scaling groups. You will add and remove nodes in the AWS console either by changing the
minimum and maximum size of each group or using a scaling plan.
Adding a node
To add a node:
1. Copy the installation directory and local home directory from the stopped node to your new node.
2. Start Confluence on your new node.
During the startup process Confluence will recover indexes from a running node to bring the new node up
to date.
3. Go to
> General Configuration > Clustering and check that the new node is visible.
You should only start one node at a time. Starting up multiple nodes simultaneously can cause serious failures.
Removing a node
To remove a node, stop Confluence on that node. You can then remove the installation and local home
directory as required.
To see the number of nodes remaining go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 835
Confluence generates an identifier for each node in your cluster. You can use the confluence.cluster.nod
e.name system property to set the node identifier on each node so that it's easier for your users and
administrators to read.
See Configuring System Properties for more information on how to set the system property.
Change Node Discovery from Multicast to TCP/IP
If you're setting up Confluence Data Center for the first time, it'll step you through the process of choosing your
discovery mode and adding cluster nodes. If you're switching from a multicast configuration to TCP/IP (unicast),
however, you'll need to edit the confluence.cfg.xml file in the local home directory of each cluster node.
Before you make any changes, shut down all nodes in your cluster
Make sure the discovery configuration is exactly the same for each node (make the same
changes to the confluence.cfg.xml file in each local home directory)
The changes you need to make may differ slightly, depending on whether you've upgraded from an older version
of Confluence Data Center or if you've started with version 5.9. We've detailed both methods, below.
If both lines exist in the file, change them to the lines below; where the confluence.cluster.address prope
rty exists, but there's no reference to the confluence.cluster.join.type property, update the first line and
add the second line as shown below.
Enter the address of each node, and separate each address with a comma.
You can now restart your cluster nodes.
To switch from TCP/IP to multicast, just perform the reverse of the changes outlined above.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 836
The simplest way to deploy your entire Data Center cluster in AWS is by using the Quick Start. The Quick
Start launches, configures, and runs the AWS compute, network, storage, and other services required to
deploy a specific workload on AWS, using AWS best practices for security and availability.
Here's an overview of the architecture for the Confluence Data Center Quick Start:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 837
The Quick Start uses c3.xlarge instances by default for Confluence and Synchrony nodes. The instance type
is up to you, but it must meet Confluence's system requirements. Smaller instance types (micro, small,
medium) are generally not adequate for running Confluence.
Not all regions offer the services required to run Confluence. You'll need to choose a region that supports
Amazon Elastic File System (EFS). You can currently deploy Confluence using the Quick Start in the
following regions:
Asia Pacific (Sydney)
EU (Frankfurt)
EU (Ireland)
US East (North Virginia)
US West (Oregon)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 838
The services offered in each region change from time to time, so check the Regional Product Services table
in the AWS documentation to see if your preferred region is supported yet.
1 At the time of writing, these regions did not yet support EFS, so also can't be used to run Confluence.
If you want to deploy an internal facing Confluence site, using your own DNS server, you can use Amazon
Route 53 to create a link between the public DNS and internal DNS.
1. In Route 53, create a hosted zone. The domain name is your preferred domain.
2. If you've already set up Confluence, go to Services > CloudFormation in the AWS console, select
the stack, and click Update Stack. (If you're setting up Confluence for the first time, follow the Quick
Start template as below).
3. Under Other Parameters, enter the domain name of your hosted zone in the Route 53 Hosted Zone
field.
4. Enter your preferred sub-domain or leave the Sub-domain for Hosted Zone field blank and we'll use
your stack name is the sub-domain.
5. Follow the prompts to update the stack. We'll then generate the load balancer and EFS url, and create
a record in Route 53 for each.
6. In Confluence go to
> General Configuration and update the Confluence base URL to your Route 53 domain.
7. Finally, terminate and re-provision each Confluence and Synchrony node to pick up the changes.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 839
Note: Adding new cluster nodes, especially automatically in response to load spikes, is a great
way to increase capacity of a cluster temporarily. Beyond a certain point, adding large numbers of
cluster nodes will bring diminishing returns. In general, increasing the size of each node (i.e.,
"vertical" scaling) will be able to handle a greater sustained capacity than increasing the number
of nodes (i.e., "horizontal" scaling), especially if the nodes themselves are small.
See the AWS documentation for more information on auto scaling groups.
It is possible to SSH to your cluster nodes and file server to perform configuration or maintenance tasks.
Note that you must keep your SSH private key file (the PEM file you downloaded from Amazon and specified
as the Key Name parameter) in a safe place. This is the key to all the nodes in your instance, and if you lose
it you may find yourself locked out.
Note: the ConfluenceDataCenter.template deploys all EC2 instances in the Subnets specified
by the Internal subnets parameter. If you have specified Internal subnets that are completely
unreachable from outside, then you may need to launch an EC2 instance with SSH running and
accessible in one of the the External subnets, and use this as a "jump box" to SSH to any
instances in your Internal subnets. That is, you SSH first to your "jump box", and from there to
any instance deployed in the Internal subnets.
When connecting to your instance over SSH, use ec2-user as the user name, for example:
The ec2-user has sudo access. SSH access is by root is not allowed.
Upgrading
Backing up
We recommend you use the AWS native backup facility, which utilizes snap-shots to back up your
Confluence Data Center.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 840
2.
Database.
3. Back up your PostgreSQL database and your existing <shared-home>/attachments directory.
4. Copy your backup files to /media/atl/confluence/shared-home in your EC2 instance.
5. Restore your PostgreSQL database dump to your RDS instance with pg_restore.
See Importing Data into PostgreSQL on Amazon RDS in Amazon documentation for more information
on how to do this.
Notes:
When you create a cluster using the CloudFormation template, the database name is confluence.
You must maintain this database name when you restore, or there will be problems when new
nodes are provisioned. You will need to drop the new database and replace it with your backup.
You don't need to copy indexes or anything from your existing local home or installation directories,
just the attachments from your existing shared home directory.
If you've modified the <shared-home>/config/cache-settings-overrides.properties file
you may want to reapply your changes in your new environment.
The _copy method described in this AWS page, Importing Data into PostgreSQL on Amazon RDS, is
not suitable for migrating Confluence.
This page contains instructions for installing the Java Development Kit (JDK). This is a manual step that's only
required if you're installing Confluence from a zip or archive file. If you're using the Confluence installer, you do
not need to install Java manually.
Check the Supported Platforms page to find out which Java versions are supported for Confluence.
Installing Java
The JDK (Java Development Kit) needs to be installed on the same server that will have Confluence installed.
We support running Confluence with the JDK or JRE (Java Runtime Environment). These instructions will just
cover installing the JDK.
For Windows: (click to expand)
Before you start, go to Control Panel > Programs and Features to check whether a JDK is already
installed.
To install the JDK on Windows:
1. Download the appropriate JDK version.
Check the Supported Platforms page to find out which JDK / JRE versions are supported for your
version of Confluence.
2. Run the Java installer. Make a note of the installation directory, as you'll need this later.
3. Once the Java installation is complete, check that the JAVA_HOME environment variable has been set
correctly.
Open a command prompt and type echo %JAVA_HOME% and hit Enter.
If you see a path to your Java installation directory, the JAVA_Home environment variable has
been set correctly.
If nothing is displayed, or only %JAVA_HOME% is returned, you'll need to set the JAVA_HOME env
ironment variable manually. See Setting the JAVA_HOME Variable in Windows for a step by
step guide.
For Linux: (click to expand)
Before you start, check whether a JDK is already installed. Open a shell console and type echo
$JAVA_HOME and hit Enter.
If it returns something like /opt/JDK7 or /usr/lib/jvm/java-7, then your JDK is installed and
properly configured.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 841
If nothing is displayed, you'll need to install the JDK or set the $JAVA_HOME environment variable.
You can set this environment variable in your user account's 'profile' file. Alternatively, you can set this
after installing Confluence, by defining this path in your Confluence installation's setenv.sh file,
usually located in the Confluence bin directory.
If you have installed an unsupported JDK and you want to use SSL then you need to install the Sun
JSSE package.
To install the JDK on Linux:
1. Download the appropriate JDK version.
Check the Supported Platforms page to find out which JDK / JRE versions are supported for your
version of Confluence.
2. Run the Java installer. Detailed installation instructions are provided on Oracle's website.
3. Open a shell console and type echo $JAVA_HOME and hit Enter to check that it has installed correctly
(see notes above).
Note: Any Java or JDK version numbers on this page are examples only. Please refer to the Supported
Platforms page for supported versions of Java.
Setting the JAVA_HOME Variable in Windows
After you've installed Java in Windows, you must set the JAVA_HOME envir Related pages
onment variable to point to the Java installation directory.
Starting
Tomcat as
This information is only relevant if you're installing Confluence a Windows
manually on a Windows server. If you're using the installer, we'll do Service
this part for you.
Installing
Confluenc
If you installed the Java Development Kit (JDK) you'll be setting the JAVA_H e in Linux
OME environment variable. If you installed the Java Runtime Environment
(JRE) you will follow the same steps but set the JRE_HOME environment
variable instead.
Set the JAVA_HOME Variable
If you didn't change the path during installation, it'll be something like C:\Program
Files\Java\jdk1.8.0_65
If the path contains spaces, use the shortened path name. For example, C:\Progra~1\Jav
a\jdk1.8.0_65
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 842
This step is optional if you are evaluating Confluence, but should be mandatory for Confluence installations
used in production. If you have used the Confluence installer on Linux, this user will be created automatically.
A dedicated user should be created to run Confluence, because Confluence runs as the user it is invoked under
and therefore can potentially be abused. For example:
If your operating system is *nix-based (for example, Linux or Solaris), type the following in a console:
$ sudo /usr/sbin/useradd --create-home --comment "Account for running
Confluence" --shell /bin/bash confluence
If your operating system is Windows:
1. Create the dedicated user account by either:
Typing the following at the Windows command line:
> net user confluence mypassword /add /comment:"Account for running
Confluence"
(This creates a user account with user name 'confluence' and password 'mypassword'. You
should choose your own password.)
Opening the Windows 'Computer Management' console to add your 'confluence' user with
its own password.
2. (Optional) Use the Windows 'Computer Management' console to remove the 'confluence' user's
membership of all unnecessary Windows groups, such as the default 'Users' group.
If Windows is operating under Microsoft Active Directory, ask your Active Directory
administrator to create your 'confluence' account (with no prior privileges).
Ensure that the following directories can be read and written to by this dedicated user account (e.g.
'confluence'):
The Confluence Installation Directory, particularly these sub-directories:
logs
temp
work
Your Confluence Home directory.
See also Best Practices for Configuring Confluence Security.
Confluence Setup Guide
Before running the Confluence Setup Wizard, as
described below, you should have already
completed installing Confluence.
When you access Confluence in your web browser
for the first time, you will see the Confluence Setup
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 843
In this step, you'll choose whether you want a trial or a production installation.
Trial installation
Set up Confluence with the embedded H2 database, default settings and sample content to get you
started.
You'll need to migrate to a supported external database before using Confluence as a production
system. This option is recommended if you're just taking Confluence for a test drive.
Production installation
Set up Confluence with your own external database. This option is recommended for setting up
Confluence in a production environment.
If you've purchased a license bundle that includes Questions or Team Calendars for Confluence (or if you're
keen to try these add-ons) you can get the setup wizard to install these add-ons automatically - choose the
add-ons you want to automatically install.
Follow the prompts to generate an evaluation license, or enter an existing license key. To retrieve an existing
license key head to my.atlassian.com, or to purchase a new commercial license go to my.atlassian.com/purc
hase.
If you selected a Trial installation in the previous step, Confluence will generate your license and then
create the embedded database. This will take a few minutes. Once complete, go to step 8 below.
If you selected a Production installation, go to the next step to set up your external database.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 844
should not be used for production use. If you choose this option, you'll need to migrate to an external
database later on.
Screenshot: Database configuration
Choose how you want Confluence to connect to your database either via a direct JDBC connection or via a
server-managed datasource connection.
Screenshot: Connection options
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 845
Direct JDBC
This uses a standard JDBC database connection. Connection pooling is handled within Confluence.
Driver Class Name The Java class name for the appropriate database driver. This will depend on
the JDBC driver, and will be found in the documentation for your database. Note that Confluence
bundles some database drivers, but you'll need to install the driver yourself if it is not bundled. See Dat
abase JDBC Drivers for details.
Database URL The JDBC URL for the database you will be connecting to. This will depend on the
JDBC driver, and will be found in the documentation for your database.
User Name and Password A valid username and password that Confluence can use to access your
database.
You will also need to know:
The size of the connection pool Confluence should maintain. If in doubt, just go with the default
provided.
What kind of database you're connecting to, so you can tell Confluence which dialect it needs to
use.
Datasource
This asks your application server (Tomcat) for a database connection. You will need to have configured a
datasource in your application server. For information about configuring an external database, see Database
Configuration.
Datasource Name - The JNDI name of the datasource, as configured in the application server.
Note: Some servers will have JNDI names like jdbc/datasourcename; others will be like java:co
mp/env/jdbc/datasourcename. Check your application server documentation.
We can help you get your new Confluence site started with some demonstration content (which you can
remove once you're up and running), or you can choose to proceed with an empty site. You'll need to create
a space in your new site before you can start adding content.
If you're migrating from another Confluence installation choose Restore from backup to import your existing
Confluence data.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 846
This option allows you to import data from an existing Confluence installation as part of the setup process.
You'll need a manual backup file from your existing Confluence installation to do this (go to Backup and
Restore in the administration console of your existing Confluence site).
Screenshot: restore data options
There are two ways to restore your data - upload the file, or restore from a location on your file system.
Upload a backup file
This option will load the data from a zipped backup file. If your backup file is very large, restoring from
the file system is a better option. Follow the prompts to browse for your backup file. Ensure select Buil
d Index is selected so the search index is generated.
Restore a backup file from the file system
This option is recommended if your backup file is very large (100mb or more), or your backup file is
already on the same server.
Copy your XML backup file into the <confluence-home>/restore directory. Your backup file will
appear in the list. Follow the prompts to restore the backup. Ensure select Build Index is selected so
the search index is generated.
When the restore process has you'll be ready to log in to Confluence. The system administrator account and
all other user data and content has been imported from your previous installation.
You can choose to manage Confluence's users and groups inside Confluence or in a JIRA application, such
as JIRA Software or JIRA Service Desk.
If you do not have a JIRA application installed, or if you would prefer to set up external user
management later, choose Manage users and groups within Confluence.
If you have a JIRA application installed, the setup wizard gives you the opportunity to configure the
JIRA connection automatically. This is a quick way of setting up your JIRA integration with the most
common options. It will configure a JIRA user directory for Confluence, and set up application links
between JIRA and Confluence for easy sharing of data. Choose Connect to JIRA.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 847
Confluence will also use this username and password to create a local administrator account which
will let you access Confluence if JIRA is unavailable. Note that this single account is stored in
Confluence's internal user directory, so if you change the password in JIRA, it will not automatically
update in Confluence.
Confluence Base URL - this is the URL JIRA will use to access your Confluence server. The URL
you give here overrides the base URL specified in Confluence, for the purposes of connecting to the
JIRA application.
User Groups - these are the JIRA groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in your
Confluence license. The default user group name differs depending on your JIRA version:
JIRA 6.4 and earlier: jira-users.
JIRA Software 7.x and later: jira-software-users
JIRA Core 7.x and later: jira-core-users
JIRA Service Desk 3.x and later: jira-servicedesk-users
Admin Groups Specify one or more JIRA groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 848
For full details and a troubleshooting guide, see Configuring JIRA Integration in the Setup Wizard.
The system administrator has full administrative power over your Confluence instance. This person will be
able to add more users, create spaces, and set further Confluence options. Please refer to the overview of
global permissions for more information.
If you've delegated user management to a JIRA application, we'll use the JIRA system administrator account
you specified as Confluence's system administrator account.
That's it, Confluence is ready to go. Click Start to jump straight in to Confluence.
Choose Further Configuration if you want to go directly to the Administration Console and complete
administrator's tasks including configuring a mail server, adding users, changing the base URL and more.
You'll be able to specify exactly which groups in your User Management Limitations and
JIRA app should also be allowed to log in to Recommendations
Confluence. Your license tiers do not need to be the Connecting to Crowd or JIRA for
same for each application. User Management
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 849
Confluence will also use this username and password to create a local administrator account which
will let you access Confluence if JIRA is unavailable. Note that this single account is stored in
Confluence's internal user directory, so if you change the password in JIRA, it will not automatically
update in Confluence.
Confluence Base URL - this is the URL JIRA will use to access your Confluence server. The URL
you give here overrides the base URL specified in Confluence, for the purposes of connecting to the
JIRA application.
User Groups - these are the JIRA groups whose members should be allowed to use Confluence.
Members of these groups will get the 'Can use' permission for Confluence, and will be counted in your
Confluence license. The default user group name differs depending on your JIRA version:
JIRA 6.4 and earlier: jira-users.
JIRA Software 7.x and later: jira-software-users
JIRA Core 7.x and later: jira-core-users
JIRA Service Desk 3.x and later: jira-servicedesk-users
Admin Groups Specify one or more JIRA groups whose members should have administrative
access to Confluence. The default group is jira-administrators. These groups will get the
system administrator and Confluence administrator global permissions in Confluence.
Troubleshooting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 850
If you have trouble connecting Confluence to JIRA, the following troubleshooting information should help you
get up and running.
If no users can log in to Confluence after you've completed the setup process, check that the people are
members of the JIRA groups you specified. Only members of these groups will get the 'Can Use' Confluence
permission.
Failed to create application The setup wizard failed to complete Follow the steps below to remo
link, or registration of the peer-to-peer ve the partial configuration the
application link with JIRA. JIRA n try the Connect to JIRA step
Failed to authenticate integration is only partially configured. again.
application link
Failed to register Confluence The setup wizard failed to complete Follow the steps below to remo
configuration in JIRA for registration of the client-server link ve the partial configuration then
shared user management with JIRA for user management. The try the Connect to JIRA step
peer-to-peer link was successfully again.
created, but integration is only partially
configured.
Error setting Crowd The setup wizard successfully Fix the problem that prevented
authentication established the peer-to-peer link with the application from saving the
JIRA, but could not persist the configuration file to disk then fo
client-server link for user management llow the steps below to remove
in your config.xml file. This may be the partial configuration before
caused by a problem in your trying the Connect to JIRA step
environment, such as a full disk. again.
Error reloading Crowd The setup wizard has completed the Restart Confluence. You
authentication integration of your application with should be able to continue with
JIRA, but is unable to start the setup wizard. If this does
synchronizing the JIRA users with not work, contact Atlassian
your application. Support for help.
java.lang.IllegalStateException: The setup wizard has not completed Follow the steps below to remo
Could not create the the integration of your application with ve the partial configuration and
application in JIRA/Crowd JIRA. The links are only partially resolve any conflict with
(code: 500) configured. The problem occurred existing links then try the
because there is already a user Connect to JIRA step again.
management configuration in JIRA for
this <application> URL.
If you hit a roadblock, you'll need to log in to JIRA and remove the partial integration before you can try again.
The specific steps will differ depending on your JIRA application and version, but the essentials are the same
for all versions:
Log in to JIRA as a user with system administrator permissions.
In the Administrator screens, go to Application Links.
Remove the application link that matches the base URL of your Confluence server.
In the User Management screens, go to JIRA User Server.
Remove the link that matches the name and base URL of your Confluence server from the list of
applications that can use JIRA for user management.
If you have multiple servers running on the same host...
If you're unable to tell which link matches your Confluence server because you have multiple
servers of the same type running on the same host you can check the application ID, which is
listed beside each server.
To find out the application ID of your new Confluence site, go to <baseUrl>/rest/applinks/1
.0/manifest (where <baseurl>is the base URL of your Confluence site). The application ID
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 851
Return to the Confluence setup wizard and try the Connect to JIRA step again.
If you're still unable to connect JIRA and Confluence using the setup wizard, you may need to skip this step
and set up the links between JIRA and Confluence manually once you've completed the Confluence setup
process. See Connecting to Crowd or JIRA for User Management.
Upgrading Confluence
In this guide we'll run you through using the installer On this page:
to upgrade your Confluence site to the latest Before you begin
Confluence version on Windows or Linux. Plan your upgrade
1. Determine your upgrade
Upgrading to any later version is free if you have
path
current software maintenance. See our Licensing
2. Complete the
FAQ to find out more.
pre-upgrade checks
3. Upgrade Confluence in a
test environment
Upgrade Confluence
4. Back up
5. Download Confluence
6. Run the installer
After the upgrade
7. Copy your database
driver
8. Re-apply any
Other ways to upgrade Confluence: modifications
9. Update your reverse
Manually upgrade without using the proxy and check you can
installer. access Confluence
Data Center upgrade your Data Center Troubleshooting
cluster.
XML backups should not be used to upgrade
Confluence.
Before you upgrade Confluence, there's a few questions you need to answer.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 852
> General Configuration > Support Tools and make sure the license support
period has not expired.
If your support period has expired, follow the prompts to renew your license and
reapply it before upgrading.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 853
Use the table below to determine the most efficient upgrade path from your current version to the latest
versions of Confluence.
2.7 or earlier Upgrade to 2.7.4 then upgrade to 3.5.17, and follow paths below.
4.0 to 4.3 Upgrade to 5.10.x then upgrade to the latest version of Confluence 6.
1. Check the Upgrade Notes for the version you plan to upgrade to (and any in between).
2. Go to
> General Configuration > Support Tools to run the health check (available in Confluence 5.5 or
later).
License expired?
If the software maintenance period included in your license has expired you can keep using
Confluence, but you'll need to renew before you can upgrade.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 854
Go to
> General Configuration > License Details and follow the prompts to renew your license.
Still using the embedded database?
If you are using the embedded (trial) database you should migrate to a different database before
upgrading.
This database is supplied for evaluation purposes only and is not recommended for production
environments. See Embedded H2 Database for more information.
Database character encoding incorrect?
Database character encoding must be set to UTF+8 (or AL32UTF8 for Oracle databases). You will
not be able to upgrade to current Confluence versions unless you have the correct character
encoding.
3. Go to
> Add-ons and scroll down to the Confluence Update Check to check the compatibility of your
add-ons.
3. Test any unsupported add-ons, customizations (such as custom theme or layouts) and proxy
configuration (if possible) before upgrading your production environment.
Upgrade Confluence
4. Back up
1. Back up your database and confirm the backup was created properly.
If your database does not support online backups you'll need to stop Confluence first.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 855
This is where your search indexes and attachments are stored. If you store attachments outside
the Confluence Home directory, you should also backup your attachments directory.
5. Download Confluence
Next, run the installer we recommend using sudo to run the installer:
$ sudo ./atlassian-confluence-X.X.X-x64.bin
You can also choose to run the installer with root user privileges.
a. When prompted choose Upgrade an existing Confluence installation (for Linux users this is
option 3).
b. Make sure the Existing Confluence installation directory suggested by the wizard is correct
(especially important if you have multiple Confluence installations on the same machine).
c. Back up Confluence home is strongly recommended. This will create a .zip backup of the
Confluence home and installation directories.
d. The installation wizard notifies you of customizations in the Confluence Installation directory.
Make a note of these as you'll need to reapply them later.
There are some limitations...
The installation wizard's ability to notify you about customizations will depend on how your
existing Confluence instance was installed:
If your current Confluence instance was installed using the installer, the wizard will
check the entire Confluence Installation directory.
If your current Confluence instance was installed manually it will only check the conf
luence subdirectory of the Confluence Installation directory. The installation wizard
will not notify you of modifications in any other directory, for example modifications to
start-up scripts under the bin directory or modifications to the server.xml file
(such as an SSL configuration).
3. The wizard will shut down your Confluence instance and proceed with the upgrade. Once complete, it
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 856
3.
will restart Confluence and you can then launch Confluence in your browser to confirm the upgrade
was successful.
Depending on the size of your instance and the number of upgrade tasks to be run, this step may take
a few minutes or several hours.
If you're using an Oracle or MySQL database, you'll need to copy the jdbc driver jar file from your existing
Confluence installation directory to confluence/WEB-INF/lib in your new installation directory.
During the upgrade the wizard migrated the following from your existing Confluence installation:
TCP port values in your server.xml file.
Location of your Confluence home directory in confluence-init.properties.
All other customizations, including CATALINA_OPTS parameters in your setenv.sh / setenv.bat files, ne
ed to be reapplied manually.
Show me how to do this...
Any other configurations or customizations (including any other modifications in the server.xml file)
are not migrated during the upgrade and need to be reapplied manually.
1. Stop your upgraded Confluence instance.
2. Reapply the customizations to the relevant files in the upgraded Confluence Installation directory.
3. Restart the upgraded Confluence instance.
We strongly recommend you test your customizations in a test instance prior to upgrading your
production instance as changes may have been made to Confluence that make your customizations
unusable.
9. Update your reverse proxy and check you can access Confluence
If you are upgrading from Confluence 5.x to Confluence 6.x you will need to modify your reverse proxy (if
used) to add Synchrony, which is required for collaborative editing. See Proxy and SSL considerations for
more information on the changes you'll need to make to your proxy config.
Once your upgrade is complete, you should access Confluence (via your reverse proxy, not directly) and:
Head to
> General Configuration > Collaborative editing and check the Synchrony status is running.
Edit any page to check that your browser can connect to Synchrony.
See Troubleshooting Collaborative Editing for suggested next steps if Synchrony is not running or you see an
error in the editor, as you may have a misconfigured reverse proxy.
Troubleshooting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 857
[confluence.upgrade.impl.DefaultUpgradeManager] isUpgradeAllowed
Your license is now outside of its support period.
You need to renew the license before you can upgrade to this version
of Confluence.
When you try to access the Confluence site in your browser, you will see the following warning screen:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 858
1. Contact Atlassian Sales to arrange for a new license to be issued, as instructed on the warning screen
illustrated above.
2. Once you have received a suitable license, supply the license key to Confluence:
Click link given on the license warning screen, illustrated above.
You will first be asked to log in as a Confluence administrator.
Then you will be presented with a simplified license administration screen. Enter the credentials
of a Confluence system administrator.
Copy the license key into the License field and choose Save.
This article provides a list of items for Confluence Administrators to check after a Confluence upgrade to ensure
that it has completed successfully. This list is not exhaustive, but it does cover common upgrade mistakes.
After you have completed an upgrade, you should see the following message in the atlassian-confluence.
log file:
Upgrade Checklist
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 859
1. The editor
Edit a page to check your browser can connect to Synchrony, which is required for collaborative editing. See Tro
ubleshooting Collaborative Editing if you are not able to edit a page.
Visit the Confluence dashboard and check that it is accessible and displays as expected. Test the different
Internet browsers that you have in use in your environment. In addition, confirm that the layout appears as
expected and that the menus are clickable and functioning.
3. Search
Try searching for content, for example pages, attachments or user names. Check that the expected results are
returned.
4. Permissions
Confirm that you can visit a page that has view restrictions, but you have permission to view. Confirm that you
can edit a page that has edit restrictions but you have permission to edit. Make sure that the permissions of child
pages are functioning as well. Involve as many space administrators as possible to confirm they are working.
Confirm that anonymous or forbidden users cannot access or modify restricted pages.
5. Attachments
6. Add-ons
Outdated third-party add-ons can cause upgrade failure. Quite often, they will just be incompatible and simply do
not work anymore. If you discover that your add-on is no longer working, please check for the latest version for
your add-on in the The Atlassian Marketplace or check for compatibility in the Universal Plugin Manager.
Migration from Wiki Markup to XHTML-Based Storage Format
If you are upgrading to Confluence 4.0 or later from an older version (From Confluence 3.5.x or earler) then as
part of the upgrade an automatic migration of your content will take place. This is a non-destructive process.
Your existing content is not overwritten. Instead, the migration process will create a new version of each wiki
markup page. The new version will use the new XHTML-based storage format, so that you can edit the page in
the Confluence rich text editor.
In addition, if you are upgrading to Confluence 4.3 or later from an older version then as part of the upgrade
an automatic migration of your page templates will take place. See Migration of Templates from Wiki Markup to
XHTML-Based Storage Format.
Note: Even though the process is non-destructive, you must be sure to perform a backup of your database and
home directory prior to starting the new version of Confluence, as we recommend for any Confluence upgrade.
Migration process
Depending on the size of your Confluence installation, the migration from wiki markup to the new XHTML-based
storage format could prove time consuming. The duration of the migration is difficult to estimate; this is due to a
number of site specific factors. As a rough guide, a test dataset we migrated was 130,000 pages, totalling
approximately 700Mb, which took six minutes.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 860
On this page:
Migration process
Watching the migration logs during the upgrade
Re-running the migration for content that
completely failed the migration
Re-attempting the migration for content in
'unmigrated-wiki-markup' macro
Notes
Related pages:
Migration of Templates from Wiki Markup to
XHTML-Based Storage Format
Upgrading Confluence
The following properties that can be modified to allow finer control over the migration process:
To monitor the progress of a site migration you should watch the output in the application log.
Typical logging progress will be shown by multiple log entries at the INFO level of the following format:
There may be a wide array of messages logged from each individual page but any errors are also collected for
display in a single migration report once all content has been processed. Here is a typical example of such a
report:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 861
Each entry in the report will identify the content that caused migration exceptions as well as displaying the
exceptions themselves.
In almost all cases any content reported as errored will have been migrated to the new XHTML-based storage
format, but will actually consist of wiki markup content wrapped within an XML 'unmigrated-wiki-markup' macro.
This content will still be viewable in Confluence and editable within the new Confluence Editor.
However, in some cases a batch of content may actually have completely failed to migrated. This is most
typically due to an unhandled exception causing a database transaction rollback. This would be reported in the
log with a message like this:
Confluence provides no further report about this scenario and will also allow Confluence to restart as normal
without retrying a migration. If a user tries to view any such unmigrated content they will see an exception similar
to this:
The solution is to ensure you manually re-run the site migration after the restart.
Re-running the migration for content that completely failed the migration
A Confluence Administrator can restart the site migration if there was any content that failed migration (see
previous section). Only the content that is still formatted in wiki markup will be migrated, so typically a
re-migration will take less time than the original migration.
To manually re-run migration:
1. Open this URL in your browser: <Confluence Address>/admin/force-upgrade.action
2. Select wikiToXhtmlMigrationUpgradeTask in the Upgrade task to run dropdown list.
3.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 862
The previous section was about dealing with the exceptional circumstance where certain content was left
completely unmigrated. The most common migration problem is that the content was migrated but remains
formatted as wiki markup on the page, within the body of an 'unmigrated-wiki-markup' macro. Any content which
is referenced in the migration report will be found in this state. This content is still viewable and editable but
since it is wiki markup it cannot be edited using the full feature set of the rich text editor.
The most common reason for content to be in this state is that the page contains an unknown macro, or a macro
that is not compatible with Confluence 4.x.
There are two possible fixes for this situation:
1. Install a version of the macro that is compatible with Confluence 4.x. See Plugin Development Upgrade
FAQ for 4.0 .
2. Edit the page and remove the problematic macro.
Regardless of the solution you choose, you can then force a re-migration of all the content (including content in
templates) that was left wrapped in an 'unmigrated-wiki-markup' macro. This feature is found at <Confluence
Address>/admin/unmigratedcontent.action
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 863
Notes
We refer to the Confluence storage format as 'XHTML-based'. To be correct, we should call it XML, because the
Confluence storage format does not comply with the XHTML definition. In particular, Confluence includes
custom elements for macros and more. We're using the term 'XHTML-based' to indicate that there is a large
proportion of HTML in the storage format.
Migration of Templates from Wiki Markup to XHTML-Based Storage Format
If you are upgrading to Confluence 4.3 or later from an older version (from Confluence 4.2.x or earlier) then
as part of the upgrade an automatic migration of your page templates will take place. This is a non-destructive
process. Your existing content is not overwritten. Instead, the migration process will create a new version of
each space template and each global template on your Confluence site. The new version will use the new
XHTML-based storage format, so that you can edit the template in the Confluence rich text editor.
Note: Nevertheless, you must be sure to perform a backup of your database and home directory prior to starting
the new version of Confluence, as we recommend for any Confluence upgrade.
To monitor the progress of a site migration you should watch the output in the application log.
A typical logging progress will be shown by multiple log entries at the INFO level of the following format:
On this page:
Watching the migration logs during the upgrade
Re-running the migration
Notes
Related pages:
Migration from Wiki Markup to XHTML-Based
Storage Format
Page Templates
Upgrading Confluence
There may be a wide array of messages logged from each individual template, but any errors are also collected
for display in a single migration report once all content has been processed. Here is a typical example of such a
report:
Each entry in the report will identify the content that caused migration exceptions as well as displaying the
exceptions themselves.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 864
In almost all cases any content reported as errored will have been migrated to the new XHTML-based storage
format, but will actually consist of wiki markup content wrapped within an XML 'unmigrated-wiki-markup' macro.
This content will still be viewable in Confluence and editable within the Confluence rich text editor.
However, in some cases a batch of content may actually have completely failed to migrate. This is most typically
due to an unhandled exception causing a database transaction rollback. This would be reported in the log with a
message like this:
Confluence provides no further report about this scenario and will also allow Confluence to restart as normal
without retrying a migration. If a user tries to view or edit an unmigrated template, the wiki template editor will be
used.
The solution is to manually re-run the site migration after the restart, as described below.
A Confluence administrator can restart the template migration if any templates have failed the migration (see
previous section). Only the templates that are still formatted in wiki markup will be migrated again. Typically, a
re-migration will take less time than the original migration.
To manually re-run the migration:
1. Open this URL in your browser: <Confluence Address>/admin/force-upgrade.action
2. Select pageTemplateWikiToXhtmlMigrationUpgradeTask in the Upgrade task to run dropdown list.
3. Choose Force Upgrade.
Screenshot: The 'Force Upgrade' screen in the Confluence administration console
Notes
We refer to the Confluence storage format as 'XHTML-based'. To be correct, we should call it XML, because the
Confluence storage format does not comply with the XHTML definition. In particular, Confluence includes
custom elements for macros and more. We're using the term 'XHTML-based' to indicate that there is a large
proportion of HTML in the storage format.
Upgrading Confluence Manually
In this guide we'll run you through upgrading your
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 865
Before you upgrade Confluence, there's a few questions you need to answer.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 866
> General Configuration > Support Tools and make sure the license support
period has not expired.
If your support period has expired, follow the prompts to renew your license and
reapply it before upgrading.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 867
Use the table below to determine the most efficient upgrade path from your current version to the latest
versions of Confluence.
2.7 or earlier Upgrade to 2.7.4 then upgrade to 3.5.17, and follow paths below.
4.0 to 4.3 Upgrade to 5.10.x then upgrade to the latest version of Confluence 6.
1. Check the Upgrade Notes for the version you plan to upgrade to (and any in between).
2. Go to
> General Configuration > Support Tools to run the health check (available in Confluence 5.5 or
later).
License expired?
If the software maintenance period included in your license has expired you can keep using
Confluence, but you'll need to renew before you can upgrade.
Go to
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 868
> General Configuration > License Details and follow the prompts to renew your license.
Still using the embedded database?
If you are using the embedded (trial) database you should migrate to a different database before
upgrading.
This database is supplied for evaluation purposes only and is not recommended for production
environments. See Embedded H2 Database for more information.
Database character encoding incorrect?
Database character encoding must be set to UTF+8 (or AL32UTF8 for Oracle databases). You will
not be able to upgrade to current Confluence versions unless you have the correct character
encoding.
3. Go to
> Add-ons and scroll down to the Confluence Update Check to check the compatibility of your
add-ons.
3. Test any unsupported add-ons, customizations (such as custom theme or layouts) and proxy
configuration (if possible) before upgrading your production environment.
Upgrade Confluence
4. Back up
1. Back up your database and confirm the backup was created properly.
If your database does not support online backups you'll need to stop Confluence first.
This is where your search indexes and attachments are stored. If you store attachments outside
the Confluence Home directory, you should also backup your attachments directory.
5. Download Confluence
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 869
1. Stop Confluence.
2. Extract (unzip) the files to a directory (this is your new installation directory, and must be different to
your existing installation directory)
Note: There are some known issues with unzipping the archive on Windows. We recommend using
7Zip or Winzip.
3. Edit <Installation-Directory>\confluence\WEB-INF\classes\confluence-init.pro
perties file to point to your existing Confluence home directory.
4. Copy your jdbc driver jar file from your existing Confluence installation directory to confluence/WEB
-INF/lib in your new installation directory.
5. There are some additional steps you make need to take if:
you are running Confluence as a Windows Service
Click here to expand...
If you are running Confluence as a Windows service, go to the command prompt and type:
<Installation-Directory>\bin\service.bat remove
Confluence
It is vital that you stop and remove the existing service prior to uninstalling the old instance
of Confluence. For more information on running Confluence as Windows service, please
refer to Start Confluence Automatically on Windows as a Service.
To remove the service installed by the Confluence installer, you'll need to run <conflue
nce auto installer installation folder>\UninstallService.bat.
6. Start your new Confluence. You should not see the setup wizard.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 870
If you have customized Confluence (such as an SSL configuration in the server.xml file, or CATALINA_OP
TS or JAVA_OPTS parameters in your confluence-init.properties file), you'll need to perform the
following steps after the upgrade is complete:
1. Stop your upgraded Confluence instance.
2. Reapply the customizations to the relevant files in the newly upgraded Confluence Installation
directory.
3. Restart the upgraded Confluence instance.
We strongly recommend you test your customizations in a test instance prior to upgrading your production
instance as changes may have been made to Confluence that make your customizations unsuable.
8. Update your reverse proxy and check you can access Confluence
If you are upgrading from Confluence 5.x to Confluence 6.x you will need to modify your reverse proxy (if
used) to add Synchrony, which is required for collaborative editing. See Proxy and SSL considerations for
more information on the changes you'll need to make to your proxy config.
Once your upgrade is complete, you should access Confluence (via your reverse proxy, not directly) and:
Head to
> General Configuration > Collaborative editing and check the Synchrony status is running.
Edit any page to check that your browser can connect to Synchrony.
See Troubleshooting Collaborative Editing for suggested next steps if Synchrony is not running or you see an
error in the editor, as you may have a misconfigured reverse proxy.
Troubleshooting
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 871
Your staging environment should closely replicate your real-live environment (production), including any
reverse proxies, SSL configuration, or load balancer (for Data Center). You may decide to use a different
physical server or a virtualized solution. The main thing is to make sure it is an appropriate replica of your
production environment.
For the purposes of these instructions, we assume your staging environment is physically separate from your
production environment, and has the same operating system (and Java version if you've installed Confluence
manually).
3 Replicate Confluence
To replicate Confluence, make a copy of your Confluence installation and point it to your staging database.
These instructions are for Confluence Server (for Data Center there are some additional steps before you
start Confluence).
1. Copy your entire production installation directory to your staging server.
2. Copy your entire production home directory to your staging server.
3. Edit <installation-directory>/confluence/WEB-INF/classes/confluence-init.pro
perties to point to your staging home directory.
4. Edit <home-directory>/confluence.cfg.xml or <installation-directory>/server.xm
l to point to your staging database.
If you're using a direct JDBC connection, the line you need to update in confluence.cfg.xml will look
something like this...
<property
name="hibernate.connection.url">jdbc:postgresql://localhost:54
32/confluencestaging</property>
If you're using a datasource connection, the lines you need to update in server.xml will look
something like this...
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 872
5. Start Confluence with the following System Properties to make sure your staging site does not send
notifications to real users.
-Datlassian.notifications.disabled=true
-Datlassian.mail.senddisabled=true
> General Configuration and change the base URL of your staging site (for example mysite.stag
ing.com)
8. Go to
> General Configuration > License Details and apply your development license.
9. Go to
> General Configuration > System Information and check that Confluence is correctly pointing to
your staging database, and staging home directory.
It's essential to check that you are not still connected to your production database.
If you have Confluence Data Center, the process is much the same as for Confluence Server described
above. You will copy each local home and installation directory to each staging node, and then:
1. Copy the production shared home directory to the staging server.
2. Edit<local-home-directory>/confluence.cfg.xml to point to your staging shared home
directory. This change must be made on every staging node.
Changes to the <installation-directory>/confluence/WEB-INF/classes/confluence-init.
properties and <home-directory>/confluence.cfg.xml must be made on every staging node.
When it comes time to start Confluence, start one node at a time, as usual.
If you're managing users in JIRA, Crowd, or in an external LDAP directory you can:
replicate JIRA, Crowd, or your external directory in your staging environment and point your
Confluence staging site to your staging external directory (recommended).
provide your staging server with network or local access to the same hosts as your production server.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 873
If you have application links between Confluence and other Atlassian applications you should change the
server ID on each staging application. See How to change the server ID of Confluence and Changing Server
ID for Test Installations for JIRA.
If you don't change the server ID and update your application links there is a chance that when you create a
new application link in production it will point to your staging server instead.
Once you have created your staging environment, you can upgrade it in the same way you would your
production environment.
Make a note of how long the upgrade takes, as this information will help you plan your production system
outage and communicate with your users.
You can also use your staging environment to test any customizations or essential add-ons in your site.
Supported Platforms
This page describes the additional software and infrastructure you'll need to On this page:
run Confluence. Please review this info before installing Confluence. The
information on this page applies to Confluence 6.4. Browsers
Operating
You should only use Confluence with a supported platform. Any systems
platforms and versions not listed on this page are unsupported, which Databases
means we don't test, fix bugs or provide assistance. Java
See End of Support Announcements for Confluence for upcoming Infrastruct
changes to supported platforms. ure
Go to
Related pages:
> General Configuration > Support Tools to check your instance
health. It looks at things like your license validity, Tomcat version, Confluenc
basic database setup and more. e
Installation
Definitions: Guide
Supported - you can use Confluence 6.4 with this platform. Confluenc
e Setup
Limited - you can evaluate Confluence on this platform, but you can't use Guide
it to run a production Confluence site.
Server
Deprecated - support for this platform will end in an upcoming release. Hardware
Requireme
nts Guide
Supported
Platforms
FAQ
Browsers
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 874
Operating systems
Databases
Java
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 875
Infrastructure
Hardware:
You can't run Confluence on SPARC based hardware. You'll need to use x86 hardware or 64bit
derivatives of x86 hardware.
You can't use an NFS mount for your installation or home directory due to Lucene requirements. If
you're installing Confluence Data Center, an NFS mount is fine for the shared home directory, but not
for the local home directories.
Virtualization:
Our support team can assist you with problems running Confluence in a Docker container, but can't
offer support for problems related to the environment itself.
Our support team can assist you with deploying Confluence Data Center in AWS using the Cloud
Formation Template or Quick Start. We won't be able to assist you if you have customised the Cloud
Formation Template.
Application server:
We only support the Tomcat version that is bundled with your Confluence version. You can't run
Confluence in your own application server.
For more information see our Server Hardware Requirements Guide and System Requirements.
This page is where we announce end of support for various platforms, browsers, and information on features
that will be discontinued in Confluence Server.
The table below summarizes the end of support announcements for upcoming Confluence releases. If a
platform (or version) has already reached its end of support date, it is not listed in the table.
jTDS driver for SQL Server With the release of Confluence 6.6 (announcement)
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 876
We are replacing the open source jTDS driver for SQL Server with the official Microsoft JDBC Driver for SQL
Server. This new driver is bundled with Confluence 6.4 and later.
Atlassian will end support for the jTDS driver in Confluence 6.6. End of support means that Atlassian will not
offer support for, or fix bugs related to, installing and running Confluence 6.6 or later with this driver.
Confluence 6.5.x will be the last major release to bundle the jTDS driver.
Confluence 6.5.x and earlier versions will continue to be supported with the jTDS driver, until their support
end date.
Confluence 6.6.x will not bundle or support the jTDS driver. We'll provide plenty of information on how to
migrate to the new driver at that time.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.
Atlassian will end support for the Oracle Solaris operating system in Confluence 6.3. End of support means
that Atlassian will not offer support for, or fix bugs related to, installing and running Confluence 6.3 or later on
this operating system.
Confluence 6.2.x will be the last major release that can be installed on Solaris.
Confluence 6.2.x and earlier versions will continue to be supported on Solaris, until their support end
date.
Check out the Supported Platforms page for the full list of supported operating systems.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.
Atlassian will end support for the default browser provided with Android 4.0.3 (Ice Cream Sandwich) in
Confluence 6.0. End of support means that Atlassian will not fix bugs related to this browser past the support
end date, except for security related issues. This means:
Confluence 5.10 will be the last major release that supports the default browser provided with
Android 4.0.3 (Ice Cream Sandwich).
Confluence 5.10.x and earlier versions will continue to work on the default browser provided with
Android 4.0.3 (Ice Cream Sandwich).
With the release of Confluence 6.0 we have added support for the default browser provided with current Android
versions from 4.4 (KitKat) and later. Check out the Supported Platforms page for the full list of supported
browsers.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 877
To help us bring you new Confluence Server releases faster, we are considering only providing 64-bit installers.
Confluence 5.10 would be the last Confluence release to provide a 32-bit installer.
Q: Can I upgrade using the 64-bit installer?
Yes. If you installed Confluence using the 32-bit installer on a 64-bit operating system, you will be able to
upgrade using the 64-bit installer.
Q: What if I am not able to use the 64-bit installer?
We'd love to hear from you to better understand how this change would impact you. Comment on this issue
CONFSERVER-42817 - Planned deprecation of 32-bit installers
RESOLVED or contact us directly at eol-announc
ement at atlassian dot com.
Atlassian will end support for Internet Explorer 10 in Confluence 6.0. End of support means that Atlassian will not
fix bugs related to Internet Explorer 10 past the support end date, except for security related issues.
This change allows us to use more modern browser technologies to give you the best user experience in
Confluence. Check out the Supported Platforms page for the full list of supported browsers.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.
Confluence 5.10 will be the last major release that supports Internet Explorer 10.
Confluence 5.10.x and earlier versions will continue to work on Internet Explorer 10.
No Confluence releases after 5.10.x will be tested with Internet Explorer 10.
This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcement
at atlassian dot com.
Notes:
Confluence 5.10 is the last version that will support MySQL 5.5.
Confluence 5.10 and previously-released versions will continue to work with the database version listed
above, however we will not fix bugs affecting these databases after the end-of-life date for your version of
Confluence.
No Confluence releases after 5.10.x will be tested with the database listed above.
With the release of Confluence 5.9 we will be ending support for the following macros, known collectively as the
'View File' macros:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 878
Office Excel
Office Word
Office PowerPoint
PDF
End of support means that Atlassian will not fix bugs related to these macros past the support end date for your
version of Confluence. We plan to remove these macros in a future Confluence release, and will provide plenty
of information to help you make the transition when the time comes.
The View File macros will still be available in future Confluence releases (including Confluence 5.9, 5.10 and
later), but we recommend inserting Office and PDF files as a thumbnail or link, and using the preview to view the
file in full, as it provides a much better way to display Office and PDF files on your pages. See Display Files and
Images for more info.
If you have any questions or concerns, please comment on this issue
CONFSERVER-39829 - Plans to remove the view file macros
OPEN
Status updates
As part of our work to make Confluence simpler and easier to use we've decided to remove the Status Updates
feature in Confluence 5.9. This includes the ability to:
update your status
see other people's status via their profile or the User Status List macro.
Our research tells us that this feature isn't widely used, and we believe that HipChat gives your team much
better ways to share their status.
We'll provide more information at the time of the Confluence 5.9 release. If you have questions or concerns,
CONFSERVER-38253 - Plans to remove status updates
please comment on this issue RESOLVED .
Documentation theme
In order to better focus our development efforts on a single theme, we plan to remove the Documentation theme
in Confluence 6.0.
We know that many customers use the Documentation theme because they like to have a page tree in their
space sidebar. This has been available in the default theme for some time now, plus other great features like
sidebar shortcuts, JIRA links, and sticky table headers.
To help you switch to the more modern default theme, we've added some of your favorite documentation theme
features, including the ability to add:
a header and footer
custom content to the sidebar.
These new additions to the default theme are available in Confluence 5.9. As these fields will continue to use
wiki markup, you will be able to drop your existing wiki markup straight from the Documentation theme into the
default theme.
To help you switch themes we've put together a step-by-step guide which covers everything from how to turn on
the default theme, find out which spaces are using the theme, and what to do if the Documentation theme is the
global theme for your whole site.
If you have any questions or concerns please comment on this issue
CONFSERVER-38256 - Plans to remove the documentation theme
RESOLVED .
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 879
This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Oracle 11.2
Notes:
Confluence 5.8 is the last version that will support the database versions listed above.
Confluence 5.8 and previously-released versions will continue to work with the database versions listed
above, however we will not fix bugs affecting these databases after the end-of-life date for your version of
Confluence.
No Confluence releases after 5.8.x will be tested with the databases listed above.
This section announces the end of Atlassian support for Tomcat 7.0.x for Confluence. As previously announced,
we now only support the version of Tomcat that is bundled with your version of Confluence.
End of support means that Atlassian will not fix bugs related to the specified version of Tomcat, past the support
end date for your version of Confluence. If you have questions or concerns regarding this announcement, please
email eol-announcement at atlassian dot com.
Atlassian will end support for Internet Explorer 9 in the next major release after Confluence 5.8.x. End of support
means that Atlassian will not fix bugs related to Internet Explorer 9 past the support end date, except for security
related issues.
This change allows us to use more modern browser technologies to give you the best user experience in
Confluence. Check out the Supported Platforms page for the full list of supported browsers.
If you have questions or concerns regarding this announcement, please email eol-announcement at atlassian
dot com.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 880
Internet Explorer 9 (IE9) End of Support Notes
Confluence 5.8 will be the last major release that supports Internet Explorer 9
Confluence 5.8.x and earlier versions will continue to work on Internet Explorer 9
No Confluence releases after 5.8.x will be tested with Internet Explorer 9
This section announces the end of Atlassian support for Java 7 for Confluence. Please note that Oracle is
planning to stop providing public updates for JRE 7 in April 2015.
End of support means that Atlassian will not fix bugs related to the specified version of Java, past the support
end date for your version of Confluence. The details are below. Please refer to the list of supported platforms fo
r details of platform support for Confluence. If you have questions or concerns regarding this announcement,
please email eol-announcement at atlassian dot com.
Java 7 notes:
Confluence 5.7 is the last major version that will support Java 7. The Confluence 5.7.x bug-fix releases
will also continue to support Java 7.
Java 7 (JRE and JDK 1.7) will still be supported in Confluence 5.7.
Confluence 5.7.x and previously-released versions will continue to work with Java 7, but we will not fix
bugs affecting Java 7 after the end-of-life date for your version of Confluence.
Confluence 5.8 will not be tested with Java 7.
To help us to make Confluence a more robust and scalable application, we have decided to stop providing an
EAR/WAR distribution. This means that the only supported application server will be will be the version of
Tomcat that is bundled with each release.
Confluence 5.6 will be the last Confluence release to provide an EAR/WAR edition.
Q: Do I need to use the installer?
No, the removal of the EAR/WAR distribution does not force you to use the installer. You can still use the
standalone distribution, which doesn't have an install script - it's just a copy of Tomcat with Confluence
configured inside it. Essentially it's a directory that you unpack and then run yourself.
Q: What if a security problem is found in the bundled version of Tomcat?
Our security team monitors vulnerabilities in all our dependencies, including Tomcat, and fixes continue to follow
our Security Bugfix Policy. If at any time you become aware of a vulnerability we've missed, please report it as
described in How to report a security issue.
If you have more questions or concerns regarding this announcement, please contact us at eol-announcemen
t at atlassian dot com.
This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 881
PostgreSQL 8.4
PostgreSQL 9.0
With the release of Confluence 5.7
PostgreSQL 9.1
MySQL 5.1
Notes:
Confluence 5.6 is the last version that will support the database versions listed above.
Confluence 5.6 and previously-released versions will continue to work with the database versions listed
above, however we will not fix bugs affecting these databases after the end-of-life date for your version
of Confluence.
Confluence 5.7 has not been tested with the databases listed above.
This section announces the end of Atlassian support for Tomcat 6.0.x for Confluence.
End of support means that Atlassian will not fix bugs related to the specified version of Tomcat, past the
support end date for your version of Confluence. The details are below. Please refer to the list of supported
platforms for details of platform support for Confluence. If you have questions or concerns regarding this
announcement, please email eol-announcement at atlassian dot com.
This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 882
Confluence 5.4 is the last version that will support PostgreSQL 8.3.
Confluence 5.4 and previously-released versions will continue to work with PostgreSQL 8.3. However,
we will not fix bugs affecting PostgreSQL 8.3 after the end-of-life date for your version of Confluence.
Confluence 5.5 will not be tested with PostgreSQL 8.3.
To allow us to dedicate resources to providing the best experience on modern browsers, Confluence 5.5
will be the last release that supports Internet Explorer 8 (IE8). The reasons behind this decision are to
enable us to provide the best user experience to our customers, accelerate our pace of innovation and give
us the ability to utilize modern browser technologies.
End of support means that Atlassian will not perform any maintenance on Confluence related to IE8 after
the final release of Confluence 5.5.x, except for security related issues. In order to minimize the impact on
you and the way your company uses Confluence, we have provided this announcement as early as
possible, and hope that the subsequent 6 month period will give you adequate time to prepare for this
change without disruption.
Atlassian will continue to support Internet Explorer 9 (IE9) and Internet Explorer 10 (IE10) as well as the
latest versions of Chrome, Firefox and Safari. For further information, please refer to the Supported
Platforms page. If you have questions or concerns regarding this announcement, please email
eol-announcement at atlassian dot com.
This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
This section announces the end of Atlassian support for Tomcat 5.5.x for Confluence. Please note: Apache
have announced that support for Apache Tomcat 5.5.x will end on 30 September 2012: End of life for Apache
Tomcat 5.5.x.
End of support means that Atlassian will not fix bugs related to the specified version of Tomcat, past the
support end date for your version of Confluence. The details are below. Please refer to the list of supported
platforms for details of platform support for Confluence. If you have questions or concerns regarding this
announcement, please email eol-announcement at atlassian dot com.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 883
This section announces the end of Atlassian support for Java 6 for Confluence. Please note that Oracle has
announced the end of public updates for Java 6: Java SE 6 End of Public Updates Notice.
End of support means that Atlassian will not fix bugs related to the specified version of Java, past the support
end date for your version of Confluence. The details are below. Please refer to the list of supported platforms fo
r details of platform support for Confluence. If you have questions or concerns regarding this announcement,
please email eol-announcement at atlassian dot com.
Java 6 (JRE and JDK 1.6) When Confluence 5.0 is released, due in early 2013
Java 6 notes:
Confluence 4.3 is the last major version that will support Java 6. The Confluence 4.3.x bug-fix releases
will also continue to support Java 6.
Java 7 (JRE and JDK 1.7) will still be supported in Confluence 5.0.
Confluence 4.3.x and previously-released versions will continue to work with Java 6. However, we will
not fix bugs affecting Java 6 after the end-of-life date for your version of Confluence.
Confluence 5.0 will not be tested with Java 6.
This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 884
we will not fix bugs affecting PostgreSQL 8.2 after the end-of-life date for your version of Confluence.
Confluence 4.3 will not be tested with PostgreSQL 8.2.
This section announces the end of Atlassian support for certain databases for Confluence. End of support
means that Atlassian will not fix bugs related to the specified database past the support end date for your
version of Confluence.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
DB2 notes:
Confluence 4.2 is the last version that will support DB2.
From Confluence 4.3, no versions of DB2 will be supported.
Confluence 4.2 and previously-released versions will continue to work with DB2. However, we will not fix
bugs affecting DB2 after the end-of-life date for your version of Confluence.
Confluence 4.3 will not be tested with DB2.
For help with moving from DB2 to a supported database, please refer to the list of supported databases
and the guide to migrating to another database.
This section announces the end of Atlassian support for certain operating systems for Confluence. End of
support means that Atlassian will not fix bugs related to running Confluence server on that operating system
past the support end date.
We will stop supporting the following operating systems from Confluence 4.0, due in late 2011:
Mac OS X (as a Confluence server platform).
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Mac OS X (as a Confluence server platform) When Confluence 4.0 releases, due in late 2011
Mac OS X Notes:
Atlassian intends to end support for Mac OS X (as a server platform) in Confluence 4.0 (due for
release in late 2011). Confluence 3.5 is the last version that will support Mac OS X.
The Sun/Oracle JDK/JRE 1.6 is the only JDK platform officially supported by Atlassian. This
means that Apple Mac OS X is not a supported operating system for the Confluence server, as
the Sun/Oracle JDK does not run on Mac OS X.
Accessing Confluence as a user from Mac OS X via a compatible web browser will still be
supported for the forseeable future.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 885
This section announces the end of Atlassian support for certain database versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain database versions past the support end date.
We will stop supporting the following database versions from Confluence 4.0, due in late 2011:
MySQL 5.0.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
MySQL (version 5.0 only) When Confluence 4.0 releases, due in late 2011
MySQL Notes:
Atlassian intends to end support for MySQL 5.0 in Confluence 4.0 (due for release in the middle
of 2011). Confluence 3.5 is the last version that will support MySQL 5.0.
MySQL 5.1 will still be supported.
'Support End Date' means that Confluence 3.5 and previously released versions will continue to
work with MySQL 5.0. However, we will not fix bugs affecting MySQL 5.0 past the support end
date.
Confluence 4.0 will not be tested with MySQL 5.0.
This section announces the end of Atlassian support for certain web browser versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain web browser versions past the support end
date.
We will stop supporting the following web browser versions from Confluence 4.0, late middle of 2011:
Microsoft Internet Explorer 7 (IE7).
Safari 4.
Firefox 3.5.
The details are below. Please refer to the list of supported platforms for details of platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Microsoft Internet Explorer (version 7 only) When Confluence 4.0 releases, late the middle of 2011
Safari (version 4 only) When Confluence 4.0 releases, due in late of 2011
Firefox (version 3.5 only) When Confluence 4.0 releases, due in late of 2011
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 886
Safari Notes:
Atlassian will introduce support for Safari 5 in Confluence 3.5.
We intend to end support for Safari 4 in Confluence 4.0 (due for release in the middle of 2011).
Confluence 3.5 is the last version that will support Safari 4.
'Support End Date' means that Confluence 3.5 and previously released versions will continue to
work with Safari 4. However, we will not fix bugs affecting Safari 4 past the support end date.
Confluence 4.0 will not be tested with Safari 4.
Firefox Notes:
Atlassian will end support for Firefox 3.0 in Confluence 3.5, as previously announced.
We intend to end support for Firefox 3.5 in Confluence 4.0 (due for release in the middle of 2011).
Confluence 3.5 is the last version that will support Firefox 3.5.
Firefox 3.6 will still be supported.
'Support End Date' means that Confluence 3.5 and previously released versions will continue to
work with Firefox 3.5. However, we will not fix bugs affecting Firefox 3.5 past the support end
date.
Confluence 4.0 will not be tested with Firefox 3.5.
This section announces the end of Atlassian support for certain database versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain database versions past the support end date.
We will stop supporting the following database versions:
From Confluence 3.5, due in the first half of 2011, Confluence will no longer support PostgreSQL 8.1.
Note, PostgreSQL 8.2 and PostgreSQL 8.4 will still be supported.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
PostgreSQL (version 8.1 only) When Confluence 3.5 releases, due in the first half of 2011
This section announces the end of Atlassian support for certain web browser versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain web browser versions past the support end
date.
We will stop supporting the following web browser versions:
From Confluence 3.5, due in the first half of 2011, Confluence will no longer support Firefox 3.0.
Note, Firefox 3.5 and Firefox 3.6 will still be supported.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 887
End of Life Announcement for Web Browser Support
Firefox (version 3.0 only) When Confluence 3.5 releases, due in the first half of 2011
This section announces the end of Atlassian support for certain database versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain database versions past the support end date.
We will stop supporting the following database versions:
From Confluence 3.4, due in the second half of 2010, Confluence will no longer support Oracle 10g (i.e.
Oracle 10.1 and Oracle 10.2).
Note, Oracle 11g (i.e. Oracle 11.1 and Oracle 11.2) will still be supported.
We have made these decisions in line with Oracle's decision to stop support for Oracle 10g, as per the "Oracle
Database (RDBMS) Releases Support Status Summary [ID 161818.1]" article on the Oracle Support site (note,
you will need an Oracle Support account to find and view the article). This also will reduce the testing time
required for each release and help us speed up our ability to deliver market-driven features. We are committed
to helping our customers understand this decision and assist them in upgrading to Oracle 11g if needed.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Oracle (version 10.1 and 10.2 only) When Confluence 3.4 releases, due in the second half of 2010
This section announces the end of Atlassian support for certain web browser versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain web browser versions past the support end
date.
We will stop supporting the following web browser versions:
From Confluence 3.4, due in the second half of 2010, Confluence will no longer support Safari 3 or
Safari 3.1.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 888
Safari (version 3 and 3.1 only) When Confluence 3.4 releases, due in the second half of 2010
This section announces the end of Atlassian support for certain database versions for Confluence. End of
support means that Atlassian will not fix bugs related to certain database versions past the support end date.
We will stop supporting the following database versions:
From Confluence 3.3, due in Q3 2010, Confluence will no longer support DB2 8.2.
Note, DB2 9.7 will still be supported.
We are reducing our database support to reduce the amount of testing time and help us speed up our ability to
deliver market-driven features. We are committed to helping our customers understand this decision and assist
them in upgrading to DB2 9.7 if needed.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
DB2 (version 8.2 only) When Confluence 3.3 releases, due Q3 2010
This section announces the end of Atlassian support for certain application servers for Confluence. End of
support means that Atlassian will not fix bugs related to certain application servers past the support end date.
We will stop supporting the following application servers:
From Confluence 3.2, due late Q1 2010, Confluence will no longer support JBoss application servers.
From Confluence 3.3, due in Q3 2010, Confluence will no longer support Oracle WebLogic, IBM
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 889
Caucho Resin 3.0, 3.1.6, 3.1.7 When Confluence 3.3 releases, due Q3 2010
We have chosen to standardize on Tomcat, because it is the most widely used application server in our user
population. It is fast, robust, secure, well-documented, easy to operate, open source, and has a huge
community driving improvements. It is the de facto industry standard, with several companies available that
specialize in providing enterprise grade support contracts for it, ranging from customizations to 24/7 support.
This section announces the end of Atlassian support for certain Java Platforms for Confluence.
We will stop supporting the following Java Platforms:
From Confluence 3.3, due Q3 2010, support for Java Platform 5 (JDK/JRE 1.5) will end.
We are ending support for Java Platform 5, in line with the Java SE Support Roadmap (i.e. "End of Service
Life" for Java Platform 5 dated October 30, 2009). We are committed to helping our customers understand this
decision and assist them in updating to Java Platform 6, our supported Java Platform.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 890
Java Platform 5 (JDK/JRE 1.5) When Confluence 3.3 releases, due Q3 2010
This section announces the end of Atlassian support for certain web browsers for Confluence.
We will stop supporting older versions of web browsers as follows:
From Confluence 3.2, due late Q1 2010, support for Firefox 2 and Safari 2 will end.
From 13 July 2010, in line with Microsoft's Support Lifecycle policy, support for IE6 will end.
The details are below. Please refer to the Supported Platforms for more details regarding platform support for
Confluence. If you have questions or concerns regarding this announcement, please email eol-announcemen
t at atlassian dot com.
Internet Explorer 6 When Confluence 3.3 releases (target Q3 2010) or 13 July 2010, whichever is sooner
Q: How does Atlassian choose which JRE versions, application servers and databases to support?
For application servers and databases, we try to pick a good cross-section of open source options and popular
commercial platforms. We then choose which JRE versions to support based on the recommended
environments for these servers.
Q: What is a supported platform?
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 891
To transfer Confluence to another server you will copy the home and install folders straight into an identical
external database and user management setup. If your new server is using a different operating system there
may be some additional changes at step 4.
1. Run the Confluence installer on your new server
2. Shut down Confluence on both your old and new servers
3. If you're using Oracle or MySQL, copy the drivers from your old server to the new one
4. Delete the contents of the home directory on your new Confluence server, then copy in the contents of
the home directory from your old Confluence server.
5. Make any additional changes required for your environment.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 892
<property
name="attachments.dir">${confluenceHome}/attachments</property
>
<property
name="lucene.index.dir">${localHome}/index</property>
<property
name="webwork.multipart.saveDir">${localHome}/temp</property>
If you're migrating from Linux to Windows, you'll need to replace the forward slashes with
backslashes in the following lines in confluence.cfg.xml:
<property
name="attachments.dir">${confluenceHome}\attachments</property
>
<property
name="lucene.index.dir">${localHome}\index</property>
<property
name="webwork.multipart.saveDir">${localHome}\temp</property>
6. Copy the <confluence-install>/conf/server.xml file from your old server to the same
location on your new server
7. If you use a data source, ensure the data source points to the new database. See Configuring a
datasource connection.
8. Start Confluence, then head to General configuration > License Details to add your license key
We strongly recommend you perform a rebuild of your content indices after performing a migration, to
ensure Confluence search works as expected.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 893
If you have already set up an evaluation Confluence site, you can skip this step.
Below is a summary of the installation and setup procedure, focusing on the choice of database.
To install Confluence:
1. Download the installer from the Confluence download site.
Note: If you are using a Mac or another unsupported platform for your evaluation, you will need to
install from a zip file. Details are in the full installation guide.
2. Run the installer and choose the express or custom installation. If you are not sure, choose Express
Install.
The express option will install Confluence with default settings.
The custom option allows you to choose the Confluence installation directory, home (data)
directory, ports and other options.
3. When prompted, choose the option to open Confluence in your browser, where you can complete
the setup.
To set up Confluence, including the database:
1. Follow the prompts in the browser-based setup wizard, to get your Confluence license.
2. Choose the Trial or Production installation type. If you are not sure, choose Trial Installation.
The Trial option will install Confluence with default settings, including the embedded database
which is automatically set up for you. You'll need to migrate to an external database before
running Confluence in a production environment (more info below).
If you have finished evaluating Confluence, you can skip this step.
Depending on your choices during the Confluence setup, your evaluation site may include sample content.
The example pages, blog posts and attachments are in the 'Demonstration space'. This space is present if:
You chose the 'Trial Installation' during setup.
Or you chose the 'Production Installation', then chose to include the 'Example Site'.
You can update the sample content, and create more of your own. You can also invite people to join you on
the site.
When you move to a production site, you can choose to copy the content and users to the new site.
To create content in your evaluation site:
Choose Spaces > Create Space to add a space, which is like a library of pages.
Choose Create to add pages and blog posts.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 894
If you have finished evaluating Confluence, you can skip this step.
Add-ons, also called plugins, provide additional features that you can install into your Confluence site. Some
of them are provided free of charge. Many of the commercial add-ons are available free for an evaluation
period.
You can browse and download add-ons on the Atlassian Marketplace. You can also find add-ons via the
Confluence user interface, which interacts with the Atlassian Marketplace for you.
To find useful add-ons via the Confluence user interface:
1. Choose the cog icon
When you are ready to move from an evaluation site to a production site, you need to migrate to a
production-ready database. This involves installing a new Confluence site with a new database, and
instructing Confluence to copy the data from your evaluation site to the new site. You will also need to check
some important configuration settings, and define your backup strategy. The instructions below lead you
through all the steps required.
Migrating your data to a production database:
1. Choose a database carefully, with a focus on reliability and backups. See our list of supported
databases. If you are unsure which one to choose, we recommend PostgreSQL.
2. Install a new database and a new Confluence site, by following our guide to migrating to another
database. The guide will lead you through the following steps:
Setting up your database server.
Adding a Confluence database (schema) to your database server.
Installing a new, production-ready Confluence site.
Copying your Confluence data from your evaluation site to your new production site.
Setting important configuration options on your production site:
Set the base URL. See Configuring the Server Base URL.
Make sure you have configured an email server. See Configuring a Server for Outgoing Mail.
Decide on proxy setup and other settings that determine where Confluence fits into your network. See
Web Server Configuration.
Consider setting up a secure connection via SSL. See Running Confluence Over SSL or HTTPS.
Read our guidelines on security. See Best Practices for Configuring Confluence Security.
Decide whether you will manage your users in Confluence or connect to an external LDAP directory.
See Configuring User Directories.
Decide whether you want to allow public (anonymous) access to your site. See Setting Up Public
Access.
Set up your permission scheme. See Permissions and restrictions.
Connect Confluence to JIRA aplications such as JIRA Software or JIRA Service Desk or other
applications. See Linking to Another Application.
Defining your backup strategy:
By default, Confluence will create daily XML backups of your content and user data. This is suitable when
you are evaluating Confluence. When you move to a production site, you need more robust backup
procedures and technologies. See Production Backup Strategy.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 895
Confluence Data Center is designed to support the unique, and complex requirements of enterprise
organizations. It is a clustered solution that can provide performance at scale and high availability. This page
provides an overview of options and considerations for large enterprises using Confluence. If you want to find
out how to make sure Confluence can scale with your organization, this information is for you.
Performance at scale: If your Confluence instance has a very heavy load (you have a lot of users
accessing Confluence at the same time) a clustered installation will spread the load evenly between
cluster nodes, enabling you to serve more requests.
High availability and failover: If one cluster node goes down, then the remaining cluster nodes can
continue servicing requests so that users see little or no loss of availability.
Instant scalability: You can rapidly provision extra capacity with no downtime. Licensing is based on
users, not the number of nodes in your cluster. This means you can join additional nodes to your
cluster at any time, making it very easy to adapt as your usage grows.
Confluence Data Center enables you to configure a cluster similar to the one pictured here:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 896
The load balancer distributes The cluster of Data Center nodes Data Center supports the same
requests from your users to the share the workload of incoming databases that are supported for
cluster nodes. If a cluster node requests. Failure of a cluster Confluence Server. It also
goes down, the load balancer node causes virtually no loss of supports any shared file system,
immediately detects the failure availability for users, because which stores: import/export files,
and automatically directs requests are immediately directed plugins, Logos directory, shared
requests to the other nodes within to other nodes. All nodes are caches, and any data directory
seconds. You can use any load active and process requests. which includes attachments,
balancer that supports session avatars and icons.
affinity.
Contact us to speak with an Atlassian or get going with Data Center straight away.
For a detailed overview of Confluence's clustering solution see Confluence Data Center Technical Overview.
For help with installation, take a look at Installing Confluence Data Center, or for quick and easy set up,
check out Running Confluence Data Center in AWS.
The basics
Confluence Data Center enables you to configure a cluster similar to the one pictured below with:
Multiple server nodes for Confluence that store:
logs
caches
Lucene indexes
configuration files
plugins
Multiple server nodes to run Synchrony, which is required for collaborative editing.
A shared file system that stores:
attachments
avatars / profile pictures
icons
export files
import files
plugins
A database that all nodes read and write to.
A load balancer to evenly direct requests to each node.
All Confluence nodes are active and process requests. A user will access the same Confluence node for all
requests until their session times out, they log out, or a node is removed from the cluster.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 897
Licensing
Your Data Center license is based on the number of users in your cluster, rather than the number of nodes.
You can monitor the available license seats in the License page.
If you wanted to automate this process (for example to send alerts when you are nearing full allocation) you
can use the REST API.
REST API...
The following GET requests require an authenticated user with system administrator permissions. The
requests return JSON.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 898
Home directories
Confluence has a concept of a local home and shared home. Each Confluence node has a local home that
contains logs, caches, Lucene indexes and configuration files. Everything else is stored in the shared home,
which is accessible to each Confluence node in the cluster. Attachments, icons and avatars are stored in the
shared home as are export and import files.
Add-ons can choose whether to store data in the local or shared home, depending on the needs of the
add-on.
If you are currently storing attachments in your database you can continue to do so, but this is not available
for new installations.
Caching
Confluence uses a distributed cache that is managed using Hazelcast. Data is evenly partitioned across all
the Confluence nodes in a cluster, instead of being replicated on each node. This allows for better horizontal
scalability, and requires less storage and processing power than a fully replicated cache.
Because of this caching solution, to minimize latency, your nodes should be located in the same physical
location.
Indexes
A full copy of the Confluence indexes are stored on each Confluence node individually. A journal service
keeps each index in synch.
When you first set up your cluster, you will copy the local home directory, including the indexes, from the first
node to each new node.
When adding a new Confluence node to an existing cluster, you will copy the local home directory of an
existing node to the new node. When you start the new node, Confluence will check if the index is current,
and if not, request a recovery snapshot of the index from either the shared home directory, or a running node
(with a matching build number) and extract it into the index directory before continuing the start up process. If
the snapshot can't be generated or is not received by the new node in time, existing index files will be
removed, and Confluence will perform a full re-index.
If a Confluence node is disconnected from the cluster for a short amount of time (hours), it will be able to use
the journal service to bring its copy of the index up-to-date when it rejoins the cluster. If a node is down for a
significant amount of time (days) its Lucene index will have become stale, and it will request a recovery
snapshot from an existing node as part of the node startup process.
If you suspect there is a problem with the index on all nodes, you can temporarily disable index recovery on
one node, rebuild the index on that node, then copy the new index over to each remaining node.
The ClusterSafetyJob scheduled task runs every 30 seconds in Confluence. In a cluster, this job is run on
one Confluence node only. The scheduled task operates on a safety number a randomly generated
number that is stored both in the database and in the distributed cache used across the cluster. The
ClusterSafetyJob compares the value in the database with the one in the cache, and if the value differs,
Confluence will shut the node down - this is known as cluster split-brain. This safety mechanism is used to
ensure your cluster nodes cannot get into an inconsistent state.
If cluster split-brain does occur, you need to ensure proper network connectivity between the clustered
nodes. Most likely multicast traffic is being blocked or not routed correctly.
This mechanism also exists in standalone Confluence.
By changing how often the cluster safety scheduled job runs and the duration of the Hazelcast heartbeat
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 899
(which controls how long a node can be out of communication before it's removed from the cluster) you can
fine tune the balance between uptime and data integrity in your cluster. In most cases the default values will
be appropriate, but there are some circumstances where you may decide to trade off data integrity for
increased uptime for example.
To find out how to change the cluster safety scheduled job, see Scheduled Jobs.
You can change the Hazelcast heartbeat default via the confluence.cluster.hazelcast.max.no.
heartbeat.seconds system property. See Configuring System Properties.
Where an action must only run on one node, for example a scheduled job or sending daily email notifications,
Confluence uses a cluster lock to ensure the action is only performed on one node.
Similarly, some actions need to be performed on one node, and then published to others. Event handling
ensures that Confluence only publishes cluster events when the current transaction is committed and
complete. This is to ensure that any data stored in the database will be available to other instances in the
cluster when the event is received and processed. Event broadcasting is done only for certain events, like
enabling or disabling an add-on.
When configuring your cluster nodes you can either supply the IP address of each cluster node, or a
multicast address.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 900
The choice of hardware and infrastructure is up to you. Below are some areas to think about when planning
your hardware and infrastructure requirements.
If you plan to run Confluence Data Center on AWS, a Quick Start is available to help you deploy Confluence
Data Center in a new or existing Virtual Private Cloud (VPC). You'll get your Confluence and Synchrony
nodes, Amazon RDS PostgreSQL database and application load balancer all configured and ready to use in
minutes. If you're new to AWS, the step-by-step Quick Start Guide will assist you through the whole process.
Confluence can only be deployed in a region that supports Amazon Elastic File System (EFS). See Running
Confluence Data Center in AWS for more information.
Servers
We recommend your servers have at least 4GB of physical RAM. A high number of concurrent users means
that a lot of RAM will be consumed. You usually don't need to assign more than 4GB per JVM process, but
can fine tune the settings as required.
You should also not run any additional applications (other than core operating system services) on the same
servers as Confluence. Running Confluence, JIRA and Bamboo on a dedicated Atlassian software server
works well for small installations but is discouraged when running at scale.
Confluence Data Center can be run successfully on virtual machines. If you're using multicast, you can't run
Confluence Data Center in Amazon Web Services (AWS) environments as AWS doesn't currently support
multicast traffic.
Cluster nodes
Your Data Center license does not restrict the number of nodes in your cluster. We have tested the
performance and stability with up to 4 nodes.
Each node does not need to be identical, but for consistent performance we recommend they are as close as
possible. All cluster nodes must:
be located in the same data center
run the same Confluence version (for Confluence nodes) or the same Synchrony version (for
Synchrony nodes)
have the same OS, Java and application server version
have the same memory configuration (both the JVM and the physical memory) (recommended)
be configured with the same time zone (and keep the current time synchronized). Using ntpd or a
similar service is a good way to ensure this.
You must ensure the clocks on your nodes don't diverge, as it can result in a range of problems with
your cluster.
Database
The most important requirement for the cluster database is that it have sufficient connections available to
support the number of nodes.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 901
All Confluence cluster nodes must have access to a shared directory in the same path. NFS and SMB/CIFS
shares are supported as the locations of the shared directory. As this directory will contain large amount of
data (including attachments and backups) it should be generously sized, and you should have a plan for how
to increase the available disk space when required.
Load balancers
We suggest using the load balancer you are most familiar with. The load balancer needs to support session
affinity and WebSockets. This is required for both Confluence and Synchrony. If you're deploying on AWS
you'll need to use an Application Load Balancer (ALB).
Here are some recommendations when configuring your load balancer:
Queue requests at the load balancer. By making sure the maximum number requests served to a
node does not exceed the total number of http threads that Tomcat can accept, you can avoid
overwhelming a node with more requests than it can handle. You can check the maxThreads in <ins
tall-directory>/conf/server.xml.
Don't replay failed idempotent requests on other nodes, as this can propagate problems across all
your nodes very quickly.
Using least connections as the load balancing method, rather than round robin, can better balance the
load when a node joins the cluster or rejoins after being removed.
Many load balancers require a URL to constantly check the health of their backends in order to automatically
remove them from the pool. It's important to use a stable and fast URL for this, but lightweight enough to not
consume unnecessary resources. The following URL returns Confluence's status and can be used for this
purpose.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 902
Here are some recommendations, when setting up monitoring, that can help a node survive small problems,
such as a long GC pause:
Wait for two consecutive failures before removing a node.
Allow existing connections to the node to finish, for say 30 seconds, before the node is removed from
the pool.
Network adapters
Use separate network adapters for communication between servers. Cluster nodes should have a separate
physical network (i.e. separate NICs) for inter-server communication. This is the best way to get the cluster to
run fast and reliably. Performance problems are likely to occur if you connect cluster nodes via a network that
has lots of other data streaming through it.
Collaborative editing in Confluence 6.0 and later is powered by Synchrony, which runs as a seperate
process. You can deploy Synchrony on the same nodes as Confluence, or in its own cluster with as many
nodes as you need.
If you chose to run Synchrony on the same nodes as Confluence, you will need at least 2 GB of additional
memory (the default maximum heap size for Synchrony is 1 GB).
Your load balancer (and any other proxies) must support WebSocket connections and session affinity.
Confluence Data Center removes the application server as a single point of failure. You can further minimize
single points of failure by ensuring your load balancer, database and shared file system are also highly
available.
User management
You can manage users in Confluence's internal directory, in an external LDAP directory, or in Atlassian
Crowd or JIRA.
You can also connect Confluence Data Center to a SAML 2.0 identity provider for authentication and single
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 903
The process for installing add-ons in Confluence Data Center is the same as for a standalone instance of
Confluence. You will not need to stop the cluster, or bring down any nodes to install or update an add-on.
The Atlassian Marketplace indicates add-ons that are compatible with Confluence Data Center.
Add-on licenses for Data Center are sold at the single server rate, but must match or exceed your
Confluence Data Center license tier. For example, if you are looking to have 3,000 people using Confluence
Data Center, then you would buy any add-ons at the 2-001-10,000 user tier.
If you have developed your own plugins for Confluence you should refer to our developer documentation on
How do I ensure my add-on works properly in a cluster? to find out how you can confirm your plugin is cluster
compatible.
A full copy of the Confluence indexes are stored on each Confluence node individually. A journal service keeps
each index in sync.
Confluence Data Center also stores a snapshot of the search index in the shared home directory, which can be
useful in a disaster recovery scenario. These snapshots are created as part of the Clean Journal Entries
scheduled job which, by default, runs once per day.
Index recovery
When you start a Confluence node it will check whether its index is current, and if not, it will request a recovery
snapshot from the shared home directory. If a snapshot is not available, it will generate a snapshot from a
running node (with a matching build number). Once the recovery snapshot is extracted into the index directory,
Confluence will continue the startup process.
If the snapshot can't be generated, or is not received in time, existing index files will be removed and Confluence
will perform a reindex on that node. If your index is very large or your file system slow, you may need to increase
the time Confluence waits for the snapshot to be generated using the confluence.cluster.index.recove
ry.generation.timeout system property.
Index recovery only happens on node startup, so if you suspect a problem with a particular cluster node's index,
restart that node to trigger index recovery.
If you suspect there's a problem with the index on all nodes, you'll need to rebuild the index on just one node
first, then copy it to the other nodes. We recommend backing up the local home directory and your shared home
directory before you begin.
In this example we'll rebuild the index on node 1. You may wish to use your load balancer to direct traffic away
from node 1 while the index is being rebuilt. This will prevent users from hitting a Confluence node with an
incomplete index.
1. Stop Confluence on node 1.
2. Set the confluence.cluster.index.recovery.num.attempts system property to 0.
This disables index recovery on node 1, so that when this node is restarted, it does not attempt to recover
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
2. 6.4 documentation 904
When you install Confluence Server, Synchrony is automatically configured to run as a seperate process on your
server.
For Confluence Data Center, we give you full control by allowing you to set Synchrony up yourself. This gives
you the flexibility to deploy Synchrony on the same nodes as Confluence, or in its own cluster with as many
nodes as you need.
When you start Synchrony, you'll pass a number of system properties to tell Synchrony how to discover nodes in
your cluster, where to find your Confluence database and more. System properties are set by passing the -D fla
g to the Java virtual machine in which Synchrony is running.
Sensitive information (like database credentials) may be provided using environmental variables (rather than via
the command line). Any dots (".") in variable names (identifiers) will need to be replaced with underscores ("_").
See Installing Confluence Data Center for a step by step guide to setting up Synchrony for Data Center.
When you start Synchrony there are a number of properties that you need to provide.
classpath This is the path to the Synchrony jar file, followed by the path to your
database driver. If you're running Synchrony on its own node, you'll
need to copy your database driver to an appropriate location then
provide the path to this location.
For Linux the syntax is:
<PATH_TO_SYNCHRONY_STANDALONE_JAR>:<JDBC_DRIVER_PATH>
cluster.join.type This tells Hazelcast how to discover nodes. This can be the same as
the join configuration for Confluence or different. Values are:
multicast
tcpip
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 905
synchrony.bind This is the network interface for Synchrony to bind to. Specify the public
IP address or hostname of this Synchrony node. It could also be a
private IP address - it should be configured to the address where
Synchrony is reachable by the other nodes.
synchrony.service.url This is the URL that the browser uses to contact Synchrony. Generally
this will be the full URL of the load balancer Synchrony will run behind
plus the Synchrony context path, for example http://yoursite.com
:8091/synchrony. Note that it does not end with /v1, unlike the syn
chrony.service.url system property passed to Confluence. If this
URL doesn't match the URL coming from a users' browser, Synchrony
will fail.
synchrony.database.url This is the URL for your Confluence database. For example jdbc:pos
tgresql://localhost:5432/confluence. You can find this URL
in <local-home>/confluence.cfg.xml.
When you start Synchrony, we pass default values for the properties listed below. You can choose to override
these values by specifying any of these properties when you start Synchrony.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 906
synchrony.cluster.bind Defaults to the same value This is the Aleph binding address. This
as synchrony.bind should be set to the same value as cl
uster.interfaces.
synchrony.context.path Defaults to the context path This is the context path for Synchrony.
of synchrony.service.u There should be no need to change
rl this.
If your users are unlikely to be able to get a WebSocket connection to Synchrony (for example your load
balancer or reverse proxy does not support WebSockets) you can enable XHR fallback by passing the synchro
ny.enable.xhr.fallback system property to Confluence. Note that this is a Confluence system property
and must be passed to Confluence, it is not part of your start Synchrony command.
Restricted Functions in Confluence Data Center
There are some features that are disabled or limited in Confluence Data Center. This is to ensure the integrity
and performance of your cluster.
The current restricted functions are:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 907
Confluence Available from The quick reload function notifies users when a new comment has been
Quick Reload 5.6.3 added to a page they are currently viewing.
Plugin
This is disabled in Confluence Data Center 5.6 and 5.6.1 for performance
reasons. You will not be able to enable the Confluence Quick Reload
Plugin in the universal plugin manager.
See
CONFSERVER-34680 - Make quick reload plugin available in Confluence
Data Center RESOLVED
for more info.
Application RESTRICTED When creating Application links to other applications (for example JIRA)
links Basic HTTP and Trusted Applications authentication is not supported for
authentication: Confluence Data Center.
Basic All application links must use OAuth authentication in a cluster.
access
(http)
Trusted
Applications
Confluence DISABLED The Confluence Usage Stats plugin provides space activity information fo
Usage Stats r a space (statistics). This is disabled by default in Confluence Server and
plugin should not be enabled in Confluence Data Center.
Scheduled jobs LIMITED On the Scheduled Jobs page in the Confluence Data Center
history and administration console you will not be able to access the last execution
status time or history for each job. The page will also only show the configured
status (scheduled or disabled) of each job, and will not indicate when a
job is in progress.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 908
Remember me LIMITED Remember me on the log in page is enabled by default (and does not
on by default appear) to allow users to move seamlessly between nodes. You can use
the cluster.login.rememberme.enabled system property to
override the default and show the checkbox - users will be prompted to
log in to another node if their current node is unavailable.
Performance gains - Under a high load, clustered Confluence has improved performance overall.
Request responses don't diminish under increased load - Adding more nodes increases throughput,
handles higher load and decreases response times.
You might observe a different trend/behavior based on your configuration and usage. For details, please see the What we tested s
ection below.
The following sections detail the testing environment and methodology we used in our performance tests.
How we tested
Our performance tests were all run on the same controlled isolated lab at Atlassian. For each test, the entire
environment was reset and rebuilt. The testing environment included the following components and
configuration:
Apache proxy_balancer
Postgres database and the required data
G1GC garbage collector
8GB Xmx settings per node
6 CPUs per node
Confluence Server on one machine or Confluence Data Center on two, or four machines as required
for the specific test.
To run the test, we used a number of machines in the lab to generate load using scripted browsers and
measuring the time taken to perform an action. An action here, means a complete user operation like
creating a page or adding comment. Each browser was scripted to perform an action from a predefined list of
actions and immediately move on the to next action (i.e. zero think time). Please note that this resulted in
each browser performing more tasks than would be possible by a real user and you should not interpret the
number of browsers to be equal to the number of real world users. Each test was run for 20 minutes, after
which statistics were collected.
What we tested
All tests used the same Postgres database containing the same number of spaces and pages.
The mix of actions we included in the tests represented a sample of the most common user actions*
representing six typical types of users (personas). The table below show the ratio of actions performed
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 909
by each of these personas. These user-based actions were repeated until the test was completed.
PageReader 7
Searcher 1
Editor 1
Creator 1
Commenter 1
Liker 1
Tests were performed with differing load sizes, from 4 up to 96 browsers. For larger load sets, profiles were
scaled up, that is, doubling each amount for the 24 browser load, tripled for the 36 browser load.
* The tests did not include admin actions as these are assumed to be relatively infrequent.
Hardware
All performance tests were all run on the same controlled, isolated lab at Atlassian using the hardware listed
below.
Rackform iServ CPU: 2 x Intel Xeon E5-2430L, 2.0GHz (6-Core, HT, 15MB Cache, 60W) 20
R304.v3 32nm
RAM: 48GB (6 x 8GB DDR3-1600 ECC Registered 2R DIMMs) Operating
at 1600 MT/s Max
NIC: Dual Intel 82574L Gigabit Ethernet Controllers - Integrated
Controller: 8 Ports 3Gb/s SAS, 2 Ports 6Gb/s SATA, and 4 Ports 3Gb/s
SATA via Intel C606 Chipset
PCIe 3.0 x16: Intel X540-T2 10GbE Dual-Port Server Adapter (X540)
10GBASE-T Cat 6A - RJ45
Fixed Drive: 240GB Intel 520 Series MLC (6Gb/s) 2.5" SATA SSD
Power Supply: 600W Power Supply with PFC - 80 PLUS Gold Certified
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 910
The browser and servers are in the same location so there was very low latency between client and
server.
The following table shows the relative performance as the load increases for each Confluence instance
configuration: Confluence Server, two node Confluence Data Center, and four node Confluence Data Center.
The table shows the response time relative to the baseline response time which we determined to be
Confluence Server with sixteen browsers.
Browsers 16 24 36 48 60 72 84 96
Overview
Before you start, you need Confluence Data Center 5.9 or later to implement the strategy described in this
guide.
This page describes what is generally referred to as a 'cold standby' strategy, which means the standby
Confluence instance isn't continuously running and that you need to take some administrative steps to start the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 911
standby instance and ensure it's in a suitable state to service the business needs of your organization.
Maintaining a runbook
The detailed steps will vary from organization to organization and, as such, we recommend you keep a
full runbook of steps on file, away from the production system it references. Make your runbook detailed
enough such that anyone in the relevant team should be able to complete the steps and recover your
service, regardless of prior knowledge or experience. We expect any runbook to contain steps that cover
the following parts of the disaster recovery process:
1. Detection of the problem
2. Isolation of the current production environment and bringing it down gracefully
3. Synchronization of data between failed production and intended recovery point
4. Warm up instructions for the recovery instance
5. Documentation, communication, and escalation guidelines
The major components you need to consider in your disaster recovery plan are:
Confluence Your standby site should have exactly the same version of Confluence installed as your
installation production site.
Database This is the primary source of truth for Confluence and contains most of the Confluence data
(except for attachments, avatars, etc). You need to replicate your database and continuously
keep it up to date to satisfy your RPO1
Attachments All attachments are stored in the Confluence Data Center shared home directory, and you
need to ensure it's replicated to the standby instance.
Search The search index isn't a primary source of truth, and can always be recreated from the
Index database. For large installations, though, this can be quite time consuming and the
functionality of Confluence will be greatly reduced until the index is fully recovered.
Confluence Data Center stores search index backups in the shared home directory, which are
covered by the shared home directory replication.
Plugins User installed plugins are stored in the database and are covered by the database replication.
Other data A few other non-critical items are stored in the Confluence Data Center shared home. Ensure
they're also replicated to your standby instance.
Install the same version of Confluence on your standby system. Configure the system to attach to the standby
database.
Replicating data to your standby location is crucial to a cold standby failover strategy. You don't want to fail over
to your standb y Confluence ins tance and find that it's out of date or that it takes many hours to re-index.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 912
Database All of the following Confluence supported database suppliers provide their own database
replication solutions:
Show me...
Oracle: http://www.oracle.com/technetwork/database/features/data-integration/index.html
PostgreSQL: https://wiki.postgresql.org/wiki/Binary_Replication_Tutorial
MySQL: http://dev.mysql.com/doc/refman/5.7/en/replication.html
Microsoft SQL Server: http://msdn.microsoft.com/en-us/library/ms151198.aspx
You need to implement a database replication strategy that meets your RTO, RPO and RCO 1.
Files You also need to implement a file server replication strategy for the Confluence shared home
directory that meets your RTO, RPO and RCO1.
Clustering considerations
For your clustered environment you need to be aware of the following, in addition to the information above:
Standby There's no need for the configuration of the standby cluster to reflect that of the live cluster. It may
cluster contain more or fewer nodes, depending on your requirements and budget. Fewer nodes may
result in lower throughput, but that may be acceptable depending on your circumstances.
Starting It's important to initially start only one node of the cluster, allow it to recover the search index,
the and check it's working correctly before starting additional nodes.
standby
cluster
You should exercise extreme care when testing any disaster recovery plan. Simple mistakes may cause your
live instance to be corrupted, for example, if testing updates are inserted into your production database. You
may detrimentally impact your ability to recover from a real disaster, while testing your disaster recovery plan.
The key is to keep the main data center as isolated as possible from the disaster recovery testing
.
This procedure will ensure that the standby environment will have all the right data, but as the testing
environment is completely separate from the standby environment, possible configuration problems on
the standby instance are not covered.
Prerequisites
Before you perform any testing, you need to isolate your production data.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 913
Attachments, You need to ensure that no plugin updates or index backups occur during the test:
plugins and
indexes 1. Disable index backups
2. Instruct sysadmins to not perform any updates in Confluence
3. Temporarily pause all replication to the standby shared home directory
4. Replicate the data from the standby shared home directory to another directory
that's isolated and with no communication with the main shared home directory
Installation 1. Clone your standby installation separate from both the live and standby instances
folders 2. Change the connection to the database in the <confluencelocalhome>/conflu
ence.cfg.xml file to avoid any conflict
3. Change the location of the shared home directory in the <confluencelocalhome
>/confluence.cfg.xml file to avoid any conflict
4. If using TCP/IP for cluster setup, change the IP addresses to that of your testing
instances in <confluencelocalhome>/confluence.cfg.xml
After this you can resume all replication to the standby instance, including the database.
Once you have isolated your production data, follow the steps below to test your disaster recovery plan:
1. Ensure that the new database is ready, with the latest snapshot and no replication
2. Ensure that the new shared home directory is ready, with the latest snapshot and no replication
3. Ensure you have a copy of Confluence on a clean server with the right database and shared home
directory settings in <confluencelocalhome>/confluence.cfg.xml
4. Ensure you have confluence.home mapped, as it was in the standby instance, in the test server
5. Disable email (See atlassian.mail.senddisabled in Configuring System Properties)
6. Start Confluence
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 914
Handling a failover
In the event your primary site is unavailable, you'll need to fail over to your standby system. The steps are as
follows:
1. Ensure your live system is shutdown and no longer updating the database
2. Ensure the contents of <confluencesharedhome> is synced to your standby instance
3. Perform whatever steps are required to activate your standby database
4. Start Confluence on one node in the standby instance
5. Wait for Confluence to start and check it is operating as expected
6. Start up other Confluence nodes
7. Update your DNS, HTTP Proxy, or other front end devices to route traffic to your standby server
In most cases, you'll want to return to using your primary instance after you've resolved the problems that
caused the disaster. This is easiest to achieve if you can schedule a reasonably-sized outage window.
Other resources
Atlassian Answers
Our community and staff are active on Atlassian Answers. Feel free to contribute your best practices, questions
and comments. Here are some of the answers relevant to this page:
Disaster Recovery Configuration for Jira and Confluence
Troubleshooting
If you encounter problems after failing over to your standby instance, check these FAQs for guidance:
What should I do if my database isn't synchronized correctly?
If your database doesn't have the data available that it should, then you'll need to restore the database from
a backup.
Once you've restored your database, the search index will no longer by in sync with the database. You can ei
ther do a full re-index, background or foreground, or recover from the latest index snapshot if you have one.
This includes the journal id file for each index snapshot. The index snapshot can be older than your database
backup; it'll synchronize itself as part of the recovery process.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 915
access to the hard drives. Tools such as rsync may be useful in these circumstances. Missing attachments
won't stop Confluence performing normally; the missing attachments won't be available, but users may be
able to upload them again.
Definitions
RPO Recovery Point How up-to-date you require your Confluence instance to be after a failure.
Objective
RTO Recovery Time Objective How quickly you require your standby system to be available after a
failure.
RCO Recovery Cost Objective How much you are willing to spend on your disaster recovery solution.
Database is being updated by an instance Add multicast route, Check firewall, Cluster
which is not part of the current cluster errors Panic due to Multiple Deployments
on a cluster
Error in log: The interface is not suitable for Change multicast interface, Add multicast
multicast communication route
Multicast being sent, but not received Check firewall, Check intermediate routers,
Increase multicast TTL
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 916
Add-on is unlicensed on some nodes after updating the Disable and re-enable the add-on in the
license on one node. Universal Plugin Manager.
After a add-on update, strings appear in the UI instead of Restart the affected node.
buttons and icons on some nodes.
Hazelcast CANNOT start on this node. No See Hazelcast CANNOT start on this node.
matching network interface found. No matching network interface found KB
article
Multicast
name="confluence.cluster.address">xxx.xx.xxx.xxx</property>
A warning message is displayed when an user changes the address from the one that Confluence has
generated by the hashing of the name. There is no way of eliminating the message any other way other than
by returning the address to the one that matches the cluster name. Purpose of the warning message is to
remind the user that the address has been changed - as it is not the hashed version any longer -
consequently the node can not join the cluster just by using the name. It is also necessary to provide the
correct address as well.
To ensure that the interface name is mapped correctly, the following tool can be used. It shows the mapping
of the interface name to the IP address.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 917
Debugging tools
Listed below are some debugging tools that help determine what the status of the multicast traffic is:
tcpdump -i inte Captures network traffic on the given interface. Most useful on an interface that only
rface receives cluster traffic.
Multicast networking requirements vary across operating systems. Some operating systems require little
configuration, while some require the multicast address to be explicitly added to a network interface before
Confluence can use it. If multicast traffic can't be sent or received correctly, adding a route for multicast traffic
on the correct interface will often fix the problem. The example below is for a Ubuntu Linux system:
To support multiple applications using multicast on different interfaces, you may need to specify a route
specific to the Confluence multicast address.
Check firewall
Ensure your firewall allows UDP traffic on the multicast address and port used by Confluence.
Prefer IPv4
There are known issues relating to IPv6. You should configure your JVM to try binding to an IPv4 address
first.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 918
Confluence might have selected the incorrect interface for multicast traffic, which means it cannot connect to
other nodes in the cluster. To override the interface used for multicast traffic after initial setup, edit the confl
uence.cluster.interface property in <local-home>/confluence.cfg.xml and specify the
network interface. For example to tell Confluence to use eth1:
<property name="confluence.cluster.interface">eth1</property>
If the solution to your problem involves changes to the Hazelcast configuration, these changes should not be
made to the Confluence configuration files. Instead, to ensure your configuration survives upgrades, make
your changes by creating a Hazelcast override file.
The multicast time-to-live (TTL) specifies how many hops a multicast packet should be allowed to travel
before it is discarded by a router. It should be set to the number of routers in between your clustered nodes:
0 if both are on the same machine, 1 if on two different machines linked by a switch or cable, 2 if on two
different machines with one intermediate router, and so on.
To increase the multicast TTL by edit the confluence.cluster.ttl property in the <local
home>/confluence.cfg.xml file on each node. For example to set the TTL to 3:
<property name="confluence.cluster.ttl">3</property>
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.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 919
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.
e. When you've established when the first affected node was removed, or when the first cluster
panic occurred, look back in time in the logs on that node, to look for root causes.
Once you know when the first affected node was removed you can start investigating root causes. From this
point on, you're only looking at events on the affected node around the time of removal (in our example
above, this is Node 3 at around 2:50). The subsequent removals and panics are usually flow-on effects of
the original node removal event, and aren't likely to provide useful root cause information.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 920
Garbage collection
Check the GC logs for the node that was removed (Node 3 in our example). Were there any GC pauses
longer than the Hazelcast heartbeat interval (30 seconds by default)? Nodes can't heartbeat during Garbage
Collection, so they will be removed from the cluster by one of the other nodes.
If there was a cluster panic, but the node was not removed from the cluster first, check the GC logs for
pauses around the time of the panic - pauses that are relatively short (less than 30 seconds) can sometimes
still cause panics (due to a race condition) in Confluence 5.10.1 and earlier.
Database connections
Check any database monitoring tools you may have. How many connections to the database were there at
the time of the outage? Heartbeats can fail to send if a node can get a connection from its connection pool
but not from the database itself, which can lead to nodes being removed from the cluster.
You won't be able to diagnose this from the Confluence logs and will need to look at any external monitoring
tools you have for your database. If the outage happens again, check the current number of connections at
the db level during the outage.
Network connectivity
Check your network monitoring tools. If a node drops off the network for a short time and cannot
communicate with the cluster, it can be removed by the other nodes. Your load balancer logs may be useful
here.
Contact Support for help troubleshooting these outages. Provide them with as much of the information above
as possible, to help their investigation.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 921
Confluence 5.3
Confluence 5.8
Confluence 5.3.4 Release Notes
Confluence 5.8.18 Release Notes Confluence 5.3.1 Release Notes
Confluence 5.8.17 Release Notes Confluence 5.3 Release Notes
Confluence 5.8.16 Release Notes
Confluence 5.8.15 Release Notes
Confluence 5.8.14 Release Notes Confluence 5.2
Confluence 5.8.13 Release Notes
(Confluence 5.8.11 and 5.8.12 were internal Confluence 5.2.5 Release Notes
releases) Confluence 5.2.4 Release Notes
Confluence 5.8.10 Release Notes Confluence 5.2.3 Release Notes
Confluence 5.8.9 Release Notes (Confluence 5.2.0 - 5.2.2 were internal
Confluence 5.8.8 Release Notes releases)
(Confluence 5.8.7 was an internal release)
Confluence 5.8.6 Release Notes Confluence 5.1
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 922
Confluence 5.7
Confluence 5.0
Confluence 5.7.6 Release Notes
Confluence 5.7.5 Release Notes Confluence 5.0.3 Release Notes
Confluence 5.7.4 Release Notes Confluence 5.0.2 Release Notes
Confluence 5.7.3 Release Notes Confluence 5.0.1 Release Notes
(Confluence 5.7.2 was an internal release) Confluence 5.0 Release Notes
Confluence 5.7.1 Release Notes
Confluence 5.7 Release Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 923
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 924
Current Release
For information about the latest release, please go to the Confluence Release Notes.
Confluence 6.4
Stability improvements
Additional bundled language packs for Estonian, Icelandic and Slovenian.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 925
Collaborative editing
Copy page hierarchies
Delete page hierarchy
Epic links for the JIRA Issues macro
Removal of the documentation theme.
Inline comments on pages and pinned comments on files to simplify your feedback loop
A whole new files experience - upload, preview, share and more.
HipChat Cloud integration to supercharge your team collaboration.
New macro for planning visual roadmaps.
Data Center improvements including cluster monitoring and the return of workbox.
New profile picture and space logo uploader
Content search REST API (CQL)
Improvements to the editor.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 926
Introducing blueprints
Meeting Notes blueprint
File List blueprint
Product Requirements blueprint
New template features
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 927
A visual refresh
Updated global navigation
Content creation made simple
New sidebar for content discovery
Editor improvements
Quick access to recently viewed pages
Redesigned space administration and space tools
Improved theming and branding
Improved user and group management for large sites
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 928
Introducing Gadgets
Drag-and-Drop
Office 2007 Support
New 'Move Page' Feature
Enhanced Image Browser
Draft Comparisons
Page Restrictions Dialog Box
Other Editor Enhancements
New Web Browser Versions Supported
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 929
Streamlined Search
Auto Save
Charts
Page Tree
Gallery
New Tutorial
More in the Menus
Alphabetical Page Ordering
Better Spam Prevention
Plugin Repository
Engine Room and Developers' Community
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 930
Editable comments
Page mailing
Personal spaces
Localization/internationalization drop-in language packs (similar to JIRA)
CAPTCHA support spam protection
Improved searching
Improved LDAP performance
Confluence ships with Tomcat 5.5
Autosave
Concurrent edit warnings
LDAP integration with Atlassian User/POLIS
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 931
Mail archiving
Themes
Trash can
More granular space permissions
Page list views alphabetical, directory view and search view of all pages in a space
Image thumbnails and thumbnail galleries
Threaded comments
Enhanced Search - indexing attachment comments and file names and contextual searching
New permissions interface
Upgrade Notes Overview
Typically, each major release of Confluence comes with upgrade notes, which are specific recommendations for
upgrading from the previous major version. If you plan to upgrade and skip a few Confluence versions, you must
read the upgrade notes for all major versions between your current version and the version to which you are
upgrading, to make sure you do not miss something important.
Please read our general information about upgrading Confluence.
For example:
When upgrading from Confluence 5.3 to Confluence 5.5, read the upgrade notes for Confluence 5.4, as
well as those for Confluence 5.5.
Also, we strongly recommend that you read the upgrade notes for any minor releases in-between, since they
contain important information that will affect your Confluence upgrade.
Below is a list of upgrade notes for previous major releases of Confluence, as well as the upgrade notes for
important minor releases:
Confluence 6.4 Upgrade Notes
Confluence 6.3 Upgrade Notes
Confluence 6.2 Upgrade Notes
Confluence 6.1 Upgrade Notes
Confluence 6.0 Upgrade Notes
Confluence 5.10 Upgrade Notes
Confluence 5.9 Upgrade Notes
Confluence 5.8 Upgrade Notes
Confluence 5.7 Upgrade Notes
Confluence 5.6 Upgrade Notes
Confluence 5.5 Upgrade Notes
Confluence 5.4 Upgrade Notes
Confluence 5.3 Upgrade Notes
Confluence 5.2 Upgrade Notes
Confluence 5.1 Upgrade Notes
Confluence 5.0 Upgrade Notes
Confluence 4.3 Upgrade Notes
Confluence 4.2 Upgrade Notes
Confluence 4.1 Upgrade Notes
Confluence 4.0 Upgrade Notes
Confluence 3.5 Upgrade Notes
Confluence 3.4 Upgrade Notes
Confluence 3.3 Upgrade Notes
Confluence 3.2 Upgrade Notes
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 932
Useful plugins
Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's
information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines
on add-on support.
RELATED TOPICS
Check the documentation for information about Administrators can access a range of
using and administering Confluence. troubleshooting and support tools within Confluence.
Go to
If you can't find what you need in the We love to hear your requests for new features and
documentation, try asking in our question and improvements! You make a feature suggestion in
answers forum, Atlassian Answers. the Confluence (CONF) project in our JIRA issue
tracker.
Alas, bugs do happen. If you find one, we'll do our
best to fix it. Please raise a bug report in our JIRA
issue tracker.
Support team
Confluence Resources
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 933
Free trial
Feature tour
Downloadable documentation
Atlassian Marketplace
Support
Atlassian Support
Support policies
Training
Atlassian training
Answers
Mailing lists
Visit http://my.atlassian.com to sign up for mailing lists relating to Atlassian products, such as technical
alerts, product announcements and developer updates.
Welcome to the support policies index page. Here, you'll find information about how Atlassian Support can help
you and how to get in touch with our helpful support engineers. Please choose the relevant page below to find
out more.
Bug Fixing Policy
New Features Policy
Security Bugfix Policy
To request support from Atlassian, please raise a support issue in our online support system. To do this, visit su
pport.atlassian.com, log in (creating an account if need be) and create an issue under Confluence. Our friendly
support engineers will get right back to you with an answer.
Bug Fixing Policy
Summary
Our Support team will help with workarounds and bug reporting
We'll generally fix critical bugs in the next maintenance release
We schedule non-critical bugs according to a variety of considerations
Report a bug
Building an add-on
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 934
Are you developing an add-on for an Atlassian product or using one of our APIs? Report any related bugs here.
Bug reports
Atlassian Support is eager and happy to help verify bugswe take pride in it! Create an issue in our support
system, providing as much information as you can about how to replicate the problem you're experiencing. We'll
replicate the bug to verify, then lodge the report for you. We'll also try to construct workarounds if possible.
Use our issue tracker to search for existing bugs, and watch the ones that are important to you. When you watch
an issue, we'll send you an e-mail notification when the issue's updated.
Maintenance (bug fix) releases come out more frequently than major releases, and attempt to target the most
critical bugs affecting our customers. The notation for a maintenance release is the final number in the version
(the 1 in 6.0.1, for example).
If a bug is critical (production application down or major malfunction causing business revenue loss or high
numbers of staff unable to perform their normal functions) we'll fix it in the next maintenance release, provided
that:
The fix is technically feasible (it doesn't require a major architectural change)
It doesn't impact the quality or integrity of a product
For non-critical bugs, the team assigned to fixing bugs prioritises the bug according to these factors:
How many of our supported configurations are affected by the problem
Whether there is an effective workaround or patch
How difficult the issue is to fix
Whether many bugs in one area can be fixed at one time
Developers responsible for fixing bugs also monitor comments on existing and new bugs, so you can comment
to provide feedback if you need to. We give high priority to security issues.
When considering the priority of a non-critical bug, we try to determine a value score for a bug. The score takes
into account the severity of the bug from our customers' perspective, how prevalent the bug is, and whether new
features on our roadmap may render the bug obsolete. Our developers combine the value score with a complexi
ty score (how difficult the bug is) when selecting issues to work on.
Further reading
Summary
We encourage and display customer comments and votes openly in our issue tracking system, http://jira.a
tlassian.com.
We do not publish roadmaps.
Product Managers review our most popular voted issues on a regular basis.
We schedule features based on a variety of factors.
Our Atlassian Bug Fixing Policy is distinct from this process.
Atlassian provides consistent updates on the top 20 issues.
When a new feature or improvement is scheduled, the 'fix-for' version will be indicated in the JIRA issue. This
happens for the upcoming release only. We maintain roadmaps for more distant releases internally, but because
these roadmaps are often pre-empted by changing customer demands, we do not publish them.
In every major release we aim to implement highly requested features, but it is not the only determining factor.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 935
Further reading
See Security @ Atlassian for more information on our security bugfix policy.
Upgrading from Confluence 3.5 to 5.1 - Simplified Guide
In accordance with Atlassian's standard s
upport policy, Confluence 3.5 will reach E
nd of Life on 6 September 2013.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 936
Wiki Markup
One of the the major differences between Confluence 3.5 and newer versions is the migration of wiki markup
to our new editor. We understand that you may still require wiki markup from time to time and we feel that the
following resources will make things easier:
Confluence 4 Editor - What's Changed for Users of the Old Rich Text Editor
The editor auto converts wiki markup to the new formatting.
The editor has the ability to Insert > Wiki Markup.
Bob Swift's Wiki Markup Addon allows you to preserve wiki markup if necessary. This plugin is
currently offered free of charge.
API Changes - Confluence now stores information in an XHTML format, which means that scripted
behavior against the Confluence API will break. We have provided the convertWikiToStorageFormat
method to ease the transition.
Preparing to upgrade
1. Check if your currently installed Plugins are compatible with the chosen target Confluence version
Verify whether a compatible version of the plugin is available in Confluence 5.1.4. We've made this easy for
you: This information is available via the Confluence Upgrade Check in the plugin administration section of
Confluence. See the documentation: Checking add-on compatibility with application updates. You can also
check the respective home pages for these plugins on the Atlassian Marketplace.
2. Test the upgrade in a staging environment before upgrading your production instance
This will allow you to anticipate any unexpected behavior during the upgrade. Testing will also allow you
to plan the upgrade of the production instance, as it will give you a better understanding of how long the
upgrade will take and how much time you will need to re-install Plugins and re-apply any customization.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 937
Make sure that you are aware of the changes listed in the Simplified Upgrade Notes - Upgrading from 3.5 to
5.1 page. These Upgrade Notes are a summary of important changes in the platforms supported by
Confluence and information to be considered during the upgrade.
Confluence 5 introduced significant changes to the user experience. To help you manage the change in your
organization, we have provided the Planning for Confluence 5 guide to help prepare your team.
Upgrading Confluence
This is a simplified version of the Confluence Upgrade process. A more detailed guide is available here.
The following instructions will help you to run the upgrade in two steps, on Windows or Linux environments:
1. Upgrade from 3.5 to 5.0.3.
2. Upgrade from 5.0.3 to 5.1.4.
This means that you will run the following steps twice. First, to upgrade from 3.5 to 5.0.3 and then a second
time to upgrade from 5.0.3 to 5.1.4.
1. Download the Confluence Windows Installer (.exe) file (for the new version of Confluence).
2. Run the .exe file to start the upgrade wizard.
If a Windows 7 (or Vista) 'User Account Control' dialog box requests if you want to allow the upgrade
wizard to make changes to your computer, specify 'Yes'. If you do not, the installation wizard will have
restricted access to your operating system and any subsequent installation options will be limited.
3. At the 'Upgrading Confluence?' step, choose the 'Upgrade an existing Confluence installation'
option.
4. In the 'Existing Confluence installation directory' field, specify the Confluence Installation Directory of
your Confluence installation to be upgraded.
The upgrade wizard will attempt to find an existing Confluence installation and use its location to
pre-populate this field. However, always verify this location, particularly if you have multiple
Confluence installations running on the same machine.
5. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following
options:
a. At the 'Back up Confluence directories' step, ensure the 'Back up Confluence home' option is
selected. This creates 'zip' archive file backups of your existing Confluence Installation and
Confluence Home Directories in their respective parent directory locations.
Please Note: Choosing this option is strongly recommended!
b. At this point, the upgrade wizard notes any customizations in your existing installation
directory which it cannot automatically migrate to your upgraded Confluence installation. If you
are notified by the installer about any files containing such customizations, please make a note
of the locations of these files as you will need to manually migrate their customizations (which
are not mentioned in the overview above) to your upgraded Confluence installation. One
relatively common customization that the upgrade wizard cannot automatically migrate is an SS
L configuration defined in the conf/server.xml file of the Confluence Installation Directory.
Please Note: when upgrading from the version that was not installed by the installer
the customizations can only be detected in the confluence subdirectory of your
existing Confluence Installation Directory. Modifications to files in directories other than conflu
ence will not be detected when you upgrade, for example, modifications to conf/server.xml
. However the next time you upgrade (e.g. to version 4.1.1) the upgrade feature will cover
modifications across the whole Confluence Installation Directory.
c. At the 'Upgrade Check List' step, perform the following steps if you have not already done so:
Back up your external database.
If your Confluence site includes third-party plugins (add-ons), check that they will be
compatible with your upgraded Confluence version. See the documentation: Checking
add-on compatibility with application updates.
d.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 938
d. Choose 'Next', your existing Confluence installation will be shut down if it is still running. The
upgrade wizard will then:
i. Back up your existing Confluence installation.
ii. Delete the contents of the existing Confluence Installation Directory.
iii. Install the new version of Confluence to the existing Confluence Installation Directory.
iv. Starts your new (upgraded) Confluence installation.
If you noted any files that contain customizations which must be migrated manually to
your upgraded Confluence installation (above), then:
1. Stop the upgraded Confluence installation.
2. Migrate the customizations from these files into the upgraded installation
directory.
3. Restart the upgraded Confluence installation.
6. At the last step of the upgrade wizard, select the option to launch the upgraded Confluence installation
in a browser so you can check the upgrade.
Congratulations, you have completed upgrading your Confluence installation on Windows!
Finished running the steps to upgrade from 3.5 to 5.0.3? Remember to run them again, upgrading
from 5.0.3 to 5.1.4.
1. Download the appropriate Confluence 'Linux 64-bit / 32-bit Installer' (.bin) file that suits your
operating system (for the new version of Confluence).
2. Open a Linux console and change directory (cd) to the '.bin' file's directory.
If the '.bin' file is not executable after downloading it, make it executable, for example:
chmod a+x atlassian-confluence-X.Y.bin
(where X.Y represents your version of Confluence)
3. Execute the '.bin' file to start the upgrade wizard.
4. When prompted to choose between creating a new Confluence installation or upgrading an existing
installation, choose the 'Upgrade an existing Confluence installation' option.
5. Specify the Confluence Installation Directory of your Confluence installation to be upgraded.
The upgrade wizard will attempt to find an existing Confluence installation and will provide its location
as a choice. However, always verify this location, particularly if you have multiple Confluence
installations running on the same machine.
6. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following
options:
a. Choose the option to back up Confluence's directories. This creates 'zip' archive file backups of
your existing Confluence Installation and Confluence Home directories in their respective parent
directory locations.
Please Note: Choosing this option is strongly recommended!
b. At this point, the upgrade wizard notes any customizations in your existing Confluence
Installation Directory which it cannot automatically migrate to your upgraded Confluence
installation. If you are notified of any files containing such customizations, please make a note
of the locations of these files as you will need to manually migrate their customizations (which
are not mentioned in the overview above) to your upgraded Confluence installation. One
relatively common customization that the upgrade wizard cannot automatically migrate is an SS
L configuration defined in the conf/server.xml file of the Confluence Installation Directory.
Please Note: when upgrading from the version that was not installed by the installer
the customizations can only be detected in the confluence subdirectory of your
existing Confluence Installation Directory. Modifications to files in directories other than conflu
ence will not be detected when you upgrade, for example, modifications to conf/server.xml
. However the next time you upgrade (e.g. to version 4.1.1) the upgrade feature will cover
modifications across the whole Confluence Installation Directory.
c. At the 'Upgrade Check List' step, perform the following steps if you have not already done so:
Back up your external database.
If your Confluence site includes third-party plugins (add-ons), check that they will be
compatible with your upgraded Confluence version. See the documentation: Checking
add-on compatibility with application updates.
d. Upon proceeding, your existing Confluence installation will be shut down if it is still running. The
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 939
d.
upgrade wizard will then:
i. Back up your existing Confluence installation.
ii. Delete the contents of the existing Confluence installation directory.
iii. Install the new version of Confluence to the existing Confluence installation directory.
iv. Starts your new (upgraded) Confluence installation.
If you noted any files that contain customizations which must be migrated manually to
your upgraded Confluence installation (above), then:
1. Stop the upgraded Confluence installation.
2. Migrate the customizations from these files into the upgraded Confluence
Installation Directory.
3. Restart the upgraded Confluence installation.
7. The last step of the upgrade wizard provides you with a link to launch the upgraded Confluence
installation in a browser, so you can check the upgrade.
Congratulations, you have completed upgrading your Confluence installation on Linux!
Finished running the steps to upgrade from 3.5 to 5.0.3? Remember to run them again, upgrading
from 5.0.3 to 5.1.4.
CONFSERVER-26596 - Using color macro inside headings in Wiki Markup results in double headings
RESOLVED
CONFSERVER-23287 - Confluence 4.0 upgrade does not take into account modifications in server.xml
RESOLVED
CONFSERVER-28495 - ConvertToRelativeLinksUpgradeTasks leaves the version comment "Corrected links that should
have been relative instead of absolute." RESOLVED
CONFSERVER-28818 - Upgrading from 3.5.x with accentedpage title, anchors break content
RESOLVED
Getting help
Check for answers from the community. Other users may have encountered the same issue. You
can check for answers from the community at Atlassian Answers.
Did you encounter a problem during the Confluence upgrade? Please refer to the guide to trouble
shooting upgrades in the Confluence Knowledge Base.
If you encounter a problem and cannot solve it, please create a support ticket and one of our
support engineers will help you.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 940
In addition, if you are upgrading from Confluence 3.5 or earlier please note that the change to the
Confluence editing experience is significant. See the guide to Planning for Confluence 4.
If you are using the Team Calendars add-on for Confluence, you will need to upgrade to Team Calendars 3.1
or later. Earlier versions of this add-on will not work with the new design in Confluence 5.0.
As previously announced, from this release onwards we no longer offer support for Java 6 (JRE and JDK
1.6). Please see End of Support Announcements for Confluence.
As previously announced, from this release onwards we no longer offer support for Tomcat 5.5.x. Please see
End of Support Announcements for Confluence.
See the complete list of supported platforms for Confluence 5 at Supported Platforms.
You will notice once you upgrade to Confluence 5.0, every page will have been edited during the migration
process. This manifests itself in the appearance of changes to every page's content by various different
users. When migrating pages, Confluence will show the same username that last contributed to your content
as the author of the change. This is the upgrade task of migrating your wiki page storage format to XHTML
from Wiki Markup. Do not be alarmed by this. This will only happen once for all current versions of content.
This will not trigger email notifications, but will update your RSS feeds. Where possible, a change comment
of "Upgraded to Confluence 4" will be added to pages and blog posts.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 941
After upgrading, user macros will not be able to be inserted until they have defined macro parameters. See U
ser Macro Template Syntax. Defining macro parameters will mean that they can once again insert these user
macros.
Email notifications
With the update of the email templates, the textual content of the notifications has also changed. These
wording changes may invalidate any email filters set up to label or organize your email notifications.
Emails are now only available in HTML format, which allows for the display of images and formatted content,
such as changes made and the full content of the updated page or blog post.
After you have completed the steps required to upgrade your Confluence installation, check all the items on
the Confluence post-upgrade checklist to ensure that everything works as expected. If something is not
working correctly, please check for known Confluence issues and try troubleshooting your upgrade as
described below:
Check for known issues. Sometimes we find out about a problem with the latest version of
Confluence after we have released the software. In such cases we publish information about the
known issues in the Confluence Knowledge Base.
Check for answers from the community. Other users may have encountered the same issue. You
can check for answers from the community at Atlassian Answers.
Did you encounter a problem during the Confluence upgrade? Please refer to the guide to trouble
shooting upgrades in the Confluence Knowledge Base.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
6.
The Confluence Health Check provides a simple way to check the set up of your Confluence instance. The
health check looks at things like your license validity, basic database setup and more.
To access the health check go to
Confluence has an inbuilt log scanner that will check your Confluence logs for errors and try to match them
against known issues in our knowledge base and bug tracker. You'll need Confluence Administrator or
System Administrator permissions to do this.
To use the Confluence log scanner:
1. Go to
If you have an add-on related issue, please check whether the add-on is supported by Atlassian or a third
party developer.
Check support information for the add-on on the Atlassian Marketplace
If the plugin is not supported by Atlassian, you'll need to contact the plugin developer directly.
You can read more about Atlassian support for add-ons.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 943
There are two ways to raise a support request with Atlassian - from within Confluence, or via our support
site.
If your problem concerns user management or performance, please take a look at the additional
requirements in Requesting Support for External User Management or Requesting Performance Support bef
ore creating a request. .
This is the most convenient method, however if your zip file is too large, or there are security restrictions on
your mail server, your request may not be correctly sent. You can also use this method to append system
information to an existing support request.
You'll need Confluence Administrator or System Administrator permissions to do this. Your site will also need
a mail server set up that allows you to send zip files.
To create a support request:
1. Go to
> General Configuration > Support Tools > Create Support Request.
2. Provide as much information as possible, following these guidelines:
Contact Email - this defaults to the email address of the logged-in user. It will be used to find
your support account or, if no account is found, to create a new account. Confluence will send
all further notifications and updates to this address.
Summary - enter a short description of the problem.
Description - enter as much information as possible, including any error messages that are
appearing or any steps our support team can take to reproduce the problem.
Support Data to Attach - choose the log and configuration information you would like to
include. These will be attached to your support request as a zip file, and will help our support
engineers resolve your problem. Refer to Working with Confluence Logs for information about
the log files.
Log files can be very large (up to 20mb with the default log4j configuration, or more if
you've customized the log settings) and your mail server may bounce the message if it is too
large.
3. Choose Send.
We recommend checking whether the email message has been successfully sent, and contacting your
email administrator if you need special provisions for this email message.
Confluence will submit your request via email to Atlassian support. If you don't already have a support
account, we'll automatically create one for you. You'll receive email updates about the request progress. You
can also view the status of your support request and add any additional information at any time at Atlassian
Support.
Screenshot: The support request form.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 944
If your Confluence instance is not running, or does not have a mail server configured, you use the Atlassian
Support site to create a request.
To create a support request:
1. If you don't have a free Atlassian support account, create one here.
2. Log in to https://support.atlassian.com.
3. Follow the prompts to choose your product and type of request.
4. Provide us as much information as possible about your problem, and your Confluence environment.
(If Confluence is running, you can go to System Information in the administration console and copy
that information into your request). You may also want to attach:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
4.
Confluence 6.4 documentation 945
A support zip. See Creating a support zip to find out how to generate it.
Your log files (if your instance won't start up). See Working with Confluence Logs to find out
how to access your log files.
You'll receive email updates about the request progress, and see the status of your request at any time in the
Support site.
We recommend that you attach a support zip file to every interaction with our support team. You'll need
Confluence Administrator or System Administrator permissions to create a support zip.
To create a support zip:
1. Go to
> General Configuration > Support Tools > Create Support Zip.
2. Keep all checkboxes selected then choose Create.
3. Confluence will create the support zip file and display its location on the screen. Log in to the
Confluence server to retrieve the file.
You can then attach the zip file to your support request (a new request or an existing one).
Screenshot: Creating a support zip file
Logging a bug
If you have found a bug, the easiest way to report it is to create numbered instructions on how to reproduce
the bug, create a support request, as described above, and then the Atlassian support team will confirm your
bug and lodge a bug report.
Alternatively, you can check to see if anyone else has reported the bug, then log a bug report yourself.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 946
To report a bug:
1. Go to the Confluence issue tracker.
2. Type keywords for your problem into the Contains text search box then click the Search icon
3. Read through the summaries of the bugs shown. If any summary describes your problem, you can
watch the issue to be notified when something changes, or add more information as a comment.
4. If there's no existing bugs that match your problem, you can create a new bug report - including any
information on how to duplicate the problem.
5. Sometimes it may be useful to include the result of the 500 error page, which you will find at this
location:
https://<domain><host>:<port>/500page.jsp
Atlassian may request a copy of the entities.xml file form your exported zip file (backup file), in order to
diagnose database corruption or to troubleshoot a bug in Confluence.
If your data is confidential, you can run an anonymizer program over your entities.xml file to remove all your
data and leaving only the structure of the export.
Usage
5. Move the original entities.xml file to a different location and then rename cleaned.xml to entitie
s.xml.
6. Re-ZIP the new entities.xml with its exportDescriptor.properties to ensure Atlassian Support
know exactly which version of Confluence the XML backup was exported from.
How it works
The Content Anonymizer replaces all text content in file entities.xml with 'x' characters. For example, the
word "Atlassian" will be transformed to "xxxxxxxxx". The resulting cleaned.xml file is expected to have the
same size as the original file.
This release of the Content Anonymizer uses STX, a fast and efficient XML transformation technology. It should
not require a lot of memory to run, even for a large backup.
Enabling Detailed SQL Logging
Confluence uses the open source persistence framework Hibernate. This
page tells you how to configure Confluence's logging to report individual
SQL requests that are sent to the database by Hibernate. It is useful for
troubleshooting the following events:
XML site backups that fail to import.
Exceptions caused by an illegal database operation.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 947
Working
with
Confluenc
e Logs
If you have a database problem and need support assistance, it's a good idea to temporarily enable
detailed SQL logging before sending us the log files. This will assist us in determining what SQL
queries were running during the reported problem. After you've enabled hibernate logging, replicate
the action that you suspect is causing the error. This is the best way to ensure that the Confluence
log file contains relevant SQL logging.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence
5. 6.4 documentation 948
log4j.appender.confluencelog.Threshold=TRACE
6. Start Confluence.
This logging level will persist, even when Confluence is restarted. As SQL logging is very verbose, you
should revert your changes to log4j.properties once you no longer need the additional info.
Sometimes you may see that Confluence is holding onto a chunk of memory over a period of time (for example,
tenured space is increasing close to Xmx). In such a situation, it is useful to find out what is stacking up in the
memory by analyzing the heap dump.
On this page:
Automatically Generating a Heap Dump when Confluence Hits OutOfMemory Error
Manually Generating a Heap Dump when Confluence Stops Responding
Submitting a Heap Dump to Atlassian Support
Typically, we would like to analyze the heap dump produced when Confluence died from an OutOfMemory Error.
For this, you can add additional JVM parameters like below:
If you do not set the HeapDumpPath parameter, by default the heap dump will be saved in the folder where
Tomcat is run from.
If you are setting these parameters in the Windows registry (when running Confluence on Windows as a
service), be sure that each parameter is on its own line.
It is also possible to get a heap dump manually using a JDK bundled tool called jmap, although we recommend
that you use the automatic method above for best result.
For Linux/Solaris-based Operating Systems:
Please execute the following command on Linux OS:
For Windows:
Please find your Confluence process ID (see below) and then execute the command below on a Windows
command line:
To find out the process ID for your Java process in Windows, you can use Process Explorer from Microsoft. This
is what it looks like:
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 949
RELATED TOPICS
To help debug support cases and provide legendary support, Confluence provides stack traces through the
web interface when an error occurs. These stack traces include information about what Confluence was
doing at the time, and some information about your deployment server.
Only non-personal information is supplied such as operating system and version and Java version. With
proper network security, this is not enough information to be considered dangerous. No usernames or
passwords are included.
If Confluence stops responding or you require information on locks being held and waited upon by threads,
then use one of methods described in Generating a Thread Dump Externally.
Our support team may ask you to use this method if the simple thread dump generated within Confluence
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 950
2. Use the process ID from the above to generate the thread dumps:
kill -3 <pid>
This won't kill your server (so long as you included the "-3" option with no space in between).
If you are not running Confluence as a service, you can generate a thread dump directly in the console.
Click the console window and press <CTRL>+BREAK (or SHIFT+CTRL+PAUSE on some keyboards). The
thread dump will print directly to the console.
The JDK (Java Development Kit) includes jstack, which is used for generating thread dumps.
Note: The JRE (Java Runtime Environment) that is bundled with the Confluence installer does not
include jstack. You'll need to have the full JDK installed.
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 951
Output
Thread dumps appear in the catalina.out file in the application directory's logs folder. Search for "thread
dump" in the log file for the beginning of the dump.
Often Support may ask you to generate a sequence of thread dumps over a short period, so that they can
compare what each dump contains and to look for any long running threads that could be the cause of the
performance issue.
You can manually generate multiple thread dumps by executing the command repeatedly, but it is often
easier to use a small script to automate the process. Here's an example that you can adapt to run on your
Linux server:
If you discovered that Confluence died without manual intervention, there may be something goes wrong during
a local Java session. Java will produce a log file that looks like the following: hs_err_pid20929.log.
The location of this log file is usually in the directory where Tomcat is run eg. /bin folder. For Windows
Services, it should be located in where Windows Services are run.
To define the path to the hs_err_pid file, add the following JVM Parameter to your existing ones:
-XX:ErrorFile=./hs_err_pid<$pid>.log
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 analyze the
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 952
results.
On this page:
Configuring YourKit in your JVM
Windows Configuration
Linux/Mac OS X Configuration
Performance Impact
Installing the YourKit Plugin
Download YourKit 6.0 for your platform and follow the installation instructions to install it.
Note: YourKit version 7 is not compatible with the Confluence yourkit plugin.
The following instructions apply to Confluence and Tomcat installations with the Oracle (previously Sun) JDK.
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 CATALINA_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:
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 the JDK, you add the agentlib parameter:
CATALINA_OPTS="$CATALINA_OPTS -Djava.awt.headless=true"
-agentlib:yjpagent "
Performance Impact
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.
Confluence 6.4 documentation 953
-agentlib:yjpagent=disablecounts,disablealloc,disablej2ee
See also Profiling overhead: how to reduce or avoid in the YourKit documentation.
Download the plugin and upload it into Confluence through the Administration, Plugins page.
A new menu option, "YourKit Profiling' will appear under the 'Administration' heading. Click it and you should see
the options to take a memory or CPU snapshot.
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.
Screenshot: You can take a memory or CPU snapshot
-agentlib:yjpagent=onexit=memory
Created in 2017 by Atlassian. Licensed under a Creative Commons Attribution 2.5 Australia License.