Configure and Start the Cluster Admin

The Cluster Admin is an agent that enables you to install, configure, and start the Docker containers for the different Polyspace^® Access services.

Prerequisites

Before configuring and starting the Cluster Admin, make sure that:

You have downloaded the Polyspace Access installation image. To download the installation image:
1. Go to the MathWorks^® download page and click the Download Rxxxxy button. You may be required to log in to your MathWorks account to complete this step.
2. On the following page, select the Polyspace Access link under Additional Rxxxxy Product Downloads.
Rxxxxy corresponds to a release number, for instance R2021a.
Docker is running on your machine. At the command line, type:
```
docker stats --no-stream
```
If you get an error message, run the command sudo systemctl start docker. If systemctl is not available, use service instead.
After you start Docker, you must be logged in as a member of the docker group to run Docker commands. To see a list of current members of this group, use the command:
```
grep 'docker' /etc/group
```
To add the current user to the docker group, use the command:
```
sudo usermod -aG docker $USER
```

Unzip Installation Image and Start Cluster Admin Agent

The Cluster Admin admin-docker-agent binary is included with the polyspace-access-VERSION.zip installation image for Polyspace Access. VERSION is the release version, for instance R2021a. After you download the installation image, unzip it to extract these files and folders:

admin-docker-agent*
admin-docker-agent.exe*
admin.tar
appdata/
download/
gateway.tar
issuetracker-server-main.tar
issuetracker.tar
issuetracker-ui-main.tar
lm/
polyspace-access-db-main.tar
polyspace-access-etl-main.tar
polyspace-access.tar
polyspace-access-web-server-main.tar
products/
usermanager-db-main.tar
usermanager-server-main.tar
usermanager.tar
usermanager-ui-main.tar
VERSION

To start the admin-docker-agent binary, from the command line, navigate to the installation folder where you extracted the contents of the zip installation image. Once inside this folder, at the command-line, enter:

admin-docker-agent

The command line outputs messages indicating that the agent is downloading image layers. After the download is complete, you see a message with information on how to connect to the agent:

time="2020-07-10T14:23:11Z" level=info msg="Cluster Admin started. You can now connect to the Cluster Admin through 
your web browser at http://localhost:9443/admin using the initial password randomPass

randomPass is a randomly generated initial password. Copy this password. The command-line output shows the password only the first time you start Cluster Admin.

By default, the Cluster Admin uses the HTTP protocol and starts with host name localhost and port 9443. To configure the Cluster Admin with HTTPS, see Choose Between HTTP and HTTPS Configuration for Polyspace Access. If the port is already in use, you get Permission denied error message. Use the flag --port to specify a different port number, for instance:

admin-docker-agent --port 9999

To reset the password, press CTRL+C to stop the admin-docker-agent binary and enter this command:

admin-docker-agent --reset-password

To view the new password, restart the binary.

The Cluster Admin agent creates a settings.json file the first time it starts, and stores this file in the same folder as the admin-docker-agent binary by default. Ensure that only the user who starts the admin-docker-agent has read/write permissions on the settings.json file.

Choose Between HTTP and HTTPS Configuration for Polyspace Access

HTTP Configuration

By default, the Cluster Admin uses the HTTP protocol. When you start the admin-docker-agent binary, you do not need to specify any additional flags.

HTTPS Configuration

To encrypt the data between Polyspace Access and client machines, configure the Cluster Admin with the HTTPS protocol. To complete the configuration, provide an SSL certificate and the private key that you used to generate the certificate as PEM files.

Do not reuse the private key file that you use for the Authentication private key file in the User Manager configuration.

It is recommended that you use a certificate issued by a certificate authority to configure HTTPS. If you do not want to use a certificate authority, you can configure HTTPS by using self-signed certificates.

Secure your private key by following best practices such as:

Do not transfer the private key between machines. Instead, generate and store the private key on a local file system.
Restrict read/write permissions. Grant access to the private key file only to the Cluster Admin administrators.
Rotate your private key and certificate regularly (annually) and audit which users have access to the private key file.

