create-cluster

Creates a Payara Server cluster.

Synopsis

asadmin [asadmin-options] create-cluster [--help]
[--config config-name]
[--systemproperties (name=value)[:name=value]*]
[--properties (name=value)[:name=value]*]
[--gmsenabled={true|false}]
[--multicastport multicast-port]
[--multicastaddress multicast-address]
[--bindaddress bind-address]
[--hosts hadb-host-list]
[--haagentport port-number]
[--haadminpassword password]
[--haadminpasswordfile file-name] [--devicesize devicesize ]
[--haproperty (name=value)[:name=value]*]
[--autohadb=false] [--portbase port-number]
cluster-name

Description

The create-cluster subcommand creates a Payara Server cluster. Initially the cluster contains no Payara Server instances, applications, or resources.

A cluster requires a reference to the named configuration that defines the configuration of all instances that are added to the cluster. The configuration can be specified in the command to create the cluster, but is not required. If no configuration is specified, the subcommand creates a configuration that is named cluster-name`-config` for the cluster. The cluster that is created is a standalone cluster because the cluster’s configuration is not shared with any other clusters or standalone instances.

To add instances to the cluster, set the --cluster option to the name of the cluster when using either of the following subcommands:

To delete server instances from the cluster at any time, use one of the following subcommands:

To associate applications and resources with all instances in the cluster, set the --target option to the name of the cluster when performing the following operations:

  • Deploying applications by using the deploy subcommand

  • Creating resources by using subcommands such as create-jdbc-resource

  • Creating references to applications that are already deployed in other targets by using the create-application-ref subcommand

  • Creating references to resources that are already created in other targets by using the create-resource-ref subcommand

This subcommand is supported in remote mode only.

Options

asadmin-options

Options for the asadmin utility. For information about these options, see the asadmin help page.

--help
-?

Displays the help text for the subcommand.

--config

Specifies the named configuration that the cluster references. The configuration must exist and must not be named default-config or server-config. Specifying the --config option creates a shared cluster. If this option is omitted, a standalone cluster is created.

--systemproperties

Defines system properties for the configuration that is created for the cluster. These properties override the property values in the default-config configuration. The following properties are available:

ASADMIN_LISTENER_PORT

This property specifies the port number of the HTTP port or HTTPS port through which the DAS connects to the instance to manage the instance. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

HTTP_LISTENER_PORT

This property specifies the port number of the port that is used to listen for HTTP requests. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

HTTP_SSL_LISTENER_PORT

This property specifies the port number of the port that is used to listen for HTTPS requests. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

IIOP_LISTENER_PORT

This property specifies the port number of the port that is used for IIOP connections. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

IIOP_SSL_LISTENER_PORT

This property specifies the port number of the port that is used for secure IIOP connections. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

IIOP_SSL_MUTUALAUTH_PORT

This property specifies the port number of the port that is used for secure IIOP connections with client authentication. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

JAVA_DEBUGGER_PORT

This property specifies the port number of the port that is used for connections to the Java Platform Debugger Architecture (JPDA) (http://www.oracle.com/technetwork/java/javase/tech/jpda-141715.adoc) debugger. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

JMS_PROVIDER_PORT

This property specifies the port number for the Java Message Service provider. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

JMX_SYSTEM_CONNECTOR_PORT

This property specifies the port number on which the JMX connector listens. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

OSGI_SHELL_TELNET_PORT

This property specifies the port number of the port that is used for connections to the Apache Felix Remote Shell (http://felix.apache.org/site/apache-felix-remote-shell.html). This shell uses the Felix shell service to interact with the OSGi module management subsystem. Valid values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges.

--properties

Defines properties for the cluster. The following properties are available:

GMS_DISCOVERY_URI_LIST

The locations of Payara Server instances in the cluster to use for discovering the cluster. This property is required only if the Group Management Service (GMS) is not using multicast for broadcasting messages.

Valid values for this property are as follows:

  • A comma-separated list of uniform resource identifiers (URIs). Each URI must locate a Payara Server instance or the DAS. This format is required if multiple Payara Server instances are running on the same host.

    The format of each URI in the list is as follows:

    scheme :// host-name-or -IP-address : port

    • scheme is the URI scheme, which is tcp.

    • host-name-or -IP-address is the host name or IP address of the host on which the instance is running.

    • port is the port number of the port on which the instance listens for messages from GMS. The system property GMS_LISTENER_PORT- clustername must be set for the instance.

  • A comma-separated list of IP addresses or host names on which the DAS or the instances are running. The list can contain a mixture of IP addresses and host names. This format can be used only if one clustered instance is running on each host. The value of the GMS_LISTENER_PORT property must be unique for each cluster in a domain.

  • The keyword generate. This format can be used only if one instance in a cluster is running on each host and the DAS is running on a separate host. Multiple instances on the same host cannot be members of the same cluster. The value of the GMS_LISTENER_PORT property must be unique for each cluster in a domain.

GMS_LISTENER_PORT

The port number of the port on which the cluster listens for messages from GMS.

The default value is a reference to the GMS_LISTENER_PORT- cluster-name system property. By default, this system property is not set. In this situation, GMS selects a free port from the range that is defined by the properties GMS_TCPSTARTPORT and GMS_TCPENDPORT. By default, this range is 9090-9200. In most situations, the default behavior should suffice.

However, if GMS is not using multicast for broadcasting messages, the GMS_LISTENER_PORT property must specify a port number that is valid for all Payara Server instances in the cluster. To use the default value to meet this requirement, use a system property to set the port number individually for each instance.

For example, use the create-system-properties subcommand to create the system property GMS_LISTENER_PORT- cluster-name for the DAS. Then, for each instance in the cluster, set the GMS_LISTENER_PORT- cluster-name system property to the port number on which the instance listens for messages from GMS. The default value of the GMS_LISTENER_PORT property for the cluster references this system property.

GMS_LOOPBACK

Specifies whether an instance may receive from itself application-level messages that the instance broadcasts to the cluster.

Possible values are as follows:

false

The instance may not receive messages from itself (default).

true

The instance may receive messages from itself. Use this setting for testing an instance when the instance is the only instance in a cluster.

GMS_MULTICAST_TIME_TO_LIVE

The maximum number of iterations or transmissions that a multicast message for the following types of events can experience before the message is discarded:

  • Group discovery

  • Member heartbeats

  • Membership changes

    To match the configuration of the network on which the DAS and clustered instances are deployed, set this value as low as possible. To determine the lowest possible value for your system, use the validate-multicast subcommand.

    A value of 0 ensures that multicast messages never leave the host from which they are broadcast.

    A value of 1 might prevent the broadcast of messages between hosts on same subnet that are connected by a switch or a router.

    The default is 4, which ensures that messages are successfully broadcast to all cluster members in networks where hosts are connected by switches or routers.

GMS_TCPENDPORT

The highest port number in the range from which GMS selects a free port if the `GMS_LISTENER_PORT-`cluster-name system property is not set. The default is 9200.

GMS_TCPSTARTPORT

The lowest port number in the range from which GMS selects a free port if the `GMS_LISTENER_PORT-`cluster-name system property is not set. The default is 9090.

--gmsenabled

Specifies whether GMS is enabled for the cluster.

Possible values are as follows:

true

GMS is enabled for the cluster (default).

When GMS is enabled for a cluster, GMS is started in each server instance in the cluster and in the DAS. The DAS participates in each cluster for which this option is set to true.

false

GMS is disabled for the cluster.

--multicastaddress

The address on which GMS listens for group events. This option must specify a multicast address in the range 224.0.0.0 through 239.255.255.255. The default is 228.9.XX.YY, where XX and YY are automatically generated independent values between 0 and 255.

--multicastport

The port number of communication port on which GMS listens for group events. This option must specify a valid port number in the range 2048-49151. The default is an automatically generated value in this range.

--bindaddress

The Internet Protocol (IP) address of the network interface to which GMS binds. This option must specify the IP address of a local network interface. The default is all public network interface addresses.

On a multihome machine, this option configures the network interface that is used for the GMS. A multihome machine possesses two or more network interfaces.

To specify an address that is valid for all Payara Server instances in the cluster, use a system property to set the address individually for each instance.

For example, use the create-system-properties subcommand to create the system property GMS-BIND-INTERFACE-ADDRESS- cluster-name. Then set the --bindaddress option of this subcommand to ${GMS-BIND-INTERFACE-ADDRESS- cluster-name } to specify the system property. Finally, for each instance in the cluster, set the GMS-BIND-INTERFACE-ADDRESS- cluster-name system property to the required network interface address on the instance’s machine.

--hosts

Do not specify this option. This option is retained for compatibility with earlier releases. If you specify this option, a syntax error does not occur. Instead, the subcommand runs successfully and displays a warning message that the option is ignored.

--haagentport

Do not specify this option. This option is retained for compatibility with earlier releases. If you specify this option, a syntax error does not occur. Instead, the subcommand runs successfully and displays a warning message that the option is ignored.

--haadminpassword

Do not specify this option. This option is retained for compatibility with earlier releases. If you specify this option, a syntax error does not occur. Instead, the subcommand runs successfully and displays a warning message that the option is ignored.

--haadminpasswordfile

Do not specify this option. This option is retained for compatibility with earlier releases. If you specify this option, a syntax error does not occur. Instead, the subcommand runs successfully and displays a warning message that the option is ignored.

--devicesize

Do not specify this option. This option is retained for compatibility with earlier releases. If you specify this option, a syntax error does not occur. Instead, the subcommand runs successfully and displays a warning message that the option is ignored.

--haproperty

Do not specify this option. This option is retained for compatibility with earlier releases. If you specify this option, a syntax error does not occur. Instead, the subcommand runs successfully and displays a warning message that the option is ignored.

--autohadb

Do not specify this option. This option is retained for compatibility with earlier releases. If you specify this option, a syntax error does not occur. Instead, the subcommand runs successfully and displays a warning message that the option is ignored.

--portbase

Do not specify this option. This option is retained for compatibility with earlier releases. If you specify this option, a syntax error does not occur. Instead, the subcommand runs successfully and displays a warning message that the option is ignored.

Operands

cluster-name

The name of the cluster.

The name must meet the following requirements:

  • The name may contain only ASCII characters.

  • The name must start with a letter, a number, or an underscore.

  • The name may contain only the following characters:

    • Lowercase letters

    • Uppercase letters

    • Numbers

    • Hyphen

    • Period

    • Underscore

  • The name must be unique in the domain and must not be the name of another cluster, a named configuration, a Payara Server instance, or a node.

  • The name must not be domain, server, or any other keyword that is reserved by Payara Server.
    If the configure-jms-cluster subcommand is to be used to configure a Message Queue cluster to provide JMS services to the Payara Server cluster, the length of the Payara Server cluster name is might be restricted:

  • If clustertype is set to enhanced in the configure-jms-cluster subcommand, the name can be no longer than n–21 characters, where n is the maximum table name length allowed by the database.

  • If configstoretype is set to shareddb in the configure-jms-cluster subcommand, the name can be no longer than n–19 characters, where n is the maximum table name length allowed by the database.

Examples

Example 1 Creating a Cluster

This example creates a cluster that is named ltscluster for which port 1169 is to be used for secure IIOP connections. Because the --config option is not specified, the cluster references a copy of the named configuration default-config that is named ltscluster-config.

asadmin> create-cluster
--systemproperties IIOP_SSL_LISTENER_PORT=1169
ltscluster
Command create-cluster executed successfully.

Example 2 Creating a Cluster With a List of URIs for Discovering the Cluster

This example creates a cluster that is named tcpcluster. In this example, GMS is not using multicast for broadcasting messages and multiple instances reside on the same host. Therefore, the GMS_DISCOVERY_URI_LIST property is set to the locations of the Payara Server instances to use for discovering the cluster. These instances reside on the host whose IP address is 10.152.23.224 and listen for GMS events on ports 9090, 9091, and 9092.

To distinguish colon (:) characters in URIs from separators in a property list, colons in URIs are escaped with single quote characters (') and backslash (\) characters. For more information about escape characters in options for the asadmin utility, see the asadmin help page.

This example assumes that the port on which each instance listens for GMS messages is set independently for the instance through the GMS_LISTENER_PORT-tcpcluster system property.

asadmin> create-cluster --properties GMS_DISCOVERY_URI_LIST=
tcp'\\:'//10.152.23.224'\\:'9090,
tcp'\\:'//10.152.23.224'\\:'9091,
tcp'\\:'//10.152.23.224'\\:'9092 tcpcluster
Command create-cluster executed successfully.

Example 3 Creating a Cluster With a List of IP Addresses for Discovering the Cluster

This example creates a cluster that is named ipcluster. In this example, GMS is not using multicast for broadcasting messages and only one clustered instance resides on each host. Therefore, the GMS_DISCOVERY_URI_LIST property is set to the IP addresses of the hosts where instances to use for discovering the cluster are running. The cluster listens for messages from GMS on port 9090.

asadmin> create-cluster --properties 'GMS_DISCOVERY_URI_LIST=
10.152.23.225,10.152.23.226,10.152.23.227,10.152.23.228:
GMS_LISTENER_PORT=9090' ipcluster
Command create-cluster executed successfully.

Example 4 Creating a Cluster With a Generated List of Instances for Discovering the Cluster

This example creates a cluster that is named gencluster. In this example, GMS is not using multicast for broadcasting messages, one instance in the cluster is running on each host and the DAS is running on a separate host. Therefore, the GMS_DISCOVERY_URI_LIST property is set to the keyword generate to generate a list of instances to use for discovering the cluster. The cluster listens for messages from GMS on port 9090.

asadmin> create-cluster --properties 'GMS_DISCOVERY_URI_LIST=generate:
GMS_LISTENER_PORT=9090' gencluster
Command create-cluster executed successfully.

Exit Status

0

command executed successfully

1

error in executing the command

See Also