In order to do global configuration, it is necessary to be logged in as a global administrator.

Plugin Mechanism

Sonar has been designed to be extensible. Since we believe in the 'eat your own food' philosophy, Sonar is a suite of plugins that use the extension mechanism.

In order to configure these plugins, log in as an administrator, go to Settings > Configuration > General Settings.

Backup / Restore

The whole Sonar configuration can be backed up and restored. This includes: Quality profiles (rules + alerts), manual metrics, events categories, global settings section (plugins) and customization.

WARNING When restoring , it will wipe ALL existing configuration No information about project configuration gets backed up (exclusions, links, quality profile associated...)

Overview

The Quality Profiles service is the nervous center of Sonar. It enables to define the various sets of source code requirements that should be used when measuring the quality of projects. It also enables to define acceptable thresholds on measures and to trigger alerts when they are reached.

A source code requirement is materialized by a coding rule in Sonar that is active, configured and has a severity. Here is an example: "A method must not have a complexity greater than 10!". Out of the box, Sonar embarks for the Java language several coding rules (requirements) engines: Checkstyle, PMD and Findbugs. It also provides its own engine for advanced requirements. This represents more than 700 rules in total.

A quality profile is a set of source code requirements. Sonar enables to define several quality profiles to fit various types of projects. Indeed, the requirements are usually not the same when starting to develop from scratch an application or when maintaining an application which is 10 years old, when developing a technical library or a web application. A quality profile is also a set of visual alerts on measures. Here is an example of alert: "Highlight the complexity by method measure in the project's dashboard when its complexity by method is greater than 3."

Here is the entry page of the "Quality Profiles" service:

Security

The Quality Profiles service can be accessed by any users (even anonymous users) but any changes (create, edit or delete) require to be logged in as a global administrator.

A project administrator can only change the quality profiles associated to its project(s). See Project Administration#SettingQualityProfiles.

Creating Profile

To create a quality profile, click on the Create button on the upper right and enter the name of the quality profile:

You can optionally provide some Checkstyle, PMD and Findbugs configuration files to fill the new quality profile with some existing rules configurations.

Copying Profile

In order to copy an existing quality profile, click on the Copy button next to the profile you want to copy. You are prompted to give the name of the new profile. The profile is the exact copy of the copied one. You can then make desired changes to the new quality profile.

Renaming Profile

Click on the Rename button. You are prompted to give the new name of the profile.

Deleting Profile

Click on the Delete button. You are prompted to confirm the deletion.
Deleting a quality profile will delete the alerts defined in the profile and will remove the association with projects. If nothing else is done, Sonar will use the default profile to perform the next analysis on the (ex-)associated projects.

Editing Profile

Configuring Rules

The rules configuration tab is the default page where you land when entering a profile. As there are numerous rules available, a very handy search engine is available in the rules configuration screen to filter only the ones to configure:

A rule can be activated or deactivated in a single click. Its severity and configuration in the profile can be changed as soon as it is activated.

Some "Bulk Change" actions are also available to quickly activate or deactivate a set of rules. For instance, you can easily add all Findbugs rules to an existing quality profile by: selecting this profile, searching for Findbugs rules and launching "Activate all" action:

No extra validation action is required to make changes to the profile.

Multiple Activations of a Rule

Some rules can be activated multiple times in the same quality profile with different parameters values. Checkstyle Regexp Singleline rule and PMD XPath rule are those kinds of rule.

If a rule can be activated multiple times, a Copy button is available at the end of the rule description:

Clicking on the Copy rule button displays a form to define the new rule from the parent one:

Once the new rule has been created, it can be managed as any other rules:

Editing Alerts

To manage alerts configuration, use the Alerts tab: 



From there it is possible to fully manage alerts, by adding new ones, editing or deleting existing ones. Choose:

• the metric you are interested in
• whether the alert will be checked against the current value of the measure or the variation of this measure (available since Sonar 3.4)
• an operator (is greater than, is less than, etc.)
• the value that will trigger a warning
• the value that will trigger an error

Any changes will apply to the next analysis.

Profile Inheritance

Maintaining Quality Profiles can be tedious over time, especially where there are many. To ease maintenance of profiles, Sonar provides the ability of inheriting from a profile. The principle is that for a custom profile, you can decide that it is going to have a parent profile by using the Profile Inheritance tab:

This means that the quality profile inherits all rules defined in the parent. This is shown visually in the rules configuration screen by a small blue marker next to the rule:

A rule inherited from a parent cannot be de-activated but it is possible to change its parameter(s) and / or its severity. As soon as one of those is changed, a red marker replaces the blue marker:

Changes made to an inherited rule can be reverted by using the button Revert to parent definition:

Alerts are not inherited from parent profiles.

Extending Rules Description

Each rule comes with a description in Sonar, but it sometimes needs to be extended: insufficient description, internal description, note on activation of a rule in a profile... This is why Sonar enables to extend rules description in two ways:

First the ability to extend the description of a rule to give more details for example. This is going to be attached to the rule in every profile and will also be available when clicking on a violation:

