activemq-artemis/docs/user-manual/using-server.adoc

= Using the Server
:idprefix:
:idseparator: -

This chapter will familiarise you with how to use the Apache ActiveMQ Artemis server.

We'll show where it is, how to start and stop it, and we'll describe the directory layout and what all the files are and what they do.

This document will refer to the full path of the directory where the ActiveMQ distribution has been extracted to as `+${ARTEMIS_HOME}+`.

== Installation

You can get the latest release from the https://activemq.apache.org/components/artemis/download/[Download] page.

The following highlights some important folders on the distribution:

----
|___ bin
|
|___ lib
|
|___ schema
|
|___ web
----

bin::
binaries and scripts needed to run ActiveMQ Artemis.

lib::
jars and libraries needed to run ActiveMQ Artemis

schema::
XML Schemas used to validate ActiveMQ Artemis configuration files

web::
The folder where the web context is loaded when the broker runs.

== Creating a Broker Instance

A broker _instance_ is the directory containing all the configuration and runtime data, such as logs and message journal, associated with a broker process.
It is recommended that you do _not_ create the instance directory under `+${ARTEMIS_HOME}+`.
This separation is encouraged so that you can more easily upgrade when the next version of ActiveMQ Artemis is released.

On Unix systems, it is a common convention to store this kind of runtime data under the `/var/lib` directory.
For example, to create an instance at `/var/lib/mybroker`, run the following commands in your command line shell:

Before the broker is used, a broker instance must be created.
This process requires the use of the xref:using-cli.adoc#command-line-interface[Command Line Interface] which is better explained in its own chapter.

In the following example a broker instance named `mybroker` will be created:

[,console]
----
$ cd /var/lib
$ ${ARTEMIS_HOME}/bin/artemis create mybroker
----

A broker instance directory will contain the following sub directories:

bin::
holds execution scripts associated with this instance.

data::
holds the data files used for storing persistent messages

etc::
hold the instance configuration files

lib::
holds any custom runtime Java dependencies like transformers, plugins, interceptors, etc.

log::
holds rotating log files

tmp::
holds temporary files that are safe to delete between broker runs

At this point you may want to adjust the default configuration located in the `etc` directory.

=== Options

There are several options you can use when creating an instance.
For a full list of options use the `help` command:

[,console]
----
$ ./artemis help create
Usage: artemis create [--aio] [--allow-anonymous] [--autocreate] [--autodelete]
                      [--backup] [--blocking] [--clustered]
                      [--disable-persistence] [--failover-on-shutdown]
                      [--force] [--jdbc] [--linux] [--mapped] [--nio]
                      [--no-amqp-acceptor] [--no-autocreate] [--no-autotune]
                      [--no-fsync] [--no-hornetq-acceptor] [--no-mqtt-acceptor]
                      [--no-stomp-acceptor] [--no-web] [--paging]
                      [--relax-jolokia] [--replicated] [--require-login]
                      [--shared-store] [--silent] [--slave]
                      [--support-advisory]
                      [--suppress-internal-management-objects]
                      [--use-client-auth] [--verbose] [--windows]
                      [--addresses=<addresses>]
                      [--cluster-password=<clusterPassword>]
                      [--cluster-user=<clusterUser>] [--data=<data>]
                      [--default-port=<defaultPort>] [--encoding=<encoding>]
                      [--etc=<etc>] [--global-max-messages=<globalMaxMessages>]
                      [--global-max-size=<globalMaxSize>] [--home=<home>]
                      [--host=<host>] [--http-host=<httpHost>]
                      [--http-port=<httpPort>] [--java-memory=<javaMemory>]
                      [--jdbc-bindings-table-name=<jdbcBindings>]
                      [--jdbc-connection-url=<jdbcURL>]
                      [--jdbc-driver-class-name=<jdbcClassName>]
                      [--jdbc-large-message-table-name=<jdbcLargeMessages>]
                      [--jdbc-lock-expiration=<jdbcLockExpiration>]
                      [--jdbc-lock-renew-period=<jdbcLockRenewPeriod>]
                      [--jdbc-message-table-name=<jdbcMessages>]
                      [--jdbc-network-timeout=<jdbcNetworkTimeout>]
                      [--jdbc-node-manager-table-name=<jdbcNodeManager>]
                      [--jdbc-page-store-table-name=<jdbcPageStore>]
                      [--journal-device-block-size=<journalDeviceBlockSize>]
                      [--journal-retention=<retentionDays>]
                      [--journal-retention-max-bytes=<retentionMaxBytes>]
                      [--max-hops=<maxHops>]
                      [--message-load-balancing=<messageLoadBalancing>]
                      [--name=<name>] [--password=<password>] [--ping=<ping>]
                      [--port-offset=<portOffset>] [--queues=<queues>]
                      [--role=<role>] [--security-manager=<securityManager>]
                      [--ssl-key=<sslKey>]
                      [--ssl-key-password=<sslKeyPassword>]
                      [--ssl-trust=<sslTrust>]
                      [--ssl-trust-password=<sslTrustPassword>]
                      [--staticCluster=<staticNode>] [--user=<user>]
                      [--java-options=<javaOptions>]... <directory>
