This guide describes how to quick start, deploy and configure Access Layer instances inside the GRID.
Briefly explained, the Access Layer is a runnable web server based on Jetty & TinyJEE that runs inside a JRE and virtually on any platform conforming to Java 1.6. The application itself is capable of utilizing multiple processors and plenty of RAM and turn this into improved performance.
This document describes how to configure and run the ACL in general. Instructions how the ACL is particularly installed (and upgraded) within the GRID production environment can be found inside document "Data Sheet - AccessLayer" which is available for offline use.
When building the ACL, output including the server application and a testsuite is created within the folder ./target/ using various formats (zip / tar.gz / folder). This output is also known as build artifacts.
Recent artifacts can be collected from:
Once build output was collected (either from one of the servers or by building the ACL manually) follow the steps:
cd ws-server-application-1.2.4-RC-dist
./addons/ - Optional resources, e.g. "init.d" scripts.
./lib/ - GACL application & 3rd party libraries
./webapps/ - GACL SDK / Admin Guide
./start.bat - Start script for Windows
./start.params.bat - A separate include file allowing the addition of
hardened startup paramters for Windows.
./start.sh - Start script for *nix
./start.params.sh - A separate include file allowing the addition of
hardened startup paramters for *nix systems.
./readme.txt
Note: Any file that was not created during the build, is built-into the application and will get created if missing (e.g. with the initial start). If this doesn't work make sure the process has proper permissions on the filesystem when performing the initial start.
The automatic creation of missing resources can be adjusted by specifying a set of command line parameters. (See the section below for a full explanation)
To get the ACL started for the first time, use one of the following command lines depending on the used system and replace "hostname" with the real values:
Windows:
cd C:\Path\To\TargetFolder\ start.bat -Dmssqlserver=<hostname> -Dcifsserver=<hostname> -Dmsmqbridgehost=<hostname>
Unix:
cd /path/to/targetfolder start.sh -Dmssqlserver=<hostname> -Dcifsserver=<hostname> -Dmsmqbridgehost=<hostname>
With the initial start, TinyJEE will initialize itself and the Access Layer for the first run and prints several lines of information to stdout, explaining what it did and how the services can be accessed.
From now on the ACL should run with default settings and work just fine. In order to create a production ready package, please follow the next sections.
Note: The hostnames for the external resources are not by default hardened inside the configuration. This means everything remains changeable. In order to harden the values you could consider editing the start scripts (*.params.*), the variables are already pre-defined in there.
All external resources require additional setup to support the ACL. If one of the resources is not ready, the ACL can be started without specifying the resource and it will gracefully fallback to an alternate implementation. Please note that implementation selection is hardened within the initial start. See next sections for more details.
Once an ACL build was started it hardened selections of repository implementations within the first start. This means for implementations where the defaults for auto-selection depend on given command line options, it may be either required to adjust the selection manually or alternatively auto-selection can be forced by deleting the repository selection files inside the config folder.
The commandline options "-Dcifsserver" and "-Dmsmqbridgehost" will influence the automatic selection sequence. One option to force auto-selection is the deletion of the files matching "repository-selection.*.xml" contained inside the "config" folder.
Note: Deleting the whole "config" folder or parts in it will not do any harm to the ACL except that previously made manual configurations may get lost (if any). In the worst case everything is re-created using the built-in defaults.
Please follow the instructions for the "Quick Start" in order to allow the ACL to build its runtime environment & the configuration files.
If this succeeded, stop the server again (pressing CTRL-C) to continue with the next step.
After the first launch, all configuration files were created under the "config" folder and are now ready for customization. In particular some things may need to be configured to make the access layer ready for deployment.
Inside the GRID network, the access layer is positioned as described in the diagram below. Configuring the access layer should lead to a setup that is similar to this.
The access layer currently supports 3 different run-modes that optimize the behaviour of the ACL for certain use cases. The run modes are "test", "development" (=default) and "production" and they can be set via the commandline option "-Dmode=name".
Defaults for connections and properties (e.g. logLevel) are defined in dependence to the run mode (See EL expression inside the configuration file).
Important Note: The default run mode is development and is best suited to get maximum log output and debugging capabilities.
In order to put the ACL into production mode, add the commandline options -Dmode=production when starting the ACL. Full performance is only reached when the ACL runs in "production" mode.
To start with the configuration, choose your favourite editor and open the main configuration file.
notepad config\tinyjee-configuration.xml
Ports can be configured inside the XML elements identified by "//configuration/connection/port".
The built-in default ports are set as:
When starting the server using "start.bat", TinyJEE will print all entry-URLs including port information. Doing so, the application can easily be discovered by the admin.
Note: TinyJEE supports dynamic port selection using the EL expression language which may be used within the configuration file. Adjusting the predefined expression may result in a behaviour diverting from the documented default.
Without any sort of configuration, the access layer uses an embedded HSQL 2.0 database to store all information. While this is suitable for development & testing, it's not suitable inside a production environment.
In order to configure the ACL to use an MSSQL database it is sufficient to specify the hostname of the DB server at the command line using -Dmssqlserver=hostname.
By default username and password is set to "CoreDB" and "tr3ndm1cro". These defaults are in sync. with the defaults for the MSSQL CoreDB Schema files which needs to be installed separatelly on the MSSQL Server. Defaults can also be changed, check the relevant section inside the configuration file.
Every value inside the configuration file can optionally be defined in a way to support its declaration via command-line parameters using EL expressions (= expressions placed inside braces like ${expression}, see http://java.sun.com/products/jsp/reference/techart/unifiedEL.html).
By default all identifiers that are used inside an EL expression are resolved against other properties inside the config file or if not defined elsewhere against variables specified via -DvariableName=value. (Note: Variable names may not contain any chars other than [a-z0-9], use the method env('name.with.dots') to get the values of such variables or to query the system environment.)
Useful predefined options include:
Note: The scripts start.params.sh and start.params.bat contain predefined sections that may be used to harden the startup parameters. It's recommended to un-comment and use them in a production environment.
The ACL is built with support for multiple implementations behind common data interfaces making it possible to run the ACL in different environments and modes without necessarily requiring a complete GRID to run.
The ACL is tuned to auto-select repository implementations based on their names using the following built-in default sequence:
Default Auto-Selection Sequence: "dummy trivial logging jpa caching"
Note: This sequence can be customized via the command line option -Dautoselect.ds.implementations=.. (or environment variable 'autoselect.ds.implementations')
Auto-selection takes place whenever a selection file is missing for the relevant run-mode. (This is the case for the inital startup and when the config folder or the file it-self was deleted)
Viewing & modifying the selection results is possible by opening the mode specific selection file using the favourite text file editor, e.g.:
notepad config\repository-selection.<mode>.xml
A repository selection looks like:
<?xml?>
...
<selector repositoryClass="com.trendmicro.grid.acl.ds.PackageProvider">
<selectedKey>jpaPackageRepository</selectedKey>
<available>dummyPackageProvider</available>
<available>jpaPackageRepository</available>
</selector>
Notes:
Please make sure you change the file 'repository-selection.production.xml' to include the correct implementations below the classes '..acl.ds.FileContentRepository' and '..acl.ds.ProcessingInitiator' or follow the steps to force auto-selection one more time after setting the right command line parameters.
When the "trivialCategoryRepository" and/or "trivialCategoryViewRepository" are selected repository implementations (see previous section), categories and category views are defined by XML files contained inside "resources/trivial-category-definitions".
The ACL ships with a built-in default set of categories that is created when the folder is empty in order to satisfy the internal parsing methods and to describe the format of the XML content.
Before the ACL can be used in "production" it is mandatory to install the latest set of categories from the P4 location: //Core/GRID/DEV/GRID/doc/GRID/Views_and_Categories.zip
Please replace the content completely!
When deployed inside the GRID a couple of additional things need to be setup in order to create a deployable package. In general it's advisable to setup all things first, create a tarball / archive and deploy it to the target nodes using a relevant deployment mechanism.
Things to validate: