Skip to content

Configuration Reference

Jump to bottom Edit New page
Fredrik Wendt edited this page Aug 26, 2017 · 2 revisions

This document describes the options that can be present in the config file specified on the commandline when running coilmq. Note that CoilMQ also has a default config file which will be used for values not explicitly overridden in the specified config file.

The config file can be specified on the commandline when starting CoilMQ. See [Commandline Reference](Commandline Reference) for more.

General Server Configuration

listen_addr

The (IPv4) IP address that the server should bind to; this defaults to 127.0.0.1 (localhost). If you want to bind to all addresses, use 0.0.0.0.

listen_addr = 192.168.1.12

This can also be specified on the commandline. See [Commandline Reference](Commandline Reference).

listen_port

The port that the server will bind to; this defaults to 61613, the standard STOMP port. Change at will.

listen_port = 61613

Logging

CoilMQ uses standard python logging module. The logging configuration sections are can be specified in the config file.

Note that unlike other commandline options, the config file will override the --logfile and --debug commandline options.

See the Python docs on config file format for more details.

If no logging configuration is specified, CoilMQ will default to STDOUT. (Note that for daemons, this will mean there is no logging.)

Debug / Diagnostics

When run in debug mode (--debug commandline option), CoilMQ will start a diagnostic thread that will report (to the configured log) the size of the queues and the number of subscribers for each queue (and probably other things as needs arise).

debug.stats_poll_interval

You can control the frequency (in seconds) of the statistics polling (and reporting) using this parameter. This value is interpreted as a float and can be set to 0 too disable the diagnostic information. (E.g. if you want to run debug logging but do not want to also have diagnostic information output to the logs.)

debug.stats_poll_interval = 10.0

Queue Storage Backend

qstore.factory

Queue storage backend implementation to use.

The value should be a dotted-path to a class or callable, which returns an object implementing coilmq.store.QueueStore.

qstore.factory = coilmq.store.memory.MemoryQueue

Queue storage implementations provided:

  • coilmq.store.memory.MemoryQueue (default) An in-memory queue storage (no persistence).
  • coilmq.store.dbm.make_dbm - Creates a coilmq.store.dbm.DbmQueue from values in config file. Stores in DBM database (uses python shelve module).
  • coilmq.store.sa.make_sa - Creates a coilmq.store.sa.SAQueue object from values in the config file. Stores in a database accessed via SQLAlchemy.

See [Extending Queue Store](Extending Queue Store) for guide to extension.

DBM Store Options

qstore.dbm.data_dir

The path to use for storing the DBM files. The DBM database consists of two files:

  1. a metadata db that holds information about the queues (which frames delivered where, etc.) and
  2. a frames db that just holds stomp frames, keyed by the message id.

qstore.dbm.checkpoint_operations

How many operations (queue/dequeue) to allow between synchronizations of the meatadata db cache to the file on disk. (The frames database is synchronized with every write.)

qstore.dbm.checkpoint_timeout

How long (in seconds) to allow between cache-disk synchronization for the metadata database.

Examples:

qstore.factory = coilmq.store.dbm.make_dbm

qstore.dbm.data_dir = ./data

; sync up every 100 operations (queue/dequeue)
qstore.dbm.checkpoint_operations = 100

; ... or at least every 20 seconds
qstore.dbm.checkpoint_timeout = 20

SQLAlchemy Store Options

In order to use the SQLAlchemy storage, you must also install the optional SQLALchemy dependency. CoilMQ has been tested to work with 0.5.x and 0.6.x versions; what we're doing is really basic.

If configured as the storage engine, SQLAlchemy will attempt to create the database tables on startup (connecting to the database you configure in the config file).

We use the {{{sqlalchemy.engine_from_config()}}} method with the 'qstore.sqlalchemy.' prefix. In practice, this means that you can set any recognized SQLAlchemy parameters in this "namespace" in the config file. Below are some of the common ones.

qstore.sqlalchemy.url

The connection URL to use.

For example:

qstore.sqlalchemy.url = sqlite:///:memory:

qstore.sqlalchemy.echo

Whether to write the queries that are executed to log.

For example:

qstore.sqlalchemy.echo = True

Authentication

CoilMQ supports requiring username and password for users who wish to communicate with your STOMP server.