Create a new broker instance.
      <directory>            The instance directory to hold the broker's
                               configuration and data. Path must be writable.
      --addresses=<addresses>
                             A comma separated list of addresses with the
                               option to specify a routing type, e.g.
                               --addresses myAddress1,myAddress2:anycast.
                               Routing-type default: multicast.
      --aio                  Set the journal as asyncio.
      --allow-anonymous      Allow connections from users with no security
                               credentials. Opposite of --require-login.
                               Default: input.
      --autocreate           Allow automatic creation of addresses & queues.
                               Default: true.
      --autodelete           Allow automatic deletion of addresses & queues.
                               Default: false.
      --backup               Be a backup broker. Valid for shared store or
                               replication.
      --blocking             Block producers when address becomes full.
                               Opposite of --paging. Default: false.
      --cluster-password=<clusterPassword>
                             The password to use for clustering. Default: input.
      --cluster-user=<clusterUser>
                             The user to use for clustering. Default: input.
      --clustered            Enable clustering.
      --data=<data>          Directory where ActiveMQ data are stored. Paths
                               can be absolute or relative to artemis.instance
                               directory. Default: data.
      --default-port=<defaultPort>
                             The port number to use for the main 'artemis'
                               acceptor. Default: 61616.
      --disable-persistence  Disable message persistence to the journal
      --encoding=<encoding>  The encoding that text files should use. Default:
                               UTF-8.
      --etc=<etc>            Directory where ActiveMQ configuration is located.
                               Paths can be absolute or relative to artemis.
                               instance directory. Default: etc.
      --failover-on-shutdown Whether broker shutdown will trigger failover for
                               clients using the core protocol. Valid only for
                               shared store. Default: false.
      --force                Overwrite configuration at destination directory.
      --global-max-messages=<globalMaxMessages>
                             Maximum number of messages that will be accepted
                               in memory before using address full policy mode.
                               Default: undefined.
      --global-max-size=<globalMaxSize>
                             Maximum amount of memory which message data may
                               consume. Default: half of the JVM's max memory.
      --home=<home>          Directory where ActiveMQ Artemis is installed.
      --host=<host>          Broker's host name. Default: 0.0.0.0 or input if
                               clustered).
      --http-host=<httpHost> Embedded web server's host name. Default:
                               localhost.
      --http-port=<httpPort> Embedded web server's port. Default: 8161.
      --java-memory=<javaMemory>
                             Define the -Xmx memory parameter for the broker.
                               Default: 2G.
      --java-options=<javaOptions>
                             Extra Java options to be passed to the profile.
      --jdbc                 Store message data in JDBC instead of local files.
      --jdbc-bindings-table-name=<jdbcBindings>
                             Name of the jdbc bindings table.
      --jdbc-connection-url=<jdbcURL>
                             The URL used for the database connection.
      --jdbc-driver-class-name=<jdbcClassName>
                             JDBC driver classname.
      --jdbc-large-message-table-name=<jdbcLargeMessages>
                             Name of the large messages table.
      --jdbc-lock-expiration=<jdbcLockExpiration>
                             Lock expiration (in milliseconds).
      --jdbc-lock-renew-period=<jdbcLockRenewPeriod>
                             Lock Renew Period (in milliseconds).
      --jdbc-message-table-name=<jdbcMessages>
                             Name of the jdbc messages table.
      --jdbc-network-timeout=<jdbcNetworkTimeout>
                             Network timeout (in milliseconds).
      --jdbc-node-manager-table-name=<jdbcNodeManager>
                             Name of the jdbc node manager table.
      --jdbc-page-store-table-name=<jdbcPageStore>
                             Name of the page store messages table.
      --journal-device-block-size=<journalDeviceBlockSize>
                             The block size of the journal's storage device.
                               Default: 4096.
      --journal-retention=<retentionDays>
                             Configure journal retention in days. If > 0 then
                               enable journal-retention-directory from broker.
                               xml allowing replay options.
      --journal-retention-max-bytes=<retentionMaxBytes>
                             Maximum number of bytes to keep in the retention
                               directory.
      --linux, --cygwin      Force Linux or Cygwin script creation. Default:
                               based on your actual system.
      --mapped               Set the journal as mapped.
      --max-hops=<maxHops>   Number of hops on the cluster configuration.
      --message-load-balancing=<messageLoadBalancing>
                             Message load balancing policy for cluster.
                               Default: ON_DEMAND. Valid values: ON_DEMAND,
                               STRICT, OFF, OFF_WITH_REDISTRIBUTION.
      --name=<name>          The name of the broker. Default: same as host name.
      --nio                  Set the journal as nio.
      --no-amqp-acceptor     Disable the AMQP specific acceptor.
      --no-autocreate        Disable auto creation for addresses & queues.
      --no-autotune          Disable auto tuning of the journal-buffer-timeout
                               in broker.xml.
      --no-fsync             Disable usage of fdatasync (channel.force(false)
                               from Java NIO) on the journal.
      --no-hornetq-acceptor  Disable the HornetQ specific acceptor.
      --no-mqtt-acceptor     Disable the MQTT specific acceptor.
      --no-stomp-acceptor    Disable the STOMP specific acceptor.
      --no-web               Whether to omit the web-server definition from
                               bootstrap.xml.
      --paging               Page messages to disk when address becomes full.
                               Opposite of --blocking. Default: true.
      --password=<password>  The user's password. Default: input.
      --ping=<ping>          A comma separated string to be passed on to the
                               broker config as network-check-list. The broker
                               will shutdown when all these addresses are
                               unreachable.
      --port-offset=<portOffset>
                             How much to off-set the ports of every acceptor.
      --queues=<queues>      A comma separated list of queues with the option
                               to specify a routing type, e.g. --queues
                               myQueue1,myQueue2:multicast. Routing-type
                               default: anycast.
      --relax-jolokia        Disable strict checking in jolokia-access.xml.
      --replicated           Enable broker replication.
      --require-login        Require security credentials from users for
                               connection. Opposite of --allow-anonymous.
      --role=<role>          The name for the role created. Default: amq.
      --security-manager=<securityManager>
                             Which security manager to use - jaas or basic.
                               Default: jaas.
      --shared-store         Enable broker shared store.
      --silent               Disable all the inputs, and make a best guess for
                               any required input.
      --slave                Deprecated for removal. Use 'backup' instead.
      --ssl-key=<sslKey>     Embedded web server's key store path.
      --ssl-key-password=<sslKeyPassword>
                             The key store's password.
      --ssl-trust=<sslTrust> The trust store path in case of client
                               authentication.
      --ssl-trust-password=<sslTrustPassword>
                             The trust store's password.
      --staticCluster, --static-cluster=<staticNode>
                             Cluster node connectors list separated by comma, e.
                               g. "tcp://server:61616,tcp://server2:61616,tcp:
                               //server3:61616".
      --support-advisory     Support advisory messages for the OpenWire
                               protocol.
      --suppress-internal-management-objects
                             Do not register any advisory addresses/queues for
                               the OpenWire protocol with the broker's
                               management service.
      --use-client-auth      Require client certificate authentication when
                               connecting to the embedded web server.
      --user=<user>          The username. Default: input.
      --verbose              Print additional information.
      --windows              Force Windows script creation. Default: based on
                               your actual system.
