Stash is now known as Bitbucket Server.
See the

Unknown macro: {spacejump}

of this page, or visit the Bitbucket Server documentation home page.

If you want to set up SSL access to Stash, when Apache HTTP Server acts as a reverse proxy for Stash, follow steps 1 to 4 below. When you are finished, users will be able to make secure connections to Apache HTTP Server; connections between Apache HTTP Server and Stash will remain unsecured (not using SSL).

Note:

  • The steps on this page would normally be performed after integrating Stash with Apache HTTP Server.
  • It would be possible to set up an SSL connection between Apache HTTP Server and Tomcat (Stash), but that configuration is very unusual, and not recommended in most circumstances.

Step 1: Configure the Tomcat Connector for SSL

Find the normal (non-SSL) Connector directive in Tomcat's server.xml file, and change the  redirectPort ,  scheme  , proxyName and  proxyPort attributes as follows:

On this page:

Related pages:

<Connector port="7990" 
     protocol="HTTP/1.1"
     connectionTimeout="20000"
     useBodyEncodingForURI="true"
     redirectPort="443"
     compression="on"
     compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,application/x-javascript"
     secure="true"
     scheme="https"
     proxyName="mycompany.com" 
     proxyPort="443" />

The redirectPort directive causes Tomcat-initiated redirections to secured resources to use the specified port. Right now, the Stash configuration of Tomcat does not involve Tomcat-initiated redirections, so the change to redirectPort is redundant. Nevertheless, we suggest that you change it as directed above for the sake of completeness.

Start, or restart, Stash.

Step 2: Set up a virtual host in Apache HTTP Server

Un-comment the following LoadModule directive in Apache HTTP Server's httpd.conf file:

LoadModule ssl_module modules/mod_ssl.so

Add the following directives to the httpd.conf file:

Listen 443
<VirtualHost *:443>
    SSLEngine On
    SSLCertificateFile    "/usr/local/apache2/conf/server.crt"
    SSLCertificateKeyFile "/usr/local/apache2/conf/server.key"
    ProxyPass        / http://localhost:7990/ connectiontimeout=5 timeout=300
    ProxyPassReverse / http://localhost:7990/
</VirtualHost>

The  Listen directive instructs Apache HTTP Server to listen for incoming requests on port 443. Actually, we could omit that directive in this case, since Apache HTTP Server listens for https requests on port 443 by default. Nevertheless, it's good to make one's intentions explicit.

The  VirtualHost directive encloses a number of child directives that apply only and always to requests that arrive at port 443. Since our VirtualHost block does not include a ServerName directive, it inherits the server name from the main server configuration.

The  SSLEngine directive toggles the use of the SSL/TLS Protocol Engine. In this case, we're using it to turn SSL on for all requests that arrive at port 443.

The  SSLCertificateFile directive tells Apache HTTP Server where to find the PEM-encoded certificate file for the server.

The  SSLCertificateKeyFile directive tells Apache HTTP Server where to find the PEM-encoded private key file corresponding to the certificate file identified by the SSLCertificateFile directive. Depending on how the certificate file was generated, it may contain a RSA or DSA private key file, making the SSLCertificateKeyFile directive redundant; however, Apache strongly discourages that practice. The recommended approach is to separate the certificate and the private key. If the private key is encrypted, Apache HTTP Server will require a pass phrase to be entered when it starts up.

The ProxyPass and ProxyPassReverse directives should be set up in the manner described in Step 5 of the Integrating Stash with Apache HTTP Server page. In particular, if Stash is to run on a separate machine from Apache, you should use that domain (and perhaps the port number and context path) in the ProxyPass and ProxyPassReverse directives.

For more information about the support for SSL in Apache HTTP Server, refer to the Apache SSL/TLS Encryption manual. In addition, you will find lots of relevant information in the <apache directory>/conf/extra/httpd-ssl.conf file, which is included in the standard Apache distribution.

Start, or restart, Apache.

Step 3: Create SSL certificate and key files

In Step 2, you specified server.crt and server.key as the certificate file and private key file respectively. Those two files must be created before we can proceed. This step assumes that OpenSSL is installed on your server.

Generate a server key file:

openssl genrsa -des3 -out server.key 1024

You will be asked to provide a password. Make sure that the password is strong because it will form the one real entry point into the SSL encryption set-up. Make a note of the password because you'll need it when starting Apache HTTP Server later.

Generate a certificate request file (server.csr):

openssl req -new -key server.key -out server.csr

Generate a self-signed certificate (server.crt): 

openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

The above command generates a self-signed certificate that is valid for one year. You can use the certificate signing request to purchase a certificate from a certificate authority. For testing purposes though, the self-signed certificate will suffice. Copy the certificate file and private key file to the locations you specified in Step 2.

cp server.key /usr/local/apache2/conf/
cp server.crt /usr/local/apache2/conf/

Step 4: Update the base URL for 'https'

Open a browser window and log into Stash using an administrator account. Go to the Stash administration area and click Server s ettings (under 'Settings'). Change Base URL to use 'https', for example, "https://stash.mycompany.com").

Using a self-signed certificate

There are two implications of using the self-signed certificate:

  • When you access Stash in a web browser, you can expect a warning to appear, alerting you that an un-trusted certificate is in use. Before proceeding you will have to indicate to the browser that you trust the certificate.
  • When you perform a git clone operation, SSL verification will fail.
The SSL verification error message will look something like this:

error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed while accessing   https://justme@mycompany/git/TP/test.git

It's easy to fix. Turn SSL verification off for individual git operations by setting the GIT_SSL_NO_VERIFY environment variable. In Unix, you can set the variable in-line with git commands as follows:

GIT_SSL_NO_VERIFY=true git clone   https://justme@mycompany/git/TP/test.git

In Windows you have to set the variable in a separate shell statement:
set GIT_SSL_NO_VERIFY=true
Once you have purchased and installed a signed certificate from a certificate authority, you will no longer have to include the GIT_SSL_NO_VERIFY modifier.
 

 

 

 

 Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.