Proxy Server

Overview

The Proxy Server is an application that allows the Deadline Client applications to connect to a Deadline farm over HTTP, instead of connecting directly to the Deadline Repository and Database. If you would like to connect over HTTPS instead, you will need to set up a web server such as NGINX.

Note that the Proxy Server application itself should NOT be exposed to the internet, as it does not provide built-in support for authentication. This is to ensure that information about your render farm and its users are not open to the internet.

../_images/proxy_overview.png

Running the Proxy Server

To start the Proxy Server:

  • On Windows, you can start the Proxy Service by double clicking on deadlineproxyserver.exe in the Deadline installed folder, usually under

    C:\Program Files\Thinkbox\Deadline[VERSION]\bin
    
  • On Linux, you can start the Proxy Service from a terminal window by running the deadlineproxyserver script in the bin folder, usually under

    /opt/Thinkbox/Deadline[VERSION]/bin
    
  • On Mac OS X, you can start the Proxy Service from a terminal by running the DeadlineProxyServer application in

    /Applications/Thinkbox/Deadline[VERSION]/DeadlineProxyServer[VERSION].app/Contents/MacOS
    

where [VERSION] is the MAJOR release number of Deadline, such as 8.

Setup

Repository Configuration

The default IP and listening Port for newly-launched Proxy Servers can be set in the Deadline Monitor through the “Tools -> Configure Repository Options” menu, under the “Web Service and Proxy Server” tab.

../_images/proxy_configure.png

The options are:

  • IP Address: This is the default IP address the Proxy Server(s) will bind to and listen for incoming traffic. The Recommended value is 0.0.0.0
  • Listening Port: This is the default port the Proxy Servers will attach to. Default port is 8080

Command Line Parameters

You can also control the Proxy Server’s behavior more granularly at runtime with command line parameters. Below is a table of available command-line parameters, they are all specified as follows:

deadlineproxyserver --<param name> <param value>

Available parameters can be queried via deadlineproxyserver –help, but are also provided here for convenience:

Param Name Param Value
ip The IP of the interface on which the Server will accept incoming connections. Defaults to 0.0.0.0.
port The Port on which the Server will accept incoming HTTP Connections. Defaults to 8080.
tls_port The Port on which the Server will accept incoming TLS (HTTPS) Connections. Defaults to 4433.
tls_cert The path to a PKCS#12 file containing an x509 certificate and key used for authentication and encryption during TLS communication. Required to serve HTTPS connections. Not specified by default.
ca_cert The path to a PKCS#12 or PEM file containing an additional trusted root certificate to use when authenticating clients. Not specified by default.

Similarly, there are a couple command line flags (which do not require a value) that help provide additional control over the Proxy Server’s behavior. The syntax for these is like the parameters above, but does not require a value, e.g.:

deadlineproxyserver --<flag name>
Flag Name Flag Behavior
tls_auth If specified, the Server requires Clients to authenticate themselves by presenting an x509 certificate. Otherwise, client certificates will not be required (but still will be validated if presented).
local_only If specified, the Server will only accept incoming requests originating from the local machine (i.e., 127.0.0.1)

Note that the Proxy Server will prioritize parameter values specified in the command line over both the default settings set in the Repository Options (see section above), and in the Local Configuration (see below).

Local Configuration

The values for all the command line parameters described above can also be permanently configured in the Client Configuration ini file, so that they don’t have to be explicitly specified every time the Proxy Server is started. Note that the parameter names in the *.ini file are different (see Client Configuration docs for the list), but the expected values and behavior remain the same.

For ease of configuration, these values can also be changed via Deadline Command. For more details, you can invoke:

deadlinecommand help ConfigureConnectionServer

Finally, the Deadline Launcher can be configured to automatically re-start the Proxy Server in the event of a crash/shutdown via the Client Configuration ini file.

Proxy Servers Panel

The Proxy Servers can be monitored through the Deadline Monitor with the “Proxy Servers” panel. You can use this panel to check the state of the Proxy Servers and to monitor their CPU and memory usage.

../_images/proxy_panel.png

Connecting to the Proxy

The “Change Repository” dialog has been extended to include an option to connect to a Proxy.

../_images/proxy_connect.png

Select the “Use Proxy” radio button and fill in either the DNS or IP address of your Proxy Server and select the correct port number. If connecting with HTTPS, you can place the path to the PFX certificate in the “Client Certificate” text box, and supply the passphrase if required. See our SSL Certificate Generation documentation on how to create the certicates for your chosen web server.

