FWD

Remote Launchers¶

• Remote Launchers
• Introduction
• System Requirements
• Installation and Configuration
• Server Configuration
• Limitations
• Missing in Implementation

Introduction¶

This chapter describes the installation and configuration of remote launching of FWD clients. A remote launcher client (also known as a “broker”) is a special FWD client designed to launch interactive web clients, batch processes and appserver clients (also known as “appserver agents”) on a remote host. Remote in this context means on a separate physical or virtual system from that on which the FWD server is running. Brokers connect to FWD servers using secured socket connections and use digital certificates for authentication.

System Requirements¶

Brokers are a special kind of FWD Client which connects to a running FWD Application Server and waits for a notification that a FWD Client process needs to be spawned. The system on which the Broker runs must meet all the requirements of a Client Installation.

Other requirements are related to the spawner tool, a native application which is used to launch a process in the context of a specific operating system (OS) user. For more details about installing and configuring the spawner tool see the Spawner Setup and Configuration chapter.

Installation and Configuration¶

The broker installation is similar to installation of a normal FWD client, configured to connect as a FWD process (non-interactively). On the remote machine create a folder which should contain a client.xml configuration file, the broker key store file, the broker trust store file and a batch file which is used to start the broker. The broker must have enough rights to access p2j.jar which contains the main class. The p2j.jar must be defined in the Java classpath. This client must also have access to the native library path. CLASSPATH and JVM arguments are inherited by spawned clients from the broker's context. As a consequence, the classpath and native library path must be accessible for both brokers and spawned clients. Basically the p2j.jar and dependencies should be installed somewhere within the machine's file system where the broker and spawned clients have access. For more details on how to install and start a FWD client see the Client_Installation chapter.

When a broker client starts, stderr is automatically redirected to a log file having the following name format:

broker_%user.name%_%time.in.millis%.log

where %user.name% is the OS account user name in which the broker runs and %time.in.millis% is the current system time in milliseconds.

A complete broker configuration file client.xml looks like:

<node type="client">
  <client>
    <mode broker="true" />
  </client>

  <net>
    <server host="192.168.1.10" />
    <server port="3333" />
    <server secure_port="3334" />
    <connection secure="true" />
  </net>

  <security>
    <certificate validate="true" />
    <truststore filename="broker-trust.store" />
    <truststore alias="timco-root" />
    <keystore filename="broker-key.store" />
    <keystore processalias="p2j_proc_alias" />
    <authentication type="program"/>
  </security>

  <access>
    <password truststore="QVBf~&amp;<b7BqCmkq+24tA2qWk8c9ItnH5nzo7" />
    <password keystore="?2nhoOwY&amp;WOsAmn7<9OqP45dYS3z2FLU#1Uk" />
    <password keyentry="7n3F$S2H6<BaL5csxTJU0T+AuTu>bF82qUxk"/>
  </access>

  <remote>
    <retry count="10" />
    <retry seconds="10" />
    <spawner file="/home/broker/spawn" />
  </remote>
</node>

The remote launch clients are using special configuration to indicate that they act as brokers. This parameter can be either preset into the client.xml file or can be sent as a command line parameter client:mode:broker=true which overrides the parameter from client.xml configuration file. As a general rule configuration file parameters can be overridden with command line parameters on broker start.

The net node in configuration file contains the FWD server address and the secure port used to connect to the server while security and access nodes contains SSL settings; is mandatory for the broker to connect in a secure mode and authenticate as a FWD process.

The security node defines the following parameters:

1. security:truststore:filename define the location of trust store file containing server and root CA authority certificates identified by aliases. This file is the same as server trust store file.
2. security:truststore:alias is the alias for the root CA authority certificate and must exists in the trust store file.
3. security:keystore:filename parameter define the location of the key store file containing the user (process) public/private keys pair. A key store file could hold multiple public/private keys pairs each pair having is own alias (identifier).
4. security:keystore:processalias parameter is the user (process) public/private keys pair identifier and must exist in the key store file. When keys are generated the alias attribute from process accounts is used as the key store identifier (alias) for a public/private key pair.
   

   <node class="process" name="p2j_proc">
     ...
     <node-attribute name="alias" value="p2j_proc_alias" />
   </node>
   