The configuration of HTTPS for the Cluster Admin enables HTTPS for the API Gateway service. This service handles all communications between the other Polyspace Access services and client machines.

The SSL certificate, private key, and CA files that you provide when you start the admin-docker-agent binary are reused in the Nodes settings, unless the node is already configured with a different set of files. When you select Enable SSL for a node, you enable HTTPS for all the services installed on that node. Enabling SSL in the Nodes settings affects communications only between the Polyspace Access services, and between those services and the bug tracking tool and LDAP servers. To view and make changes to the Nodes settings, click Configure Nodes on the Cluster Dashboard.

By default, all services are installed on the same node and the services ports are not exposed. You do not need to enable HTTPS for the User Manager, Issue Tracker, and Polyspace Access services unless you install these services on different nodes, or you start the admin-docker-agent binary with option --force-exposing-ports.

Use Certificates Signed by a Certificate Authority

These steps illustrate how to configure SSL encryption on a Debian Linux system by using your organization's certificate authority and the openssl utility.

Create a certificate signing request. In the CN field (common name), specify hostName, the fully qualified domain name (FQDN) of the machine where you run the admin-docker-agent binary.
```
openssl req -new -newkey rsa:4096 -nodes -out myRequest.csr -keyout myKey.key \
-subj "/C=US/ST=/L=/O=/CN=hostName"
```
The command outputs a private key file myKey.key and the file myRequest.csr, which contains a public key and data that describes your server.
Submit myRequest.csr to your organization's certificate authority. The certificate authority uses the file to generate a signed server certificate. For instance, admin_cert.cer.
Start admin-docker-agent and use the generated private key and signed certificate. Specify the FQDN hostName and the full path to the certificate trust store file ca-certificates.crt :
```
./admin-docker-agent --hostname hostName\
--ssl-cert-file fullPathTo/admin_cert.cer \
--ssl-key-file fullPathTo/myKey.key \
--ssl-ca-file  /etc/ssl/certs/ca-certificates.crt
```
The hostName you specify in this command must match the hostName you specified in step 1. fullPathTo is the full file path.

When you open the Cluster Admin web interface, your browser considers the connection secure if the browser uses the certificate trust store that you specify for --ssl-ca-file.

Use Self-Signed Certificates

To configure HTTPS on a Debian Linux system by using a self-signed certificate that you generate with openssl, follow these steps:

Generate a certificate and private key as PEM files. In the CN field (common name), specify hostName, the fully qualified domain name (FQDN) of the machine where you run the admin-docker-agent binary.
```
openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -keyout private_key.pem \
-out certificate.pem -subj "/C=US/ST=/L=/O=/CN=hostName"
```
Start the admin-docker-agent binary and use the generated certificate.pem and private_key.pem files. Specify the FQDN hostName.
```
./admin-docker-agent --hostname hostName\
--ssl-cert-file fullPathTo/certificate.pem \
--ssl-key-file fullPathTo/private_key.pem \
--ssl-ca-file  fullPathTo/certificate.pem
```
The hostName you specify in this command must match the hostName you specified in step 1. The self-signed certificate.pem file is also used as the certificate trust store file. fullPathTo is the full file path. If you use relative paths, you get an error message.

When you open the Cluster Admin web interface, your browser shows a warning about the certificate being untrusted.

Open the Cluster Admin Interface

After you configure and start the Cluster Admin, open your web browser and go to URL specified in the command-line output when you started the admin-docker-agent binary.

Log in with the initial password that you obtained when you started the Cluster Admin agent. If this is your first time logging in, follow the prompts.

Cluster Admin Dashboard interface.

It is best practice to change your Cluster Admin password after your first login. To set a new password, click Account in the upper right corner of the web interface and select Change password. Share the Cluster Admin password only with users who configure and manage the Polyspace Access services.

On the Cluster Dashboard, click Configure Apps to go to the Cluster Settings. Whenever you change the settings, return to the Cluster Dashboard and click Restart Apps for the changes to take effect. To save partially filled settings, clear Validate on Save.

Note

On Windows^® systems, all the file paths that you specify must point to local drives.

Documentation