Configuring WebCC with Custom Parameters on Windows

WebCC can run with no parameters, but it also provides some customization options. Among other things, you can change the port number, adjust its security settings and configure it to run with SSL security.

If you installed WebCC as a Windows service, you can customize its parameters by modifying its command line in the Harmony Control Panel. If you use Service Launcher to run WebCC, you can easily add parameters in the Other Parameters field of the WebCC tab of Service Launcher.

TIP: You can also configure WebCC to run a custom script or executable every time a user updates a scene, whether by importing it or by updating it from Harmony. To do this, on the WebCC server, set the environment variable WEBCC_POST_IMPORT_SCRIPT to the path of a script or executable that you want to be launched each time a scene is updated. The script or executable will be launched with the environment, job and scene name as its command line parameters, in that order.

WebCC Parameters Table

The following is a table of parameters that can be specified to customize the behaviour of your WebCC server. They can be used in both the WebCC shell script and in Service Launcher.

Parameter Description

-numWorkers <number>

The amount of server nodes to launch to process client requests. Each node requires one CPU core, and a single node can only process one client request at a time. Therefore, the more nodes are launched, the less likely the server is to stall under heavy load.

If this parameter is not specified, WebCC will use as many nodes as there are CPU cores on the server.

-noAuth

Disables authentication. With this option enabled, any user accessing the WebCC web interface will be logged in as usabatch and will administrative privileges on the entire database.

-port <port number>

The port to which HarmonyWebCC is deployed.

The default port for accessing WebCC is 8080. For browsers to access WebCC without specifying the port number, you can use port 80.

NOTE: If either the -http or -https parameter is specified, the -port parameter will be ignored.

-exchange <directory>

The location of the exchange directory on the local filesystem. This directory is where all packages are stored when exporting or importing scenes.

By default, this directory is /USA_DB/exchange.

-cacheDuration <seconds>

The amount of seconds to keep data in the cache. This can be set to any value between 1 and 999999. By default, this is set to 3600.

-allowAllOrigin

Enables cross-origin resource sharing on the WebCC server.

By default, as a standard security measure, only files on the same server as the WebCC server are allowed to use WebCC resources. With this option enabled, it is possible to create web interfaces on other servers that use resources stored on the WebCC server, or to store different modules of WebCC on different servers and let them communicate together.

In most use cases, this option should be disabled to prevent other machines from exploiting resources on the WebCC server.

-disableAnalytics

Disables Google Analytics tracking for all clients. By default, this is enabled.

-permission <user type> <action> <on|off>

Overrides a default permission for the given user type.

At the moment, this parameter can only be used for the user type animator and for the permission import_export_any_scene. Hence, when used with the following syntax, animator-type users can export and import any scene in the database, without requiring the scene to be assigned to them first.

-permission animator import_export_any_scene on

 

HTTPS/SSL Parameters Table

The following parameters can be used to enable and configure SSL for your WebCC server.

NOTE: For more information on how to configure WebCC with SSL, see About SSL, HTTPS and WebCC on Windows.
Parameter Description

-https <port number>

Enables connection to the server through the https protocol using the specified port number.

A commonly used port for accessing WebCC through the https protocol is 8443. For web browsers to access WebCC via https without specifying the port number—provided that the address of the server is preceded by https://—you can use port 443.

For https to work, you must either specify a pair of PEM format key and certificate with the -key and -cert option, or a PFX format certificate with the -pfx option.

-http <port number>

If access through the https protocol is enabled, this parameter allows you to also allow access through the http protocol through the specified port.

Using this parameter is optional. If the -https parameter is specified, but not the -http parameter, WebCC will only accept connections through https.

The default port for accessing WebCC through the http protocol is 8080. For browsers to access WebCC via http without specifying the port number, you can use port 80.

-key <key file>

The location of the private key file for the SSL session. This must be specified along with the -cert parameter.

The private key must be in Privacy Enhanced Mail (PEM) format, which is an ASCII format where the key is encoded in Base64 and located between -----BEGIN PRVATE KEY----- and -----END PRIVATE KEY----- tags. Typically private keys in this format have a .key extension.

-cert <certificate file>

The location of the security certificate file for the SSL session. This must be specified along with the -key parameter.

The certificate must be in Privacy Enhanced Mail (PEM) format, which is an ASCII format where the certificate is encoded in Base64 and located between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags. Typically, such certificates have a .crt, .cer or .pem extension.

-pfx <pfx certificate file>

If you have a Personal Information Exchange (PFX) certificate, you can use this parameter to specify its location, instead of using a PEM certificate and key. Typically, such certificates have a .pfx or .p12 extension. Since these certificates include their own private key, specifying a key with this certificate type is not required.

-ca <root ca certificate file>

If you have a domain certificate that is signed by a certificate authority (CA), this parameter allows you to specify the root CA certificate and/or its intermediate certificates.

If you want to specify several certificates so as to compose the chain going from your domain certificate to the root CA certificate, you can repeat the parameter, like so:

-ca <intermediate certificate 1> -ca <intermediate certificate 2> -ca <root CA certificate>

Typically, you will be able to log on to WebCC using SSL from a Web browser even if WebCC is only configured with your domain certificate, provided that it is signed by a reputable certificate authority. However, if you want project collaborators to be able to use the Download Database Changes and Update Database Scene functionalities in Harmony via SSL, it may be necessary to specify the root CA certificates and/or its intermediates, as Harmony may not otherwise be able to recognize the authority of the CA who signed your certificate.

Typically, you can obtain the root CA certificates or intermediate certificates from the root certificate authority of the certificate authority who signed your domain certificate.

NOTE: If necessary, you can allow Harmony to trust the WebCC server even if it has a self-signed certificate—see Disabling SSL Certificate Validation for WebCC in Harmony.