Setup

Attention

We recommend using the latest config file as a starting point and moving changes from your old config file into the new one.

Configuration values are defined by nested XML elements in the scyld-cloud-workstation.xml config file. In Linux this can be found at /opt/scyld-cloud-workstation/bin/scyld-cloud-workstation.xml and in Windows this can be found at C:\Program Files\Penguin Computing\Scyld Cloud Workstation\scyld-cloud-workstation.xml. This section describes properties in the config file.

For the purpose of this document, we refer to properties by using dot notation. For example, config.Server.LogLevel indicates that LogLevel is a property within Server, which is a property within config. Since all properties begin with ‘config’, for brevity we ignore it. Properties are case-sensitive.

Warning

The config file and private key files contains sensitive information that can compromise security if an attacker can read it. We strongly recommend limiting read and write access to the root / system administrator account.

Warning

Scyld Cloud Workstation includes a default private key, certificate file, username, and password that are not secure and should be changed.

Applying Config File Changes

Saved changes to the config file are only applicable once the service restarts. The Server.Auth.ShadowPassword setting is the one exception to this rule - saved changes to it are applicable immediately.

In Linux you can restart the service using the service command:

service scyld-cloud-workstation restart

In Windows you can restart the service using the Services tool. First open the Task Manager by right-clicking on the Task Bar and select Start Task Manager. At the Task Manager, go to the Services tab and click on Services. Right-click on scyld-cloud-workstation in the the list of services and select Restart from the dropdown of actions.

The Scyld Cloud Workstation sign-in page should return after a few seconds.

Config File Settings

Attention

We recommend using the latest config file as a starting point and moving changes from your old config file into the new one.

The default config file comes with appropriate values for nearly all of the server settings.

In this section we discuss config settings that are commonly changed from the default config file.

License Management

For more information on license management, please see: Flexera License Management.

Server Authentication

User’s are authenticated using credentials defined by the config file or by the ScyldCloudAuth web service. To disable any of these, simply comment out these elements by wrapping them with <!-- and -->.

Authentication is enabled by default and in should not be disabled in production systems. Server.Auth.Enabled should always be set to true.

There are several authentication schemes supported by Scyld Cloud Workstation. Each system is independent and can be enabled in parallel.

  • Config File Authentication
  • ScyldCloudAuth Authentication
  • OS Credential Authentication

Config File Authentication

Config File Authentication uses credentials stored in the config file. The following settings control Config File Authentication:

The ShadowPassword is set by calling scyld-cloud-workstation.sh --passwd in Linux with sudo privileges or scyld-cloud-workstation.bat /passwd in Windows as an Administrator.

Config File Authentication can be disabled by commenting or removing Server.Auth.Username and Server.Auth.ShadowPassword.

ScyldCloudAuth Authentication

ScyldCloudAuth Authentication uses the ScyldCloudAuth proxy service for authentication. To enable ScyldCloudAuth for authentication, set:

ScyldCloudAuth can be disabled by commenting or removing Server.Auth.ScyldCloudAuth.URL.

OS Credential Authentication

The credentials accepted by your remote Windows or Linux host can be used to sign into Scyld Cloud Workstation. This supports ActiveDirectory for Windows, and LDAP / PAM for Linux.

Important

While config file or ScyldCloutAuth usernames can be used to sign in to Scyld Cloud Workstation at any time, only a single set of OS credentials can only be used to sign-in at a time. This prevents different OS credentials from signing in at the same time.

This feature can be disabled by setting Server.Auth.OSAuthEnabled to false or removing it from the config file.

Server Security

The cipher list will determine what ciphers are used to encrypt communication between your clients and your server. It is always a good idea to keep your server’s OpenSSL updated to the latest version.

We recommend using the default values for openSSL.server.cipherList.

Firewall

Your server host’s firewall needs to allows incoming connections to the server over port 443 if you are using use HTTPS or port 80 if you are using HTTP.

In Windows these rules are automatically set by the installer and removed by the uninstaller.

In Linux, you will have to update your firewall using iptables. In most cases, adding the following line to your rules file (CentOS/RHEL: /etc/sysconfig/iptables) and restarting the iptables service will allow incoming HTTPS traffic.

# Allow all https
-A INPUT -p tcp --dport 443 -j ACCEPT

Change 443 to 80 in the line above to accept incoming HTTP traffic over port 80 instead.

HTTPS / SSL Certificates

HTTPS is required to make all of your interactions with the server secure.

