GitHub Enterprise uses Ubuntu's UFW firewall on the virtual appliance.

After GitHub Enterprise is installed, all required network ports are automatically opened to accept connections. Every non-required port is automatically configured to deny, and the default outgoing policy is configured as allow. Stateful tracking is enabled for any new connections; these are typically network packets with the SYN bit set.

The UFW firewall also opens several other ports that are required for GitHub Enterprise to operate properly. For more information on the UFW ruleset, see the UFW README.

Viewing the default firewall rules

  1. As a site admin, SSH into your GitHub Enterprise instance:

    ssh -p 122 admin@hostname
    
  2. To view the default firewall rules, type sudo ufw status. You should see output similar to the following:

    sudo ufw status
    Status: active
    To                         Action      From
    --                         ------      ----
    ghe-1194                   ALLOW       Anywhere
    ghe-122                    ALLOW       Anywhere
    ghe-161                    ALLOW       Anywhere
    ghe-22                     ALLOW       Anywhere
    ghe-25                     ALLOW       Anywhere
    ghe-443                    ALLOW       Anywhere
    ghe-80                     ALLOW       Anywhere
    ghe-8080                   ALLOW       Anywhere
    ghe-8443                   ALLOW       Anywhere
    ghe-9418                   ALLOW       Anywhere
    ghe-1194 (v6)              ALLOW       Anywhere (v6)
    ghe-122 (v6)               ALLOW       Anywhere (v6)
    ghe-161 (v6)               ALLOW       Anywhere (v6)
    ghe-22 (v6)                ALLOW       Anywhere (v6)
    ghe-25 (v6)                ALLOW       Anywhere (v6)
    ghe-443 (v6)               ALLOW       Anywhere (v6)
    ghe-80 (v6)                ALLOW       Anywhere (v6)
    ghe-8080 (v6)              ALLOW       Anywhere (v6)
    ghe-8443 (v6)              ALLOW       Anywhere (v6)
    ghe-9418 (v6)              ALLOW       Anywhere (v6)
    

Adding custom firewall rules

Tip: Custom firewall rules don't persist after your upgrade GitHub Enterprise. Any customizations that you make to the firewall must be re-applied after running ghe-upgrade. We recommend that you create a script to apply your custom rules in case you need to re-apply them.

Every new GitHub Enterprise release automatically updates the firewall whitelist of allowed services. Administrators can configure their firewall by prepending new rules to it. Below are some examples demonstrating various custom configurations.

Warning: Before you add custom firewall rules, back up your current rules in case you need to reset to a known working state. If you're locked out of your server, contact GitHub Enterprise Support to reconfigure the original firewall rules. Note that restoring the original firewall rules involves downtime for your server.

Example: limiting SSH connections

This example blocks all SSH connections from IP addresses from IP addresses outside the 172.0.0.0/16 network:

  1. As a site admin, SSH into your GitHub Enterprise instance:

    ssh -p 122 admin@hostname
    
  2. To back up your custom firewall rules, use the cpcommand to move the rules to a new file:

    sudo cp -r /lib/ufw ~/ufw.backup
    
  3. To add a new rule that allows SSH connections from 172.0.0.0/16, use the allow command:

    sudo ufw insert 1 allow proto tcp from 172.0.0.0/16 to any port 22
    
  4. To add a new rule that block all other SSH connections, use the block command:

    sudo ufw insert 2 deny 22/tcp
    
  5. To check the status of the change, use the status numbered command:

    sudo ufw status numbered
    Status: active
        To                         Action      From
        --                         ------      ----
    [ 1] 22/tcp                     ALLOW IN    172.0.0.0/16
    [ 2] 22/tcp                     DENY IN     Anywhere
    

Example: blocking excessive connections

This example blocks SSH connections from any IP address that tries to initiate six or more connections within a 30 second period:

  1. As a site admin, SSH into your GitHub Enterprise instance:

    ssh -p 122 admin@hostname
    
  2. To back up your custom firewall rules, use the cpcommand to move the rules to a new file:

    sudo cp -r /lib/ufw ~/ufw.backup
    
  3. To add a new rule that limits SSH connections, use the limit command:

    sudo ufw insert 1 limit 22/tcp
    
  4. To check the status of the change, use the status numbered command:

    sudo ufw status numbered
    Status: active
         To                         Action      From
         --                         ------      ----
    [ 1] 22/tcp                     LIMIT IN    Anywhere
    

Example: blocking Git's server port

This example blocks Git's server port:

  1. As a site admin, SSH into your GitHub Enterprise instance:

    ssh -p 122 admin@hostname
    
  2. To back up your custom firewall rules, use the cpcommand to move the rules to a new file:

    sudo cp -r /lib/ufw ~/ufw.backup
    
  3. To add a new rule that blocks the Git server port, use the deny command:

    sudo ufw insert 1 deny 9418/tcp
    
  4. To check the status of the change, use the status numbered command:

    sudo ufw status numbered
    Status: active
         To                         Action      From
         --                         ------      ----
    [ 1] 9418/tcp                   DENY IN     Anywhere
    

Restoring the default firewall rules

If something goes wrong after you change the firewall rules, you can reset the rules from your original backup.

Warning: If you didn't back up the original rules before making changes to the firewall, contact GitHub Enterprise Support for further assistance.

  1. As a site admin, SSH into your GitHub Enterprise instance:

    ssh -p 122 admin@hostname
    
  2. To restore the previous backup rules, copy them back to the firewall with cp:

    sudo cp -f ~/ufw.backup/*rules /lib/ufw
    
  3. Restart the firewall with the restart command:

    sudo restart ufw
    
  4. Confirm that the rules are back to their defaults with the ufw status command:

    sudo ufw status
    Status: active
    To                         Action      From
    --                         ------      ----
    ghe-1194                   ALLOW       Anywhere
    ghe-122                    ALLOW       Anywhere
    ghe-161                    ALLOW       Anywhere
    ghe-22                     ALLOW       Anywhere
    ghe-25                     ALLOW       Anywhere
    ghe-443                    ALLOW       Anywhere
    ghe-80                     ALLOW       Anywhere
    ghe-8080                   ALLOW       Anywhere
    ghe-8443                   ALLOW       Anywhere
    ghe-9418                   ALLOW       Anywhere
    ghe-1194 (v6)              ALLOW       Anywhere (v6)
    ghe-122 (v6)               ALLOW       Anywhere (v6)
    ghe-161 (v6)               ALLOW       Anywhere (v6)
    ghe-22 (v6)                ALLOW       Anywhere (v6)
    ghe-25 (v6)                ALLOW       Anywhere (v6)
    ghe-443 (v6)               ALLOW       Anywhere (v6)
    ghe-80 (v6)                ALLOW       Anywhere (v6)
    ghe-8080 (v6)              ALLOW       Anywhere (v6)
    ghe-8443 (v6)              ALLOW       Anywhere (v6)
    ghe-9418 (v6)              ALLOW       Anywhere (v6)