5. security:certificate:validate if true, then the server's certificate must be present in the trust store for authentication to succeed.
6. security:authentication:type specifies the authentication type. Valid values: program

The access node holds the following parameters:

1. access:password:truststore Specifies the password to be used to read/decrypt the trust store file.
2. access:password:keystore Specifies the password to be used to read/decrypt the key store file.
3. access:password:keyentry Specifies the password to be used to read/decrypt the in-memory key manager.

For more details see Bootstrap Configuration chapter.

The remote node contains broker specific parameters. When a broker is connected and registered to a FWD server it remains connected having an active session open. If for some reasons a broker is disconnected from server it will try to automatically reconnect to server, depending on the configured remote:retry:count and remote:retry:seconds parameters. Possible scenarios are server is shutdown or network errors. Parameter remote:retry:count defines the number of trials to reconnect having the default value set to 10. The value is decremented on each try and when it reached 0 the broker will exit. Parameter remote:retry:seconds defines the amount of time in seconds between each try having the default value set to 10. When a broker is terminated it is automatically unregistered from the server to which it was connected.

Brokers use the spawner tool in order to perform the remote launch. Parameter remote:spawner:file defines the location of the spawner tool's executable within machine's file system. The spawner tool is a native executable (binary program) that must be installed on the machine on which the broker runs and the broker must have sufficient OS permissions to access (and execute) it. For more details about installing and configuring the spawn tool see the Spawner Setup and Configuration chapter.

Server Configuration¶

On the server side the brokers are defined and configured inside the server directory. Each application server can have a list of brokers. Each broker on the list has a name and an optional list of account user names. The account attributes refer to user names for OS accounts which are used for remote spawning. These accounts must exist on the machine where the brokers (offering remote launch services for these users) reside. Brokers without a list of accounts (called generic brokers) are used when the OS user resolved for a remote spawn (i.e. specified by the user, for web clients, or configured at a FWD process) is not explicitly listed for any broker. In this case the generic brokers are used one by one until the remote spawn succeeds; if no generic broker can authenticate as the specified user, then the remote launch fails.

Brokers are defined inside the server directory by adding the following node to either /server/default or /server/<server-id> node. Default and explicit, per server, configurations are not merged.

<node class="container" name="brokers">
  <node class="broker" name="broker1">
    <node-attribute name="account" value="os_account_1"/>
    <node-attribute name="account" value="os_account_2"/>
  </node>
  <node class="broker" name="broker2"/>
</node>

The account and broker attributes (as defined in file dir_schema.xml) have the following usage:

node-attribute	Type	Default Value	Mandatory	Description
account	string	n/a	no	OS account user name used on remote spawn.
broker	string	n/a	no	Broker name.

Remote launchers are FWD clients using a server process account and digital certificates for authentication. Only process accounts can be used by brokers. If a process account is used as broker the account node within /security/accounts/processes node must contain the node-attribute broker which is the link between broker instances and defined brokers.

<node class="process" name="p2j_proc">
  ...
  <node-attribute name="broker" value="broker1"/>
</node>

Process accounts used by brokers need to access server resources. For security reasons access to resources are protected and these broker accounts need special rights to have access to resources. This is done using ACL (Access Control List) settings inside the server directory. For more details see the Access Control Lists (ACLs) chapter.

When a broker is registered, the FWD user account is checked to be a process account having a valid broker name attribute (a broker name which is already defined). An ACL is needed for the broker to have access to the accounts resource. Something similar to the following node should be added to /security/acl/system node (at a minimum, the ACL number will probably need to be different in the actual entry):

 <node class="container" name="000500">
   <node class="strings" name="subjects">
     <node-attribute name="values" value="all_others"/>
   </node>
   <node class="systemRights" name="rights">
     <node-attribute name="check" value="true"/>
   </node>
   <node class="resource" name="resource-instance">
     <node-attribute name="reference" value="accounts"/>
     <node-attribute name="reftype" value="TRUE"/>
   </node>
 </node>

