Operating the server
Running SonarQube Server as a service on Windows
Install or uninstall SonarQube as a service
Start or stop the service
By default, the service will use the Java executable available on the Windows PATH. This setting can be changed by setting the environmental variable SONAR_JAVA_PATH
. See more in Adjusting the Java installation.
> <sonarqubeHome>\bin\windows-x86-64\SonarService.bat stop
does a graceful shutdown where no new analysis report processing can start, but the tasks in progress are allowed to finish. The time a stop will take depends on the processing time of the tasks in progress. You'll need to kill all SonarQube Server processes manually to force a stop.
Service status
Check if the SonarQube service is running:
Running SonarQube Server manually on Linux
Start or stop the instance
Stop does a graceful shutdown where no new analysis report processing can start, but the tasks in progress are allowed to finish. The time a stop will take depends on the processing time of the tasks in progress. Use force stop for a hard stop.
Running SonarQube Server as a service on Linux with systemd
On a Unix system using systemd, you can install SonarQube as a service. You cannot run SonarQube as root in Unix systems. Ideally, you will have created a new account dedicated to the purpose of running SonarQube. Let's suppose:
- The user used to start the service is
sonarqube
- The group used to start the service is
sonarqube
- The Java Virtual Machine is installed in
/opt/java/
- SonarQube has been unzipped into
/opt/sonarqube/
Then create the file /etc/systemd/system/sonarqube.service
based on the following:
- Because the sonar-application jar name ends with the version of SonarQube Server, you will need to adjust the
ExecStart
command accordingly on install and at each upgrade. - All SonarQube Server directories should be owned by the
sonarqube
user. - If you have multiple Java versions, you will need to modify the
java
path in theExecStart
command. This also meansSONAR_JAVA_PATH
will not work with SonarQube Server as a service.
Once your sonarqube.service
file is created and properly configured, run:
Running SonarQube Server as a service on Linux with initd
The following has been tested on Ubuntu 20.04 and CentOS 6.2.
You cannot run SonarQube Server as root
in 'nix systems. Ideally, you will have created a new account dedicated to the purpose of running SonarQube Server. Let's suppose the user used to start the service is sonarqube
. Then create the file /etc/init.d/sonar
based on the following:
Register SonarQube Server at boot time (RedHat, CentOS, 64 bit):
Register SonarQube Server at boot time (Ubuntu, 64 bit):
Once registration is done, run:
Securing SonarQube Server behind a proxy
This section helps you configure SonarQube Server if you want to run it behind a proxy. This can be done for security concerns or to consolidate multiple disparate applications. To run SonarQube Server over HTTPS, see the HTTPS Configuration section below.
For security reasons, we recommend only giving external access to the main port.
Using an Apache Proxy
We assume that you've already installed Apache 2 with module mod_proxy, that SonarQube Server is running and available on http://private_sonar_host:sonar_port/
, and that you want to configure a Virtual Host for www.public_sonar.com
.
At this point, edit the HTTPd configuration file for the www.public_sonar.com
virtual host. Include the following to expose SonarQube Server via mod_proxy
at http://www.public_sonar.com/
Apache configuration is going to vary based on your own application's requirements and the way you intend to expose SonarQube Server to the outside world. If you need more details about Apache HTTPd and mod_proxy, please see https://httpd.apache.org.
Using Nginx
We assume that you've already installed Nginx, that you are using a Virtual Host for www.somecompany.com
and that SonarQube Server is running and available on http://sonarhost:sonarport/
.
At this point, edit the Nginx configuration file. Include the following to expose SonarQube Server at http://www.somecompany.com/
:
Nginx configuration will vary based on your own application's requirements and the way you intend to expose SonarQube Server to the outside world. If you need more details about Nginx, please see https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/.
Note that you may need to increase the max URL length since SonarQube Server requests can have URLs longer than 2048.
Using IIS on Windows
Using IIS on Windows, you can create a website that acts as a reverse proxy and access your SonarQube Server instance over SSL.
Because of possibly long query strings with SonarQube Server web API, you must increase the default maxQueryString
(default is 2048) and maxQueryStringLength
to much larger values. Otherwise, request filtering will be applied which can yield HTTP 404 errors; this may cause projects to not appear on the projects dashboard, for example.
To adjust these values, enter the “Request Filtering” module for your IIS site, right-click, select “Edit Feature Settings…”, and increase the “Maximum query string” value to a much larger value. Alternatively, you can add the following to your web.config
file for the associated IIS site (adjust maxQueryString
and maxQueryStringLength
as needed):
See Request Limits <requestLimits> | Microsoft Learn for more information.
Prerequisites
- Internet Information Services (IIS) enabled. In the following example, IIS is enabled on the same machine as the SonarQube instance.
- The Url Rewrite extension for IIS
- The Application Based Routing extension for IIS
- A self-signed SSL certificate, or a real one
Note that you must import the self-signed certificate to the Java truststore of the machine running the scanner.
To make sure the extensions are enabled, restart your IIS Manager after you install them.
Creating an IIS website
- In the IIS Manager, select Your machine > Sites > Add Website...
- Under Site name, enter a name for your website.
- Under Content Directory > Physical path, select a physical path for your website’s folder. Based on the default IIS website, we recommend creating a
%SystemDrive%\inetpub\wwwroot_sonarqube
folder and using it as a physical path. - In Binding, select Type > https.
- For Host name, enter the hostname you will use to access SonarQube.
- Under SSL certificate, select an SSL certificate.
- Click OK.
Using your IIS website as a reverse proxy
Once you’ve created your website using the IIS Manager, you can use the URL Rewrite extension to use that website as a reverse proxy.
- From the IIS Manager home page, select your website and open URL Rewrite.
- Click Add Rule(s) to create a new rule.
- Select Reverse Proxy from the list of templates.
- Enter the destination server URL. It can be
localhost:9000
or a remote server. - Click OK to create the rule.
The URL Rewrite page now displays a reverse proxy inbound rule.
Adding the HTTP_X_FORWARDED_PROTO server variable
Using the URL Rewrite module, you can create a server variable to handle the HTTP_X_FORWARDED_PROTO
header and pass it to SonarQube. See the HTTPS Configuration section on this page for more information on that server variable.
From the URL Rewrite page:
- Click View Server Variables. This opens the Allowed Server Variables page.
- To add a server variable, click Add..., enter
HTTP_X_FORWARDED_PROTO
in the field and click OK. The server variable is now displayed on the Allowed Server Variables page. - Click Back to Rules to go to the URL Rewrite rules list.
- Select the reverse proxy inbound rule for your website. Under Inbound Rules, click Edit.
- Expand the Server variables section of the rule definition.
- Add the
HTTP_X_FORWARDED_PROTO
server variable and give it the value https. - Apply the changes.
SonarQube can now be accessed over SSL.
If SAML authentication is used
For SAML through IIS, you must perform the following additional steps:
- Make sure the host headers are preserved. This is set at the IIS server level, by executing the following command:
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/proxy -preserveHostHeader:true /commit:apphost
You should then see an output that says something like:
Applied configuration changes to section "system.webServer/proxy" for "MACHINE/WEBROOT/APPHOST" at configuration commit path "MACHINE/WEBROOT/APPHOST"
- Disable the Reverse rewrite host in the response headers as follows:
- At the server level in IIS, go to Application Request Routing > Server proxy settings.
- Uncheck the box Reverse rewrite host in response headers.
- Apply the change.
- Restart IIS.
Checking that the connection is enabled
With your SonarQube instance and your IIS website running, open the IIS Manager and click the link under Your website > Browse Website > Browse, or enter the website’s URL in a browser. You should see the login or home page of your SonarQube instance.
Next steps
You can configure your SonarQube instance to only accept traffic from your reverse proxy, by adding the following line to the sonar.properties
file:
sonar.web.host=127.0.0.1
Another option is to use the Windows Firewall to only accept traffic from localhost.
Resources
The setup described here is inspired by this Configure SSL for SonarQube on Windows blog post.
HTTPS configuration
Forward SonarQube Server custom headers
SonarQube Server adds custom HTTP headers. The reverse proxy should be configured to forward the following headers:
SonarQube-Authentication-Token-Expiration
This header is added to a web service response when using tokens to authenticate. Forwarding this header is not required for the SonarQube Server features to work properly.Sonar-MD5
This header is used to verify the integrity of the plugins downloaded by the scanner. You must forward this header to successfully execute analyses that use plugins.
Secure your network
To further lock down the communication in between the reverse proxy and SonarQube Server, you can define the following network rules:
Protocol | Source | Destination | Port | default |
TCP | Reverse Proxy | SonarQube Server | sonar.web.port | 9000 |
TCP | SonarQube Server | SonarQube Server | sonar.search.port | 9001 |
TCP | SonarQube Server | SonarQube Server | sonar.es.port | random |
You can further segment your network configuration if you specify a frontend network and keep Elasticsearch restricted to the loopback NiC.
Network | Parameter | Description | default |
Frontend | sonar.web.host | Frontend HTTP Network | 0.0.0.0 |
Elasticsearch | sonar.search.host | Elasticsearch Network | 127.0.0.1 |
Was this page helpful?