Project

General

Profile

Bootstrap Configuration

There are only two sources of configuration data for any given FWD server or client. The first source is called the bootstrap configuration. The second source is the FWD Directory (for details, please see the Directory chapter).

The majority of the server's configuration resides in the directory. When starting the FWD server, it must somehow find/access the directory. The bootstrap configuration is the minimum set of information needed to startup either the FWD server or the FWD client. It contains enough information to initialize networking or (on the server) to find the directory.

The bootstrap configuration is a kind of "database" which has a list of values. Each element in the list is arranged with a 3-part name (category:group:key). The list is encoded in an XML format. The content is contained in 1 or two XML files (optionally encrypted) which hold the minimum configuration values needed to name the server/client, initialize the network and and either connect to the server (if this node is a client) or to connect to the directory server (if this node is a server). All other configuration data is stored in the FWD Directory.

Portions of the bootstrap configuration of the client may be shared among multiple users. Thus, the client side bootstrap configuration may be specified as one or two XML files, whereas the server side is always one XML file. When two XML files are used, the result is considered a single logical XML file (values can be arbitrarily specified in either of the files).

Both client and server applications accept the bootstrap configuration file(s) as command-line parameters. This allows configuration to be provided via scripting instead of only by file. If no command line bootstrap configuration values are specified, then a default bootstrap configuration file is loaded if found. If more configuration files are specified than permitted (ie. one on server side and two on client side), the application will terminate with an error message.

Configurations values saved in xml files can be overridden at runtime using the command-line parameter approach. It is possible to have no bootstrap configuration file at all and only use command line parameters. Likewise it is possible to only use a bootstrap configuration file and not the command line parameters. Or both can be used, making the effective bootstrap configuration the combined set of values from the bootstrap configuration file and those passed on the command line.

Definitions

Regardless of the side, the bootstrap information is organized as a three level tree: category, group and key.

The split of item name in three parts is conventional and helps configuration file be more organized.

The name of the element (each of its 3-part name) is handled in case-insensitive even though xml is case-sensitive by its nature. By convention this document will use lower-case names for all three parts (category, group and key). Of course, the values of the configuration item is case-sensitive. Queried values are always strings, the conversion to other data type is left to the user.

Example:

net:server:host = “p2j.mycompany.com”

This particular entry specifies the address or IP where the server runs. The category is “net”, the group is “server” and key is “host”. The value of the item is the string p2j.mycompany.com.

XML File Structure

The root element of a XML bootstrap configuration file is always a <node type="type"> element, where type is either server or client. The type of the node should match the type of the object being constructed based on this XML file. Categories and groups are nested XML elements. Keys are attributes that may be queried. They always return strings, so the interpretation of the values is beyond the responsibilities of this package.

Internally, categories are represented by the first level nodes into the xml root node and do not have attributes. If any attribute is encounter it is silently ignored.

The second tree-level is occupied by groups. They are represented as are xml sub-nodes of a category and do not have sub-nodes (they are ignored if present).

The key are the leaves of the three-level tree. They are encoded as attributes of groups. The names are the keys whilst their values are the the values of the configuration item.

Example:

Value Meaning
<?xml version="1.0"?> xml header
<node type="client"> client bootstrap configuration file
<net> "net" category begins
<server host="p2j.company.com" port="3333"/> In this case "server" group node of “net” category holds both
"host" key and the "port" key. They define the server's TCP/IP host name or IP address and port number
<dispatcher threads="3"/> The net:dispatcher:threads represents the number of dispatcher's threads.
</net> "net" category ends
<security> "security" category begins
<truststore filename="trust.store"/>
<truststore alias="MainServer"/>
In this case even though “filename” and “alias” share the same group (
truststore) and category (security), they are encoded in separate xml nodes.
<keystore filename="key.store"/> The security:keystore:filename specify where this client or application's X.509 certificates and private keys are stored.
</security> "security" category ends
</node> end of client bootstrap configuration file

