Configuration of the EAP6 / JBoss AS7 with CLI scripts

The JBoss EAP6 and AS7 supports different approaches to mange server configurations. One approach is the command line interface (CLI). It is based on the De-Typed Management API and allows the execution of management operations. The CLI has support for CLI scripts with management and configuration operations that can be executed in a non-interactive mode.

In this post we want to introduce two ways of using CLI scripts to manage server configurations.

Execute CLI scripts with the JBoss AS Maven plugin

The JBoss AS7 Maven plugin can be used to deploy an application, to run and to configure the application server directly from the Maven build process.

Since a few days, a new release of the jboss-as-maven-plugin is available. I am happy to introduce in this post a new feature, that we contributed. The feature supports the execution of CLI commands from a separate script with the execute-commands goal of the plugin on a running JBoss Application Server.

A CLI script is specified in the configuration section of the jboss-as-maven-plugin. The plugin configuration below shows an example integration into the Maven build lifecycle. During the install lifecycle phase of the Maven build, the plugin will execute the CLI commands from the script and deploy the enterprise archive artifact on a running application server.

</project>
...
  <build>
    <plugins>
      <plugin>
        <groupId>org.jboss.as.plugins</groupId>
        <artifactId>jboss-as-maven-plugin</artifactId>
        <version>7.4.Final</version>

        <configuration>
          <execute-commands>
            <scripts>
              <script>src/main/resources/configuration.scr</script>
             </scripts>
           </execute-commands>

           <groupId>de.akquinet</groupId>
           <artifactId>blog-ear</artifactId>
           <version>1.0-SNAPSHOT</version>
           <name>blog.ear</name>

         </configuration>
                        
         <!-- Deploy the application on install phase -->
         <executions>
           <execution>
             <id>configure</id>
             <phase>install</phase>
             <goals>
                <goal>execute-commands</goal>
                <goal>deploy-artifact</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
  </build>
…
</project>

The CLI script can contain common CLI operations to configure the application server. The following listing shows an example CLI script to configure a JAAS-Loginmodule.

batch

# add security domain

/subsystem=security/security-domain=secure-domain/:add(cache-type=default)

/subsystem=security/security-domain=secure-domain/authentication=classic :add(login-modules=[{"code"=>"Database", "flag"=>"required", "module-options"=>[("dsJndiName"=>"java:jboss\/datasources\/DefaultDS"),("principalsQuery"=>"SELECT PASSWORD FROM CM_USER WHERE LOGIN = ?"), ("rolesQuery"=>"SELECT R.NAME, 'Roles' FROM CM_ROLE_CM_USER RU INNER JOIN CM_ROLE R ON R.ID = RU.ROLES_ID INNER JOIN CM_USER U ON U.ID = RU.USERS_ID WHERE U.LOGIN = ?")]}])

# Execute
run-batch

This CLI script can also be used directly with the CLI Tool of the JBoss Application Server.

Deploying CLI Archives

Another approach to manage configurations is to use a JBoss-specific CLI deployment. A CLI deployment is a conventional Java Archive with the extension .cli instead of .jar. The archive can contain multiple deployments, such as enterprise archives or web archives, and CLI scripts for configuration and deployment operations.

The following listing shows an example, to generate a CLI archive with Maven.

…
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
         <version>2.4</version>

          <executions>
            <execution>
              <id>dist</id>
              <phase>generate-resources</phase>
              <goals>
                <goal>single</goal>
              </goals>

              <configuration>
                <descriptors>
                  <descriptor>src/assemble/distribution.xml</descriptor>
                </descriptors>
              </configuration>

            </execution>
          </executions>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-antrun-plugin</artifactId>
        <version>1.7</version>
        <executions>
          <execution>
            <phase>install</phase>
            <goals>
              <goal>run</goal>
            </goals>
            <configuration>
              <target>
                <move file="target/blog-jboss-config-${project.version}-distribution.jar" tofile="target/blog-distribution.cli"/>
              </target>
            </configuration>
          </execution>
        </executions>
      </plugin>
…
    </plugins>
  </build>
…

In the example, the resources of the archive are packaged with the maven-assembly-plugin and the corresponding assembly descriptor. The distribution from the assembly descriptor is then renamed by the maven-ant-run plugin to the final name with the extension .cli.

<assembly xmlns=http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
  <id>distribution</id>
  <formats>
    <format>jar</format>
  </formats>

  <includeBaseDirectory>false</includeBaseDirectory>

  <dependencySets>
    <dependencySet>
      <includes>
        <include>de.akquinet:blog-ear</include>
      </includes>
    </dependencySet>
  </dependencySets>
  
   <fileSets>
    <fileSet>
      <directory>${basedir}/src/main/resources</directory>
      <outputDirectory>/</outputDirectory>
      <includes>
        <include>*.scr</include>
      </includes>
    </fileSet>
  </fileSets>
</assembly>

The descriptor specifies the type of assembly archive to create and the contents of the archive. In our case, the CLI archive contains an enterprise archive and the CLI scripts for the deployment and undeployment operations of the archive.

The illustration below shows the contents of the CLI archive.

blog-distribution.cli
|-- META-INF
|   `-- MANIFEST.MF
|-- blog-ear-1.0-SNAPSHOT.ear
|-- deploy.scr
`-- undeploy.scr

The CLI archive can be deployed with the deploy operation as follows:

deploy target/blog-distribution.cli

The deploy operation will execute the commands from the deploy.scr file of the CLI archive. This file includes the necessary configuration for the application server and also contains the deploy operation for the deployment of our enterprise archive. After successful execution, the operations from the CLI script are printed to the console:

#1 /subsystem=security/security-domain=secure-domain:add(cache-type=default)
#2 …
#3 deploy blog-ear-1.0-SNAPSHOT.ear

To remove the application, the deploy operation is used as well, but with the undeploy.scr file, as shown in the following listing.

deploy target/blog-distribution.cli --script=undeploy.scr 
#1 /subsystem=security/security-domain=secure-domain:remove
#2 undeploy blog-ear-1.0-SNAPSHOT.ear

The undeploy.scr file contains the operations to remove the configuration and undeploy the enterprise archive.

Summary

The handling of configurations for the application server with CLI commands and scripts is a powerful way to manage application-specific configuration. A CLI script can be reused in different scenarios, e.g. for development or operation processes. An integration in the Maven build process is supported by the JBoss AS7 Maven plugin. The use of CLI archives allows the distribution of the server configuration and the deployment with a single artifact.

If you have any questions to this post feel free to comment or write an e-mail to

• heinz.wilming (at) akquinet.de