admin-docker-agent

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

Since R2020b

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.

Examples

Configure HTTPS Protocol With Self-Signed Certificate

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

OPTIONS — Options to manage the Cluster Admin

string

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

General Options

Option	Description
--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-password	Reset the password that you use to log into the Cluster Admin web interface.
--version	Display the version number of the Admin agent.
--help	Display the help menu.

HTTPS Configuration Options

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

Option	Description
--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.

Option	Description
--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

R2023b: Option -master-node Will Be Removed in a Future Release

The option -master-node will be removed in a future release. To create a main node when configuring the Polyspace Access™ services to run on multiple machines, use option -main-node instead.