When two configuration files are used, both have to be of type client. The logical structure of the union is simply a set of categories from both files. The client processes them one at the time, in the order they are specified. Each key is read and saved internally in the order they are declared inside the xml. If the same key appears more than once in a file then only the first value is considered. Also, if the key appears in the second file the it is also not taken into consideration. To summarize, if a key/value occurs multiple times only the first declaration is validated any ulterior occurrence is ignored and discarded.

Any settings that are specified in one or two configuration file can be overridden using command-line parameters with the following syntax:

java com.goldencode.p2j.main.ClientDriver client.xml net:dispatcher:threads=3

Here, the size of the dispatcher's thread pool is resized to 3, no matter how it was configured in client.xml.

The same category may be coded multiple times. Same group may be coded multiple times within the category, too. Normally, this is used to code different keys. If a key is coded more than once, the first occurrence is used. Besides that, the order of categories, groups and keys does not matter. Any number of attributes can be coded with elements.

Split Configuration Usage

As noted above, on the FWD client it is possible to have the bootstrap configuration split across two XML files. This allows common configuration values to be shared by multiple users, while providing for a user-specific file to allow per-user customizations.

If you need to share some bootstrap configuration between two or more users group all common entries to shared configuration file. Then, for each of users create a xml file with customized settings. Of course, both shared and customized xml files must have the node type set to “client”. The bootstrap manager will load both files and merge their content.

The advantage of this approach is that if something changes in common entries, you only need to alter only one file and if a user has to change something, the only affected file will be his own customized configuration file. Even more, if you need to configure another user to connect to the same server simply create a new configuration file for the new user and put inside only the user's custom settings.

By default, the client loads (if the file exists) the standard_client.xml configuration file from the location where it was started. In order to specify other configuration file it needs to be added to the command-line as parameter. To have a split configuration add the second configuration file also in command line. Both configuration file can be added with relative or absolute filenames. If the files are encrypted then the filename should be followed by the -p parameter with the decryption password or '?' to force an interactive password prompt.

Here is an example of launching the client with default bootstrap configuration file:

java com.goldencode.p2j.main.ClientDriver

To specify a custom file use:

java com.goldencode.p2j.main.ClientDriver client.xml

To configure the client to run with two configuration files, both of them need to be appended:

java com.goldencode.p2j.main.ClientDriver common_client.xml custom_client.xml

If more than two files are specified then a syntax error will be printed on screen and application will exit with error. If a key entry appear in both common and custom files only the first one (common) is used.

Examples

The general structure of the XML file is shown below.

In the samples below all attributes are coded separately, This is not a requirement. They can be grouped. Values are typed in italics.

Client XML - Single File

Here is a simple client configuration sample (values are in italics):

<?xml version="1.0"?>
<node type="client">
   <net>
      <server host="p2j.company.com"/>
      <server port="3333"/>
      <dispatcher threads="3"/>
   </net>
   <security>
      <truststore filename="trust.store"/>
      <truststore alias="MainServer"/>
      <keystore filename="key.store"/>
   </security>
</node>

In the above sample there are two categories (net and security), each one having some groups and keys:

Configuration item name Category Group Key Value
net:server:host net server host p2j.company.com
net:server:port net server port 3333
net:dispatcher:threads net dispatcher threads 3
security:truststore:filename security truststore filename trust.store
security:truststore:alias security truststore alias MainServer
security:keystore:filename security keystore filename key.store

See the table at the end of the chapter for full reference of supported bootstrap client items.

Client XML - Multiple Files

Let's assume that all your users will connect to the same server, with the same other settings. However, because they work in different locations, they see the server with a different name (maybe routed through some kind of firewall). So we create a configuration file with all common settings and each user will receive a custom xml file with the appropriate network settings. Practically, staring from the single xml configuration we will create the common_client.xml file by removing the non-shared settings:

