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@myhostnameDashboard Usage
For on-premises server instances created using the dashboard interface, edit the corresponding server properties in the dashboard.
For server deployments on the cloud using a reference architecture, edit the corresponding server properties in the cloud dashboard. For more details, see the cloud dashboard documentation for your deployment.
HTTP and HTTPS
http — HTTP endpoint for insecure server connections
Syntax
--http port --http host:port
Description
http specifies the interface port and optional address or
hostname.
Parameters
| Port number used by the server instance to accept connections. Bind
to any available port by specifying
Default: |
| 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:
|
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.
https — HTTPS endpoint for secure server connections
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
| 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 number used by the server instance to accept connections. Bind
to any available port by specifying |
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
mcr-root — Location of MATLAB Runtime installation
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-rootmust 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 to the root folder of the MATLAB Runtime installation. Default: |
Examples
Use the latest version of the MATLAB Runtime.
--mcr-root /usr/local/MATLAB/MATLAB_Runtime/R2024bTo 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/v98Dashboard 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/R2024bTo specify multiple versions, separate them by commas.
/usr/local/MATLAB/MATLAB_Runtime/R2024b, /usr/local/MATLAB/MATLAB_Runtime/v98user-data — Associate MATLAB data value with string key
Syntax
--user-data key value
Description
user-data associates MATLAB data valuekey\) 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 used to access a MATLAB value, specified as a string. |
| MATLAB 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
license — Locations for valid licenses
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$MPS_INSTALL
For more details on licensing, see Manage Licenses for MATLAB Production Server.
Parameters
| Path to one or more license servers or license files. Separate
multiple entries by the appropriate path separator for the platform. Use a
colon ( |
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.
license-grace-period — Maximum time that server responds to HTTP requests after lost license server heartbeat
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
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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.
license-poll-interval — Time interval to poll license server after it times out or grace period expires
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
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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
ssl-verify-peer-mode — Client verification level required by server
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 used to authenticate clients. Valid values are:
Default:
|
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.
ssl-tmp-dh-param — Pregenerated ephemeral DH key file
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 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.
ssl-tmp-ec-param — Elliptic curve used for ECDHE ciphers
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
| 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.
ssl-protocols — SSL protocols allowed
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
| Comma-separated list of allowed protocols. Valid entries are:
Default:
|
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.
ssl-ciphers — Cipher suites used for encryption
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
| Cipher suites the server instance uses for encryption. Valid values are:
To provide finer control over the selected cipher, you can pass OpenSSL configuration strings with the ciphers. Default:
|
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.
ssl-allowed-client — MATLAB programs client can access
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
| Common name of the client. |
| 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.
enable-ssl-renegotiation — Option to enable SSL renegotiation
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
x509-private-key — Private key file in PEM format
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 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.
x509-passphrase — Passphrase file that decodes private key
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 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.
x509-cert-chain — Server certificate chain file
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 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.
x509-ca-file-store — Server certificate authority file
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 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.
x509-use-system-store — Option to use certificate authority store provided by system
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.
x509-use-crl — Option to use certificate revocation list
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
http-authentication-method — HTTP authentication method
Syntax
--http-authentication-method method
Description
--http-authentication-method
specifies the HTTP authentication method that the server uses to authenticate the
client.method
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
| Name of HTTP authentication 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.
client-credential-delegation — Client credential delegation method
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
| Name of the client credential delegation 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
access-control-provider — Identity management service provider
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
| Identity 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
access-control-config — Identity management service provider configuration file
Syntax
--access-control-config path
Description
--access-control-config
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
path./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 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
access-control-policy — Access control policy file
Syntax
--access-control-policy path
Description
--access-control-policy
specifies the path to the access control policy file on a server instance. Setting
this property is optional. The default path is
path./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 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
num-workers — Maximum number of workers allowed to process work simultaneously
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
| 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:
|
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.
component-isolation — Deployable archives to be assigned their own pools of workers, specified by a regular expression
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.
| ECMAScript regular expression which matches filenames of deployable archives to be isolated
|
| Positive integer which overrides
|
|
Example If there are 2
|
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.
worker-restart-interval — Time interval at which server instance stops and restarts workers
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
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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
worker-restart-memory-limit — Memory threshold for restarting a worker
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
| Amount of memory used by worker. Specify
If you do not specify a unit, |
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.
worker-restart-memory-limit-interval — Time interval for which worker can exceed memory limit before restart
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
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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.
worker-memory-check-interval — Time interval at which workers are polled for memory usage
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
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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.
worker-memory-trigger — Upper-bound memory usage threshold at which to begin shutting down workers
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
| Memory amount size. Specify
If you do not specify a unit, |
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.
worker-memory-target — Lower-bound memory usage threshold at which to stop shutting down workers
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
| Memory amount size. Specify
If you do not specify a unit, |
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.
queue-time-trigger — Time interval at which to grow worker pool for requests in queue
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:
Sort requests by their arrival time on the server.
Map requests, from oldest to newest, onto idle workers.
If a request is unable to map to a worker, and the queue time of the request exceeds the
queue-time-triggervalue, create additional workers to process the requests.Stop creating additional workers when either of these conditions are met:
The queue time of the oldest request falls below the
queue-time-targetvalue.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
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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.
queue-time-target — Time interval at which to stop growing worker pool for requests in queue
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:
Sort requests by their arrival time on the server.
Map requests, from oldest to newest, onto idle workers.
If a request is unable to map to a worker, and the queue time of the request exceeds the
queue-time-triggervalue, create additional workers to process the requests.Stop creating additional workers when either of these conditions are met:
The queue time of the oldest request falls below the
queue-time-targetvalue.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
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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.
merge-worker-streams — Option to merge stdout and stderr worker streams into single stream
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
socket-root — Sockets folder for interprocess communication
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
| Path 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
request-size-limit — Maximum request size
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 of the request. Specify
If you do not specify a unit, |
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.
request-timeout — Time interval at which requests time out
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
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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.
cors-allowed-origins — Domain origins that clients can make server requests from
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. |
| 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.
http-linger-threshold — Data amount discarded between HTTP error and TCP connection closing
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
| Amount of data received before the TCP connection is reset. Specify
If you do not specify a unit, |
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.
enable-http-pipelining — Option to enable parallel execution of pipelined requests
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.
files-root — Path to files for serving static content over HTTP or HTTPS
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
hostportfilename.extextis the file extension
For details on serving static content using web handlers, see Handle Custom Routes and Payloads in HTTP Requests.
Parameters
| 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
routes-file — Location of URL routes file for HTTP web handlers
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
| Path 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
server-memory-threshold — Size threshold of server process at which responses are archived or purged
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
sizeserver-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
| Threshold size of the server process. Specify
If you do not specify a unit, |
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.
server-memory-threshold-overflow-action — Action taken when memory size threshold of server process is breached
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
| Overflow action to take when the server reaches the memory threshold. Valid values are:
|
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.
response-archive-root — Response archive folder
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 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
response-archive-limit — Maximum disk space available to server process for archiving
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 of the server process. Specify
If you do not specify a unit, |
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
num-threads — Number of request-processing threads within server instance
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
| Number of threads available in the thread pool, specified as a positive integer. Default:
|
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.
use-single-comp-thread — Option to start MATLAB Runtime with single computational thread
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
auto-deploy-root — Folder that the server instance scans for deployable archives
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 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
async-deploy-on-startup — Option to deploy archives after server starts
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
extract-root — Root folder used to store contents of deployed archives
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 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
enable-discovery — Option to enable API for discovering MATLAB functions deployed on server
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.
enable-metrics — Option to enable API for retrieving server metrics
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
log-root — Log file folder
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 ofmain.logreaches the limit set by thelog-rotation-sizeproperty, the server renamesmain.logtomain__DATE__SERIAL.logand archives it in the folder set by thelog-archive-rootproperty. The default archive location is theold_logsfolder 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 to the folder containing log files for a server instance. Default:
|
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
pid-root — PID file folder
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 processworker_N.pid— The process identifiers of each worker processN
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 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
endpoint-root — Server-named endpoint folder
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 interfacecontrol— 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 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
log-severity — Severity at which messages are logged
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
| Severity threshold at which messages are logged. Valid values are:
The levels are cumulative. For example,
specifying |
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.
log-rotation-size — Size at which log is archived
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 of the log file. Specify
If you do not specify a unit, |
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.
hide-matlab-error-stack — Option to hide MATLAB error stack from clients
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.
log-archive-root — Archived log file folder
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 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
log-archive-max-size — Maximum size of log archive folder
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, in bytes, of the archive folder. Specify
If you do not specify a unit, |
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.
log-handler — Add custom log handler
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.outINSTANCE_ROOT/log/custom_logger_N.err
Parameters
| Format used to write log events. Valid values are:
|
| 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
main-log-format — Text format of main log file
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 for writing log events. Valid values are:
|
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
profile — Log server profile information
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
| Flag to control whether the server writes profile information to the main log. Valid states are:
|
object | Information to log. Valid objects are:
The objects are hierarchical. For example, specifying
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
disable-control-c — Option to disable keyboard interruptions for server instance
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
enable-graceful-shutdown — Option to enable graceful shutdown of server processes
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
no-display — Option to disable X11 graphics display for worker processes on UNIX® systems
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
server-termination-grace-period — Time interval to wait before forcibly terminating all server processes
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-stopwith the--timeoutoption, server processes forcibly terminate at thehr:min:sec.fractSecvalue specified byserver-termination-grace-period.If you run
mps-stopwith both the-kand--timeoutoptions, then server processes forcibly terminate within the duration specified by the--timeoutvalue.
Parameters
| Hours in interval |
| Minutes in interval |
| Seconds in interval |
| Fractional 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
R2021a: Provider option of access-control-provider property will be renamed
In the access-control-provider property, specify the provider option as
OAuth2 instead of AzureAD. Specifying
OAuth2 includes support for AzureAD.
R2021a: azure_ad.json filename of access-control-config property will be removed
In the access-control-config property, the azure_ad.json filename
will be removed in a future release. If the access-control-provider
property is set to OAuth2, the default name for the access control
configuration file is now jwt_idp.json instead of
azure_ad.json.
R2020b: requests and worker_pool objects of profile property will be removed
In the profile property, the objects requests and
worker_pool will be removed in a future release. Use
server.request instead of requests and
server.worker.pool instead of worker_pool.
See Also
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)