Scripting Tool for JBoss Application Server

Building the Server Configuration on Another Machine

Some sites separate the administration of SAS applications and the administration of Web application servers. For sites that do not permit running the SAS Deployment Wizard on the Web application server machine, the configuration scripting tool can be used to configure JBoss. The configuration scripting tool is archived from the machine where the SAS Deployment Wizard was run and provided to the Web application server administrator. The configuration scripting tool can configure JBoss identically to what is created with an automated deployment with SAS Deployment Wizard. The configuration scripting tool is located in SAS-config-dir\Lev1\Web\Scripts\JBoss. The name of the command is jbossScripting.bat. The jbossScripting.properties file in the same directory contains all the settings that are needed to configure JBoss. The following example shows the command syntax for creating or re-creating the JBoss configuration with the default properties file:

jbossScripting.bat

Note: For UNIX deployments, the command is named jbossScripting.sh.

On the Web application server machine, create the directory structure that was used on the machine where the SAS Deployment Wizard was run. The following commands are examples for a Windows environment:
```
mkdir c:\SAS\Config\Lev1\Web\Staging
mkdir c:\SAS\Config\Lev1\Web\Scripts
mkdir c:\SAS\Config\Lev1\Web\Common
mkdir c:\SAS\Config\Lev1\AppData
```
Note: These directory paths must be archived from the machine where the SAS Deployment Wizard was run. The archive must be transferred to the Web application server machine.
Extract the archive into the directories that were created in the previous step.
Open the Scripts\JBoss\jbossScripting.properties file in a text editor. Review the following properties to make sure that values for the JDK and JBoss installation directory are accurate:
- config.appserver.version
- config.host.type.win
- config.jboss.install.dir
- config.jdk.install.dir
- config.lev.dir
Begin the configuration by running jbossScripting.bat.

If the Cache Credentials check box was not selected on the Web Application Server: Scripting Configuration page in the SAS Deployment Wizard, monitor the progress because the tool prompts you for credentials. The following code is an example:
```
...
configJBoss: loginmodule - processing options: optionName=domain value=DefaultAuth
configJBoss: addAttribute: Set name
configJBoss: loginmodule - processing options: optionName=debug value=false
configJBoss: addAttribute: Set name
configJBoss: util - found java.io.Console, using for prompting

Enter Password
        LoginModule=com.sas.services.security.login.OMILoginModule
        trusteduser=sastrust@saspw
        Password=
```

After the script completes, JBoss is configured with all the resources that are needed for the SAS Web applications. All the applications are deployed. The servers are not started automatically.

After the configuration scripting tool runs and JBoss is configured, some additional tasks must be performed manually on the machine where the SAS Deployment Wizard was run. (For a multiple-machine deployment, this is the machine where the middle-tier configuration was performed.) These tasks are recorded in the Instructions.html file that is generated by the SAS Deployment Wizard. Before you perform those tasks, confirm or correct the JDK_HOME environment variable that is identified in SAS-config-dir\Lev1\level_env.bat. For UNIX deployments, the file is named level_env.sh. Open the file in an editor and make sure that the value for JDK_HOME identifies the path to a JDK or JRE.

Rebuilding the JBoss Configuration

You can rebuild the JBoss configuration by running the configuration scripting tool. The tool can re-create the entire JBoss configuration and restore it to the originally configured state. The tool reads the commands in the commands file and configures the resources according to the settings in the properties files.

Configuring a Single Resource (Preproduction)

You can execute a single command to configure a single resource from a command line. The following example shows how to use the -s command line option to configure servers and the -n command line option to configure the named instance only:

jbossScripting.bat -s -n server1

This example uses the default properties file, jbossScripting.properties. The properties file must include the configuration settings for the property key server1. If you are creating a resource that requires credentials, such as a data source, remember to create property keys in the jbossScripting.properties file.

Command Syntax

Optional Arguments

