Main Content

admin-docker-agent

(DOS/UNIX) Launch Cluster Admin interface to manage User Manager, Issue Tracker, and Polyspace Access Apps

Since R2020b

collapse all in page

Syntax

admin-docker-agent [OPTIONS]

Description

admin-docker-agent [OPTIONS] starts the Cluster Admin interface. If you do not specify additional OPTIONS, the Admin agent uses host name localhost and starts with the HTTP protocol on port 9443.

example

Examples

collapse all

The Cluster Admin uses the HTTP protocol by default. Encrypt the data between the Cluster Admin and client machines by configuring the Cluster Admin with the HTTPS protocol. This configuration also enables HTTPS for the API Gateway service, which handles communications between all the other services and client machines.

If you install Polyspace® Access on multiple nodes, or if you use the --force-exposing-ports to start the Admin agent, you must configure HTTPS for the User Manager, Issue Tracker, and Polyspace Access services separately. To configure HTTPS for the services, click Configure Nodes on the Cluster Dashboard.

Create a self-signed SSL certificate and private key file by using the openssl toolkit. 

openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout self_key.pem -out self_cert.pem
After you enter the command, follow the prompts on the screen. You can leave most fields blank, but you must provide a Common Name (CN). The CN must match the fully qualified domain name (FQDN) of the machine running the admin-docker-agent. The command outputs a certificate file self_cert.pem and a private key file self_key.pem.

To obtain the FQDN of the machine, use the command hostname --fqdn on Linux® or net config workstation | findstr /C:"Full Computer name" on Windows®.

Start the admin-docker-agent by using the certificate and private key files that you generated and specify hostName, the FQDN of the machine. hostName must match the FQDN that you entered for the CN of the SSL certificate. In the command, specify the absolute path to the files.

Windows PowerShell 
admin-docker-agent --hostname hostName`
--ssl-cert-file absolutePathTo\self_cert.pem `
--ssl-key-file absolutePathTo\self_key.pem.pem `
--ssl-ca-file absolutePathTo\self_cert.pem
Linux 
./admin-docker-agent --hostname hostName \
--ssl-cert-file absolutePathTo/self_cert.pem \
--ssl-key-file absolutePathTo/self_key.pem.pem \
--ssl-ca-file absolutePathTo/self_cert.pem

You can now access the Cluster Admin web interface from your browser by using https://hostName:9443/admin.

Input Arguments

collapse all

Options to specify and manage the connection settings of the Cluster Admin.

General Options

OptionDescription

--hostname hostName

Specify the fully qualified domain name of the machine on which you run the Cluster Admin. This option is required if you use the HTTPS configuration options. hostName must match the Common Name (CN) that you specify to obtain SSL certificates.

The default host name is localhost.

--port portNumber

Specify the server port number that you use to access the Cluster Admin web interface.

The default port value is 9443.

--data-dir dirPath

Specify the absolute path to the folder containing the settings.json file.

If the file does not exist, the Cluster Admin creates it in the specified folder.

If the file already exists, the Cluster Admin reuses its contents to configure the settings.

The default folder is the current folder.

--network-name networkName

Specify the name of the Docker® network that the Polyspace Access™, User Manager, and Issue Tracker apps use.

Use this option if you do not want the apps to use the default mathworks network, for instance, if that network conflicts with an existing network.

To check if your docker network conflicts with an existing network, run this command:

docker network inspect networkName
and inspect the IPAM.Config node to view the IP range that is used by the network. You might need to contact your network administrator to determine if the IP range is used by other services. To find networkName, use the command docker network ls.

To create a new network, see docker network create.

--force-exposing-ports

Specify this option to expose the ports of the services when you install all the services on a single node. To specify the Docker host port to which the exposed ports bind, open the Cluster Admin, click Configure Nodes, then go to the Services tab.

By default, when you install on a single node, the ports of the services are not exposed.

Use this option if you install on a single node but you must communicate with one of the services through a third party tool, for instance if you use PostgreSQL utilities to communicate with the Polyspace Access database.

--reset-passwordReset the password that you use to log into the Cluster Admin web interface.
--versionDisplay the version number of the Admin agent.
--helpDisplay the help menu.

HTTPS Configuration Options

On Windows systems, all paths must point to local drives.

OptionDescription

--ssl-cert-file absolutePath

Specify the absolute path to the SSL certificate PEM file.

--ssl-key-file absolutePath

Specify the absolute path to the SSL private key PEM file that you used to generate the certificate.

--ssl-ca-file absolutePath

Specify the absolute path to the certificate store where you store trusted certificate authorities. For instance, on a Linux Debian® distribution, /etc/ssl/certs/ca-certificates.crt.

If you use self-signed certificates, use the same file that you specify for --ssl-cert-file

--restart-gateway

Use this option to restart the Gateway service if you restart the admin-docker-agent and you make changes to the HTTPS configuration options or you specify a different port.

Restart the Gateway service by using this option if you make changes to the HTTPS configuration options or specify a different port.

New Node Configuration Options

If you choose to install Polyspace Access on multiple machines, use these options to create nodes on the different machines. In the Cluster Dashboard, click Configure Nodes, and then select the Services tab to select the node on which you want to run the service.

Before you create a node, you must have an instance of the admin-docker-agent already running on at least one other machine. This other machine hosts the main node.

OptionDescription

--main-host hostName:port

Specify the host name and port number of the machine hosting the main node.

--node-id nodeName

Name of the node that you create. After you start the Cluster Admin, you see this node listed in the Node drop-down lists on the Services tab of the Nodes settings.

Version History

Introduced in R2020b

expand all

See Also

Topics