Getting Started Guide

Users can also be created non-interactively by passing parameters to the add-user script. This approach is not recommended on shared systems, because the passwords will be visible in log and history files. For more information, see Running the Add-User Utility Non-Interactively.

You can run the add-user script non-interactively by passing in arguments on the command line. At a minimum, the username and password must be provided.

Create a User Belonging to Multiple Groups

The following command adds a management user (mgmtuser1) with the guest and mgmtgroup groups.

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser1' -p 'password1!' -g 'guest,mgmtgroup'

Specify an Alternative Properties File

By default, user and group information created using the add-user script are stored in properties files located in the server configuration directory.

User information is stored in the following properties files:

Group information is stored in the following properties files:

These default directories and properties file names can be overridden. The following command adds a new user, specifying a different name and location for the user properties files.

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser2' -p 'password1!' -sc '/path/to/standaloneconfig/' -dc '/path/to/domainconfig/' -up 'newname.properties'

The new user was added to the user properties files now located at /path/to/standaloneconfig/newname.properties and /path/to/domainconfig/newname.properties. Note that these files must already exist or you will see an error.

For a complete listing of all available add-user arguments and their purposes, use the --help argument or see the Add-User Utility Arguments section.

The management command-line interface (CLI) is a command-line administration tool for JBoss EAP.

Use the management CLI to start and stop servers, deploy and undeploy applications, configure system settings, and perform other administrative tasks. Operations can be performed in batch mode, allowing multiple tasks to be run as a group.

Many common terminal commands are available, such as ls, cd, and pwd. The management CLI also supports tab completion.

For detailed information on using the management CLI, including commands and operations, syntax, and running in batch mode, see the JBoss EAP Management CLI Guide.

Launch the Management CLI

$ EAP_HOME/bin/jboss-cli.sh

Connect to a Running Server

connect

Or you can launch the management CLI and connect in one step by using the EAP_HOME/bin/jboss-cli.sh --connect command.

Display Help

Use the following command for general help.

help

Use the following command for help on a specific command.

deploy --help

Quit the Management CLI

quit

View System Settings

The following command uses the read-attribute operation to display whether the example datasource is enabled.

/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
{
    "outcome" => "success",
    "result" => true
}

When running in a managed domain, you must specify which profile to update by preceding the command with /profile=PROFILE_NAME.

/profile=default/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)

Update System Settings

The following command uses the write-attribute operation to disable the example datasource.

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=false)

Start Servers

The management CLI can also be used to start and stop servers when running in a managed domain.

/host=HOST_NAME/server-config=server-one:start

The management console is a web-based administration tool for JBoss EAP.

Use the management console to start and stop servers, deploy and undeploy applications, tune system settings, and make persistent modifications to the server configuration. The management console also has the ability to perform administrative tasks, with live notifications when any changes performed by the current user require the server instance to be restarted or reloaded.

In a managed domain, server instances and server groups in the same domain can be centrally managed from the management console of the domain controller.

For a JBoss EAP instance running on the local host using the default management port, the management console can be accessed through a web browser at http://localhost:9990/console/App.html. You will need to authenticate with a user that has permissions to access the management console.

The management console provides the following tabs for navigating and managing your JBoss EAP standalone server or managed domain.

The standalone configuration files are located in the EAP_HOME/standalone/configuration/ directory. A separate file exists for each of the four predefined profiles (default, ha, full, full-ha).

By default, starting JBoss EAP as a standalone server uses the standalone.xml file. To start JBoss EAP with a different configuration, use the --server-config argument. For example,

$ EAP_HOME/bin/standalone.sh --server-config=standalone-full.xml

The managed domain configuration files are located in the EAP_HOME/domain/configuration/ directory.

By default, starting JBoss EAP in a managed domain uses the host.xml file. To start JBoss EAP with a different configuration, use the --host-config argument. For example,

$ EAP_HOME/bin/domain.sh --host-config=host-master.xml

In order to later restore the JBoss EAP server configuration, items in the following locations should be backed up:

To assist in the maintenance and management of the server, JBoss EAP creates a timestamped version of the original configuration file at the time of startup. Any additional configuration changes made by management operations will result in the original file being automatically backed up, and a working copy of the instance being preserved for reference and rollback. Additionally, configuration snapshots can be taken, which are point-in-time copies of the current server configuration. These snapshots can be saved and loaded by an administrator.

The following examples use the standalone.xml file, but the same process applies to the domain.xml and host.xml files.

Take a Snapshot

Use the management CLI to take a snapshot of the current configurations.

:take-snapshot
{
    "outcome" => "success",
    "result" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20151022-133109702standalone.xml"
}

List Snapshots

Use the management CLI to list all snapshots that have been taken.

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
        "names" => [
            "20151022-133109702standalone.xml",
            "20151022-132715958standalone.xml"
        ]
    }
}

Delete a Snapshot

Use the management CLI to delete a snapshot.

:delete-snapshot(name=20151022-133109702standalone.xml)

Start the Server with a Snapshot

The server can be started using a snapshot or an automatically-saved version of the configuration.