<?xml version="1.0"?>
<node type="client">
   <net>
      <dispatcher threads="3"/>
   </net>
   <security>
      <truststore filename="trust.store"/>
      <truststore alias="MainServer"/>
      <keystore filename="key.store"/>
   </security>
</node>

Now, it suffice to create the customized file with removed keys from shared file having custom values, in this case a NAT address for server:

<?xml version="1.0"?>
<node type="client">
   <net>
      <server host="192.168.1.68"/>
      <server port="3333"/>
      <dispatcher threads="6"/>
   </net>
</node>

Observe that the net:dispatcher:threads is redefined in this second file. As this file will be the second one in command line parameter-list the new value “6” will be ignored.

Server XML

To specify a bootstrap configuration file, simply add it to server command line. By default, if no other bootstrap file is specified the server will attempt to load the standard_server.xml file located into current directory, if such a file exists.

Here is a simple server bootstrap configuration file:

<?xml version="1.0"?>
<node type="server">
   <net>
      <router threads="2"/>
   </net>
   <security>
      <server id="security.server"/>
      <keystore filename="key.store"/>
      <keystore alias="keyalias"/>
   </security>
   <directory>
      <backend type="xml"/>
      <xml filename="directory.xml"/>
   </directory>
   <access>
      <password keystore="keystore"/>
      <password keyentry="keyentry"/>
   </access>
</node>

See the table at the end of the chapter for a full reference of supported bootstrap server items.

References

Values of the configuration items looking like "#word1.word2.word3" are interpreted as pointers to another items, or references. When such a value is queried, the class tries to resolve the reference and look for another item with category=word1, group=word2 and key=word3. If such an item can be found in the file, its value is returned instead.

References may point to references, but to avoid endless loops, the class limits the number of lookups to 5. If the nesting level is more than 5 the internal default value will be used. Invalid references are returned as themselves. Broken references are returned as empty strings.

For example, if the security server is the same as p2j server, a client configuration file will look like:

<?xml version="1.0"?>
<node type="client">
   <net>
      <server host="p2j.company.com"/>
      <dispatcher threads="3"/>
   </net>
   <security>
      <truststore filename="trust.store"/>
      <truststore alias="#net.server.host"/>
      <keystore filename="key.store"/>
   </security>
</node>

The value of security:truststore:alias will be the same like net.server.host which is “p2j.company.com”.

Encryption

The bootstrap configuration files can be stored in the file system in an encrypted form for higher security. The encryption method used is "PBEWithMD5AndDES@".

After the configuration file
config.xml is edited and ready to deploy, use the BootstrapConfig utility to encrypt its content. The syntax is the following:

java com.goldencode.p2j.cfg.BootstrapConfig encrypt config.xml config_enc.dat

The config_enc.dat is the output file that contains the encrypted version of the config.xml. The utility will prompt you for the passphrase.

The encrypted file is decrypted by the application (server or client) automatically when -p parameter is specified in command line.

However if the content of the configuration file needs to be changed you can use the the BootstrapConfig utility again to obtain the plain version. The syntax is the following:

java com.goldencode.p2j.cfg.BootstrapConfig decrypt config_enc.dat config.xml

The config_enc.dat is the encrypted file and that will be the decrypted to the plain version: config.xml. The utility will prompt you again for the passphrase.

Encrypted configuration files are passed to application, like plain xmls, in command-line parameter list but should be followed by the -p parameter with the decryption password. If '?' is used instead of password then the application will enter an interactive password prompt. If the client is using two configuration files, then they be encrypted independently and in this case each file should be followed by the password (if the case).

Example:

java com.goldencode.p2j.main.ClientDriver common_client.dat -p ? custom_client.xml

The client will be launched in split configuration mode. First it will prompt you for the passphrase needed to decrypt the common_client.dat and then will read and merge the settings both files.

Configuration Reference