The jbossScripting.bat command has optional arguments:

jbossScripting.bat [propertiesFile] [resourceType] [-n resourceName]

propertiesFile

If you want to use the default properties file, jbossScripting.properties, then you do not need to provide this command argument. If you want to use a different properties file, then provide the fully qualified path to the properties file. It must be the first command argument.

resourceType

If you want to configure one type of resource only, then provide the command line option for that resource type. For example, to configure applications only, use the -a command line option. For the resource types, see the following table.

-n resourceName

If you are configuring one type of resource only, you can also choose to configure a single instance of that resource too. For example, to configure SASServer2 only, use the -s -n server2 command line options to configure only the named server, SASServer2. The mapping between the property key (server2) and the server instance name (SASServer2) is performed in the jbossScripting.properties file.

Command Line Options

The command line options for the jbossScripting.bat file are provided in the following table:

JbossScripting.bat Command Line Options
Short Option Name	Full Option Name	Description
	--unconfigure	This option is used internally by the configuration scripting tool. It cannot be used to unconfigure a resource such as a server or to undeploy an application.
-a	--applications	Use this option to configure all applications.
-c	--connectionFactories	Use this option to configure all connection factories.
-d	--datasources	Use this option to configure all data sources.
-e	--externalContexts	Use this option to configure all external contexts.
-h	--help	Use this option to see the command help.
-l	--loginmodules	Use this option to configure all login modules.
-m	--mailsessions	Use this option to configure all mail sessions.
-n	--resource-name	Use this option to configure a single named resource. For an example, see Configuring a Single Resource (Preproduction).
-q	--queues	Use this option to configure all queues.
-s	--servers	Use this option to configure all servers.
-t	--topics	Use this option to configure all topics.

Properties Reference

Common Properties

The following properties are common to a number of resource types.

config.jboss.install.dir

is the fully qualified path to JBoss.

config.jdk.install.dir

is the fully qualified path to the JDK.

config.jboss.bind.host

is a string that represents bind host for JBoss. The default value is -b 0.0.0.0.

config.host.type

is either win or unx.

config.tanuki.wrapper.dir

is the fully qualified path of the Tanuki service wrapper for deployments that use Windows.

config.appserver.version

is a string that represents the JBoss version.

config.java.version

is a string that represents the JDK version.

config.lev.dir

is the fully qualified path to the SAS-config-dir/Levn directory.

config.loglevel

identifies the logging level. Values are DEBUG or INFO.

config.type

is either auto or manual. This value identifies whether the Web application server was configured automatically by the SAS Deployment Wizard or configured manually.

Server Properties

The resources are stored in the pattern server.servern.property

server

is a space-separated list of server instances (for example, server1 server2 server3, and so on). This property is used by the configuration scripting tool to determine the servers instance to configure.

server.servern.name

is the name of the server configuration such as SASServer1, SASServer2, and so on.

server.servern.options

is a semicolon-separated list of JVM options for server instance n. Escape colon and equal sign characters with a backslash (\).

server.servern.portIncrement

is an integer value that identifies the increment to add to the default set of port numbers such as 0, 100, 200, 300, and so on.

Tip

Do not set this property to a number other than zero and also set the other port number-related properties to unique values. Either use this property to set an offset from the default port numbers, or set this property to zero and set each of the other port-related properties to the values that you want.

server.servern.source

identifies the template to use when creating server instance n (for example, default, standard, all, and so on).

server.servern.transaction

indicates whether local or distributed transactions are configured. Use JTA to indicate local transactions and JTS to indicate distributed transactions.

server.servern.jmssecurity

is a Boolean value that indicates whether JMS security needs to be configured. If set to true, then passwords are used on JMS calls.

server.servern.all.policy.file

is the fully qualified path to a Java policy file. SAS recommends using a policy file that has no restrictions.

server.servern.restrictive.policy.file

is the fully qualified path to a Java policy file with preset restrictions.