----

Some of these options may be mandatory in certain configurations and the system may ask you for additional input, e.g.:

[,console]
----
$ ./artemis create /usr/server
Creating ActiveMQ Artemis instance at: /usr/server

--user:
What is the default username?
admin

--password: is mandatory with this configuration:
What is the default password?


--allow-anonymous | --require-login:
Allow anonymous access?, valid values are Y, N, True, False
y

Auto tuning journal ...
done! Your system can make 250 writes per millisecond, your journal-buffer-timeout will be 4000

You can now start the broker by executing:

   "/usr/server" run

Or you can run the broker in the background using:

   "/usr/server" start
----

== Starting and Stopping a Broker Instance

Assuming you created the broker instance under `/var/lib/mybroker` all you need to do start running the broker instance is execute:

[,console]
----
/var/lib/mybroker/bin/artemis run
----

To stop the Apache ActiveMQ Artemis instance you will use the same `artemis` script, but with the `stop` argument.
Example:

[,console]
----
/var/lib/mybroker/bin/artemis stop
----

Please note that Apache ActiveMQ Artemis requires a Java 11 or later.

By default the `etc/bootstrap.xml` configuration is used.
The configuration can be changed e.g. by running `+./artemis run -- xml:path/to/bootstrap.xml+` or another config of your choosing.