The following table documents the full set of honored bootstrap configuration values and their purposes in alphabetical order of item name:

Category Group Key Default Value Example Value Type Required server Required client Purpose
access password keyentry null ytfryu string no no Specifies the password to be used to read/decrypt the in-memory key manager.
- - keyentry-<alias> null tryursj string no no Specifies the password to be used to decrypt the in-directory private key for the specified certificate <alias>.
- - keystore null kjhdsa string no no Specifies the password to be used to read/decrypt the custom keystore.
- - masterkeyentry null vjakls string no no Specifies the master password to be used to decrypt the in-directory private keys, when the private keys for each certificate are encrypted with the same master password.
- - truststore null ohjuou string n/a no Specifies the password to be used to read/decrypt the custom truststore (file). Since the server doesn't use a file-based trust-store, this is not needed and will not be used on the server.
- - user null asjakkl string n/a no If the standard SecurityManager client authentication hook is used, this will override the password instead of forcing the user to be prompted via stdin.
- subject id null user1 string n/a no If the standard SecurityManager client authentication hook is used, this will override the userid instead of forcing the user to be prompted via stdin.
client chui background black #A0A0A0 string n/a no Background color for client window (the value can be converted to a Color by Color.decode())
- - columns 80 120 int n/a no The number of columns in client window.
- - fontname monospaced Courier string n/a no The font used in client window (a monospaced (fixed width) font family name).
- - fontsize 12 10 int n/a no The size of text in client window.
- - foreground 0xFFA500 yellow string n/a no Text color for the client window (the value can be converted to a Color by Color.decode())
- - rows 24 45 int n/a no Number of rows in client window.
- - selection blue blue string n/a no Selection highlighting in client window (the value can be converted to a Color by Color.decode())
- cmd-line-option clientlog null "./logs/client.log" string n/a no Filename for the client-side log. If not specified, logging occurs to STDERR. If specified, it must be a filename of a file that the user can create and which the user can write to. Without this, it is important to redirect STDERR to control the logging. A relative filename will created in relation to the current directory at the time the client is launched.
- - debugalert false false boolean n/a no Allows specifying the value of the SESSION:DEBUG-ALERT attribute.
- - param null "-T /tmp/whatever/, -db some-db-name" string n/a no Specifies the value of the SESSION:STARTUP-PARAMETER, which in Progress is the comma-separated list of command line options (from the default $DLC/startup.pf, a user-specified .pf, the actual pro/mpro/prowin32.exe command line parameters or the contents of the $PROSTARTUP environment variable. FWD does not manufacture this at this time. If your application reads this value to make a decision at runtime, you must override it here.
- - startup-procedure null "./relative/path/to/some-abl-procedure.p" string n/a no This allows an override of the default entry point for the application. It is equivalent to specifying the -p option on the pro, mpro or prowin32.exe command line. The value MUST be a pathname that is relative to the PROPATH AND it must be the ABL procedure name (not the converted Java class name) AND it must have been converted/compiled into the application's jar file.

This user-specified procedure is subject to the EntryPointResource security plugin. By default, no user-specified value is honored and the normal directory configuration is used. ACLs can specify exact matches or a regex match for the resource name. The following lists the configuration needed to enable this feature.

Add the following to /security/config/resource-plugins/:

<node-attribute name="values" value="com.goldencode.p2j.main.EntryPointResource"/>


Add this ACL to /security/acl/:

        <node class="container" name="entrypoint">
          <node class="container" name="000100">
            <node class="resource" name="resource-instance">
              <node-attribute name="reference" value=".*"/>
              <node-attribute name="reftype" value="false"/>
            </node>
            <node class="entryPointRights" name="rights">
              <node-attribute name="allow" value="true"/>
            </node>
            <node class="strings" name="subjects">
              <node-attribute name="values" value="all_others"/>
            </node>
          </node>
        </node>


The .* is a regular expression that matches all possible program names and reftype being set to false tells the SecurityManager that it is a regex. By setting allow to true and subjects to all_others, this results in all users being able to execute all possible converted program names. The container must be set to a unique name (in this example, it is name=000100). Each ACL must have a unique value for that container (the numeric value determines the order in which the ACLs are processed). This is NOT a secure configuration. It is just an example that can be useful for testing and development purposes.

To use it pass the parameter as client:cmd-line-option:startup-procedure="./some/program.p" to the ClientDriver.
- driver background false false boolean n/a no When true, this flag indicates a batch 4GL program which was run as a background OS process (on the legacy system).
- - type null chui_native string n/a no The driver used to render text in client application. Valid values are:
chui_native
chui_web
chui_batch
swing_chui_frame
- - window-system the driver's window system TTY string n/a no Sets the client's window system. If missing, it defaults to the driver's window-system (TTY for ChUI drivers and MS-WINDOWS for GUI drivers). Valid values are TTY, MS-WINDOWS, MS-WIN95 and MS-WINXP.
- mode batch false false boolean n/a no Sets a client to be run in batch mode.
- tty name null "/dev/pts/1" string n/a no Defines the terminal name that will be reported when the _connect._connect-device metadata field is read for this user's session.
- web host null localhost string n/a no Sets the host of the embedded web server, on which the FWD client will listen for incoming connections. If not set, it defaults to the server's host.
- - port 0 4646 int n/a no Sets the port of the embedded web server, on which the FWD client will listen for incoming connections. If not set it defaults to 0, and the operating system will assign a random, free port.
- - socketTimeout -1 30 int n/a no Sets the timeout (in seconds) after which the web socket connection will be closed, unless new data is received.
- - watchdogTimeout -1 30 int n/a no Sets the timeout (in seconds) after which the FWD client terminates, if no new web socket connections are established.
directory backend class null com.acme.directory.MyBackEnd string no n/a Specifies the class name of the directory back-end to use. This class must implement the Remapper interface.
- backend type null xml string yes n/a Specifies either of the 2 back-end types that are available in the directory package: xml or ldap.
- ldap alias null   string no n/a Alias of the certificate which will be selected from ones present in keystore.
Required if using the LDAP back-end AND LDAPS (TLS transport for LDAP).
- - aliaspasswd null   string no n/a Password which will be used to decrypt certificate.
Required if using the LDAP back-end AND LDAPS (TLS transport for LDAP).
- - auth null simple string no n/a Authorization mode for LDAP bind operation. Recognized values are "simple" and "EXTERNAL".
- - credentials null   string no n/a Credentials (like password) used in LDAP authentication.
- - keypasswd null   string no n/a Password which will be used to decrypt keystore.
Required if using the LDAP back-end AND LDAPS (TLS transport for LDAP).
- - keystore null   string no n/a Keystore filename that contain certificate to be used for LDAP connection.
Required if using the LDAP back-end AND LDAPS (TLS transport for LDAP).
- - mapping null   string no n/a If mapping mode is set to "file" then mapping specifies a file name where FWD to LDAP mapping is stored. If mapping mode is set to "subtree", mapping should contain two parts separated with '/'. First part defines LDAP distinguished name of the node where mapping is stored. Second part defines name of the attribute which holds mapping data.
Required if the LDAP back-end is in use.
- - mode null file string no n/a Must be one of these mapping modes: FILE, URL, ATTRIBUTE, SUBTREE.
Required if the LDAP back-end is in use.
- - principal null   string no n/a Distinctive Name (DN) to be used for LDAP authentication
- - trustpasswd null   string no n/a Password which will be used to decrypt truststore.
Required if using the LDAP back-end AND LDAPS (TLS transport for LDAP).
- - truststore null   string no n/a Truststore that contain private keys to be used for LDAP connection.
Required if using the LDAP back-end AND LDAPS (TLS transport for LDAP).
- - url null   string no n/a Required if the LDAP back-end is in use. Defines full LDAP server URL and initial context, like this "ldap://localhost:389/dc=goldencode,dc=com". For the ordinary connection URL should have protocol "ldap". For TLS connection protocol should be set to "ldaps".
- xml filename null directory.xml string no n/a Required if using the XML back-end. Defines the xml file that provides persistent storage for the directory.
- xml must_exist true false boolean no n/a Required if using the XML back-end. Constrains if the xml file should exist.
logging debug enable true false boolean n/a no Enable logging on client application.
net connection secure false false boolean no n/a Force secure network connection.
- dispatcher threads 2 10 int no no The size of the dispatcher's thread pool.
- queue conversation FALSE TRUE boolean n/a no Enable/disable conversation mode for the associated client. Note that the server's session is automatically configured based on the mode of the client.
- - start_thread FALSE TRUE boolean n/a no If true, a daemon thread will be started to drive conversation mode. If conversation mode is disabled, this value is ignored.
- router threads 2 2 int no n/a The size of the router's thread pool.
- server host null localhost string n/a yes Specifies the hostname or IP address on which the server resides.
- - insecure_port -1 3333 int n/a no Specifies the insecure connection port.
- - nodeAddr 0x00010000 65536 int no n/a The DAP node address of a router node. All leaf nodes connected to this node will have addresses assigned from the low word while the high word will be identical.
- - nodeaddress null   string no n/a FWD node address of this server .
- - port -1 3333 int yes yes The TCP port on which the server will listen or which the client will use to contact the server.
- - secure_port -1 4333 int no no Specifies the secure port to be used when connecting to server.
Mandatory on server side if the key net:connection:secure = true.
- - timeout 600000 30000 int no no The number of milliseconds that a sender of the an initialization request will wait for the associated reply.
process arch single false false boolean no n/a Enable single client architecture.
security authentication type null program string no n/a Specifies the authentication type. Valid values: program
- certificate validate false TRUE boolean n/a no If true, then the server's certificate must be present in the truststore for authentication to succeed. This is a way of authenticating the server.
- keystore alias null server1 string no n/a Required to find the server's private key if there are multiple aliases in the keystore.
- - bytes null hex-encoded byte array string no no Used internally by FWD when the server is instructed to launch a process client, and the private keys are configured in the directory. It sends to the client side the hex-encoded key store, storing the process' associated private key.
- - filename null custom_keys.store string yes no Specifies the filename or URL from which a custom keystore can be read. If this is specified, then the security:keystore:bytes configuration will be ignored.
- - processalias null batch_process_1 string n/a no Used to enable process (non-interactive) authentication instead of the normal interactive authentication. If this value is non-null, then a non-interactive authentication type is used. In addition, the SecurityManager uses this to find the client's private key if there are multiple aliases in the keystore.
- - useralias null client1 string n/a no Required to find the client's private key if there are multiple aliases in the keystore. This should not be specified if a processalias has been specified. It should only be used for interactive clients.
- server id null server1 string yes n/a This is the server's name, used to find the associated configuration for that server in the directory.
- transport refresh false true boolean n/a no Used internally by FWD. It forces the refresh of the security transport, on client-side.
- trust_mgr disable false true boolean n/a no Disable trust manager.
- truststore alias null server1 string no no Used when security:certificate:validate is true to identify the certificate in the truststore to be used for validation. Used on the client and on the server only during the creation of a virtual session (in which case the server acts like a client).
- - bytes null hex-encoded byte array string no no Used internally by FWD when the server is instructed to launch a process client. It sends to the client side the hex-encoded trust store, storing the server's trusted certificates.
- - filename null custom_trust.store string n/a no Specifies the custom trust store for the client to use for validation of server certificates. Note that the server dynamically builds a truststore from the directory so this is not needed for servers. If this is specified, then the security:truststore:bytes configuration will be ignored.

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