# Stash Latest (2.12) : Setting up SSH port forwarding

Created and last modified by pwatson on Oct 22, 2013

## Why set up port forwarding?

There are two scenarios where you might want to set up port forwarding.

### Remove port numbers from your SSH URLs

Stash listens for SSH connections on port 7999 by default.

Your users will need to include the port in the URL they use to clone from Stash, for example:

    git clone ssh://git@stash.mycompany.com:7999/PROJECT/repo.git

Rather than have the port number in the URL, you may wish to set up port forwarding so that connections to the default SSH port are forwarded to the port Stash is listening on (e.g. you could forward port 22 to port 7999).

This would allow your users to use a URL without a port number in it, like this:

     git clone ssh://git@stash.mycompany.com/PROJECT/repo.git

### Stash is running behind a reverse proxy on a separate machine

You may be following our instructions for setting up Stash behind an Apache front-end.

In this case, your users may not be able to access Stash directly for SSH connections, or if they can, you may wish to make the SSH and HTTPS URLs consistent.

For example, if you have the above topology, without port forwarding (and assuming the default port of 7999), your users will need to clone Stash directly from the backend, like this:

    git clone ssh://git@stash.backend.atlassian.com:7999/PROJECT/repo.git

In your network, the `stash.backend.atlassian.com` machine may not be accessible directly, or you may want the URL to be consistent with the HTTPS URL of `https://stash.atlassian.com/scm/PROJECT/repo.git`.

In this case, you need to set up port forwarding on the `stash.atlassian.com` machine to accept connections and forward them to port 7999 on the `stash.backend.atlassian.com` machine.

# How to set up port forwarding

### HAProxy

Atlassian recommends the use of HAProxy for forwarding SSH connections through to Stash.

HAProxy is supported on Linux, Solaris and FreeBSD.

Icon

HAProxy is not an Atlassian product, so Atlassian does not guarantee to provide support for its configuration. T his section is provided for your information only – use it at your own risk. We recommend that you refer to the HAProxy documentation.

### Installing HAProxy

Your Operating System may support installing HAProxy via it's system package manager, such as `apt-get`, `yum` or `rpm`. This will be the easiest way.

Alternatively, you may build HAProxy yourself and install it.

1. Download the latest version of HAProxy from http://haproxy.1wt.eu/#down.

2. Extract the archive and cd into the directory:

       tar xzvf haproxy-1.4.21.tar.gz
       cd haproxy-1.4.21

3. Read the instructions in the README for how to build on your system. This is generally quite simple - on a Linux 64 bit 2.6 Kernel, the command is:

       make TARGET=linux26 ARCH=x86_64

4. If it completes successfully, install it following the instructions in the README:

       sudo make install

### Configuring HAProxy

HAProxy is extremely powerful - it is designed as a HTTPS load balancer, but also can serve as a port forwarder for ssh.

The full documentation for version 1.4 is here. More documentation is available on the HAProxy web site.

An example simple configuration is as follows:

    global
           daemon
           maxconn 10000

    defaults
           timeout connect 500s
           timeout client 5000s
           timeout server 1h

    frontend sshd
           bind *:7999
           default_backend ssh
           timeout client 1h

    backend ssh
           mode tcp
           server localhost-stash-ssh 127.0.0.1:7999 check port 7999

The above configuration will listen on port 7999 (indicated by the `bind` directive) on all network interfaces. As indicated by the `server` directive, traffic is forwarded to 127.0.0.1, port 7999. You will need to replace `127.0.0.1` with the IP address of the machine running Stash.

You can check your configuration by running:

    haproxy -f haproxyconf.txt -c

To run haproxy, simply start it using

    haproxy -f haproxyconf.txt

Icon

If you use HAProxy to additionally proxy HTTP traffic, ensure that the running `mode` configuration is set to `http`:

    backend http
           mode http
    	   bind *:80
           server localhost-stash-http 127.0.0.1:7990

#### Using the default SSH port

You can configure HAProxy to listen on the default SSH port instead, so that the port does not need to be specified in the clone URL.

By default, the normal ssh daemon is running on port 22. You have several options:

- Configure HAProxy to listen on an alternate port as in the previous example.
- Configure multiple network interfaces on the physical machine and force the default ssh daemon to listen on all but the interface for accessing Stash. Configure HAProxy to only listen on that interface.
- Move the default ssh daemon to listen on another port and let HAProxy bind on port 22.

We do not provide instructions on the last two options, except for how to configure HAProxy.

Use the same configuration as the last example, but change the bind port to 22, e.g.

    ...
    frontend sshd
           bind *:22
    ...

You will have to run this configuration as the `root` user, using `sudo`, because it specifies a port to listen on that is less than 1024.

    sudo haproxy -f haproxyconf.txt

## Configuring the SSH base URL

Once port forwarding is set up, you will need to configure the SSH base URL in Stash so that the clone urls presented in Stash indicate the correct host and port to clone from. See the SSH base URL section in Enabling SSH access to Git repositories in Stash.