server.servern.port.webserverHttp

identifies the port to use for HTTP communication. The default value is 8080.

server.servern.port.webserverHttps

identifies the port to use for HTTPS communication. The default value is 8443.

server.servern.port.jndi

identifies the port to use for the JNDI naming server. The default value is 1099.

server.servern.port.rmi

identifies the port to use for RMI communication. The default value is 1098.

server.servern.service.dependency

is a string that is used to create a Windows Service dependency.

Application Properties

These properties represent the applications that are deployed in a JBoss server. The resources are stored in the pattern application.applicationn.property.

application

is a space-separated list of application instances such as application1 application2 application3, and so on. This property is used by the configuration scripting tool to determine the application instances to configure.

application.applicationn.appname

is the name of application instance n.

application.applicationn.deploymentdir

identifies the directory where the application is deployed

application.applicationn.pathtoear

is the fully qualified path to the EAR file for the application.

application.applicationn.explode

is a Boolean value. If set to true, then the EAR and WAR files contents are extracted in the deployment directory.

application.applicationn.servername

identifies the name of the server configuration where the application is deployed, such as SASServer1, SASServer2, and so on. Do not supply more than one value for servername.

Credential Properties

All properties defining credentials are stored in the jbossScriptingCredentials.properties file. The tool prompts you for these properties. This properties file does not need to be edited directly. These values are cleared after the tool completes if the global property webappsrvScriptingCacheCredentials is set to false. When stored, they are stored in SAS base-64 encoding, not clear-text. If the option to cache credentials was enabled when the SAS Deployment Wizard was run, then the credentials are updated when the Update passwords feature of the SAS Deployment Wizard is used.

server.servern.jmssecurity.user

is a string that identifies the jmssecurity user ID.

server.servern.jmssecurity.password

is an encoded string that identifies the jmssecurity password.

server.servern.jmssecurity.encoding

is a Boolean value. Use this property to indicate whether the password needs to remain encoded when used.

datasource.datasourcen.user

is the user ID that is passed to the datasource driver. This property is not used if a security-domain is used as an option for the datasource.datasourcen.options property.

datasource.datasourcen.password

is the password that is passed to the datasource driver. This property is not used if a security-domain is used as an option for the datasource.datasourcen.options property.

Data Source Properties

Data source properties are used to configure JDBC data source resources in JBoss. The resources are stored in the pattern datasource.datasourcen.properties.

datasource

is a space-separated list of datasource instances such as datasource1 datasource2 datasource3. This property is used by the configuration scripting tool to determine the datasource instances to configure.

datasource.datasourcen.name

is the name of datasourcen.

datasource.datasourcen.classpath

is the fully qualified path to each of the JAR files that are required for the JDBC driver. For drivers that use more than one JAR file, use a semicolon to separate each of the paths.

datasource.datasourcen.connectionUrl

is the JDBC connection URL for the datasource resource.

datasource.datasourcen.driver

is the class name for the JDBC driver.

datasource.datasourcen.jndiname

is the JNDI name for the datasource.

datasource.datasourcen.servername

is the name of the server configuration where the datasource is configured, such as SASServer1, SASServer2, and so on. Do not supply more than one value for servername.

datasource.datasourcen.xa

is a Boolean value. If set to true, then an xa-datasource-property is added as a datasource property. If set to any other value, then a connection-property is added as a datasource option. The default action is to add connection-property as the datasource option.

datasource.datasourcen.options

is a comma-separated list of options for the datasource.

External Context Properties

An external context enables you to access resources in another JVM through JNDI. The resources are brought into the JBoss server JNDI namespace. The term external refers to any naming service that is external to the naming service that is running in the JBoss server JVM.

The resources are stored in the pattern externalcontext.externalcontextn.property.

externalcontext

is a space-separated list of externalcontext instances such as externalcontext1 externalcontext2 externalcontext3, and so on. This property is used by the configuration scripting tool to determine the externalcontext instances to configure.