JBoss EAP allows you to use expressions to define replaceable properties in place of literal values in the configuration. Expressions use the format ${PARAMETER:DEFAULT_VALUE}. If the specified parameter is set, then the parameter’s value will be used. Otherwise, the default value provided will be used.

The supported sources for resolving expressions are system properties, environment variables, and the vault. For deployments only, the source can be properties listed in a META-INF/jboss.properties file in the deployment archive. For deployment types that support subdeployments, the resolution is scoped to all subdeployments if the properties file is in the outer deployment, for example the EAR. If the properties file is in the subdeployment, then the resolution is scoped just to that subdeployment.

The example below from the standalone.xml configuration file sets the inet-address for the public interface to 127.0.0.1 unless the jboss.bind.address parameter is set.

<interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
</interface>

The jboss.bind.address parameter can be set when starting EAP as a standalone server with the following command:

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS

Nested Expressions

Expressions can be nested, which allows for more advanced use of expressions in place of fixed values. The format of a nested expression is like that of a normal expression, but one expression is embedded in the other, for example:

${SYSTEM_VALUE_1${SYSTEM_VALUE_2}}

Nested expressions are evaluated recursively, so the inner expression is first evaluated, then the outer expression is evaluated. Expressions may also be recursive, where an expression resolves to another expression, which is then resolved. Nested expressions are permitted anywhere that expressions are permitted, with the exception of management CLI commands.

An example of where a nested expression might be used is if the password used in a datasource definition is masked. The configuration for the datasource might have the following line:

<password>${VAULT::ds_ExampleDS::password::1}</password>

The value of ds_ExampleDS could be replaced with a system property (datasource_name) using a nested expression. The configuration for the datasource could instead have the following line:

<password>${VAULT::${datasource_name}::password::1}</password>

JBoss EAP would first evaluate the expression ${datasource_name}, then input this to the larger expression and evaluate the resulting expression. The advantage of this configuration is that the name of the datasource is abstracted from the fixed configuration.

Descriptor-Based Property Replacement

Application configuration, such as datasource connection parameters, typically varies between development, testing, and production environments. This variance is sometimes accommodated by build system scripts, as the Java EE specification does not contain a method to externalize these configurations. With JBoss EAP, you can use descriptor-based property replacement to manage configuration externally.

Descriptor-based property replacement substitutes properties based on descriptors, allowing you to remove assumptions about the environment from the application and the build chain. Environment-specific configurations can be specified in deployment descriptors rather than annotations or build system scripts. You can provide configuration in files or as parameters at the command line.

There are several flags in the ee subsystem that control whether property replacement is applied.

JBoss-specific descriptor replacement is controlled by the jboss-descriptor-property-replacement flag and is enabled by default. When enabled, properties can be replaced in the following deployment descriptors:

The following management CLI command can be used to enable or disable property replacement in JBoss-specific descriptors:

/subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)

Java EE descriptor replacement controlled by the spec-descriptor-property-replacement flag and is disabled by default. When enabled, properties can be replaced in the following deployment descriptors:

The following management CLI command can be used to enable or disable property replacement in Java EE descriptors:

/subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)

<interfaces>
  <interface name="management">
    <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
  </interface>
  <interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
  </interface>
  <interface name="private">
    <inet-address value="${jboss.bind.address.private:127.0.0.1}"/>
  </interface>
  <interface name="unsecure">
    <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/>
  </interface>
</interfaces>

By default, JBoss EAP binds these interfaces to 127.0.0.1, but these values can be overridden at runtime by setting the appropriate property. For example, the inet-address of the public interface can be set when starting JBoss EAP as a standalone server with the following command.

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS

Alternatively, you can use the -b switch on the server start command line. For more information about server start options, see Server Runtime Arguments.

Network interfaces are declared by specifying a logical name and selection criteria for the physical interface. The selection criteria can reference a wildcard address or specify a set of one or more characteristics that an interface or address must have in order to be a valid match. For a listing of all available interface selection criteria, see the Interface Attributes section.

Interfaces can be configured using the management console or the management CLI. Below are several examples of adding and updating interfaces. The management CLI command is shown first, followed by the corresponding configuration XML.

Add an Interface with a NIC Value

Add a new interface with a NIC value of eth0.

/interface=external:add(nic=eth0)

<interface name="external">
   <nic name="eth0"/>
</interface>

Add an Interface with Several Conditional Values

Add a new interface that matches any interface/address on the correct subnet if it is up, supports multicast, and is not point-to-point.

/interface=default:add(subnet-match=192.168.0.0/16,up=true,multicast=true,not={point-to-point=true})

<interface name="default">
   <subnet-match value="192.168.0.0/16"/>
   <up/>
   <multicast/>
   <not>
      <point-to-point/>
   </not>
</interface>

Update an Interface Attribute

Update the public interface’s default inet-address value, keeping the jboss.bind.address property to allow for this value to be set at runtime.

/interface=public:write-attribute(name=inet-address,value="${jboss.bind.address:192.168.0.0}")

<interface name="public">
    <inet-address value="${jboss.bind.address:192.168.0.0}"/>
</interface>

Add an Interface to a Server in a Managed Domain

/host=master/server-config=SERVER_NAME/interface=INTERFACE_NAME:add(inet-address=127.0.0.1)

<servers>
   <server name="SERVER_NAME" group="main-server-group">
      <interfaces>
         <interface name="INTERFACE_NAME">
            <inet-address value="127.0.0.1"/>
         </interface>
      </interfaces>
   </server>
</servers>

Management ports were consolidated in JBoss EAP 7. By default, JBoss EAP 7 uses port 9990 for both native management, used by the management CLI, and HTTP management, used by the web-based management console. Port 9999, which was used as the native management port in JBoss EAP 6, is no longer used but can still be enabled if desired.

If HTTPS is enabled for the management console, then port 9993 is used by default.

JBoss EAP ships with a socket binding group for each of the four predefined profiles (default, ha, full, full-ha).

For detailed information about the default socket bindings, such as default ports and descriptions, see the Default Socket Bindings section.

Standalone Server

When running as a standalone server, only one socket binding group is defined per configuration file. Each standalone configuration file (standalone.xml, standalone-ha.xml, standalone-full.xml, standalone-full-ha.xml) defines socket bindings for the technologies used by its corresponding profile.

For example, the default standalone configuration file (standalone.xml) specifies the below socket bindings.

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
    <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
        <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
</socket-binding-group>

Managed Domain

When running in a managed domain, all socket binding groups are defined in the domain.xml file. There are four predefined socket binding groups:

Each socket binding group specifies socket bindings for the technologies used by its corresponding profile. For example, the full-ha-sockets socket binding group defines several jgroups socket bindings, which are used by the full-ha profile for high availability.

<socket-binding-groups>
    <socket-binding-group name="standard-sockets" default-interface="public">
        <!-- Needed for server groups using the 'default' profile  -->
        <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
        <socket-binding name="http" port="${jboss.http.port:8080}"/>
        <socket-binding name="https" port="${jboss.https.port:8443}"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
    <socket-binding-group name="ha-sockets" default-interface="public">
        <!-- Needed for server groups using the 'ha' profile  -->
    ...
    </socket-binding-group>
    <socket-binding-group name="full-sockets" default-interface="public">
        <!-- Needed for server groups using the 'full' profile  -->
    ...
    </socket-binding-group>
    <socket-binding-group name="full-ha-sockets" default-interface="public">
        <!-- Needed for server groups using the 'full-ha' profile  -->
        <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
        <socket-binding name="http" port="${jboss.http.port:8080}"/>
        <socket-binding name="https" port="${jboss.https.port:8443}"/>
        <socket-binding name="iiop" interface="unsecure" port="3528"/>
        <socket-binding name="iiop-ssl" interface="unsecure" port="3529"/>
        <socket-binding name="jgroups-mping" interface="private" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
        <socket-binding name="jgroups-tcp" interface="private" port="7600"/>
        <socket-binding name="jgroups-tcp-fd" interface="private" port="57600"/>
        <socket-binding name="jgroups-udp" interface="private" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
        <socket-binding name="jgroups-udp-fd" interface="private" port="54200"/>
        <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
</socket-binding-groups>

When defining a socket binding, you can configure the port and interface attributes, as well as multicast settings such as multicast-address and multicast-port. For details on all available socket bindings attributes, see the Socket Binding Attributes section.

Socket bindings can be configured using the management console or the management CLI. The following steps go through adding a socket binding group, adding a socket binding, and configuring socket binding settings using the management CLI.

The following example shows how the XML configuration may look after the above steps have been completed.

<socket-binding-groups>
    ...
    <socket-binding-group name="new-sockets" default-interface="public">
        <socket-binding name="new-socket-binding" interface="unsecure" port="1234"/>
    </socket-binding-group>
</socket-binding-groups>

A port offset is a numeric offset value added to all port values specified in the socket binding group for that server. This allows the server to inherit the port values defined in its socket binding group, with an offset to ensure that it does not conflict with any other servers on the same host. For instance, if the HTTP port of the socket binding group is 8080, and a server uses a port offset of 100, then its HTTP port is 8180.

Below is an example of setting a port offset of 250 for a server in a managed domain using the management CLI.

/host=master/server-config=server-two/:write-attribute(name=socket-binding-port-offset,value=250)

Port offsets can be used for servers in a managed domain and for running multiple standalone servers on the same host.

You can pass in a port offset when starting a standalone server using the jboss.socket.binding.port-offset property.

$ EAP_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=100

JBoss EAP comes with a comprehensive set of quickstart code examples designed to help users begin writing applications using various Java EE 7 technologies. The quickstarts can be downloaded from the Red Hat Customer Portal.

Once the quickstarts have been downloaded, they can be imported into JBoss Developer Studio and deployed to JBoss EAP.

You can easily build and deploy the quickstarts from the command line using Maven. If you do not yet have Maven installed, see the Apache Maven project to download and install it.

A README.md file is provided at the root directory of the quickstarts that contains general information about system requirements, configuring Maven, adding users, and running the quickstarts.

Each quickstart also contains its own README.md file that provides the specific instructions and Maven commands to run that quickstart.