Environment variables are used to provide ease of changing ports, hosts and data directories used and can be found in `etc/artemis.profile` on linux and `etc\artemis.profile.cmd` on Windows.

== Configuration Files

These are the files you're likely to find in the `etc` directory of a default broker instance with a short explanation of what they configure.
Scroll down further for additional details as appropriate.

artemis.profile::
system properties and JVM arguments (e.g. `Xmx`, `Xms`,  etc.)

artemis-roles.properties::
user/role mapping for the default xref:security.adoc#propertiesloginmodule[properties-based JAAS login module]

artemis-users.properties::
user/password for the default xref:security.adoc#propertiesloginmodule[properties-based JAAS login module]

bootstrap.xml::
embedded web server, security, location of `broker.xml`

broker.xml::
core broker configuration, e.g. acceptors, addresses, queues, diverts, clustering; xref:configuration-index.adoc#configuration-reference[full reference]

jolokia-access.xml::
https://jolokia.org/reference/html/security.html[security for Jolokia], specifically Cross-Origin Resource Sharing (CORS)

log4j2.properties::
xref:logging.adoc#logging[logging config] like levels, log file locations, etc.

login.config:: standard Java configuration for JAAS xref:security.adoc#authentication-authorization[security]

management.xml::
remote connectivity and xref:management.adoc#role-based-authorisation-for-jmx[security for JMX MBeans]

=== Bootstrap Configuration File

The `bootstrap.xml` file is very simple.
Let's take a look at an example:

[,xml]
----
<broker xmlns="http://activemq.apache.org/schema">

   <jaas-security domain="activemq"/>

   <server configuration="file:/path/to/broker.xml"/>

   <web path="web">
      <binding uri="http://localhost:8161">
         <app url="activemq-branding" war="activemq-branding.war"/>
         <app url="artemis-plugin" war="artemis-plugin.war"/>
         <app url="console" war="console.war"/>
      </binding>
   </web>
</broker>
----

