Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

NO-JIRA clarify broker setup/config doc

This commit is contained in:
Justin Bertram 2021-06-15 12:16:11 -05:00 committed by GitHub
parent a8c17fa290
commit 48d489ec42
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 283 additions and 238 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

263
docs/user-manual/en/using-server.md
View File

@ -6,37 +6,32 @@ 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.
For the remainder of this chapter when we talk about the Apache ActiveMQ
Artemis server we mean the Apache ActiveMQ Artemis standalone server, in its
default configuration with a JMS Service enabled.
This document will refer to the full path of the directory where the ActiveMQ
distribution has been extracted to as `${ARTEMIS_HOME}` directory.
distribution has been extracted to as `${ARTEMIS_HOME}`.
## Installation
After downloading the distribution, the following highlights some important
folders on the distribution:
|___ bin
|
|___ examples
| |___ common
| |___ features
| |___ perf
| |___ protocols
|
|___ lib
| |___ client
|
|___ schema
|
|___ web
The following highlights some important folders on the distribution:
```
|___ bin
|
|___ examples
| |___ common
| |___ features
| |___ perf
| |___ protocols
|
|___ lib
| |___ client
|
|___ schema
|
|___ web
|___ api
|___ hacking-guide
|___ migration-guide
|___ user-manual
```
- `bin` - binaries and scripts needed to run ActiveMQ Artemis.
@ -56,15 +51,15 @@ folders on the distribution:
## Creating a Broker Instance
A broker instance is the directory containing all the configuration and runtime
data, such as logs and data files, associated with a broker process. It is
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:
`/var/lib/mybroker`, run the following commands in your command line shell:
```sh
cd /var/lib
@ -74,8 +69,10 @@ ${ARTEMIS_HOME}/bin/artemis create mybroker
A broker instance directory will contain the following sub directories:
- `bin`: holds execution scripts associated with this instance.
- `etc`: hold the instance configuration files
- `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
@ -84,16 +81,15 @@ At this point you may want to adjust the default configuration located in the
### Options
There are several options you can use when creating an instance.
For a full list of updated properties always use:
There are several options you can use when creating an instance. For a full list
of options use the `help` command:
```
$./artemis help create
NAME
$./artemis help create
NAME
artemis create - creates a new broker instance
SYNOPSIS
SYNOPSIS
artemis create [--addresses <addresses>] [--aio] [--allow-anonymous]
[--autocreate] [--blocking] [--cluster-password <clusterPassword>]
[--cluster-user <clusterUser>] [--clustered] [--data <data>]
@ -101,19 +97,31 @@ For a full list of updated properties always use:
[--encoding <encoding>] [--etc <etc>] [--failover-on-shutdown] [--force]
[--global-max-size <globalMaxSize>] [--home <home>] [--host <host>]
[--http-host <httpHost>] [--http-port <httpPort>]
[--java-options <javaOptions>] [--mapped] [--max-hops <maxHops>]
[--message-load-balancing <messageLoadBalancing>] [--name <name>]
[--nio] [--no-amqp-acceptor] [--no-autocreate] [--no-autotune]
[--no-fsync] [--no-hornetq-acceptor] [--no-mqtt-acceptor]
[--no-stomp-acceptor] [--no-web] [--paging] [--password <password>]
[--ping <ping>] [--port-offset <portOffset>] [--queues <queues>]
[--replicated] [--require-login] [--role <role>] [--shared-store]
[--java-options <javaOptions>] [--jdbc]
[--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>] [--mapped]
[--max-hops <maxHops>] [--message-load-balancing <messageLoadBalancing>]
[--name <name>] [--nio] [--no-amqp-acceptor] [--no-autocreate]
[--no-autotune] [--no-fsync] [--no-hornetq-acceptor]
[--no-mqtt-acceptor] [--no-stomp-acceptor] [--no-web] [--paging]
[--password <password>] [--ping <ping>] [--port-offset <portOffset>]
[--queues <queues>] [--relax-jolokia] [--replicated] [--require-login]
[--role <role>] [--security-manager <securityManager>] [--shared-store]
[--silent] [--slave] [--ssl-key <sslKey>]
[--ssl-key-password <sslKeyPassword>] [--ssl-trust <sslTrust>]
[--ssl-trust-password <sslTrustPassword>] [--use-client-auth]
[--user <user>] [--verbose] [--] <directory>
[--ssl-trust-password <sslTrustPassword>] [--staticCluster <staticNode>]
[--use-client-auth] [--user <user>] [--verbose] [--] <directory>
OPTIONS
OPTIONS
--addresses <addresses>
Comma separated list of addresses
@ -155,8 +163,9 @@ For a full list of updated properties always use:
The encoding that text files should use
--etc <etc>
Directory where ActiveMQ configuration is located. Paths can be absolute or
relative to artemis.instance directory ('etc' by default)
Directory where ActiveMQ configuration is located. Paths can be
absolute or relative to artemis.instance directory ('etc' by
default)
--failover-on-shutdown
Valid for shared store: will shutdown trigger a failover? (Default:
@ -184,6 +193,42 @@ For a full list of updated properties always use:
--java-options <javaOptions>
Extra java options to be passed to the profile
--jdbc
It will activate jdbc
--jdbc-bindings-table-name <jdbcBindings>
Name of the jdbc bindigns table
--jdbc-connection-url <jdbcURL>
The connection used for the database
--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
--jdbc-lock-renew-period <jdbcLockRenewPeriod>
Lock Renew Period
--jdbc-message-table-name <jdbcMessages>
Name of the jdbc messages table
--jdbc-network-timeout <jdbcNetworkTimeout>
Network timeout
--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 by the device, default at 4096.
--mapped
Sets the journal as mapped.
@ -241,7 +286,11 @@ For a full list of updated properties always use:
Off sets the ports of every acceptor
--queues <queues>
Comma separated list of queues.
Comma separated list of queues with the option to specify a routing
type. (ex: --queues myqueue,mytopic:multicast)
--relax-jolokia
disable strict checking on jolokia-access.xml
--replicated
Enable broker replication
@ -253,6 +302,9 @@ For a full list of updated properties always use:
--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
@ -275,6 +327,10 @@ For a full list of updated properties always use:
--ssl-trust-password <sslTrustPassword>
The trust store password
--staticCluster <staticNode>
Cluster node connectors list, separated by comma: Example
"tcp://server:61616,tcp://server2:61616,tcp://server3:61616"
--use-client-auth
If the embedded server requires client authentication
@ -292,12 +348,13 @@ For a full list of updated properties always use:
<directory>
The instance directory to hold the broker's configuration and data.
Path must be writable.
```
Some of these properties may be mandatory in certain configurations and the
system may ask you for additional input.
```
Some of these options may be mandatory in certain configurations and the
system may ask you for additional input, e.g.:
```sh
./artemis create /usr/server
Creating ActiveMQ Artemis instance at: /user/server
@ -345,8 +402,7 @@ script, but with the `stop` argument. Example:
/var/lib/mybroker/bin/artemis stop
```
Please note that Apache ActiveMQ Artemis requires a Java 7 or later runtime to
run.
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
@ -356,19 +412,6 @@ 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.
## Server JVM settings
The run scripts set some JVM settings for tuning the garbage collection policy
and heap size. We recommend using a parallel garbage collection algorithm to
smooth out latency and minimise large GC pauses.
By default Apache ActiveMQ Artemis runs in a maximum of 1GiB of RAM. To
increase the memory settings change the `-Xms` and `-Xmx` memory settings as
you would for any Java program.
If you wish to add any more JVM arguments or tune the existing ones, the run
scripts are the place to do it.
## Library Path
If you're using the [Asynchronous IO Journal](libaio.md) on Linux, you need to
@ -381,43 +424,31 @@ 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](libaio.html#runtime-dependencies).
## System properties
Apache ActiveMQ Artemis can take a system property on the command line for
configuring logging.
For more information on configuring logging, please see the section on
[Logging](logging.md).
## Configuration files
The configuration file used to bootstrap the server (e.g. `bootstrap.xml` by
default) references the specific broker 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.
- `broker.xml`. This is the main ActiveMQ configuration file. All the
parameters in this file are described [here](configuration-index.md)
It is also 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.
- `artemis.profile` - system properties and JVM arguments (e.g. `Xmx`, `Xms`,
etc.)
- `artemis-roles.properties` - user/role mapping for the default
[properties-based JAAS login module](security.md#propertiesloginmodule)
- `artemis-users.properties` - user/password for the default
[properties-based JAAS login module](security.md#propertiesloginmodule)
- `bootstrap.xml` - embedded web server, security, location of `broker.xml`
- `broker.xml` - core broker configuration, e.g. acceptors, addresses, queues,
diverts, clustering; [full reference](configuration-index.md).
- `jolokia-access.xml` - [security for Jolokia](https://jolokia.org/reference/html/security.html),
specifically Cross-Origin Resource Sharing (CORS)
- `logging.properties` - [logging config](logging.md) like levels, log files
locations, etc.
- `login.config` - standard Java configuration for JAAS [security](security.md)
- `management.xml` - remote connectivity and [security for JMX MBeans](management.md#role-based-authorisation-for-jmx)
### Bootstrap configuration file
The stand-alone server is basically a set of POJOs which are instantiated by
Airline commands.
The bootstrap file is very simple. Let's take a look at an example:
The `bootstrap.xml` file is very simple. Let's take a look at an example:
```xml
<broker xmlns="http://activemq.org/schema">
@ -434,10 +465,6 @@ The bootstrap file is very simple. Let's take a look at an example:
</broker>
```
- `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.
- `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
@ -445,21 +472,39 @@ The bootstrap file is very simple. Let's take a look at an example:
`security-manager`. See the "Custom Security Manager" section in the
[security chapter](security.md) for more details.
- `web` - Configures an embedded Jetty instance to serve web applications like
the admin console.
- `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 server is contained in
`broker.xml`. This is what the FileConfiguration bean uses to configure the
messaging server.
The configuration for the Apache ActiveMQ Artemis core broker is contained in
`broker.xml`.
There are many attributes which you can configure Apache ActiveMQ Artemis. In
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](configuration-index.md).
configuration file. The different configuration will be explained throughout the
manual or you can refer to the configuration reference [here](configuration-index.md).
## 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