Main Content

Server Configuration Properties

Configure MATLAB Production Server instance using configuration file or dashboard

Each MATLAB® Production Server™ instance has its own server configuration file, main_config. To change the server properties for an on-premises server instance managed using the command line, edit the main_config file that corresponds to your specific server instance at this path.

server_instance_name/config/main_config

When editing this file, remember these coding considerations:

  • You must restart the server instance for the changes to take effect.

  • Enter only one configuration property and its options per line. Each configuration property entry starts with two dashes (--).

  • The server ignores any line beginning with a pound sign (#) and considers it as a comment.

  • The server ignores lines of white space.

These sample properties configure the server to listen for client requests on port 9910 and execute three concurrent MATLAB requests. These properties also set the MATLAB Runtime root and license server address.

--http 9910
--num-workers 3
--mcr-root /usr/local/MATLAB/MATLAB_Runtime/R2024b
--license 27000@myhostname

Dashboard Usage

HTTP and HTTPS

expand all

Syntax

--http port
--http host:port

Description

http specifies the interface port and optional address or hostname.

Parameters

port

Port number used by the server instance to accept connections. Bind to any available port by specifying 0.

Default: 9910

host

Hostname or IP address of the machine running the server instance. If you do not specify the host, the server binds to all interfaces on the current machine.

Default: 0.0.0.0

Examples

Restrict access to the HTTP interface for local clients to port 9911.

--http 9911

Bind to any free port. The bound address is written to $INSTANCE/endpoint/http.

--http 0

Bind to a specific IP address and port.

--http 234.27.101.3:9920

Bind to a specific hostname on any free port.

--http my.hostname.com:0

Dashboard Usage

In the Settings tab of your server instance, under HTTP, set the HTTP property to the desired value. For example: 234.27.101.3:9920.

Syntax

--https host:port

Description

https specifies the interface port and optional address or hostname to use for secure client-server communication. For more details on the HTTPS protocol, see Enable HTTPS.

If you set the https property, you must set the x509-private-key and x509-cert-chain properties or the server fails to start.

Parameters

host

Hostname or IP address of the machine running the server instance. If you do not specify the host, the server binds to any available interface.

port

Port number used by the server instance to accept connections. Bind to any available port by specifying 0.

Examples

Restrict access to the HTTPS interface for local clients to port 9920.

--https 9920

To bind to any free port, set the https property to 0. The bound address is written to $INSTANCE/endpoint/http.

--https 0

You can also bind to a specific IP address and port.

--https 234.27.101.3:9920

To bind to a specific hostname on any free port, set the port number to 0.

--https my.hostname.com:0

Dashboard Usage

In the Settings tab of your server instance, under HTTP, set the HTTPS property to the desired value. For example: 9920.

MATLAB Runtime

expand all

Syntax

--mcr-root path

Description

mcr-root specifies the path to a MATLAB Runtime installation on a system that has a MATLAB Production Server instance installed. For more details on specifying the MATLAB Runtime version, see Specify MATLAB Runtime for Server Instance Using Command Line.

You can configure a server instance to use multiple MATLAB Runtime versions by specifying multiple mcr-root properties. Specify each property on a separate line, ordering them from the latest MATLAB Runtime version to the oldest. The server instance scans the list of specified mcr-root properties in order from first to last, then chooses the first MATLAB Runtime installation capable of processing a server request. A MATLAB Runtime installation can process a server request if it is compatible with the deployable archive containing the MATLAB function being evaluated.

When you configure the server to use multiple MATLAB Runtime versions, the server uses dynamic worker pool management, where it starts the worker processes in response to demand, and stops them in response to system resource utilization. Specifying multiple MATLAB Runtime installations of the same version has no effect on server performance. For more details, see Support Multiple MATLAB Runtime Versions.

An installation of MATLAB Production Server supports the current MATLAB Runtime version and the five previous MATLAB Runtime versions. Cloud deployments of MATLAB Production Server come installed with these six versions, and the deployment automatically configures mcr-root to support these six versions. For more details, see Supported MATLAB Runtime Versions for MATLAB Production Server.

Note

  • Specify the path to a MATLAB Runtime installation on a local file system when configuring a server instance. Specifying a path on a network partition might cause worker processes to fail.

  • All values for mcr-root must be for the same operating system and hardware combination.

Instead of setting the MATLAB Runtime root manually, you can use the mps-setup command to set mcr-root using the prompts provided by this setup script.

Parameters

path

Path to the root folder of the MATLAB Runtime installation.

Default: mCRrOOTuNsET

Examples

Use the latest version of the MATLAB Runtime.

--mcr-root /usr/local/MATLAB/MATLAB_Runtime/R2024b

To specify two MATLAB Runtime versions, add a separate line for each version.

--mcr-root /usr/local/MATLAB/MATLAB_Runtime/R2024b
--mcr-root /usr/local/MATLAB/MATLAB_Runtime/v98

Dashboard Usage

In the Settings tab of your server instance, under Core, set MATLAB Runtime to the desired value. For example:

/usr/local/MATLAB/MATLAB_Runtime/R2024b

To specify multiple versions, separate them by commas.

/usr/local/MATLAB/MATLAB_Runtime/R2024b, /usr/local/MATLAB/MATLAB_Runtime/v98

Syntax

--user-data key value

Description

user-data associates MATLAB data value with a string key. Surround strings containing spaces with double quotes. Use the backslash (\) character as the escape character for inserting double quotes or backslashes. For example, \" specifies a double-quote character and \\ specifies a backslash character. The application can retrieve the data value by using getmcruserdata(key). For more details, see Using MATLAB Runtime User Data Interface (MATLAB Compiler).

Parameters

key

Key used to access a MATLAB value, specified as a string.

valueMATLAB value associated with the key, specified as a string.

Examples

Set user data with parallel profile settings.

--user-data ParallelProfile c:\\MPS\\myprofile.settings

Set user data that contains escaped quote characters.

--user-data MyValue "Quoted string with escaped \"quotes\" and \\backslash."

Dashboard Usage

In the Settings tab of your server instance, under Advanced, set User Data to the desired value. For example:

--user-data ParallelProfile c:\\MPS\\myprofile.settings

To specify multiple key-value pairs, separate them by commas.

--user-data ParallelProfile c:\\MPS\\myprofile.settings, --user-data MyValue "Quoted string with escaped \"quotes\" and \\backslash."w

License

expand all

Syntax

--license pathList

Description

license specifies the address of the license servers or the path to the license files that a server instance uses. You can specify multiple license sources with this option.

If you do not specify a value for this property, the server searches for the license files in $MPS_INSTALL/licenses, where $MPS_INSTALL is the location in which MATLAB Production Server is installed.

For more details on licensing, see Manage Licenses for MATLAB Production Server.

Parameters

pathList

Path to one or more license servers or license files. Separate multiple entries by the appropriate path separator for the platform. Use a colon (:) as the path separator for Linux® and semi-colon (;) as the path separator for Windows®.

Examples

On a Linux server, look for licenses using a license server hosted on port 27000 of hostA and in /opt/license/license.dat.

--license 27000@hostA
--license /opt/license/license.dat

To specify the same configuration on one line in Linux, separate the configurations with a colon (:).

--license 27000@hostA:/opt/license/license.dat

On a Windows server, look for licenses using a license server hosted on port 27000 of hostA and in c:\license\license.dat.

--license 27000@hostA
--license c:\license\license.dat

To specify the same configuration on one line in Windows, separate the configurations with a semicolon (;).

--license 27000@hostA;c:\license\license.dat

Dashboard Usage

In the Settings tab of your server instance, under License, set License to the desired value. For example: 27000@hostA:/opt/license/license.dat.

Syntax

--license-grace-period hr:min:sec.fractSec

Description

license-grace-period specifies the license grace period, which starts at the first heartbeat loss event. Once the grace period expires, the server instance rejects any new incoming HTTP requests.

The default grace period is 2 hours and 30 minutes. The maximum value is also 2 hours and 30 minutes. The minimum value is 10 minutes.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

Set a license grace period that lasts for 1 hour, 29 minutes, and 5 seconds.

--license-grace-period 1:29:05

Set a license grace period that lasts for 10 minutes and 250 milliseconds.

--license-grace-period 00:10:00.25

Dashboard Usage

In the Settings tab of your server instance, under License, set License Grace Period to the desired value. For example: 1:29:05.

Syntax

--license-poll-interval hr:min:sec.fractSec

Description

license-poll-interval specifies the interval at which the server instance polls the license server after the license server has timed out or after the grace period has expired.

The default poll interval is 10 minutes. The minimum value is 10 minutes.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

Poll for licenses at intervals of 1 hour, 29 minutes, and 5 seconds.

--license-poll-interval 1:29:05

Poll for licenses at intervals of 10 minutes and 250 ms.

--license-poll-interval 00:10:00.25

Dashboard Usage

In the Settings tab of your server instance, under License, set License Poll Interval to the desired value. For example: 1:29:05.

SSL/TLS Security

expand all

Syntax

--ssl-verify-peer-mode mode

Description

ssl-verify-peer-mode specifies whether the server requires clients to present a valid SSL certificate to connect to it. All requests still require authorization.

If you set ssl-verify-peer-mode to verify-peer-require-peer-cert, you must set either the x509-ca-file-store or x509-use-system-store property.

For more details on using this property, see Configure Client Authentication.

Parameters

mode

Mode used to authenticate clients. Valid values are:

  • no-verify-peer — No peer certificate verification. The client side does not need to provide a certificate.

  • verify-peer-require-peer-cert — The client must provide a certificate and the certificate will be verified.

Default: no-verify-peer

Examples

Require clients to provide an SSL certificate.

--ssl-verify-peer-mode verify-peer-require-peer-cert

Dashboard Usage

In the dashboard, in the Settings tab of your server instance, under SSL, set SSL Verify Peer Mode to the desired value. For example: verify-peer-require-peer-cert.

Syntax

--ssl-tmp-dh-param path

Description

ssl-tmp-dh-param specifies the path to the pregenerated ephemeral DH key. If this parameter is not provided, the server instance automatically generates the DH key at startup. Providing a pregenerated DH key can decrease instance start time.

Parameters

path

Path to the pre-generated DH key. Relative and absolute paths are valid.

Examples

Load the DH key from a dh_param.pem file located in the x509 folder of the instance root.

--ssl-tmp-dh-param ./x509/dh_param.pem

Dashboard Usage

In the Settings tab of your server instance, under SSL, set SSL DH Key Parameter File to the desired value. For example: ./x509/dh_param.pem.

Syntax

--ssl-tmp-ec-param elliptic_curve_name

Description

ssl-tmp-ec-param specifies the name of the elliptic curve used for the ECDHE ciphers.

ECDHE ciphers are enabled by default. If you do not specify the elliptic curve name, ECDHE ciphers use a default elliptic curve. The default elliptic curves are in the following order: x25519, secp256r1, x448, secp521r1, secp384r1. During the SSL/TLS handshake, the client advertises the curves that it supports. Based on this client-server negotiation, one of the default curves is used to establish a secure connection for the subsequent data exchange.

If this property is not specified, all ECDHE ciphers are disabled.

Parameters

elliptic_curve_name

Name of curve, specified as any curve supported by OpenSSL.

Examples

Use the prime256v1 curve.

--ssl-tmp-ec-param prime256v1

Dashboard Usage

In the Settings tab of your server instance, under SSL, set SSL Elliptic Curve Identifier to the desired value. For example: prime256v1.

Syntax

--ssl-protocols protocols

Description

ssl-protocols specifies the allowed SSL protocols. If you do not set this property, the server allows the use of all supported SSL protocols. Supported protocols are TLSv1, TLSv1.1, and TLSv1.2.

SSLv3 is not supported.

For more details on using this property, see Enable HTTPS and Adjust Security Protocols.

Parameters

protocols

Comma-separated list of allowed protocols. Valid entries are:

  • TLSv1

  • TLSv1.1

  • TLSv1.2

Default: TLSv1.2

Examples

Enable use of the TLSv1 protocol only.

--ssl-protocols TLSv1

Dashboard Usage

In the dashboard, in the Settings tab of your server instance, under SSL, enter the protocols in the SSL Protocols property, for example, TLSv1.

Syntax

--ssl-ciphers ciphers

Description

ssl-ciphers specifies the list of cipher suites that the server uses for encryption.

For more details on using this property, see Enable HTTPS and Adjust Security Protocols.

Parameters

ciphers

Cipher suites the server instance uses for encryption. Valid values are:

  • ALL — Use all available cipher suites except eNULL.

  • HIGH — Use all available high encryption cipher suites.

  • Comma-separated list of cipher suites to use.

To provide finer control over the selected cipher, you can pass OpenSSL configuration strings with the ciphers.

Default: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305

Examples

Use only high encryption cipher suites.

--ssl-ciphers HIGH

Disable the use of ADH ciphers.

--ssl-ciphers ALL:!ADH

Use the strongest available ECDHE ciphers.

--ssl-ciphers ALL:@STRENGTH

Disable the use of ADH ciphers and use the strongest available ECDHE ciphers.

--ssl-ciphers ALL:!ADH@STRENGTH

Dashboard Usage

In the dashboard, in the Settings tab of your server instance, under SSL, set SSL Ciphers to the desired value, for example, HIGH.

Syntax

--ssl-allowed-client client1,...,clientN:archive1,...,archiveN

Description

ssl-allowed-client authorizes clients based on the client certificate common name. Only authorized clients can request the evaluation of MATLAB functions deployed to the server.

If no archive names follow the common name of the client, the client can access all the deployed archives. Otherwise, the client can access only the specified archives.

You can set either the ssl-allowed-client or access-control-provider property. If you set both, MATLAB Production Server fails to start.

For more details on using this property, see Specify Access to MATLAB Programs and Configure Client Authentication.

Parameters

client

Common name of the client.

archive

Name of the deployed archive that the client can access.

Examples

Allow client1 and client2 to access magic.ctf and helloworld.ctf. Allow client3 access to all deployed archives.

--ssl-allowed-client client1,client2:magic,helloworld
--ssl-allowed-client client3

Dashboard Usage

In the dashboard, in the Settings tab of your server instance, under SSL, set SSL Allowed Client to the desired value. For example: client1,client2:magic,helloworld.

Since R2023a

Syntax

--enable-ssl-renegotiation

Description

enable-ssl-renegotiation enables SSL renegotiation on your MATLAB Production Server instance. When server authentication requirements change, SSL renegotiation lets clients maintain their connection to the server by enabling them to re-enter their authentication details.

Caution

Enabling SSL renegotiation exposes security vulnerabilities.

By default, SSL renegotiation is disabled.

Examples

Enable SSL renegotiation.

--enable-ssl-renegotiation

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--enable-ssl-renegotiation

Syntax

--x509-private-key path

Description

x509-private-key specifies the path to the private key. The key must be in PEM format.

If you do not set this property, the server instance does not load the private key or the server-side certificates.

If https is enabled on the server, you must set the x509-private-key and x509-cert-chain properties. Otherwise, the server fails to start.

For more details on the HTTPS protocol, see Enable HTTPS.

Parameters

path

Path to the PEM-format private key file. Relative and absolute paths are valid.

Examples

Load a private key file named private_key.pem from the x509 folder of the instance root.

--x509-private-key ./x509/private_key.pem

Dashboard Usage

In the Settings tab of your server instance, under SSL, set X509 Private Key to the desired value. For example: ./x509/private_key.pem.

Syntax

--x509-passphrase path

Description

x509-passphrase specifies the path to the file containing the passphrase of the encrypted private key. This property is required if x509-private-key is specified and the private key file is encrypted. Otherwise, the private key fails to load.

Note

This file must be owner read-only.

Parameters

path

Path to the passphrase file. Relative and absolute paths are valid.

Examples

Load a passphrase from the key_passphrase.pem file located in the x509 folder of the instance root.

--x509-passphrase ./x509/key_passphrase.pem

Dashboard Usage

In the Settings tab of your server instance, under SSL, set X509 Passphrase File to the desired value. For example: ./x509/key_passphrase.pem.

Syntax

--x509-cert-chain path

Description

x509-cert-chain specifies the server certificate chain file. It contains one or more PEM-format certificates. The chain begins with the server certificate, which is followed by a chain of untrusted certificates. To use the certificate chain file, specify the x509-private-key property.

If https is enabled on the server, you must set the x509-private-key and x509-cert-chain properties. Otherwise, the server fails to start.

For more details on the HTTPS protocol, see Enable HTTPS.

Note

Do not specify trusted certificates in the certificate chain file.

Parameters

path

Path to the certificate chain file. Relative and absolute paths are valid.

Examples

Load a certificate chain from the cert_chain.pem file located in the x509 folder of the instance root.

--x509-cert-chain ./x509/cert_chain.pem

Dashboard Usage

In the Settings tab of your server instance, under SSL, set X509 Certificate Chain to the desired value. For example: ./x509/cert_chain.pem.

Syntax

--x509-ca-file-store path

Description

x509-ca-file-store specifies the certificate authority (CA) file to verify peer certificates. This file contains trusted certificates and certificate revocation lists. You can also put intermediate certificates into the CA file. An intermediate certificate in the CA file becomes a trusted certificate.

Parameters

path

Path to the certificate CA file store. Relative and absolute paths are valid.

Examples

Load a CA store from the ca_file.pem file located in the x509 folder of the instance root.

--x509-cert-chain ./x509/ca_file.pem

Dashboard Usage

In the Settings tab of your server instance, under SSL, set X509 CA File Store to the desired value. For example: ./x509/ca_file.pem.

Syntax

--x509-use-system-store

Description

x509-use-system-store specifies that the server instance use the system-provided certificate authority (CA) store. By default, the server uses the file /etc/ssl/certs/ca-certificates.crt as the trusted CA store and searches for trusted certificates under the folder /etc/ssl/certs. You can override these locations by setting the environment variables SSL_CERT_FILE and SSL_CERT_DIR.

For more details on using this property, see Configure Client Authentication.

Examples

Enable use of the system CA store.

--x509-use-system-store

Dashboard Usage

In the Settings tab of your server instance, under SSL, select or clear X509 Use System Store.

Syntax

--x509-use-crl

Description

x509-use-crl specifies that the server instance use the certificate revocation list (CRL). By default, instances do not use any CRLs. In this case, the CRLs in the certificate authority store are ignored.

If x509-use-crl is added, the CRLs are loaded and participate in the client certificate verification. If the CRL has expired, the SSL handshake is rejected.

For more details on using this property, see Configure Client Authentication.

Examples

Use the certificate revocation list when authenticating clients.

--x509-use-crl

Dashboard Usage

In the Settings tab of your server instance, under SSL, select or clear the X509 Use CRL property.

Authentication and Delegation

expand all

Syntax

--http-authentication-method method

Description

--http-authentication-method method specifies the HTTP authentication method that the server uses to authenticate the client.

If you do not specify this property, the server does not perform HTTP authentication. You can still authenticate using an HTTPS client certificate. For more information on authentication, see Configure Client Authentication and Use Kerberos Authentication and Kerberos Delegation.

Parameters

method

Name of HTTP authentication method. spnego (Simple and Protected Negotiation Mechanism) is the only supported method.

Examples

Specify spnego as the HTTP authentication method.

--http-authentication-method spnego

Dashboard Usage

In the Settings tab of your server instance, under Authentication and Delegation, set HTTP Authentication Method to the desired value. For example: spnego.

Syntax

--client-credential-delegation method

Description

client-credential-delegation specifies the client credential delegation method that the server uses. Currently, kerberos-without-protocol-transition is the only supported method. If you set client-credential-delegation to kerberos-without-protocol-transition, then you must set http-authentication-method to spnego; otherwise, the server fails to start.

For details on Kerberos delegation, see Use Kerberos Authentication and Kerberos Delegation.

Parameters

method

Name of the client credential delegation method. kerberos-without-protocol-transition is the only supported method.

Examples

Use kerberos-without-protocol-transition as the client credential delegation method.

--client-credential-delegation kerberos-without-protocol-transition

Dashboard Usage

In the Settings tab of your server instance, under Authentication and Delegation, set Client Credential Delegation to the desired value. For example: kerberos-without-protocol-transition.

Application Access Control

expand all

Syntax

--access-control-provider provider

Description

--access-control-provider enables access control using generic identity providers for applications deployed to a server.

You can set either the access-control-provider property or the ssl-allowed-client property. If you set both, the server fails to start.

For more details on access control, see Application Access Control.

Parameters

providerIdentity provider that MATLAB Production Server uses for application access control. Supported values for provider include OAuth2.

Examples

Enable access control using the OAuth 2.0 protocol.

--access-control-provider OAuth2

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--access-control-provider OAuth2

Syntax

--access-control-config path

Description

--access-control-config path specifies the path to the identity provider specific configuration file. Specifying this property is optional. The default path for the OAuth 2.0 identity provider is ./config/jwt_idp.json.

If you enable access control on a server instance by specifying the access-control-provider property, the access control configuration file must exist in path. Otherwise, the server instance fails to start.

For more details on access control, see Access Control Configuration File.

Parameters

path

Path to access the configuration file.

Examples

Specify the path to the OAuth 2.0 configuration file.

--access-control-config ./config/jwt_idp.json

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--access-control-config ./config/jwt_idp.json

Syntax

--access-control-policy path

Description

--access-control-policy path specifies the path to the access control policy file on a server instance. Setting this property is optional. The default path is ./config/ac_policy.json.

If you enable access control by specifying the access-control-provider property, the access control policy file must exist in path. Otherwise, the server instance fails to start.

If access control is enabled, then after the instance starts, it scans the policy file every five seconds for any changes. If the policy file is absent or contains errors, the server continues to run, but it denies all requests and logs an error message in the main.log file.

For more details on access control, see Access Control Configuration File.

Parameters

path

Path to the policy file.

Examples

Specify the path to the access control policy JSON file.

--access-control-policy ./config/ac_policy.json

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--access-control-policy ./config/ac_policy.json

Worker Management

expand all

Syntax

--num-workers count

Description

num-workers defines the number of concurrent MATLAB execution requests that a server instance can simultaneously process. Set the number of workers based on the number of hardware threads available on the local host.

If you specify a single value for the mcr-root property, the num-workers property determines the fixed size of the worker pool. For example, if you specify a single value for mcr-root and set num-workers to 4, your machine has 4 workers available.

If you specify multiple MATLAB Runtime versions in your server configuration, num-workers is the maximum size of the worker subpool specific to a MATLAB Runtime version. With multiple MATLAB Runtime versions on a server, the total number of workers can exceed those specified by num-workers. However, num-workers is the maximum number of workers that are allowed to process a request. For example, a server configuration that has three MATLAB Runtime versions and num-workers set to 2 has six workers available. The maximum number of workers in each subpool is two, and the maximum number of workers that can be active at a given time is two. For more details on multiple MATLAB Runtime versions, see Support Multiple MATLAB Runtime Versions.

Parameters

count

Number of workers available to evaluate functions, specified as a positive integer.

The maximum value is determined by the number of license keys available for MATLAB Production Server.

Default: 1

Examples

Allow ten workers to process requests at a time.

--num-workers 10

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Maximum Workers to the desired value. For example: 10.

Syntax

--component-isolation component-match=<ecma-regular-expression>[ ; max-workers=<positive-integer>]
--component-isolation max-isolated-components=<positive-integer>

Description

This setting allows you to give any number of deployable archives their own exclusive pools of workers. You select the deployable archives with an ECMAScript regular expression that matches the stem of the corresponding filename (for a file named myctf.ctf, the stem is myctf). For these isolated deployable archives, no other archive, whether isolated or non-isolated, will ever use this pool of workers. The server restarts workers in these isolated pools during a hot-deploy update of an existing deployable archive.

Parameters

The attributes delimiter (";") may have white space before and after.

component-match

ECMAScript regular expression which matches filenames of deployable archives to be isolated

  • Required for each entry.

  • Cannot contain white space or any other configuration delimiters.

  • Many entries are allowed but the first runtime match specified will be the one to be used to match each request.

max-workers

Positive integer which overrides --num-workers setting for each match

  • Optional, but defaults to --num-workers for each match.

  • Must be greater than 0.

  • May be greater than --num-workers but will be restricted to --num-workers at server startup time.

max-isolated-components
  • Must exist and be on its own separate line

  • May only occur once

  • Must be greater than 0

  • Must be less than or equal to 512 / number-of-mcr-root-entries (see --mcr-root configuration entries. Each entry represents a MATLAB Runtime version.)

    This internal threshold places a cap on the total amount of resources pre-allocated in the server at startup time. This number also is an upper limit reasonable estimation of how many isolated deployable archives per configured MATLAB Runtime version may be needed. Typically, there is a technical reason to isolate any one individual deployable archive. Therefore, the total number of isolated deployable archives should be limited in scope. Configuring this number to be greater than needed is not memory-expensive by itself. Only when a deployable archive starts using it may it affect how many workers can potentially start. There is no performance penalty for unused pre-allocation.

  • If startup matching deployable archives exceed this number (per MATLAB Runtime version), an error will be logged and the server will start but subsequent requests to the failed archive will not be recognized. Likewise, if a post-startup auto-deploy (a.k.a "hot-deploy") of a new matching deployable archive exceeds this number (per MATLAB Runtime version), the auto-deploy will fail with the appropriate log message and the failed deployable archive will not be recognized.

Example

If there are 2 --mcr-root instances configured and max-isolated-components=12, then there will be 24 pre-allocated isolation pools that can service any configured isolated deployable archive that appears in the auto_deploy directory for the contained MATLAB Runtime version number. There will be 12 pools for the first --mcr-root entry and 12 pools for the second --mcr-root entry.

Examples

Exact Matches

assume isolated deployable archive names in auto_deploy using different max-workers sizes

The CTFs are named myctf1 and myctf2. This isolates only these exact deployable archive names when they are encountered.

--component-isolation component-match=^myctf1$ ; max-workers=3
--component-isolation component-match=^myctf2$;max-workers=2
--component-isolation max-isolated-components=3

Partial Generalized Matches

Assume the following isolated deployable archive names in auto_deploy:

group1_component1 group1_component2 group2_component1 group2_component2

--component-isolation component-match=^group1_;max-workers=3
--component-isolation max-isolated-components=3

Fully Generalized Match

Assume up to 128 (per MATLAB Runtime version) different deployable archives can be isolated (or will be isolated during hot-deploy). This will isolate all deployable archive names. This setting is not dependent on any name change during hot-deploy.

--component-isolation component-match=.*;max-workers=3
--component-isolation max-isolated-components=128

For more information on reasons to use component-isolation property, see Isolate Deployable Archives in MATLAB Production Server.

Syntax

--worker-restart-interval hr:min:sec.fractSec

Description

worker-restart-interval specifies the time interval at which the server instance stops and restarts its worker processes. If a worker process has not completed request processing at the specified restart interval, it completes the processing and then restarts.

If you do not specify this property, the workers do not restart in response to time.

For more details on restarting workers, see Control Worker Restarts.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

Restart workers at intervals of 1 hour, 29 minutes, 5 seconds.

--worker-restart-interval 1:29:051:29:05

Restart workers at intervals of 10 minutes and 250 ms.

--worker-restart-interval 00:10:00.25

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Worker Restart Interval to the desired value. For example:

00:10:00.25

Syntax

--worker-restart-memory-limit size

Description

worker-restart-memory-limit sets the memory usage limit of a worker process. If a worker's working set size exceeds worker-restart-memory-limit for an interval of time greater than worker-restart-memory-limit-interval, then the server restarts that worker.

This property is disabled by default. For more details on restarting workers, see Control Worker Restarts.

Parameters

size

Amount of memory used by worker.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

Examples

Restart any worker whose working set size exceeds 1 GB for more than 1 hour.

--worker-restart-memory-limit 1GB
--worker-restart-memory-limit-interval 1:00:00

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Worker Restart Memory Limit to the desired value. For example: 1GB.

Syntax

--worker-restart-memory-limit-interval hr:min:sec.fractSec

Description

worker-restart-memory-limit-interval sets the interval for which a worker process can exceed its memory limit before restart. If a worker's working set size exceeds worker-restart-memory-limit for an interval of time greater than worker-restart-memory-limit-interval, then the server restarts that worker.

This property is disabled by default. For more details on restarting workers, see Control Worker Restarts.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

Restart any worker whose working set size exceeds 1 GB for more than 1 hour.

--worker-restart-memory-limit 1GB
--worker-restart-memory-limit-interval 1:00:00

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Worker Restart Memory Limit Interval to the desired value. For example: 1:00:00.

Syntax

--worker-memory-check-interval hr:min:sec.fractSec

Description

worker-memory-check-interval specifies how often to poll the memory usage of a worker process. This setting affects the behavior of all other settings that act based on worker memory usage, such as worker-memory-trigger, worker-memory-target, and worker-restart-memory-limit.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

Check memory usage every one and a half minutes.

--worker-memory-check-interval 0:01:30

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Worker Memory Check Interval to the desired value. For example: 0:01:30.

Syntax

--worker-memory-trigger size

Description

worker-memory-trigger specifies the memory usage threshold at which to begin shutting down workers to preserve memory. This property is disabled by default and applies only when you specify multiple MATLAB Runtime versions in the mcr-root property. For more details, see Support Multiple MATLAB Runtime Versions.

When the amount of memory used across all workers exceeds the worker-memory-trigger value, then workers are shut down from oldest to newest until memory usage drops below the worker-memory-target value.

Set worker-memory-trigger to a value less than the amount of physical memory on the host. worker-memory-target must be set less than or equal to worker-memory-trigger. If you do not specify either worker-memory-target or worker-memory-trigger, then workers are never shut down in response to memory usage.

Parameters

size

Memory amount size.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

Examples

When the worker pool exceeds 4 GB, shrink the pool down to 2 GB.

--worker-memory-trigger 4GB
--worker-memory-target 2GB

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Worker Memory Trigger to the desired value. For example: 4GB.

Syntax

--worker-memory-target size

Description

worker-memory-target specifies the lower-bound memory usage threshold at which to stop shutting down MATLAB workers. This property applies only when workers start shutting down once their memory usage reaches the worker-memory-trigger threshold. This property is disabled by default and applies only when you specify multiple MATLAB Runtime versions in the mcr-root property. For more details, see Support Multiple MATLAB Runtime Versions.

When the amount of memory used across all workers exceeds the worker-memory-trigger value, then workers are shut down from oldest to newest until memory usage drops below the worker-memory-target value.

Set worker-memory-trigger to a value less than the amount of physical memory on the host. worker-memory-target must be set less than or equal to worker-memory-trigger. If you do not specify either worker-memory-target or worker-memory-trigger, then workers are never shut down in response to memory usage.

Examples

When the worker pool exceeds 4 GB, shrink the pool down to 2 GB.

--worker-memory-trigger 4GB
--worker-memory-target 2GB

Parameters

size

Memory amount size.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

When the amount of memory used across all workers exceeds the worker-memory-trigger value, then workers are shut down from oldest to newest until memory usage drops below the worker-memory-target value.

Set worker-memory-trigger to a value less than the amount of physical memory on the host. worker-memory-target must be set less than or equal to worker-memory-trigger. If you do not specify either worker-memory-target or worker-memory-trigger, then workers are never shut down in response to memory usage.

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Worker Memory Target to the desired value. For example: 2GB.

Syntax

--queue-time-trigger hr:min:sec.fractSec

Description

queue-time-trigger specifies the time interval at which to create additional MATLAB workers to process requests in the server queue. This property applies only when you specify multiple MATLAB Runtime versions in the mcr-root property. For more details, see Support Multiple MATLAB Runtime Versions.

The server creates workers based on queue time, which is how long a request has waited to be processed since it arrived on the server. The server follows this algorithm:

  1. Sort requests by their arrival time on the server.

  2. Map requests, from oldest to newest, onto idle workers.

  3. If a request is unable to map to a worker, and the queue time of the request exceeds the queue-time-trigger value, create additional workers to process the requests.

  4. Stop creating additional workers when either of these conditions are met:

    • The queue time of the oldest request falls below the queue-time-target value.

    • The number of workers per subpool exceeds the value specified by num-workers.

The default value for queue-time-trigger and queue-time-target is 250 ms. queue-time-target must be less than or equal to queue-time-trigger.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

When the queue time exceeds 500 ms, grow the worker pool until the queue time falls below 100 ms.

--queue-time-trigger 0:00:00.5
--queue-time-target 0:00:00.1

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Queue Time Trigger to the desired value. For example: 0:00:00.5.

Syntax

--queue-time-target hr:min:sec.fractSec

Description

queue-time-target specifies the time interval at which to stop creating additional MATLAB workers to process requests in the server queue. This property applies only when you specify multiple MATLAB Runtime versions in the mcr-root property. For more details, see Support Multiple MATLAB Runtime Versions.

The server creates workers based on queue time, which is how long a request has waited to be processed since it arrived on the server. The server follows this algorithm:

  1. Sort requests by their arrival time on the server.

  2. Map requests, from oldest to newest, onto idle workers.

  3. If a request is unable to map to a worker, and the queue time of the request exceeds the queue-time-trigger value, create additional workers to process the requests.

  4. Stop creating additional workers when either of these conditions are met:

    • The queue time of the oldest request falls below the queue-time-target value.

    • The number of workers per subpool exceeds the value specified by num-workers.

The default value for queue-time-trigger and queue-time-target is 250 ms. queue-time-target must be less than or equal to queue-time-trigger.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

When the queue time exceeds 500 ms, grow the worker pool until the queue time falls below 100 ms.

--queue-time-trigger 0:00:00.5
--queue-time-target 0:00:00.1

Dashboard Usage

In the Settings tab of your server instance, under Worker, set Queue Time Target to the desired value. For example: 0:00:00.1.

Syntax

--merge-worker-streams

Description

merge-worker-streams merges the stdout and stderr worker streams into a single stream.

By default, this property is disabled.

Examples

Merge the stdout and stderr worker streams into a single stream.

--merge-worker-streams

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--merge-worker-streams

Syntax

--socket-root path

Description

socket-root specifies the folder location of sockets used for interprocess communication while the server is running. This property applies to local and POSIX installations only.

By default, the socket root is the .mps_socket folder of your server instance.

Parameters

pathPath to socket root

Examples

Specify the path to the socket root.

--socket-root ./.mps_socket

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--socket-root ./.mps_socket

Requests and Routing

expand all

Syntax

--request-size-limit size

Description

request-size-limit specifies the maximum size of a request. The default request size is 64 MB. The maximum allowed request size is 2,147,483,647 bytes, which is the maximum positive value for a 32-bit signed integer.

Parameters

size

Size of the request.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

Examples

Set a request size of 128 MB.

--request-size-limit 128MB

Dashboard Usage

In the Settings tab of your server instance, under Core, set Request Size Limit to the desired value. For example: 128MB.

Syntax

--request-timeout hr:min:sec.fractSec

Description

request-timeout specifies the duration after which the request times out upon reaching a terminal state. At this point, the server deletes the request unless a client process has already deleted the request.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

Set requests to time out after two hours.

--request-timeout 2:00:00

Dashboard Usage

In the Settings tab of your server instance, under Core, set Request Timeout to the desired value. For example: 2:00:00.

Syntax

--cors-allowed-origins *
--cors-allowed-origins origin1,...,originN

Description

cors-allowed-origins specifies the set of domain origins from which clients are allowed to make requests to a MATLAB Production Server instance. Cross-Origin Resource Sharing (CORS) defines how client-side web applications and a server can interact to safely determine whether or not to allow a cross-origin request. Browser clients and client code written in JavaScript® commonly use the XMLHttpRequest object to make a cross-domain request. For MATLAB Production Server to support such requests, you must enable cors-allowed-origins on the server.

Parameters

*

Allow requests from any domain origin access to the sever.

origin1,...,originN

Comma-separated list of domain origins that are allowed access to the server.

Examples

Allow requests from any domain origin to access the server.

--cors-allowed-origins *

Allow requests from specific domain origins to access the server.

--cors-allowed-origins http://www.w3.org, https://www.apache.org

Dashboard Usage

In the Settings tab of your server instance, under HTTP, set CORS Allowed Origins to the desired value. For example: http://www.w3.org, https://www.apache.org.

Syntax

--http-linger-threshold size

Description

http-linger-threshold sets the amount of data a server instance reads after an error. If an HTTP request is rejected and the server instance sends back an HTTP error response such as HTTP 404/413, the server instance does not close the TCP connection immediately. Instead it waits for the client to shut down the TCP connection. This behavior ensures that the client receives the HTTP error response sent by the server instance. During this time, the server instance receives and discards data from the client until the amount of data received equals http-linger-threshold. At that threshold, the server instance resets the TCP connection.

By default, the threshold is unlimited and the server instance waits to receive the entire HTTP request.

Parameters

size

Amount of data received before the TCP connection is reset.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

Examples

Set the linger threshold to be 64 MB.

--http-linger-threshold 64MB

Set the linger threshold to be 32 KB.

--http-linger-threshold 32KB

Set the linger threshold to be 1024 B.

--http-linger-threshold 1024

Dashboard Usage

In the Settings tab of your server instance, under HTTP, select HTTP Linger Threshold to the desired value. For example: 64MB.

Syntax

--enable-http-pipelining

Description

enable-http-pipelining enables parallel execution of pipelined requests. By default, this property is disabled.

Examples

Enable parallel pipeline execution.

--enable-http-pipelining

Dashboard Usage

In the Settings tab of your server instance, under HTTP, select or clear Enable HTTP Pipelining.

Syntax

--files-root path

Description

files-root enables MATLAB Production Server to serve static content over HTTP or HTTPS.

To access this static file content from a web browser, enter this URL:

http(s):host:port/~files/filename.ext
  • host — Server hostname

  • port — Server port number

  • filename.ext — Name of static file, where ext is the file extension

For details on serving static content using web handlers, see Handle Custom Routes and Payloads in HTTP Requests.

Parameters

path

Path to the folder containing static files.

Examples

Enable the server to serve static content. Assume that you have a server running at the my.server.com and port number 9910. Also assume that you have a text file, my_file.txt, stored in a folder called static_files, and static_files is located in the root folder of your server instance. Specify the path to the static_files folder as the parameter to the files-root property.

--files-root ./static_files

To access my_file.txt from a web browser, specify the following in the address bar of your browser, http://my.server.com:9910/~files/my_file.txt.

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--files-root ./static_files

Since R2022a

Syntax

--routes-file path

Description

routes-file specifies the location of the file used to specify URL routes. URL routes enable the server to map the path in request URLs to any deployable archive and MATLAB function deployed on the server.

The default name of the file is routes.json and its default location is in the /config folder of your server instance.

Alternatively, you can define URL routes in JSON files that are specific to each archive deployed on the server and organize your routes by deployable archive name. For more details on defining URL routes, see Handle Custom Routes and Payloads in HTTP Requests.

Parameters

pathPath to routes file

Examples

Specify the path to the URL routes file.

--routes-file ./config/routes.json

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--routes-file ./config/routes.json

Server Memory

expand all

Syntax

--server-memory-threshold size

Description

server-memory-threshold sets the memory size limit of a server process. If the size of a server process size exceeds size, then responses are archived or purged, as specified by server-memory-threshold-overflow-action (to archive_responses or purge_responses, respectively). If server-memory-threshold is unset, then responses are bound to the server process, causing the memory footprint to increase. To prevent the memory of the server process from growing, client processes can delete a request after usage.

Parameters

size

Threshold size of the server process.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

Examples

Archive responses when the server process memory footprint reaches 500 MB.

--server-memory-threshold 500MB
--server-memory-threshold-overflow-action archive_responses

Dashboard Usage

In the Settings tab of your server instance, under Server Memory, set Server Memory Threshold to the desired value. For example: 2GB.

Syntax

--server-memory-threshold-overflow-action action

Description

server-memory-threshold-overflow-action specifies whether responses are archived or purged when the size of the server process in memory set by server-memory-threshold is breached.

Parameters

action

Overflow action to take when the server reaches the memory threshold. Valid values are:

  • archive_responses — Archive the responses.

  • purge_responses — Purge the responses.

Examples

Archive responses when the server process memory footprint reaches 500 MB.

--server-memory-threshold 500MB
--server-memory-threshold-overflow-action archive_responses

Dashboard Usage

In the Settings tab of your server instance, under Server Memory, set Server Memory Threshold Overflow Action to the desired value. For example: archive_responses.

Syntax

--response-archive-root path

Description

response-archive-root specifies the location where responses specified by path are archived. This option must be set if the server-memory-threshold-overflow-action option is set to archive_responses. The server process must have read and write permissions to the path.

Parameters

path

Path to the response archive root.

Examples

Set the archive root.

--response-archive-root ./.response_archive

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--response-archive-root ./.response_archive

Syntax

--response-archive-limit size

Description

response-archive-limit specifies the maximum disk space available to the server process for archiving. If the limit set by size is reached, the archives are deleted in a first-in, first-out order until the space for the server process falls below size. If this limit is not specified, the server process assumes there is no limit to disk usage for archiving.

Parameters

size

Size of the server process.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

Examples

Set the size of the archive to 5 GB.

--response-archive-limit 5GB

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--response-archive-limit 5GB

Server Performance

expand all

Syntax

--num-threads count

Description

num-threads sets the size of the thread pool available to a MATLAB Production Server instance for processing client requests. Server instances do not allocate a unique thread to each client connection. When data is available on a connection, the required processing is scheduled on the pool of threads in the main server process.

The threads in this pool do not directly evaluate MATLAB functions. Each worker process has a single thread that executes MATLAB code on behalf of the client.

Set this parameter to 1, and increase it only if the expected load consists of a high volume of short-running requests. This strategy ensures that the available processor resources are balanced between MATLAB function evaluation and processing client-server requests. Increasing this parameter to more than the number of available cores usually provides no benefit.

Parameters

count

Number of threads available in the thread pool, specified as a positive integer.

Default: 1

Examples

Create a pool of ten threads for processing requests.

--num-threads 10

Dashboard Usage

In the Settings tab of your server instance, under Core, set Maximum Threads to the desired value. For example: 10.

Syntax

--use-single-comp-thread

Description

--use-single-comp-thread specifies that workers start the MATLAB Runtime with a single computational thread.

Examples

Start MATLAB Runtime with a single computational thread.

--use-single-comp-thread

Dashboard Usage

In the Settings tab of your server instance, under Core, select or clear Use Single Computational Thread.

Auto-Deployment

expand all

Syntax

--auto-deploy-root path

Description

auto-deploy-root specifies the folder that the server instance scans for deployable archives.

The server instance automatically unpacks and deploys archives placed in this folder when it starts.

If you set async-deploy-on-startup, the server instance deploys the archives only after it starts. (since R2020a)

You do not need to restart the server after a deployable archive is added, updated, or removed. Multiple server instances can share a single auto-deploy-root folder. Using this folder allows near-simultaneous hot deployment to multiple instances. The server scans the folder every five seconds for any changes.

For more details on auto-deployment, see Deploy Archive to MATLAB Production Server and Modifying Deployed Functions.

Parameters

path

Path to the folder that the server instance scans for deployable archives. The path is relative to the server instance root folder.

Examples

Scan the auto_deploy folder for deployable archives to auto-deploy.

--auto-deploy-root ./auto_deploy

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--auto-deploy-root ./auto_deploy

Since R2020a

Syntax

--async-deploy-on-startup

Description

async-deploy-on-startup delays deployment of the deployable archives until after the server starts. After starting, the server scans the folder specified by the auto-deploy-root property for archives to deploy, and then deploys them. Due to this delayed deployment, the archives are accessible only after the server finishes deploying them and are not accessible immediately after the server starts. If you have several archives or large archives to deploy, then set this property to avoid server timeout on startup.

If you do not set this property, the server instance automatically unpacks and deploys the archives placed in the folder specified by the auto-deploy-root property when it starts.

For more details on auto-deployment, see Deploy Archive to MATLAB Production Server and Modifying Deployed Functions.

Examples

Deploy archives after the server starts.

--async-deploy-on-startup

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--async-deploy-on-startup

Syntax

--extract-root path

Description

extract-root specifies the root folder used to store the expanded contents of the deployable archives deployed on the server instance. Deployable archives are unpacked to a hidden subdirectory of extract-root.

Parameters

path

Path to the root folder used to store contents of deployable archives relative to the server instance's root folder.

Examples

Extract deployable archives into the archives folder.

--extract-root ./archives

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--extract-root ./archives

Discovery and Metrics

expand all

Syntax

--enable-discovery

Description

enable-discovery enables HTTP or HTTPS access to the function discovery API used to learn about MATLAB functions deployed to the server. The API is available at this path:

http(s)://host:port/api/discovery

The API returns the discovery information as a JSON object. To call the API, see GET Discovery Information. For additional details about the API, see RESTful API for Discovery and Diagnostics. By default, this property is disabled.

Examples

Enable the discovery API.

--enable-discovery

Dashboard Usage

In the Settings tab of your server instance, under Core, select or clear Enable Discovery.

Syntax

--enable-metrics

Description

enable-metrics enables HTTP or HTTPS access to the API for retrieving metrics or a server instance in the Prometheus® metrics format.

The API is available at this path:

http(s)://host:port/api/metrics

By default, this property is disabled.

To call the API, see GET Metrics. For additional details about the API, see RESTful API for Discovery and Diagnostics.

Examples

Enable the metrics API.

--enable-metrics

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--enable-metrics

Logging

expand all

Syntax

--log-root path

Description

log-root specifies the location of the folder where a MATLAB Production Server instance writes log files. This property is available only for an on-premises server installation.

The server creates the following log files when it starts.

  • main.log — Most recent log file.

  • main.out — Captures standard output from the main process.

  • main.err — Captures standard error output from the main process.

  • main__DATE__SERIAL.log — Main process log. When a server instance restarts or the size of main.log reaches the limit set by the log-rotation-size property, the server renames main.log to main__DATE__SERIAL.log and archives it in the folder set by the log-archive-root property. The default archive location is the old_logs folder of a server instance.

For more details on logging, see Manage Log Files and Server Diagnostic Tools.

Note

Omitting this property disables all logging.

Parameters

path

Path to the folder containing log files for a server instance.

Default: ./log

Examples

Store server logs in the default location, which is the log folder of the server instance.

--log-root ./log

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--log-root ./log

Syntax

--pid-root path

Description

pid-root specifies the folder used to store PID files. PID files record the system-specific process identifiers for all processes associated with the server instance. These files include:

  • main.pid — The process identifiers of the server head process

  • worker_N.pid — The process identifiers of each worker process N

If worker_2.pid is present but worker_1.pid is not, it is possible that worker_1 crashed and was restarted automatically. You can confirm this action by checking the main log file.

The format of these files is a single decimal integer, that is, the process identifier.

Parameters

path

Path to the folder used to store PID files relative to the server instance's root folder.

Examples

Store PID files in the pid folder.

--pid-root ./pid

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--pid-root ./pid

Syntax

--endpoint-root path

Description

endpoint-root specifies the location for storing server-named endpoints. Each interface used for external communication generates an endpoint file in this folder. Normally these files are:

  • http — HTTP function execution interface

  • control — Local control interface used by scripting commands

These files contain the host:post portion of the URL used to communicate with the named service.

Note

Although modifying this location is allowed, each instance must have a unique endpoint directory. Otherwise, the behavior is undefined.

Parameters

path

Path to the folder used to store endpoint files relative to the root folder of the server instance.

Examples

Store endpoint files in the endpt folder.

--endpoint-root ./endpt

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--endpoint-root ./endpt

Syntax

--log-severity level

Description

log-severity specifies the level of detail at which to add information to the main log. For more details on logging, see Manage Log Files.

Parameters

level

Severity threshold at which messages are logged. Valid values are:

  • error — Notification of problems or unexpected results

  • warning — Events that could lead to problems if not addressed

  • information — High-level information about major server events

  • trace — Detailed information about the internal state of the server

The levels are cumulative. For example, specifying information includes warning and error messages.

Examples

Enable all log messages by setting the severity level to trace.

--log-severity trace

Dashboard Usage

In the Settings tab of your server instance, under Logging, set Log Severity to the desired value. For example: trace.

Syntax

--log-rotation-size size

Description

log-rotation-size specifies the maximum size to which the log can grow before it is rotated into the archive area. If you specify a size lower than 1 MB, the server issues a warning and increases the effective size to 1 MB.

No entry signifies that logs are never archived.

Parameters

size

Size of the log file.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

Examples

Rotate logs when they reach 5 MB.

--log-rotation-size 5MB

Dashboard Usage

In the Settings tab of your server instance, under Logging, set Log Rotation Size to the desired value. For example: 5MB.

Syntax

--hide-matlab-error-stack

Description

hide-matlab-error-stack controls whether the server sends the MATLAB error stack to the client. You can choose to send the error stack during development and debug phases but can turn it off in production.

Examples

Disable transmission of the error stack to clients.

--hide-matlab-error-stack

A REST client receives an error like this one.

{
    "error": {
        "id": "MATLAB:invalidConversion",
        "message": "Conversion to double from struct is not possible.",
        "type": "matlaberror"
    }
}

To enable transmission of the error stack to clients, add a # to comment out the property.

#--hide-matlab-error-stack

Now, a REST client receives an error like this one.

{
    "error": {
        "id": "MATLAB:invalidConversion",
        "message": "Conversion to double from struct is not possible.",
        "stack": [
            {
                "file": "C:\\Program Files\\MATLAB\\MATLAB Runtime\\v99\\mcr\\toolbox\\matlab\\elmat\\magic.m",
                "line": 9,
                "name": "magic"
            },
            {
                "file": "J:\\server20b\\.mps_deployed\\mpsTestData_6\\mpsTestData\\m\\myMagic.m",
                "line": 7,
                "name": "myMagic"
            }
        ],
        "type": "matlaberror"
    }
}

Dashboard Usage

In the Settings tab of your server instance, under Core, select or clear Hide MATLAB Error Stack.

Syntax

--log-archive-root path

Description

log-archive-root specifies the path to the directory that stores rotated log files.

Note

If you omit this property, rotated logs remain in the log root directory, which grows unbounded as logs are rotated.

Parameters

path

Path to the folder where log files are archived relative to the server instance's root folder.

Examples

Archive logs to a folder named old_logs, located in the root folder of the server instance.

--log-archive-root ./old_logs

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--log-archive-root ./old_logs

Syntax

--log-archive-max-size size

Description

log-archive-max-size specifies the maximum size to which the log archive folder can grow before old log files are deleted.

If this property is not specified, then the log archive grows without limit.

Parameters

size

Size, in bytes, of the archive folder.

Specify size as an integer, followed by one of these optional strings specifying the unit.

  • b — Bytes

  • k — Kilobytes (1024 bytes)

  • m — Megabytes (10242 bytes)

  • g — Gigabytes (10243 bytes)

  • t — Terabytes (10244 bytes)

  • p — Petabytes (10245 bytes)

If you do not specify a unit, size is measured in bytes. Unit letters are not case-sensitive. The server reads only the first letter of the unit string.

Examples

Reap log archives when they reach 5 MB.

--log-archive-max-size 5MB

Dashboard Usage

In the dashboard, in the Settings tab of your server instance, under Logging, set Log Archive Max Size to the desired value. For example: 5MB.

Syntax

--log-handler format command

Description

log-handler adds a log handler that writes log data to the application specified by command in the format specified by format.

The server instance launches an instance of the log handler at startup. All log events are sent to the STDIN stream of the log handler. The STDOUT and STDERR streams of the log handler are captured and written to INSTANCE_ROOT/log/custom_logger_N.out and INSTANCE_ROOT/log/custom_logger_N.err.

Parameters

format

Format used to write log events. Valid values are:

  • text/plain

  • text/json

  • text/xml

command

Application launched to process log events.

Examples

Send log events to a custom JSON parser that prepares performance graphs.

--log-handler text/json perf_grapher

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--log-handler text/json perf_grapher

Since R2020a

Syntax

--main-log-format format

Description

main-log-format specifies the text format for logging events in the main.log file. If you do not set this property, the server writes the log data as plain text.

For more details on logging, see Manage Log Files.

Parameters

format

Format for writing log events. Valid values are:

  • text/plain — Log the data in plain text.

  • text/json — Log the data in JSON format.

  • text/xml — Log the data in XML format.

Examples

Log events in JSON format.

--main-log-format text/json

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--main-log-format text/json

Syntax

--profile state object

Description

profile logs server profile information in the main log for an object when the state is on. The default state is off, where the server does not log any profile information. You can log profile information for multiple objects by specifying multiple profile properties.

To set up profiling options when you configure a server, specify the profile property. If you update the profile property for a server that is already running, you must restart the server for the update to take effect. To set or update the profiling options for an already running server without having to restart the server, use the mps-profile command. Running mps-profile overrides any profiling options set using the profile property.

For more details about logging, see Manage Log Files.

Note

Activating profiling has a negative impact on performance.

Parameters

state

Flag to control whether the server writes profile information to the main log. Valid states are:

  • on — Log profile information.

  • off — Do not log profile information.

object

Information to log. Valid objects are:

  • server — Information about requests that the server receives and the worker pool

  • server.request — Information about server requests, which includes information about the requested archives and the clients that make the requests

  • server.request.archive — Information about archives in the request

  • server.request.client — Information about clients that make the request

  • server.worker and server.worker.pool — Information about the worker pool

The objects are hierarchical. For example, specifying server.request implies specifying server.request.archive and server.request.client.

If you do not specify an object, the server logs information for all the objects.

Examples

Log profile information for all objects.

--profile on

Log profile information for server requests only.

--profile on server.request

Log profile information for the clients in a request and workers.

--profile on server.request.client
--profile on server.worker

This excerpt of a main log contains profiling information for all objects.

93 [2020.03.19 13:05:56.554236] [profile] [client:[::1]:62736] [component:mymagic] [connection_id:2] 
[function:magic] [mode:sync] [request_id:0:1:1][service:http-connection] [type:request_arrive] 
Request arrived and was placed in the queue.
94 [2020.03.19 13:05:56.554236] [profile] 
Request to allocate next available worker
95 [2020.03.19 13:05:56.555240] [profile] 
Lease created for worker-1
96 [2020.03.19 13:05:56.555240] [profile] [client:[::1]:62736] [request_id:0:1:1] [type:request_start] [worker_id:1] 
Request started executing on worker 1
...
99 [2020.03.19 13:05:56.558233] [profile] [client:[::1]:62736] [request_id:0:1:1] [type:request_finish] [worker_id:1] 
Request completed with HTTP status 200
100 [2020.03.19 13:05:56.558233] [profile] 
Lease terminated for worker-1
101 [2020.03.19 13:05:56.558233] [profile] 
worker-1 PASSED health check; returning to the pool

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--profile on server.request.client
--profile on server.worker

Startup and Shutdown

expand all

Syntax

--disable-control-c

Description

disable-control-c disables Ctrl+C terminal interruption for the server instance.

If you set both disable-control-c and enable-graceful-shutdown, then the server ignores the Ctrl+C terminal interrupt event. The server gracefully shuts down only when receiving the program termination signal or when the system shuts down or restarts.

Examples

Disable Ctrl+C terminal interruption.

--disable-control-c

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--disable-control-c

Since R2020a

Syntax

--enable-graceful-shutdown

Description

enable-graceful-shutdown enables graceful shutdown of server processes if they are interrupted by a terminal interrupt signal or terminated by the program termination signal. When the system that runs the server shuts down or restarts, the server releases any checked out licenses.

If you set both disable-control-c and enable-graceful-shutdown, then the server ignores the Ctrl+C terminal interrupt event. The server gracefully shuts down only when receiving the program termination signal or when the system shuts down or restarts.

Examples

Enable graceful server shutdown.

--enable-graceful-shutdown

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--enable-graceful-shutdown

Syntax

--no-display

Description

no-display disables the X11 graphics display for worker processes running on UNIX systems. Graphics display is disabled by default. Enabling it is not recommended. MATLAB code deployed to the server typically does not require a graphical display. On UNIX systems, enabling the display significantly degrades performance through an increase in average request latency and a decrease in throughput.

Examples

Enable the X11 graphics display by commenting out the no-display property (not recommended).

# --no-display

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

# --no-display

Since R2020a

Syntax

--server-termination-grace-period hr:min:sec.fractSec

Description

server-termination-grace-period specifies the time interval to wait, after receiving an mps-stop command, before forcibly terminating all running server and worker processes. This grace period gives the server time to gracefully shut down.

If the server has a server-termination-grace-period value specified, then:

  • If you run mps-stop with the --timeout option, server processes forcibly terminate at the hr:min:sec.fractSec value specified by server-termination-grace-period.

  • If you run mps-stop with both the -k and --timeout options, then server processes forcibly terminate within the duration specified by the --timeout value.

Parameters

hrHours in interval
minMinutes in interval
secSeconds in interval
fractSecFractional seconds in interval

Examples

Forcibly terminate server instance processes after 1 hour, 29 minutes, and 5 seconds.

--server-termination-grace-period 1:29:05

Forcibly terminate server instance processes after 10 minutes and 250 ms.

--server-termination-grace-period 00:10:00.25

Dashboard Usage

In the Settings tab of your server instance, under Advanced, specify the property setting in the Additional Options box. For example:

--server-termination-grace-period 1:29:05

Version History

expand all