jaas-security::
Configures JAAS-based security for the server.
The `domain` attribute refers to the relevant login module entry in `login.config`.
If different behavior is needed then a custom security manager can be configured by replacing `jaas-security` with `security-manager`.
See the "Custom Security Manager" section in the xref:security.adoc#authentication-authorization[security chapter] for more details.

server::
Instantiates a core server using the configuration file from the `configuration` attribute.
This is the main broker POJO necessary to do all the real messaging work.

web::
Configures an embedded web server for things like the admin console.

=== Broker configuration file

The configuration for the Apache ActiveMQ Artemis core broker is contained in `broker.xml`.

There are many attributes which you can configure for Apache ActiveMQ Artemis.
In most cases the defaults will do fine, in fact every attribute can be defaulted which means a file with a single empty `configuration` element is a valid configuration file.
The different configuration will be explained throughout the manual or you can refer to the configuration reference xref:configuration-index.adoc#configuration-reference[here].

== Other Use-Cases

=== System Property Substitution

It is possible to use system property substitution in all the configuration files.
by replacing a value with the name of a system property.
Here is an example of this with a connector configuration:

[,xml]
----
<connector name="netty">tcp://${activemq.remoting.netty.host:localhost}:${activemq.remoting.netty.port:61616}</connector>
----

Here you can see we have replaced 2 values with system properties `activemq.remoting.netty.host` and `activemq.remoting.netty.port`.
These values will be replaced by the value found in the system property if there is one, if not they default back to `localhost` or `61616` respectively.
It is also possible to not supply a default (i.e. `${activemq.remoting.netty.host}`), however the system property _must_ be supplied in that case.

=== Windows Server

On windows you will have the option to run ActiveMQ Artemis as a service.
Just use the following command to install it:

----
 $ ./artemis-service.exe install
----

The create process should give you a hint of the available commands available for the artemis-service.exe

=== Adding Bootstrap Dependencies

Bootstrap dependencies like logging handlers must be accessible by the log manager at boot time.
Package the dependency in a jar and put it on the boot classpath before of log manager jar.
This can be done appending the jar at the variable `JAVA_ARGS`, defined in `artemis.profile`, with the option `-Xbootclasspath/a`.

NOTE: the environment variable `JAVA_ARGS_APPEND` can be used to append or override options.

=== Adding Runtime Dependencies

Runtime dependencies like transformers, broker plugins, JDBC drivers, password decoders, etc. must be accessible by the broker at runtime.
Package the dependency in a jar, and put it on the broker's classpath.
This can be done by placing the jar file in the `lib` directory of the broker distribution itself,
by placing the jar file in the `lib` directory of the broker instance,
by setting the system property `artemis.extra.libs` with the directory that contains the jar file, or
by setting the environment variable `ARTEMIS_EXTRA_LIBS` with the directory that contains the jar file,
A broker instance does not have a `lib` directory by default so it may need to be created.
It should be on the "top" level with the `bin`, `data`, `log`, etc.
directories.
The system property `artemis.extra.libs` is a comma separated list of directories that contains jar files, i.e.
```
-Dartemis.extra.libs=/usr/local/share/java/lib1,/usr/local/share/java/lib2
```
The environment variable `ARTEMIS_EXTRA_LIBS` is a comma separated list of directories that contains jar files and
is ignored if the system property `artemis.extra.libs` is defined, i.e.
```
export ARTEMIS_EXTRA_LIBS=/usr/local/share/java/lib1,/usr/local/share/java/lib2
```

=== Library Path

If you're using the xref:libaio.adoc#libaio-native-libraries[Asynchronous IO Journal] on Linux, you need to specify `java.library.path` as a property on your Java options.
This is done automatically in the scripts.

If you don't specify `java.library.path` at your Java options then the JVM will use the environment variable `LD_LIBRARY_PATH`.

You will need to make sure libaio is installed on Linux.
For more information refer to the xref:libaio.adoc#runtime-dependencies[libaio chapter].