Hub Help

Proxy Configuration

Note: <hub_home>/directory_name should be read as “open the console and change directory to directory_name under Hub home directory.”

All commands listed below are Unix/Linux/Mac OS X commands. If you’re working on a Windows server, simply replace .sh with .bat.

Configuring Hub to Work Behind Reverse Proxy

You can set up Hub to work behind a reverse proxy server.

Start with configuring Hub to use a Base URL (the URL that end users will request for to access your Hub installation):

<hub_home>/bin/hub.sh configure --listen-port 1111 --base-url http://hub.mydomain.com:2222

where:

  • 1111 is the port number Hub will listen to
  • http://hub.mydomain.com is the address of your proxy server
  • 2222 is the port number your proxy will listen to

NOTE: Make sure to execute configure command on behalf of the same OS user that runs Hub service itself. This command creates configuration files and folders; Hub service user should have enough file system permissions to access them afterwards.

Now configure headers in your proxy server, and you’re done. Configuration guidelines for Nginx, Apache HTTP Server, and IIS are provided below.

Nginx configuration

Sample Nginx headers configuration (non SSL)

server { listen 2222; server_name localhost; location / { proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_pass http://hubmachine.domain.local:1111; } }

where:

  • listen 2222 is the port that you have previously specified as a --base-url parameter
  • proxy_pass http://hubmachine.domain.local:1111 is the path to your Hub machine with the port that you have previously specified using the -–listen-port command

Sample Nginx headers configuration (SSL)

server { listen 443 ssl; ssl_certificate <path_to_certificate> ssl_certificate_key <path_to_key> server_name localhost; location / { proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_pass http://hubmachine.domain.local:1111; } }

Note: Please refer to the corresponding Nginx documentation pages for a description of server_name, proxy_set_header , proxy_pass.

Converting Java Key Store to Format Required by Nginx

If you currently use Java Key Store, in order to configure SSL terminating proxy with Nginx you must convert it to the format required by Nginx — PKCS12 key store.

You will use keytool and openssl to perform conversion.

To get a PKCS12 key store:

  1. Convert your current .jks file to PKCS12 key store format .p12:
    keytool -importkeystore -srckeystore oldkeystore.jks -destkeystore newkeystore.p12 -deststoretype PKCS12 Enter destination keystore password: [enter private key password from oldkeystore.jks, it will be password for newkeystore.p12] Re-enter new password: [same as above] Enter source keystore password: [enter password for oldkeystore.jks] ... Enter key password for <key alias name> [enter private key password from oldkeystore.jks] ...

    Note: You will be required to enter a "destination keystore password". If your .jks keystore contains a private key with a password, then the "destination keystore password" should equal the password of the private key.

  2. List the new keystore file contents:
    keytool -deststoretype PKCS12 -keystore newkeystore.p12 -list Enter keystore password: [enter password for newkeystore.p12 provided on step 1] ...
  3. Extract pem (certificate) from .p12 keystore file:
    openssl pkcs12 -nokeys -in newkeystore.p12 -out certfile.pem Enter Import Password: [enter password for newkeystore.p12 provided on step 1] ...
  4. Extract unencrypted key file from .p12 keystore file:
    openssl pkcs12 -nocerts -nodes -in newkeystore.p12 -out keyfile.key Enter Import Password: [enter password for newkeystore.p12 provided on step 1] ...

Apache HTTP server configuration

Make sure to enable proxy_http, rewrite modules (and optionally headers if you want to use SSL) using the a2enmod script:

$ a2enmod headers $ a2enmod rewrite $ a2enmod proxy_http

Add the following directives to the VirtualHost section of a relevant .conf file:

DefaultType none RewriteEngine on AllowEncodedSlashes on RewriteCond %{QUERY_STRING} transport=polling RewriteRule /(.*)$ http://127.0.0.1:1111/$1 [P] ProxyRequests off ProxyPass / http://127.0.0.1:1111/ ProxyPassReverse / http://127.0.0.1:1111/

where 1111 is the port number you configured Hub to listen to.

If you want to use SSL, additionally add the following directives to the VirtualHost section:

RequestHeader set X-Forwarded-Proto "https"

IIS reverse proxy

Note: Please make sure that Anonymous Auth is enabled in IIS!

To use IIS and ARR as a reverse proxy:

  1. Install ARR from here
  2. In IIS Manager, connect to the IIS server - in this case, localhost.
  3. Highlight the server in the Connections pane.
  4. Double-click URL Rewrite.
  5. Click View server variables on the right pane.
  6. Add HTTP_X_FORWARDED_HOST, HTTP_X_FORWARDED_SCHEMA, and HTTP_X_FORWARDED_PROTO to the list.
  7. Highlight the server in the Connections pane.
  8. Double-click Application Request Routing Cache.
  9. Click Server Proxy Settings under the Proxy heading in the Actions pane.
  10. Tick the Enable proxy checkbox.
  11. Clear the Reverse rewrite host in response headers checkbox and then click Apply.
  12. In the Connections pane, under Sites, highlight Default Web Site.
  13. Double-click the URL Rewrite feature, and click Add Rule(s)… in the Actions pane.
  14. Add a reverse proxy rule, with server name: localhost:1111 (replace with real location and port of your Hub service).
  15. Open created rule, check rewrite url, add server variables:
    • set HTTP_X_FORWARDED_HOST to {HTTP_HOST}
    • set HTTP_X_FORWARDED_SCHEMA to https (if the IIS site is configured to https, else set to http)
    • set HTTP_X_FORWARDED_PROTO to https (if the IIS site is configured to https, else set to http)
Last modified: 2 June 2016