Using the Server

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

The following highlights some important folders on the distribution:

  1. |___ bin
  2. |
  3. |___ examples
  4. |      |___ common
  5. |      |___ features
  6. |      |___ perf
  7. |      |___ protocols
  8. |
  9. |___ lib
  10. |      |___ client
  11. |
  12. |___ schema
  13. |
  14. |___ web
  15.       |___ api
  16.       |___ hacking-guide
  17.       |___ migration-guide
  18.       |___ user-manual

  • bin - binaries and scripts needed to run ActiveMQ Artemis.

  • examples - All manner of examples. Please refer to the examples chapter for details on how to run them.

  • 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.

  • api - The api documentation is placed under the web folder.

  • user-manual - The user manual is placed under the web folder.

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:

  1. cd /var/lib
  2. ${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:

  1. $./artemis help create
  2. NAME
  3.         artemis create - creates a new broker instance
  5. SYNOPSIS
  6.         artemis create [--addresses <addresses>] [--aio] [--allow-anonymous]
  7.                 [--autocreate] [--blocking] [--cluster-password <clusterPassword>]
  8.                 [--cluster-user <clusterUser>] [--clustered] [--data <data>]
  9.                 [--default-port <defaultPort>] [--disable-persistence]
  10.                 [--encoding <encoding>] [--etc <etc>] [--failover-on-shutdown] [--force]
  11.                 [--global-max-size <globalMaxSize>] [--home <home>] [--host <host>]
  12.                 [--http-host <httpHost>] [--http-port <httpPort>]
  13.                 [--java-options <javaOptions>] [--jdbc]
  14.                 [--jdbc-bindings-table-name <jdbcBindings>]
  15.                 [--jdbc-connection-url <jdbcURL>]
  16.                 [--jdbc-driver-class-name <jdbcClassName>]
  17.                 [--jdbc-large-message-table-name <jdbcLargeMessages>]
  18.                 [--jdbc-lock-expiration <jdbcLockExpiration>]
  19.                 [--jdbc-lock-renew-period <jdbcLockRenewPeriod>]
  20.                 [--jdbc-message-table-name <jdbcMessages>]
  21.                 [--jdbc-network-timeout <jdbcNetworkTimeout>]
  22.                 [--jdbc-node-manager-table-name <jdbcNodeManager>]
  23.                 [--jdbc-page-store-table-name <jdbcPageStore>]
  24.                 [--journal-device-block-size <journalDeviceBlockSize>] [--mapped]
  25.                 [--max-hops <maxHops>] [--message-load-balancing <messageLoadBalancing>]
  26.                 [--name <name>] [--nio] [--no-amqp-acceptor] [--no-autocreate]
  27.                 [--no-autotune] [--no-fsync] [--no-hornetq-acceptor]
  28.                 [--no-mqtt-acceptor] [--no-stomp-acceptor] [--no-web] [--paging]
  29.                 [--password <password>] [--ping <ping>] [--port-offset <portOffset>]
  30.                 [--queues <queues>] [--relax-jolokia] [--replicated] [--require-login]
  31.                 [--role <role>] [--security-manager <securityManager>] [--shared-store]
  32.                 [--silent] [--slave] [--ssl-key <sslKey>]
  33.                 [--ssl-key-password <sslKeyPassword>] [--ssl-trust <sslTrust>]
  34.                 [--ssl-trust-password <sslTrustPassword>] [--staticCluster <staticNode>]
  35.                 [--use-client-auth] [--user <user>] [--verbose] [--] <directory>
  37. OPTIONS
  38.         --addresses <addresses>
  39.             Comma separated list of addresses
  41.         --aio
  42.             Sets the journal as asyncio.
  44.         --allow-anonymous
  45.             Enables anonymous configuration on security, opposite of
  46.             --require-login (Default: input)
  48.         --autocreate
  49.             Auto create addresses. (default: true)
  51.         --blocking
  52.             Block producers when address becomes full, opposite of --paging
  53.             (Default: false)
  55.         --cluster-password <clusterPassword>
  56.             The cluster password to use for clustering. (Default: input)
  58.         --cluster-user <clusterUser>
  59.             The cluster user to use for clustering. (Default: input)
  61.         --clustered
  62.             Enable clustering
  64.         --data <data>
  65.             Directory where ActiveMQ data are stored. Paths can be absolute or
  66.             relative to artemis.instance directory ('data' by default)
  68.         --default-port <defaultPort>
  69.             The port number to use for the main 'artemis' acceptor (Default:
  70.             61616)
  72.         --disable-persistence
  73.             Disable message persistence to the journal
  75.         --encoding <encoding>
  76.             The encoding that text files should use
  78.         --etc <etc>
  79.             Directory where ActiveMQ configuration is located. Paths can be
  80.             absolute or relative to artemis.instance directory ('etc' by
  81.             default)
  83.         --failover-on-shutdown
  84.             Valid for shared store: will shutdown trigger a failover? (Default:
  85.             false)
  87.         --force
  88.             Overwrite configuration at destination directory
  90.         --global-max-size <globalMaxSize>
  91.             Maximum amount of memory which message data may consume (Default:
  92.             Undefined, half of the system's memory)
  94.         --home <home>
  95.             Directory where ActiveMQ Artemis is installed
  97.         --host <host>
  98.             The host name of the broker (Default: 0.0.0.0 or input if clustered)
  100.         --http-host <httpHost>
  101.             The host name to use for embedded web server (Default: localhost)
  103.         --http-port <httpPort>
  104.             The port number to use for embedded web server (Default: 8161)
  106.         --java-options <javaOptions>
  107.             Extra java options to be passed to the profile
  109.         --jdbc
  110.             It will activate jdbc
  112.         --jdbc-bindings-table-name <jdbcBindings>
  113.             Name of the jdbc bindigns table
  115.         --jdbc-connection-url <jdbcURL>
  116.             The connection used for the database
  118.         --jdbc-driver-class-name <jdbcClassName>
  119.             JDBC driver classname
  121.         --jdbc-large-message-table-name <jdbcLargeMessages>
  122.             Name of the large messages table
  124.         --jdbc-lock-expiration <jdbcLockExpiration>
  125.             Lock expiration
  127.         --jdbc-lock-renew-period <jdbcLockRenewPeriod>
  128.             Lock Renew Period
  130.         --jdbc-message-table-name <jdbcMessages>
  131.             Name of the jdbc messages table
  133.         --jdbc-network-timeout <jdbcNetworkTimeout>
  134.             Network timeout
  136.         --jdbc-node-manager-table-name <jdbcNodeManager>
  137.             Name of the jdbc node manager table
  139.         --jdbc-page-store-table-name <jdbcPageStore>
  140.             Name of the page store messages table
  142.         --journal-device-block-size <journalDeviceBlockSize>
  143.             The block size by the device, default at 4096.
  145.         --mapped
  146.             Sets the journal as mapped.
  148.         --max-hops <maxHops>
  149.             Number of hops on the cluster configuration
  151.         --message-load-balancing <messageLoadBalancing>
  152.             Load balancing policy on cluster. [ON_DEMAND (default) | STRICT |
  153.             OFF]
  155.         --name <name>
  156.             The name of the broker (Default: same as host)
  158.         --nio
  159.             Sets the journal as nio.
  161.         --no-amqp-acceptor
  162.             Disable the AMQP specific acceptor.
  164.         --no-autocreate
  165.             Disable Auto create addresses.
  167.         --no-autotune
  168.             Disable auto tuning on the journal.
  170.         --no-fsync
  171.             Disable usage of fdatasync (channel.force(false) from java nio) on
  172.             the journal
  174.         --no-hornetq-acceptor
  175.             Disable the HornetQ specific acceptor.
  177.         --no-mqtt-acceptor
  178.             Disable the MQTT specific acceptor.
  180.         --no-stomp-acceptor
  181.             Disable the STOMP specific acceptor.
  183.         --no-web
  184.             Remove the web-server definition from bootstrap.xml
  186.         --paging
  187.             Page messages to disk when address becomes full, opposite of
  188.             --blocking (Default: true)
  190.         --password <password>
  191.             The user's password (Default: input)
  193.         --ping <ping>
  194.             A comma separated string to be passed on to the broker config as
  195.             network-check-list. The broker will shutdown when all these
  196.             addresses are unreachable.
  198.         --port-offset <portOffset>
  199.             Off sets the ports of every acceptor
  201.         --queues <queues>
  202.             Comma separated list of queues with the option to specify a routing
  203.             type. (ex: --queues myqueue,mytopic:multicast)
  205.         --relax-jolokia
  206.             disable strict checking on jolokia-access.xml
  208.         --replicated
  209.             Enable broker replication
  211.         --require-login
  212.             This will configure security to require user / password, opposite of
  213.             --allow-anonymous
  215.         --role <role>
  216.             The name for the role created (Default: amq)
  218.         --security-manager <securityManager>
  219.             Which security manager to use - jaas or basic (Default: jaas)
  221.         --shared-store
  222.             Enable broker shared store
  224.         --silent
  225.             It will disable all the inputs, and it would make a best guess for
  226.             any required input
  228.         --slave
  229.             Valid for shared store or replication: this is a slave server?
  231.         --ssl-key <sslKey>
  232.             The key store path for embedded web server
  234.         --ssl-key-password <sslKeyPassword>
  235.             The key store password
  237.         --ssl-trust <sslTrust>
  238.             The trust store path in case of client authentication
  240.         --ssl-trust-password <sslTrustPassword>
  241.             The trust store password
  243.         --staticCluster <staticNode>
  244.             Cluster node connectors list, separated by comma: Example
  245.             "tcp://server:61616,tcp://server2:61616,tcp://server3:61616"
  247.         --use-client-auth
  248.             If the embedded server requires client authentication
  250.         --user <user>
  251.             The username (Default: input)
  253.         --verbose
  254.             Adds more information on the execution
  256.         --
  257.             This option can be used to separate command-line options from the
  258.             list of argument, (useful when arguments might be mistaken for
  259.             command-line options
  261.         <directory>
  262.             The instance directory to hold the broker's configuration and data.
  263.             Path must be writable.

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

  1. ./artemis create /usr/server
  2. Creating ActiveMQ Artemis instance at: /user/server
  4. --user: is a mandatory property!
  5. Please provide the default username:
  6. admin
  8. --password: is mandatory with this configuration:
  9. Please provide the default password:
  12. --allow-anonymous | --require-login: is a mandatory property!
  13. Allow anonymous access?, valid values are Y,N,True,False
  14. y
  16. Auto tuning journal ...
  17. done! Your system can make 0.34 writes per millisecond, your journal-buffer-timeout will be 2956000
  19. You can now start the broker by executing:
  21.    "/user/server/bin/artemis" run
  23. Or you can run the broker in the background using:
  25.    "/user/server/bin/artemis-service" 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:

  1. /var/lib/mybroker/bin/artemis run

Now that the broker is running, you can optionally run some of the included examples to verify the broker is running properly.

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

  1. /var/lib/mybroker/bin/artemis stop

Please note that Apache ActiveMQ Artemis requires a Java 8 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.

Library Path

If you’re using the 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 libaio chapter.

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.

Bootstrap configuration file

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

  1. <broker xmlns="http://activemq.org/schema">
  3.    <jaas-security domain="activemq"/>
  5.    <server configuration="file:/path/to/broker.xml"/>
  7.    <web bind="http://localhost:8161" path="web">
  8.       <app url="activemq-branding" war="activemq-branding.war"/>
  9.       <app url="artemis-plugin" war="artemis-plugin.war"/>
  10.       <app url="console" war="console.war"/>
  11.    </web>
  12. </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 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 here.

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:

  1. <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:

  1.  $ ./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.

Adding Runtime Dependencies

Runtime dependencies like diverts, 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 or in the lib directory of the broker instance. 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.