externalcontext.externalcontextn.local

is the local JNDI name for the externalcontext.

externalcontext.externalcontextn.remote

is the remote JNDI name for the externalcontext.

externalcontext.externalcontextn.url

is the connection URL for the external resource.

externalcontext.externalcontextn.initialcontextfactory

is the JBoss context factory to use when creating the externalcontext.

externalcontext.externalcontextn.servername

is the name of the server configuration where the externalcontext is configured, such as SASServer1, SASServer2, and so on. Do not supply more than one value for servername.

JMS Connection Factory Properties

The resources are stored in the pattern connectionfactory.connectionfactoryn.property.

connectionfactory

is a space-separated list of connectionfactory instances such as connectionfactory1 connectionfactory2 connectionfactory3, and so on. This property is used by the configuration scripting tool to determine the connectionfactory instances to configure.

connectionfactory.connectionfactoryn.name

is the name for the connectionfactory.

connectionfactory.connectionfactoryn.jndiname

is the local JNDI name for the connectionfactory.

connectionfactory.connectionfactoryn.servername

is the name of the server configuration where the connectionfactory is configured, such as SASServer1, SASServer2, and so on. Do not supply more than one value for servername.

JMS Queue Properties

The resources are stored in the pattern queue.queuen.property.

queue

is a space-separated list of queue instances such as queue1 queue2 queue3, and so on. This property is used by the configuration scripting tool to determine what queue instances to configure.

queue.queuen.name

is the name for the queue.

queue.queuen.jndiname

is the local JNDI name for the queue.

queue.queuen.servername

is the name of the server configuration where the queue is configured, such as SASServer1, SASServer2, and so on. Do not supply more than one value for servername.

JMS Topic Properties

The resources are stored in the pattern topic.topicn.property.

topic

is a space-separated list of topic instances such as topic1 topic2 topic3, and so on. This property is used by the configuration scripting tool to determine which topic instances to configure.

topic.topicn.name

is the name for the topic.

topic.topicn.jndiname

is the local JNDI name for the topic.

topic.topicn.servername

is the name of the server configuration where the topic is configured, such as SASServer1, SASServer2, and so on. Do not supply more than one value for servername.

Login Module Properties

The resources are stored in the pattern loginmodule.loginmodulen.property.

loginmodule

is a space-separated list of loginmodule instances such as loginmodule1 loginmodule2 loginmodule3, and so on. This property is used by the configuration scripting tool to determine the loginmodule instances to configure.

loginmodule.loginmodulen.policy

identifies the policy for the loginmodule.

loginmodule.loginmodulen.classmate

identifies the class to use for the loginmodule.

loginmodule.loginmodulen.flag

is the flag for loginmodulen. Values include required, requisite, sufficient, and optional.

loginmodule.loginmodulen.options

is a comma-separated list of options for the loginmodule. Escape equal sign characters with a backslash (\).

loginmodule.loginmodulen.deleted

is a Boolean value that determines whether this entry needs to be deleted from the login_config.xml file.

loginmodule.loginmodulen.servername

is the name of the server configuration where the loginmodule is configured, such as SASServer1, SASServer2, and so on. Do not supply more than one value for servername.

Mail Session Properties

The resources are stored in the pattern mailsession.mailsessionn.property.

mailsession

is a space-separated list of mailsession instances such as mailsession1 mailsession2 mailsession3, and so on. This property is used by the configuration scripting tool to determine the mailsession instances to configure.

mailsession.mailsessionn.name

is the name for the mailsession.

mailsession.mailsessionn.jndiname

is the JNDI name for the mailsession.

mailsession.mailsessionn.mailhost

identifies the host name of the mail server for the mailsession.

mailsession.mailsessionn.servername

is the name of the server configuration where the mailsession is configured, such as SASServer1, SASServer2, and so on. Do not supply more than one value for servername.