Skip to main content

This version of GitHub Enterprise Server was discontinued on 2024-09-25. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Cluster network configuration

A GitHub Enterprise Server cluster requires proper DNS name resolution, load balancing, and communication between nodes.

Who can use this feature?

GitHub determines eligibility for clustering, and must enable the configuration for your instance's license. Clustering requires careful planning and additional administrative overhead. For more information, see "About clustering."

About networking for a GitHub Enterprise Server cluster

Each node in your GitHub Enterprise Server cluster must be able to communicate with all of the other nodes in the cluster over the network. You can review the required ports and protocols for end users, administration, and communication between nodes. To distribute traffic among front-end nodes, GitHub recommends that you configure an external load balancer.

Network considerations

The simplest network design for clustering is to place the nodes on a single LAN. If a cluster must span subnetworks, we do not recommend configuring any firewall rules between the networks. The latency between nodes should be less than 1 millisecond.

The latency between primary and replica nodes must be less than 70 milliseconds. We don't recommend configuring a firewall between the nodes' networks.

Application ports for end users

Application ports provide web application and Git access for end users.

PortDescriptionEncrypted
22/TCPGit over SSH
25/TCPSMTPRequires STARTTLS
80/TCPHTTP

When SSL is enabled this port redirects to HTTPS
443/TCPHTTPS
9418/TCPSimple Git protocol port
(Disabled in private mode)

Administrative ports

Administrative ports are not required for basic application use by end users.

PortDescriptionEncrypted
ICMPICMP Ping
122/TCPAdministrative SSH
161/UDPSNMP
8080/TCPManagement Console HTTP

When SSL is enabled this port redirects to HTTPS
8443/TCPManagement Console HTTPS

Cluster communication ports

If a network level firewall is in place between nodes, these ports will need to be accessible. The communication between nodes is not encrypted. These ports should not be accessible externally.

PortDescription
1336/TCPInternal API
3033/TCPInternal SVN access
3037/TCPInternal SVN access
3306/TCPMySQL
4486/TCPGovernor access
5115/TCPStorage backend
5208/TCPInternal SVN access
6379/TCPRedis
8001/TCPGrafana
8090/TCPInternal GPG access
8149/TCPGitRPC file server access
8300/TCPConsul
8301/TCPConsul
8302/TCPConsul
9000/TCPGit Daemon
9102/TCPPages file server
9105/TCPLFS server
9200/TCPElasticsearch
9203/TCPSemantic code service
9300/TCPElasticsearch
11211/TCPMemcache
161/UDPSNMP
8125/UDPStatsd
8301/UDPConsul
8302/UDPConsul
25827/UDPCollectd

Configuring a load balancer

We recommend an external TCP-based load balancer that supports the PROXY protocol to distribute traffic across nodes. Consider these load balancer configurations:

  • TCP ports (shown below) should be forwarded to nodes running the web-server service. These are the only nodes that serve external client requests.
  • Sticky sessions shouldn't be enabled.

Warning

When terminating HTTPS connections on a load balancer, the requests from the load balancer to GitHub Enterprise Server also need to use HTTPS. Downgrading the connection to HTTP is not supported.

Handling client connection information

Because client connections to the cluster come from the load balancer, the client IP address can be lost. To properly capture the client connection information, additional consideration is required.

If your load balancer can support it, we strongly recommend implementing the PROXY protocol. When no PROXY support is available, it is also possible to load balance the HTTP and HTTPS ports using the X-Forwarded-For header.

Caution

When either PROXY support or HTTP forwarding is enabled, it is critical that no external traffic can directly reach the GitHub Enterprise Server appliances. If external traffic is not properly blocked, the source IP addresses can be forged.

Enabling PROXY support on GitHub Enterprise Server

We strongly recommend enabling PROXY support for both your instance and the load balancer.

Note

GitHub Enterprise Server supports PROXY Protocol V1, which is incompatible with AWS Network Load Balancers. If you use AWS Network Load Balancers with GitHub Enterprise Server, do not enable PROXY support.

  • For your instance, use this command:

    ghe-config 'loadbalancer.proxy-protocol' 'true' && ghe-cluster-config-apply
    
  • For the load balancer, use the instructions provided by your vendor.

PROXY protocol TCP port mappings

Source portDestination portService description
2223Git over SSH
8081HTTP
443444HTTPS
80808081Management Console HTTP
84438444Management Console HTTPS
94189419Git

Enabling X-Forwarded-For support on GitHub Enterprise Server

Use the X-Forwarded-For protocol only when the PROXY protocol is unavailable. The X-Forwarded-For header is compatible with HTTP and HTTPS only. For Git connections over SSH, the IP address reported will be that of the load balancer. In some environments, client IP addresses in the instance's audit log may incorrectly appear as 127.0.0.1.

To enable the X-Forwarded-For header, use this command:

ghe-config 'loadbalancer.http-forward' 'true' && ghe-cluster-config-apply

Protocol TCP port mappings for use without PROXY support

Source portDestination portService description
2222Git over SSH
2525SMTP
8080HTTP
443443HTTPS
80808080Management Console HTTP
84438443Management Console HTTPS

Configuring health checks

Health checks allow a load balancer to stop sending traffic to a node that is not responding if a pre-configured check fails on that node. If a cluster node fails, health checks paired with redundant nodes provides high availability.

Configure the load balancer to check the following URL.

http(s)://HOSTNAME/status

The endpoint will return status code 200 (OK) if the node is healthy and available to service end-user requests. For more information, see "Monitoring a high-availability configuration."

Note

When the appliance is in maintenance mode, the https://HOSTNAME/status URL will return status code 503 (Service Unavailable). For more information, see "Enabling and scheduling maintenance mode."

DNS requirements

DNS lookups for the GitHub Enterprise Server hostname should resolve to the load balancer. We recommend that you enable subdomain isolation. If subdomain isolation is enabled, an additional wildcard record (*.HOSTNAME) should also resolve to the load balancer. For more information, see "Enabling subdomain isolation."