[Other doc versions]
[Doc downloads (PDF, HTML, XML)]
You can run Stash behind a reverse proxy, such as Apache HTTP Server or nginx, that is secured using HTTPS (HTTP over SSL). You should consider doing this, and making secure access mandatory, if usernames, passwords and other proprietary data may be at risk.
There are other network topology options for running Stash; for an overview of some common options, see Proxying and securing Stash.
When Stash is set up following the instructions on this page, external access to Stash is via Apache HTTP Server as a reverse proxy, where external communication with the proxy uses HTTPS. All communication between the user's browser and Apache will be secured, whereas communication between Apache and Stash will not be secured (it doesn't use SSL).
Note that:
mod_auth_basic
.Find the normal (non-SSL) Connector
directive in Tomcat's server.xml
file, and change the redirectPort
,
scheme
, proxyName
and
proxyPort
attributes as follows:
<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.
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" SSLCertificateChainFile "/usr/local/apache2/conf/server.crt" 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 SSLCertificateChainFile
is optional. Please consult with the CA vendor to verify if this is required. This directive sets the optional all-in-one file where you can assemble the certificates of Certification Authorities (CA) which form the certificate chain of the server certificate.
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.
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.
If you don't wish to specify a password, don't use the -des3
option in the command above.
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/
Open a browser window and log into Stash using an administrator account. Go to the Stash administration area and click Server settings (under 'Settings'). Change Base URL to use 'https', for example, "https://stash.mycompany.com").
There are two implications of using the self-signed certificate:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed while accessing https://justme@mycompany/git/TP/test.git
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
set GIT_SSL_NO_VERIFY=true
git clone https://justme@mycompany/git/TP/test.git
GIT_SSL_NO_VERIFY
modifier.