Setting Options for the Platform Assistant

From RAD Studio
Jump to: navigation, search

Go Up to PAServer, the Platform Assistant Server Application


When you run the Platform Assistant, the following configuration is used by default:

  • The port number is 64211.
  • No password is required.
  • The scratch directory is located inside the Platform Assistant installation directory. See The Scratch Directory for more information about this directory.

To configure the port, the password, and the scratch directory options when you run the Platform Assistant from the command line, do either of the following:

The value for an option is determined as follows:

  1. If you define the value for an option on the command line, the Platform Assistant uses that value.
  2. If you define the value for an option in the specified configuration file and you do not define the value on the command line, the Platform Assistant uses the value specified in the configuration file.
  3. If you do not define the value for an option neither on the command line nor in a specified configuration file, the Platform Assistant uses the default value for that option.
Note: Options have effect only while the Platform Assistant is running. If you want to use the same options the next time you run the Platform Assistant, you must specify again those options in the command line. You can use a configuration file to specify a group of options with a single command-line switch.

You can also create an encrypted password file (.passfile) so that another person can connect to the Platform Assistant without knowing the password you have configured on the Platform Assistant.

Configuring the Platform Assistant with Command-Line Switches

Configuring the Port Number on the Command Line

To specify the port where the Platform Assistant listens for incoming connections, use the -port when you run the Platform Assistant from the command line:

  • Windows:
    > paserver -port=nnnnn
  • macOS:
    $ ./paserver -port=nnnnn
  • Linux:
    $ ./paserver -port=nnnnn

The port number must be between 1 and 65,535.

Configuring the Password on the Command Line

The Platform Assistant can be configured with a password. If you specify a password, when a client (for example, RAD Studio) attempts to connect to the Platform Assistant, the Platform Assistant requires the client to provide the password.

When you run the Platform Assistant, you are prompted for a password (or no password). You can alternatively specify a password (or no password) with the -password command-line switch when you run the Platform Assistant on the command line:

  • Windows:
    > paserver -password=B2C3d4!
  • macOS:
    $ ./paserver -password=B2C3d4!
  • Linux:
    $ ./paserver -password=B2C3d4!

Configuring the Scratch Directory on the Command Line

The Platform Assistant saves project output files inside a scratch directory that you can specify and configure.

Specifying the Scratch Directory Location on the Command Line

To specify a custom location for the scratch directory, use the -scratchdir option when you run the Platform Assistant from the command line:

  • Windows:
    > paserver -scratchdir=NewScratchDirectory
  • macOS:
    $ ./paserver -scratchdir=NewScratchDirectory
  • Linux:
    $ ./paserver -scratchdir=NewScratchDirectory

The path to the new scratch directory is relative to the Platform Assistant installation directory by default. On macOS and Linux, you can specify a scratch directory path relative to your user directory by prefacing the directory path with a tilde-slash (~/) when you start the Platform Assistant: 

$ ./paserver -scratchdir=~/MyTestDir

This command configures /Users/MyUsername/MyTestDir directory as the scratch directory on the Mac.
This command configures /Home/MyUsername/MyTestDir directory as the scratch directory on Linux.

You may also provide the absolute path, for example:

  • Windows:
    > paserver -scratchdir=C:\PAServer\scratch-dir
  • macOS:
    $ ./paserver -scratchdir=/PAServer/scratch-dir
  • Linux:
    $ ./paserver -scratchdir=/PAServer-19.0/scratch-dir

Scratch Directory Exceptions

If you provide a path as the scratch directory that does not exist, but can be created (for example, the path includes directories that do not exist), the Platform Assistant automatically creates any missing directories. If that is not possible, the The system cannot find the path specified error occurs.

The following exceptions may occur in relation to the scratch-dir settings:

Allowing File Operations Outside the Scratch Directory on the Command Line

Caution: Using -unrestricted mode with the Platform Assistant is not recommended.