auth.factory

Implementation to use for authenticating users.

The value should be a dotted-path to a class or callable, which returns an object implementing methods from coilmq.auth.Authenticator.

# The make_simple() function in coilmq.auth.simple module.
auth.factory = coilmq.auth.simple.make_simple

Auth implementations available:

  • coilma.auth.simple.make_simple, factory that returns configured coilmq.auth.simple.SimpleAuthenticator instance.
  • (More coming in 0.2 release)

See [Extending Authenticator](Extending Authenticator) for instructions on how to write your own authenticator implementation.

Simple Auth Options

auth.simple.file

For SimpleAuthenticator (default), this is the "config-style" file from which to read usernames and passwords.

auth.simple.file = coilmq/tests/resources/auth.ini

Config file is expected to contain an [auth] section:

[auth]
username1 = password1
username2 = password2

File is parsed using ConfigParser.RawConfigParser.

Schedulers

CoilMQ supports schedulers which are algorithm implementations that instruct the system on how to prioritize various queues or subscribers within a queue. (Likely that other schedulers could be added in the future too.)

scheduler.subscriber_priority_factory

The algorithm to use when determining which subscriber should be chosen for delivery of messages to a queue (in a queue messages are only delivered to a single "worker" subscriber).

This value should be a dotted-path to a class or callable, which returns an object implementing methods from coilmq.scheduler.SubscriberPriorityScheduler.

Implementations available:

  • coilmq.scheduler.FavorReliableSubscriberScheduler (default)
  • coilmq.scheduler.RandomSubscriberScheduler

scheduler.queue_priority_factory

In situations where the server must choose a single queue from which to dequeue and deliver a message (typically this is when a reliable subscriber acknowledges a previous message), this is the algorithm that should be used to choose which queue to use.

This value should be a dotted-path to a class or callable, which returns an object implementing methods from coilmq.scheduler.QueuePriorityScheduler.

Implementations available:

  • coilmq.scheduler.RandomQueueScheduler (default)

See [Extending Schedulers](Extending Schedulers) for instructions on how to write your own schedulers.

Example Config File

Here is an example configuration file. Note that a sample configuration file and a file containing configuration defaults is also provided in the coilmq.config package.

[coilmq]

listen_addr = 127.0.0.1
listen_port = 61613

; Backend implementation configuration.
; -------------------------------------
; Factories for implementations can be configured by passing a dotted-path.
; This is typically the path to a class or to a callable that returns a configured
; object (that implements the necessary functionality).  The reason to use a callable
; is in cases when the object may need to be initialized with values from the
; app configuration.  (For example, a database storage engine will need to know
; the database connect URI.)

; Configuration backend used for storage
qstore.factory = coilmq.store.memory.MemoryQueue

; Configure some defaults for the DBM store
qstore.dbm.checkpoint_operations = 100
qstore.dbm.checkpoint_timeout = 20

; Configure the scheduler implementations used
scheduler.subscriber_priority_factory = coilmq.scheduler.FavorReliableSubscriberScheduler
scheduler.queue_priority_factory = coilmq.scheduler.RandomQueueScheduler

; Authentication configuration
; auth.factory = coilmq.auth.simple.make_simple
; auth.simple.file = coilmq/tests/resources/auth.ini

[loggers]
keys=root,coilmq

[handlers]
keys=console,file,syslog

[formatters]
keys=threaded,syslog

[logger_root]
level=DEBUG
handlers=console,file,syslog

[logger_coilmq]
level=DEBUG
handlers=console,file,syslog
qualname=coilmq
propagate=0

[handler_console]
class=StreamHandler
level=DEBUG
formatter=threaded
args=(sys.stdout,)

[handler_syslog]
class=handlers.SysLogHandler
level=DEBUG
formatter=syslog
args=('/dev/log',)

[handler_file]
class=FileHandler
level=DEBUG
formatter=threaded
args=('/tmp/coilmq.log', 'w')

[formatter_syslog]
format=[%(threadName)s] %(name)s - %(levelname)s - %(message)s
datefmt= 

[formatter_threaded]
format=%(asctime)s [%(threadName)s] %(name)s - %(levelname)s - %(message)s
datefmt=
Add a custom footer
Add a custom sidebar
Clone this wiki locally