To create a broker, the following information is required:
Table 1. Required broker information
|name||A unique identifier for the broker.|
Specify the following information to change the default behavior:
Table 2. Changing the default behavior
|Admin password||Admin||The password for connecting to a remote broker. This is used with the username.|
|Admin username||Admin||The username for connection to a remote broker. This is used with the password.|
|Data directory||The value of the osgi.instance.area system property or the current directory if the system property has not been set.||The broker needs a location to store configuration data and runtime information, such as publications and subscriptions.|
|Maximum message size||50kb||The maximum message size that will be processed by the broker. The size is specified in kilobytes. If a message is received that exceeds this amount, it will be ignored and an error will be written using the OSGi log service.|
|Maximum number of clients||-1 (unlimited)||The maximum number of simultaneous clients that can be connected to the broker. If a client attempts to connect once the maximum has been reached, it will be refused.|
|Port||1883||The port number the broker listens on for TCPIP connections.|
|Persistence definition||See persistence table below.||The persistence definition holds all the information for how the broker should store its data.|
|Message Expiry Default||180 days||If a message is received by the broker without a message expiry value set, then this default value will be used. The default value means that messages will be expired and thus removed after that time.|
Default persistence information:
Table 3. Default persistence information
|Maximum transaction log size||3000kb (3MB)||The maximum size of the transaction log in kilobytes. See below for further details.|
|Maximum data store size|
|The maximum size of the data store in kilobytes. See below for further details.|
|Minimum data store size||3000kb (3MB)||The minimum size of the data store in kilobytes. See below for further details.|
|Persistence type||Full persistence||See persistence type explanations below for valid options.|
Queuing definition information:
Table 4. Queuing definition information
|Dynamic Queue Creation Enabled||True||Whether or not to allow the creation of dynamic queues.|
|Queue Expiry Enabled||True||Whether or not to allow dynamic queues to be automatically expired.|
|Dynamic Queue Expiry Default||28 days||The default period of inactivity to wait before expiring a dynamic queue.|
|Maximum Depth Default||1000 messages||The default maximum depth for all queues.|
Creating the transaction log
The broker uses a transaction log to hold information about open transactions. An open transaction is created when sending a message to or from an MQTT client and when a transaction is created using a JMS client before it is committed or rolled back.
There are a number of factors on which to base the size of the transaction log. These include the size of the messages being processed, the number of clients connected, and the rate at which messages are sent. The higher these numbers, the larger the size of the transaction log should be.
Creating the data store
The broker uses a data store to hold information about publications and subscriptions. The more publications and subscriptions the broker handles, the more space this store requires. The reason for having a minimum size as well as a maximum size is that there is an overhead when increasing the store size. When the store is first created, it is takes up the minimum size and is then filled, rather than starting off with a zero-size file. It grows as more information needs to be stored. This also ensures that your machine has the capability to create a store this big as the maximum size could be set to a size greater than can be created.
Persistence defines when data is stored to disk. There are three different types of persistence that can be used:
Full persistence provides protection against crashes. Data is constantly saved as messages are processed.Shutdown persistence
Shutdown persistence provides no protection against crashes. Data is saved during a clean shutdown and reloaded at startup.Memory persistence
Memory persistence writes no state to disk. When the micro broker is shutdown, no information is saved.
Which persistence should be used
If data needs to be persisted between stopping and starting the micro broker, you must use shutdown or full persistence. If data needs to be persisted in the event of an abnormal shutdown, you must use full persistence. Another consideration depends on what level the Quality of Service messages are being published. For Quality of Service 0 messages, memory persistence is acceptable; however, if Quality of Service 1 or Quality of Service 2 are being used, the full persistence must be used to assure the delivery of those messages which could be in flight when the micro broker is shutdown.
Parent topic: Creating and starting a broker: XPD621