To ensure that connections are using the latest TLS protocol (as of 2015), set openSSL.server.requireTLSv1_2 to true and enable HTTPS by setting Server.Secure to true.

Set openSSL.server.privateKeyFile and openSSL.server.certificateFile to the appropriate private key and SSL certificate paths.

If you have set a passphrase for your private key you will need to set openSSL.server.privateKeyPassphraseHandler.options.password.

An SSL certificate signed by a trusted certificate authority (CA) is used to encrypt and authenticate communication between a browser and server. To obtain an SSL certificate from a CA, you need to generate a certificate signing request (CSR) and submit it to the CA. A list of popular CA’s is given below:

Attention

You need to install OpenSSL on your server to complete the setup.

The following sections describe how to use the openSSL command to create a new private key and CSR, a new CSR from an existing private key, and a self-signed SSL certificate (not recommended).

Create a Private Key and a CSR

Use the openssl command to creates a 2048-bit private key (domain.key) and a CSR (domain.csr). If your CA supports SHA-2, add the -sha256 option to sign the CSR with SHA-2.

openssl req -newkey rsa:2048 -nodes -sha256 -keyout domain.key -out domain.csr

Fill out the prompted questions to complete the CSR.

Warning

The contents of your private key should never be shared with anyone.

Create a CSR from an Existing Private Key

To create a CSR from an existing private key:

openssl req -key domain.key -new -out domain.csr

Fill out the prompted questions to complete the CSR.

Create a Private Key and Self-Signed SSL Certificate

You can create a self-signed SSL certificate instead of having one signed by a CA. The disadvantage to this is that in order to establish trust between the browser and the server, you must make a security exception for this certificate when you visit the page or install it in every browser.

openssl req \
        -newkey rsa:2048 -nodes -sha256 -keyout domain.key \
        -x509 -days 365 -out domain.crt

Fill out the prompted questions to complete the CSR.

Warning

The contents of your private key should never be shared with anyone.

Create a Self-Signed SSL Certificate from an Existing Private Key

To create a self-signed certificate from an existing private key:

openssl req \
        -key domain.key -new \
        -x509 -sha256 -days 365 -out domain.crt

Fill out the prompted questions to complete the CSR.

Settings Glossary

In this section we describe all of the settings available in the config file.

Note

All changes to Scyld.Auth settings except Scyld.Auth.Enabled take effect without a service restart.

Server.LogLevel

The verbosity of output in the log file.

The LogLevel value can be any one of the following (ordered least-to-most verbose): ‘none’, ‘fatal’, ‘critical’, ‘error’, ‘warning’, ‘notice’, ‘information’, ‘debug’, and ‘trace’.

Server.LogFormat

Format of the output. By default, Scyld Cloud Workstation does not display a timestamp with each log message. To add timestamps to all of your output, open the scyld-cloud-workstation.xml and set LogFormat to: %Y-%m-%d %H:%M:%S %q%q: %s:%u: %t.

Server.LogFile

A path to the log file of the Scyld Cloud Workstation server. By default this can be found in the directory of the Scyld Cloud Workstation executable and is named scyld-cloud-workstation.log. For more information on log output, see Log Output.

Changed in v5.0.0. Default value changed.

Server.BootLogFile

Windows only. A path to the log file of the Scyld Cloud Workstation meta-server. By default this can be found in the directory of the Scyld Cloud Workstation executable and is named boot.log. For more information on log output, see Log Output.

Changed in v5.0.0. Previously named Server.ServiceLogFile in v2.2.0. Default value changed

Server.LocalCursor

Determines if the client’s local cursor should be shown instead of the remote cursor. Enabling local cursor typically improves the user experience. Defaults to true.

Added in v2.2.0.

Server.AutoLock

Determines if Scyld Cloud Workstation calls on the OS to lock the desktop upon disconnecting from the web page. Experimental. Defaults to false.

Warning

NOTE: In Linux, screen locking is achieved by entering Ctrl+Alt+l on behalf of the user. While this will lock the screen for most, this feature is not guaranteed to work on all Linux systems.

Updated in v5.0.0.

Server.IdleUserTimeout

The length of time (in minutes) that users must be inactive before all users are disconnected. This feature is disabled if value is 0.0 or less. Defaults to 120.

Added in v5.0.0.

Server.Port

The port number used by the server. Defaults to 443 if Server.Secure is true or 80 if Server.Secure is false.

Server.Secure

Determines if the server operates over HTTPS (recommended). Defaults to true.

Server.LicenseFile