But we have also added the ability to comment a rule in the context of a specific quality profile, to comment for example why it has been assigned a high priority or a special threshold:

Associating Project to Quality Profile

To associate projects to a quality profile or to dissociate projects from a quality profile, go to the Projects tab:

When a project is not explicitly associated to a quality profile, Sonar uses the default quality profile to perform the next analysis.

Backuping/Restoring Profile

This backup/restore mechanism is useful for instance to promote a quality profile from a test environment to a production environment or to share quality profiles with contractors.

Click on the Backup button to export an XML file.

To restore a quality profile, click on the Restore profile link on the upper right of the Quality profiles page, choose the XML file to restore and click on the Restore profile button:

Comparing Profiles

It is possible to compare 2 quality profiles to understand the differences between them:

The comparison service shows all differences (rules in one profile but not in the other, parameters differences) and also identical ones:

Version Control

Every time a change is made to a quality profile, it is going to appear in the changes log:

Rules extensions

See Extending Coding Rules for detailed information and tutorials.

Sonar comes out of the box with a complete mechanism to manage security. Configuring security in Sonar enables to cover two main use cases:

• Manage access rights to resources, information, etc.
• Enable customization (custom dashboards, notifications, etc.) of Sonar for users

Built-in Security

Authentication

Default Admin Credentials

When installing Sonar, a unique user gets created:

• Login: admin
• Password: admin

Log in and click on your name (the top right of the screen).

Enter the old password, the new one and confirm it:

LDAP plugin When the LDAP plugin is installed and activated, it is no longer possible for users to change their password. Then, only system administrators can do so through Settings > Security > Users.

Authorization

The way authorization is implemented in Sonar is pretty standard. It is possible to create as many users and groups of users as required in the system. The users can then be attached (or not) to (multiple) groups. Groups and / or users are then given (multiple) roles. The roles grant access to projects, services and functionalities in Sonar.

Groups

Overview

A group is a set of users.

To create a new group, go to Configuration > Groups > Add new group:

To add/remove users to/from a group:

Special groups

Two groups have a special status in Sonar:

• Anyone is a group that exists in the system, but that cannot be managed. Every user belongs to this group.
• sonar-users is the group to which users are automatically added. This group can be changed through the Security Global Settings. See Global Security Settings, property sonar.defaultGroup for more information.

Roles

Overview

There are 4 roles in Sonar, 1 is global, the 3 others are defined at project level:

• Global roles:
  • Global Administrators: have the ability to perform all administration tasks on the Sonar instance like global configuration, customization of the home page, of the time machine, etc.

• Project roles:
  • Administrators: have the ability to perform administration tasks for a project by accessing its settings
  • Users: have the ability to navigate through every service of a project, except viewing source code and settings
  • Code viewers: have the ability to view source code of a project

Default project roles

It is possible to configure the system so that when a new project is created, some users/groups are automatically granted roles on this project.

In the example below, once a new project has been created:

• All the users in the sonar-administrators group can administrate (Administrators), access the project (Users) and browse the source code (Code viewers).
• The myAuditor user can access access the project (Users) and browse the source code (Code viewers).

Security Settings

1. Default user group: any new user created will automatically join this group.
2. Force user authentication: this is really the first question that should be answered when setting the security strategy in Sonar. Can anybody browse the Sonar instance or do you need to be authenticated?
3. Allow users to sign up online: this means that anybody can access a form to create himself an account in the system. Note that after filling up the form, the user should log in.
4. Import sources: if set to false, source code will not be accessible for any user, to restrict access to source code for some users only, see Code viewers role.

Delegation to an External System

In order to leverage existing infrastructures, Sonar provides the capability of delegating authentication and authorization to external systems through plugins:

• LDAP with the Sonar LDAP Plugin
• Active Directory with the Sonar LDAP Plugin
• PAM with the Sonar PAM Plugin
• Crowd with the Sonar Crowd Plugin

Settings Encryption

Encryption of settings is available since release 3.0.1.

Encryption is mostly used to remove clear passwords from settings, ie the database or SCM credentials. The implemented solution is based on a symetric key algorithm. The keypoint is that the secret key is stored in a secured file on disk. This file must be readable and owned by only the system account that executes the different Java process (Maven Plugin, Ant task, continuous integration server, sonar server, ...).

The algorithm is AES 128 bits. Note that 256 bits cipher is not used because it's not supported by default on all Java Virtual Machines (see this article).

How to generate the secret key

An unique secret key is shared between all the parts of the Sonar infrastructure (server and code analyzers). It is generated online with the administration console (Configuration > General Settings > Encryption). Follow the instructions to store the key in a secured file on the server, generally in ~/.sonar/sonar-secret.txt. If the file is elsewhere, then declare its path with the property sonar.secretKeyPath in conf/sonar.properties and restart the server.

If you want to encrypt properties that are used by code analyzers, then copy the file on all the required machines. Use the same property sonar.secretKeyPath to change the default location.

When this is done, you can start encrypting settings.

How to encrypt settings

The administration console used to generate the secret key allows also to encrypt text values. Simply copy the encrypted texts in the appropriate locations.

Troubleshooting

See the Security section of the FAQ.