On the server side a broker services interface (API) is exported which allows communication between the server and broker. Brokers need to access exported services in order to register with the server and to allow the server to send commands down to the broker. In order to have access to the server's exported services, the following ACL node must be added to /security/acl/net node (at a minimum, the ACL number will probably need to be different in the actual entry):

<node class="container" name="002350">
  <node class="resource" name="resource-instance">
    <node-attribute name="reftype" value="TRUE"/>
    <node-attribute name="reference" value="com.goldencode.p2j.main.BrokerServerServices"/>
  </node>
  <node class="netRights" name="rights">
    <node-attribute name="permissions" value="'0101'B"/>
  </node>
  <node class="strings" name="subjects">
    <node-attribute name="values" value="all_others"/>
  </node>
</node>

Limitations¶

1. Client working directory parameter read from server directory is platform specific. Processes are spawned on OS user's environments. By default the working directory will be set to user's home directory. Then, the spawner tool switches to the runtime resolved working directory for this client launch. As the working directory parameter is platform specific, all brokers with a certain name must run on the same OS. However using "." as the working directory is a valid directory name on both Windows and Linux. Using this approach, brokers are able to run on mixed platforms. Unfortunately the workingDirectory parameter is defined per server not per broker and the limitations are applied to all registered brokers regarding their names. If we have 3 brokers registered for broker1 running on 3 different machines and the working directory is set as absolute path like /opt/p2j/ for example all 3 brokers must run on the same OS family Linux, Unix. It is better to use a relative path for working directory like ./p2j/work_area because the client log files are created in the user working directory. With absolute paths the log files will be created in the same folder for all users. The same restriction is applied also in this case regarding OS family Linux, Unix. The working directory could be somethings like f:\p2j or .\p2j\work_area which are Windows OS specific. In this case the brokers must run on a Windows OS family and the working directory must exist on all machines where the brokers are running. The same rule is applied also to Linux/Unix; the working directory must exist on each machine where brokers are running. Using “.”, without a file separator, sets the working directory as the user's home directory since a the default current directory at login is the user's home directory. This is a cross platform folder name.
   When a process is spawned on an OS account, the working directory is first set to the user's home directory. This is done by spawner tool in C code. Then a change directory is made also by spawner in C code using the working directory parameter read from directory and sent as a command line argument.
   

   <node class="string" name="workingDir">
     <node-attribute name="value" value="." />
   </node>
   

   
   For more details see Spawner Setup and Configuration chapter.
2. For web clients the IP address of the embedded web server is the IP address of the machine where the web client has been spawned. When the web client is spawned remotely, the embedded web server selects reports its IP address and the browser client is redirected to this address. For this reason, the web browser must be able to reach this IP address (it must have a network route to this address or be on the same subnet as this address). The simplest way is to run on a machine from the same network/subnet.
3. Batch clients are using an OS account to spawn batch processes. Directory settings are OS specific. On Windows we need systemUser and systemPassword while on Linux only systemUser is used. This OS account must exist on all machines on which we want to remote launch batch clients via brokers. OS account credentials are configured in node /server/runtime/<process-account>
   

   <node class="container" name="clientConfig">
     <node class="string" name="systemUser">
       <node-attribute name="value" value="username"/>
     </node>
     <node class="string" name="systemPassword">
       <node-attribute name="value" value="password"/>
     </node>
   </node>
   

   
   For more details see Spawner Setup and Configuration chapter.

Missing in Implementation¶

System loading is used as a load-balancing parameter by the broker schedule algorithm. In the current implementation, load balancing only works on the Linux OS because the JVM provides enough information to properly detect the load. A pure Java solution which works on both Linux and Windows platforms is not yet available. A JNI solution will be designed and implemented in the future. A possible solution might be the use of SIGAR API by Hyperic.

---

© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.