See also Firewall and Security Considerations to ensure you allow the Proxy Server to be accessible through your firewall.

Windows URL Namespace Reservation

If the Proxy Server is running on Windows, you may also need to add a namespace reservation for the current user that the Proxy Server is running under, so that it can reserve namespaces for the URL connection. See the Configuring Namespace Reservations section in this MSDN Article for more information. Note, Windows XP users require SP2 to be installed and XP 64bit does NOT support namespace reservation. It is recommended to use a server based Windows OS such as Windows 2003, 2008 R2, 2012 or newer.

Note that by default, the Proxy Server listens on http://+:8080/, so make sure you set the port number correctly in the URL you use when reserving the namespace. For example:

netsh http add urlacl url=http://+:8080/ user=USERNAME

Ensure you have correctly elevated permissions when executing the above in a command prompt and replace USERNAME with the appropriate %USERNAME% that the Proxy Server is running under. Depending on your local security policy, the user account may need to have local administrator rights temporarily for you to initially reserve the namespace. The namespace reservation will also need updating if you ever modify the port number or user account used. Use the following command in a command prompt to help list what namespace reservations are currently present on your machine:

netsh http show urlacl

Note that this is NOT the same reservation that is required for the Web Service.

Linux Open File Limits

If the Proxy Server is running on Linux, it is recommended that you increase the maximum number of open files for the Proxy Server process. Since socket connections are treated as open files on Linux it is very easy for the default maximum value (1024) to be reached in an active farm. We recommend setting it to at least 64000. You can set by running the following command before running the Proxy Server:

ulimit -n 64000

The Proxy Server will check the file limit on startup and print a warning to the beginning of the log if it is set to a value that is too low, but will run anyway.

HTTPS

The Proxy Server can be configured to authenticate incoming clients and use encrypted communications if needed. To do so, you will need to configure the Proxy Server in the following manner: - ‘TLS Certificate’ must be specified, and be a valid PKCS#12 file containing a certificate and corresponding private key. - ‘TLS Port’ must be specified to be a bindable Port that is not already in use by another application. - ‘TLS Auth’ should be sepecified to require clients connecting to the server to authenticate themselves by presenting a client x509 certificate. - ‘CA Cert’ can optionally be specified to provide an additional trusted Root CA to use when building a trust chain from incoming clients’ certificates.

Note that when configured to serve HTTPS connections, trying to connect to the HTTP Port directly (8080 by default) from an external machine will result in an 403 error being returned.

To create SSL certificates see the SSL Certificate Generation documentation.

In addition to configuring the Proxy Server to handle TLS connections itself, you can also configure a third party Web Server to handle the TLS termination as well. This might be desirable if you are looking to maximize performance, or are also in need of Load Balancing (see section below). In either case, if you are looking to have a third party server handle TLS termination, the Proxy itself would not need any of the above TLS configuration, and should NOT be exposed externally at all. It is also recommended in this case to use the Network Whitelisting feature to restrict incoming connections to only the machine hosting the TLS termination, ensuring that only connections coming through that server are allowed.

Load Balancing

Load Balancing can be achieved using a Web Server such as NGINX. See our NGINX section for instructions on how to get started with a basic setup.

FAQ

Does Proxy Server use any license?

No. It is an unlicensed product and included in the Deadline Client software installer.

Can I run Proxy Server on any machine in my farm?

You can run Proxy Server on any machine in your farm, including the Repository or Database machine. However, for larger farms, we recommend running Proxy Server on a dedicated machine.

When choosing a machine to run Proxy Server on, you should be aware that non-Server editions of Windows have a TCP/IP connection limitation of 10 new connections per second. If your render farm consists of more than 100 machines, it is very likely that you’ll hit this limitation every now and then (and the odds continue to increase as the number of machines increase). Therefore, if you are running Proxy Server on a farm with 100 machines or more, we recommend using a Server edition of Windows, or a different operating system like Linux.

Can I run Proxy Server as a service or daemon?

Yes. If you’re running the Launcher as a service or daemon, then it will run Proxy Server in the background as well. See the Client Installation documentation for more information.

Is Proxy Server used for usage based licensing or 3rd party licensing?

No. This is handled by the Cloud License Server Proxy and License Forwarder application respectively.