By default, the Platform Assistant operates in restricted mode. That is, the Platform Assistant performs file operations (put and remove) only inside the scratch directory for your connection profile. In the default (restricted) mode, RAD Studio and paclient.exe can add or delete files only inside the scratch directory.

However, if you specify the -unrestricted command-line switch when you start the Platform Assistant, the Platform Assistant allows file operations outside the scratch directory.

Configuring the Platform Assistant with a Configuration File

You can use the -config command-line switch to specify a custom configuration file for the Platform Assistant.

The default configuration file of the Platform Assistant, paserver.config, is located in the Platform Assistant installation directory. This configuration file can contain any of the parameters accepted by the Platform Assistant, including those described above. For a complete list of the available options, run the Platform Assistant command-line help.

By default, the paserver.config file contains only the following two commands, but you can edit them and add other Platform Assistant commands (such as passfile, password, or unrestricted): 

port=
scratchdir=

These two parameters define:

  • The communication port: the default value is 64211 for all platforms.
  • The scratch directory: is used for the Platform Assistant file operations.
    • For Windows, the scratchdir parameter is empty. The default scratch directory is the C:\Program Files (x86)\Embarcadero\PAServer\19.0\scratch-dir folder.
    • For Mac macOS, the scratchdir parameter is empty. The default scratch directory for the MyOSX connection profile is the Username-MyOSX folder.
    • For Linux, the scratchdir parameter has the following value: ~/PAServer/scratch-dir.

Note: The default scratch directory is named scratch-dir and is located inside the Platform Assistant installation directory. A separate folder is created for each connection profile. You can provide a different scratch-dir, either as an absolute path or a relative path (relative to the Platform Assistant installation directory). See Specifying the Scratch Directory Location on the Command Line for examples.

Generating and Using an Encrypted Password File

Instead of providing a password to connect to the running Platform Assistant, the Platform Assistant can generate an encrypted password file (.passfile), which you can distribute to your Platform Assistant clients (for example, instances of RAD Studio) to connect to the Platform Assistant. If you start paserver with the .passfile option, paserver requires a connection profile to contain the password that is encrypted in the .passfile.

Generating an Encrypted Password File

Run the Platform Assistant in macOS, Windows, or Linux, when you get to the command prompt, enter the g command to generate an encrypted password file:

> g

The Platform Assistant generates the encrypted password file, and displays the path to the generated file.

When you generate the encrypted password file from a running instance of the Platform Assistant, the instance starts using the encrypted password file automatically. However, the next time you start the Platform Assistant, you need to specify the encrypted password file from the command line.

Starting the Platform Assistant with an Encrypted Password File

To start the Platform Assistant with a specific encrypted password file, you must start the Platform Assistant from the command line using the -passfile switch, with the path to the encrypted password file as the value:

  • Windows:
    > paserver -passfile=filename
  • macOS:
    $ ./paserver -passfile=filename
  • Linux:
    $ ./paserver -passfile=filename

In order to connect to this instance of the Platform Assistant from RAD Studio, you must provide the encrypted password file when you configure the connection profile to use.

Specifying an Encrypted Password File in a Connection Profile

In order to connect to a running Platform Assistant that is using an encrypted password file, you must configure your connection profile to use the encrypted password file for the connection:

  1. Copy the .passfile file from the Mac into your PC.
  2. In RAD Studio, select Tools > Options > Deployment > Connection Profile Manager.
  3. On the Connection Profile Manager dialog box, select the connection profile that you want to use the encrypted password file.
  4. Click the ellipsis [...] in the Password field.
  5. Navigate to the .passfile file you copied from the Mac, and click OK.
  6. Back to the Connection Profile Manager dialog box, click OK to save the changes.

You can now use the modified connection profile to connect to the Platform Assistant.

Note: The steps above describe how to modify an existing profile. You can also create a new profile and configure its Password field as described above.

See Also

Retrieved from "https://docwiki.embarcadero.com/RADStudio/Athens/e/index.php?title=Setting_Options_for_the_Platform_Assistant&oldid=270533"