Specifies a license file path or a port@host address where a Scyld FlexLM license server is hosted. If the default license server port is being used (27002), then @host is also acceptable. Defaults to scyld-cloud-workstation.lic.

For more information on installing license files, see Flexera License Management

Added in v5.0.0.

Server.StartDelay

Specifies a sleep time to delay the start-up of Scyld Cloud Workstation in seconds. Defaults to 0.

Added in v5.0.0.

Server.Auth.Enabled

Determines if authentication is enabled and valid credentials are required to sign-in (recommended). Defaults to true.

If false, then all authentication is disabled and any credentials can be used to sign-in.

Note

Changing this value takes effect after a service restart.

Server.Auth.Username

Declares a username to be used in combination with the password defined by Server.Auth.ShadowPassword at the Scyld Cloud Workstation sign in page.

Config File Authentication can be disabled by commenting or removing Server.Auth.Username and Server.Auth.ShadowPassword. To This must be specified with Server.Auth.ShadowPassword and is not necessarily the same as the username used by the remote operating system.

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.ShadowPassword

A shadowed password used to sign in to the Scyld Cloud Workstation sign in page. Config File Authentication can be disabled by commenting or removing Server.Auth.Username and Server.Auth.ShadowPassword. The format is as follows:

$6$<salt>$<hash>

The initial 6 value should never be changed and signals that SHA-512 should be used. The <salt> and the plain text password are used to create the hashed password using the UNIX crypt method. See http://linux.die.net/man/3/crypt for more information on UNIX crypt.

Password rules are dependent on length:

Length Password Restrictions
8-11 Use mixed case characters, numbers, and symbols
12-15 Use mixed case characters and either numbers or symbols
16-19 Use mixed case characters
20+ No restrictions

We recommend using passphrases of four randomly generated english words (i.e. “mail design kick office” for the best combination of usability and security.

Warning

Even though the ShadowPassword value encrypts your password, its contents should remain private. If you suspect that any part of the ShadowPassword has been compromised, please change your password immediately using our password update utility:

  • Linux: scyld-cloud-workstation.sh --passwd
  • Windows: scyld-cloud-workstation.bat /passwd

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.MinPasswordLength

The length of the password that is hashed and stored as Server.Auth.ShadowPassword. This may be set as low as 8, but we recommend at least 12 characters.

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.FailAttempts

The number of unsuccessful sign in attempts a client is allowed before the server temporarily rejects future requests from that client for a time period specified by Server.Auth.FailDelay. This helps reduce brute force attacks.

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.FailDelay

The length of time that the server will reject sign in requests from clients that repeatedly fail to sign in. See Server.Auth.FailAttempts for more information.

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.ScyldCloudAuth.URL

The URL to the Scyld Cloud Auth authentication web service. Only applies to Scyld Cloud Manager products.

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.ScyldCloudAuth.Allow

A list of <Username></Username> elements. Each <Username> element enables a username to be authenticated by ScyldCloudAuth. Usernames elements can use asterisk wildcard characters (i.e. *@penguincomputing.com will enable all usernames that end in @penguincomputing.com).

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.ScyldCloudAuth.Deny

A list of <Username></Username> elements. Each <Username> element disables a username to be authenticated by ScyldCloudAuth. Usernames that are mentioned by both the Deny and Allow list are denied.

Usernames elements can use asterisk wildcard characters (i.e. *@penguincomputing.com will enable all usernames that end in @penguincomputing.com).

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.Session.DefaultTimeout

The lifetime (in seconds) of a session token that starts upon successfully signing in. Session tokens let you access protected resources from the server such as creating a new remote-visualization connection. Increasing this value means a longer period of time you can access the resources without signing in again.

Existing remote-visualization connections are unaffected by session token timeouts. Defaults to 60 seconds.

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.Auth.OSAuthEnabled

Determines if authentication using OS credentials is enabled. Defaults to true.

Important

While config file or ScyldCloutAuth usernames can be used to sign in to Scyld Cloud Workstation at any time, only a single set of OS credentials can only be used to sign-in at a time. This prevents different OS credentials from signing in at the same time.

Note

Changing this value takes effect after a service restart.

Added in v6.1.0.

Server.Auth.Session.OnSignIn

The path of a script to execute immediately after signing in. The script is passed the system account name of the user as an argument. By default this is not set, but it can be used for custom sign-in initialization.

Note

Changing this value takes effect without a service restart.

Changed in v5.0.0.

Server.VideoSource

The video capture mechanism. Currently supports nvfbc, stream, and auto. The default is auto.

Set to auto if you’d like the system to use nvfbc when the service detects an NVIDIA GRID compatible card and stream in all other cases.

Set to nvfbc only if you have an NVIDIA GRID SDK compatible graphics card and driver.

Set to stream to use our CPU-based encoding solution.

Changed in v5.0.0.

Server.Video.MaxWidth

Any server-side video that exceeds this width is scaled down to this value. This is primarily used to prevent clients from receiving video with resolutions so high that the client can not process them fast enough.

A value of -1 disables this threshold.

Defaults to 1920.

Updated in v5.0.0. Changed default.

Server.Video.MaxHeight

Any server-side video that exceeds this height is scaled down to this value. This is primarily used to prevent clients from receiving video with resolutions so high that the client can not process them fast enough.

A value of -1 disables this threshold.

Defaults to 1080.

Updated in v5.0.0. Changed default.

Server.Video.StartFrameRate

Initial frame rate. Measured in frames per second. Defaults to 24.

Added in v2.2.0.

Server.Video.MinFrameRate

The lowest valid frame rate for a connection. Measured in frames per second. Defaults to 2.

Added in v2.2.0.

Server.Video.MaxFrameRate

The highest allowable frame rate for a connection. Measured in frames per second. Defaults to 60.

Server.ConcurrentClients.MaxClientCount

The maximum number of clients that can be connected at a time. Defaults to 6.

Added in v3.0.0.

Server.QoS.Enabled

Enables the automatic adjustment of frame rate to adapt to current performance conditions. Frame rate will start at Server.Video.StartFrameRate and jump between Server.Video.MinFrameRate and Server.Video.MaxFrameRate.

Setting this to false will cause the server to send a constant frame rate specified by Server.Video.StartFrameRate. Server.Video.MinFrameRate and Server.Video.MaxFrameRate are ignored in this case.

Defaults to true.

openSSL

All elements within the openSSL tag are described in the Poco SSLManager documentation.

openSSL.server.privateKeyFile

The path to the file containing the private key for the certificate in PEM format (or containing both the private key and the certificate). This path can be absolute or relative to the xml config file. Required for HTTPS support.

openSSL.server.certificateFile

The path to the file containing the server’s or client’s certificate in PEM format. Can be omitted if the the file given in privateKeyFile contains the certificate as well. This path can be absolute or relative to the xml config file.

openSSL.server.verificationMode

Specifies whether and how peer certificates are validated (see the Poco Context class for details). Valid values are none, relaxed, strict, and once. Defaults to none.

Changed in v3.0.0. Default value changed.

openSSL.server.loadDefaultCAFile

Boolean value. Specifies wheter the builtin CA certificates from OpenSSL are used. Defaults to true.

openSSL.server.cipherList

Specifies the supported ciphers in OpenSSL notation.

Changed in v3.0.0. Default value changed.

openSSL.server.privateKeyPassphraseHandler.name

Defaults to KeyFileHandler. The name of the Poco class used for obtaining the passphrase for accessing the private key. If your private key does not use a passphrase, this value is ignored.

Added in v2.2.0. Default value changed.

openSSL.server.privateKeyPassphraseHandler.options.password

The private key passphrase (ignored if there is no passphrase for the private key).

openSSL.server.invalidCertificateHandler.name

This should be set to ConsoleCertificateHandler. The name of the class used for confirming invalid certificates. Defaults to RejectCertificateHandler.

Added in v2.2.0. Default value changed.

openSSL.server.cacheSessions

This should be set to false. Enables or disables session caching.

openSSL.server.extendedVerification

Enable or disable the automatic post-connection extended certificate verification.

openSSL.server.requireTLSv1_2

Require a TLSv1.2 connection. Defaults to true.

Added in v2.2.0. Default value changed.

openSSL.client.verificationMode

Specifies whether and how peer certificates are validated when the server acts as a client to a third-party host (see the Poco Context class for details). Valid values are none, relaxed, strict, and once. Defaults to relaxed. Setting this value to none is not recommended.

Added in v3.0.0.

openSSL.fips

Enable or disable OpenSSL FIPS mode. Only supported if the OpenSSL version that this library is built against supports FIPS mode.

Client Settings

Clients and browsers that meet the requirements listed in Client Requirements support TLS 1.2, WebGL, and WebSockets by default and require no further setup.

Attention

Contact your system administrator if TLS 1.2, WebGL, or WebSockets are disabled.