Version 4.1 Documentation

Enmasse reference (YAML export/import)

This chapter is a reference for all the options available in enmasse YAML files. For an overview of enmasse, see the enmasse overview page.

REST channels

Key: channel_rest

Name	Required	Description
name	Yes	Unique name of the REST channel
service	Yes	Name of the Zato service that the channel invokes
url_path	Yes	URL path that the channel listens on, e.g. `/api/v1/my-endpoint`
security	---	Name of a security definition to protect the channel with
method	---	HTTP method the channel accepts, e.g. `GET` or `POST` (if omitted, all methods are accepted)
data_format	---	Expected data format of incoming requests (default is `json`)
content_type	---	Content type that the channel expects in incoming requests
content_encoding	---	Content encoding that the channel expects, e.g. `gzip`
timeout	---	Request timeout in seconds
groups	---	List of security group names whose members are allowed to call this channel

channel_rest:
  - name: enmasse.channel.rest.1
    service: demo.ping
    url_path: /enmasse.rest.1

  - name: enmasse.channel.rest.2
    service: demo.ping
    url_path: /enmasse.rest.2
    security: enmasse.basic_auth.1
    data_format: json

More details in the REST channels chapter.

Rate limiting on REST channels

Rate limiting is configured as a nested rate_limiting key inside each channel_rest entry. It is a list of rules, evaluated top to bottom. The first rule whose address list matches the client IP is used. Within each rule, time ranges are checked in order, and the all-day default applies when no specific time range matches.

Each rule contains:

Name	Required	Description
cidr_list	---	List of IP addresses or ranges, e.g. `10.0.0.0/8` or `192.168.1.10`. If empty, the rule matches all clients.
time_range	Yes	List of time range entries (see below). The first entry must be the all-day default (`is_all_day: true`).

Each time range entry contains:

Name	Required	Description
is_all_day	Yes	`true` for the all-day default, `false` for a specific time range
time_from	---	Start time in `HH:MM` format (required when `is_all_day` is `false`)
time_to	---	End time in `HH:MM` format (required when `is_all_day` is `false`)
disabled	Yes	If `true`, the time range is skipped during evaluation
disallowed	Yes	If `true`, matching requests are silently dropped at the TCP level
rate	Yes	Requests per second (sustained)
burst	Yes	Maximum burst size before throttling
limit	Yes	Hard cap on total requests within the time unit
limit_unit	Yes	Time unit for the hard cap - one of `second`, `minute`, `hour`, `day`, `month`

channel_rest:

  # Simple channel with 200 requests per minute, burst up to 50/s
  - name: crm.customer.get
    service: crm.customer.get-details
    url_path: /api/v1/customers
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 50
            burst: 50
            limit: 200
            limit_unit: minute

  # Internal IPs get generous limits, everything else is silently dropped
  - name: billing.internal.sync
    service: billing.sync
    url_path: /internal/billing/sync
    rate_limiting:
      - cidr_list:
          - 10.0.0.0/8
          - 172.16.0.0/12
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 100
            burst: 200
            limit: 50000
            limit_unit: hour
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: true
            rate: 0
            burst: 0
            limit: 0
            limit_unit: minute

  # Higher limits during the nightly batch window, stricter during the day
  - name: warehouse.inventory.update
    service: warehouse.inventory.bulk-update
    url_path: /api/v1/inventory
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 20
            burst: 50
            limit: 5000
            limit_unit: hour
          - is_all_day: false
            time_from: "01:00"
            time_to: "03:00"
            disabled: false
            disallowed: false
            rate: 200
            burst: 500
            limit: 100000
            limit_unit: hour

  # Block a specific range, allow everyone else at 100/minute
  - name: public.search
    service: search.query
    url_path: /api/v1/search
    rate_limiting:
      - cidr_list:
          - 198.51.100.0/24
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: true
            rate: 0
            burst: 0
            limit: 0
            limit_unit: minute
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 20
            burst: 40
            limit: 100
            limit_unit: minute

  # Strict daily budget - 10,000 requests per day, 10/s sustained
  - name: reports.generate
    service: reports.generate-pdf
    url_path: /api/v1/reports
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 10
            burst: 20
            limit: 10000
            limit_unit: day

For a full explanation of all rate limiting concepts, see the Rate limiting and firewall chapter.

Outgoing REST connections

Key: outgoing_rest

Name	Required	Description
name	Yes	Unique name of the outgoing connection
host	Yes	Base host URL of the remote endpoint, e.g. `https://api.example.com`
url_path	Yes	URL path appended to the host when making requests, e.g. `/v1/endpoint`
security	---	Name of a security definition to use when connecting
data_format	---	Data format of outgoing requests (default is `json`)
timeout	---	Request timeout in seconds (default is `60`)
ping_method	---	HTTP method used to ping the connection (default is `GET`)
pool_size	---	Size of the connection pool (default is `20`)
tls_verify	---	Whether to verify the remote TLS certificate (default is `true`)
content_type	---	Content type header sent with outgoing requests
content_encoding	---	Content encoding header sent with outgoing requests

outgoing_rest:
  - name: enmasse.outgoing.rest.1
    host: https://example.com
    url_path: /api/v1
    data_format: json
    timeout: 60

  - name: enmasse.outgoing.rest.2
    host: https://example.com
    url_path: /api/v2
    security: enmasse.bearer_token.1
    tls_verify: false

Outgoing SOAP connections

Key: outgoing_soap

Name	Required	Description
name	Yes	Unique name of the outgoing connection
host	Yes	Base host URL of the remote endpoint, e.g. `https://api.example.com`
url_path	Yes	URL path appended to the host when making requests, e.g. `/v1/endpoint`
security	---	Name of a security definition to use when connecting
soap_action	---	SOAP action header sent with requests
soap_version	---	SOAP protocol version (default is `1.1`)
data_format	---	Data format of outgoing requests
timeout	---	Request timeout in seconds (default is `60`)
ping_method	---	HTTP method used to ping the connection (default is `GET`)
pool_size	---	Size of the connection pool (default is `20`)
tls_verify	---	Whether to verify the remote TLS certificate (default is `true`)
content_type	---	Content type header sent with outgoing requests
content_encoding	---	Content encoding header sent with outgoing requests

outgoing_soap:
  - name: enmasse.outgoing.soap.1
    host: https://example.com
    url_path: /SOAP
    security: enmasse.ntlm.1
    soap_action: urn:microsoft-dynamics-schemas/page/example:Create
    soap_version: "1.1"
    tls_verify: false
    timeout: 20

More details in the Python SOAP chapter.

Security definitions

Key: security

basic_auth

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `basic_auth`
username	Yes	Username
password	---	Password - can be set via an environment variable
realm	---	HTTP Basic Auth realm (default is `zato`)
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.basic_auth.1
    type: basic_auth
    username: enmasse.1
    password: Zato_Enmasse_Env.BasicAuth1

apikey

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `apikey`
password	---	The API key value - can be set via an environment variable
header	---	Name of the HTTP header that carries the API key (default is `X-API-Key`)
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.apikey.1
    type: apikey
    username: enmasse.1
    password: Zato_Enmasse_Env.EnmasseApiKey1

ntlm

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `ntlm`
username	Yes	Username, typically in `DOMAIN\user` format
password	---	Password - can be set via an environment variable
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.ntlm.1
    type: ntlm
    username: enmasse\\user
    password: Zato_Enmasse_Env.NTLMPassword

bearer_token

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `bearer_token`
username	Yes	Client ID used to obtain the token
auth_endpoint	Yes	URL of the token endpoint
password	---	Client secret - can be set via an environment variable
grant_type	---	OAuth grant type (default is `client_credentials`)
client_id_field	---	Name of the client ID field sent to the token endpoint (default is `client_id`)
client_secret_field	---	Name of the client secret field sent to the token endpoint (default is `client_secret`)
data_format	---	Format of the token request (default is `form`)
extra_fields	---	List of additional fields to include in the token request, e.g. `audience=https://api.example.com`
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.bearer_token.1
    type: bearer_token
    username: enmasse.1
    password: Zato_Enmasse_Env.EnmasseBearerToken1
    auth_endpoint: https://example.com/oauth/token
    client_id_field: username
    client_secret_field: password
    grant_type: password
    data_format: form

  - name: enmasse.bearer_token.2
    type: bearer_token
    username: enmasse.2
    password: Zato_Enmasse_Env.EnmasseBearerToken2
    auth_endpoint: https://example.com/oauth/token
    extra_fields:
      - audience=https://api.example.com

Rate limiting on security definitions

Rate limiting on security definitions uses the same nested rate_limiting key inside each security entry. The rules apply to every channel that uses the definition - the limit follows the credential, not the endpoint. If a partner authenticates to five different channels, they all share one set of counters.

The rule and time range structure is identical to the channel rate limiting section above.

security:

  # Partner gets 1,000 requests per hour across all channels they call
  - name: partner-acme
    type: basic_auth
    username: acme
    password: Zato_Enmasse_Env.AcmePassword
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 20
            burst: 40
            limit: 1000
            limit_unit: hour

  # External vendor limited to 500/day, only from their known IP range
  - name: vendor-logistics
    type: apikey
    password: Zato_Enmasse_Env.LogisticsApiKey
    rate_limiting:
      - cidr_list:
          - 198.51.100.0/24
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 5
            burst: 10
            limit: 500
            limit_unit: day
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: true
            rate: 0
            burst: 0
            limit: 0
            limit_unit: minute

  # Gold tier partner - 50,000 per hour
  - name: partner-gold
    type: basic_auth
    username: gold
    password: Zato_Enmasse_Env.GoldPassword
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 100
            burst: 200
            limit: 50000
            limit_unit: hour

  # Silver tier partner - 5,000 per hour
  - name: partner-silver
    type: basic_auth
    username: silver
    password: Zato_Enmasse_Env.SilverPassword
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 10
            burst: 20
            limit: 5000
            limit_unit: hour

  # Block all access from a compromised API key
  - name: apikey-compromised
    type: apikey
    password: Zato_Enmasse_Env.CompromisedKey
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: true
            rate: 0
            burst: 0
            limit: 0
            limit_unit: minute

  # Internal service account - higher limits during nightly ETL, strict during the day
  - name: etl-service-account
    type: basic_auth
    username: etl
    password: Zato_Enmasse_Env.EtlPassword
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 10
            burst: 20
            limit: 1000
            limit_unit: hour
          - is_all_day: false
            time_from: "00:00"
            time_to: "04:00"
            disabled: false
            disallowed: false
            rate: 200
            burst: 500
            limit: 200000
            limit_unit: hour

For a full explanation of all rate limiting concepts, see the Rate limiting and firewall chapter.

Scheduler jobs

Key: scheduler

At least one interval field (weeks, days, hours, minutes or seconds) must be non-zero.

Name	Required	Description
name	Yes	Unique name of the scheduler job
service	Yes	Name of the Zato service that the job invokes
job_type	Yes	Type of the job - must be `interval_based`
start_date	Yes	Date and time when the job first becomes eligible to run, e.g. `2027-01-01 00:00:00`
is_active	---	Whether the job is active (default is `true`)
weeks	---	Number of weeks between runs (default is `0`)
days	---	Number of days between runs (default is `0`)
hours	---	Number of hours between runs (default is `0`)
minutes	---	Number of minutes between runs (default is `1`)
seconds	---	Number of seconds between runs (default is `0`)
repeats	---	How many times the job should run before stopping (default is unlimited)
extra	---	List of extra lines passed to the service as input

scheduler:
  - name: enmasse.scheduler.1
    service: demo.ping
    job_type: interval_based
    start_date: '2027-01-11 11:23:52'
    seconds: 2
    is_active: true

  - name: enmasse.scheduler.2
    service: demo.ping
    job_type: interval_based
    start_date: '2027-02-19 12:00:00'
    hours: 3

For Python scheduler examples, visit the scheduler examples page.

SQL connections

Key: sql

Name	Required	Description
name	Yes	Unique name of the connection
type	Yes	Database engine type - one of `mysql`, `oracle`, `postgresql` or `mssql`
host	Yes	Database server host
port	Yes	Database server port
db_name	Yes	Name of the database to connect to
username	Yes	Database username
password	---	Database password - can be set via an environment variable
pool_size	---	Size of the connection pool (default is `5`)
extra	---	Extra connection parameters, e.g. `connect_timeout=10`
is_active	---	Whether the connection is active (default is `true`)

sql:
  - name: enmasse.sql.1
    type: mysql
    host: 127.0.0.1
    port: 3306
    db_name: mydb
    username: enmasse.1
    password: Zato_Enmasse_Env.SQL_Password_1

  - name: enmasse.sql.2
    type: mssql
    host: 10.152.81.199
    port: 1433
    db_name: mydb
    username: enmasse.2
    password: Zato_Enmasse_Env.SQL_Password_2
    extra: connect_timeout=10
    pool_size: 10

Database-specific guides: MySQL · PostgreSQL · Oracle · Microsoft SQL Server

Cache

Key: cache

Name	Required	Description
name	Yes	Unique name of the cache
is_active	---	Whether the cache is active (default is `true`)
is_default	---	Whether this is the default cache (default is `false`)
max_size	---	Maximum number of items in the cache (default is `10000`)
max_item_size	---	Maximum size of a single item in bytes (default is `1000000`)
extend_expiry_on_get	---	Whether to extend expiry on each get (default is `true`)
extend_expiry_on_set	---	Whether to extend expiry on each set (default is `false`)
sync_method	---	How the cache is synced to persistent storage (default is `in-background`)
persistent_storage	---	Persistent storage backend (default is `sqlite`)

cache:
  - name: enmasse.cache.builtin.1
    extend_expiry_on_get: true
    extend_expiry_on_set: false

Learn more about Python Redis programming as an alternative caching backend.

Email - IMAP

Key: email_imap

Name	Required	Description
name	Yes	Unique name of the connection
host	Yes	IMAP server host
port	Yes	IMAP server port
username	Yes	Username
password	---	Password - can be set via an environment variable
mode	---	Connection mode, e.g. `ssl` or `plain` (default is `plain`)
timeout	---	Connection timeout in seconds (default is `30`)
debug_level	---	Debug level for the IMAP library (default is `0`)
get_criteria	---	Criteria used to fetch messages (default is `{}`)
is_active	---	Whether the connection is active (default is `true`)

email_imap:
  - name: enmasse.email.imap.1
    host: imap.example.com
    port: 993
    username: enmasse@example.com
    password: Zato_Enmasse_Env.IMAPPassword

Read the Python IMAP email guide, including Microsoft 365 and OAuth2.

Email - SMTP

Key: email_smtp

Name	Required	Description
name	Yes	Unique name of the connection
host	Yes	SMTP server host
port	Yes	SMTP server port
username	---	Username
password	---	Password - can be set via an environment variable
mode	---	Connection mode, e.g. `starttls` or `plain` (default is `plain`)
timeout	---	Connection timeout in seconds (default is `60`)
ping_address	---	Email address used to ping the connection
is_debug	---	Whether to enable debug output (default is `false`)
is_active	---	Whether the connection is active (default is `true`)

email_smtp:
  - name: enmasse.email.smtp.1
    host: smtp.example.com
    port: 587
    username: enmasse@example.com
    password: Zato_Enmasse_Env.SMTPPassword

More details in the Python SMTP email chapter.

LDAP

Key: ldap

Name	Required	Description
name	Yes	Unique name of the connection
username	Yes	Distinguished name (DN) of the user to bind as
server_list	Yes	Comma-separated list of LDAP servers, e.g. `127.0.0.1:389`
auth_type	---	Authentication type, e.g. `NTLM` or `SIMPLE`
password	---	Password - can be set via an environment variable
is_active	---	Whether the connection is active (default is `true`)

ldap:
  - name: enmasse.ldap.1
    username: 'CN=enmasse,OU=testing,OU=Servers,DC=enmasse'
    auth_type: NTLM
    server_list: 127.0.0.1:389
    password: Zato_Enmasse_Env.Enmasse_LDAP_Password

See custom authentication for how to use LDAP credentials in services.

Confluence

Key: confluence

Name	Required	Description
name	Yes	Unique name of the connection
address	Yes	URL of the Confluence instance, e.g. `https://example.atlassian.net`
username	Yes	Username or email address
password	---	API token or password - can be set via an environment variable
api_version	---	Confluence API version (default is `v1`)
is_active	---	Whether the connection is active (default is `true`)

confluence:
  - name: enmasse.confluence.1
    address: https://example.atlassian.net
    username: api_user@example.com
    password: Zato_Enmasse_Env.ConfluenceAPIToken

For calling external APIs in general, see calling external REST APIs.

Jira

Key: jira

Name	Required	Description
name	Yes	Unique name of the connection
address	Yes	URL of the Jira instance, e.g. `https://example.atlassian.net`
username	Yes	Username or email address
password	---	API token or password - can be set via an environment variable
api_version	---	Jira API version (default is `v1`)
is_active	---	Whether the connection is active (default is `true`)

jira:
  - name: enmasse.jira.1
    address: https://example.atlassian.net
    username: enmasse@example.com
    password: Zato_Enmasse_Env.JiraAPIToken

Practical examples are available in the Jira integration examples chapter.

Microsoft 365

Key: microsoft_365

Name	Required	Description
name	Yes	Unique name of the connection
client_id	Yes	Azure application (client) ID
tenant_id	Yes	Azure tenant ID
secret_value	Yes	Client secret - can be set via an environment variable
scopes	---	Space-separated list of OAuth scopes
is_active	---	Whether the connection is active (default is `true`)

microsoft_365:
  - name: enmasse.cloud.microsoft365.1
    client_id: 12345678-1234-1234-1234-123456789abc
    tenant_id: 87654321-4321-4321-4321-cba987654321
    secret_value: Zato_Enmasse_Env.Microsoft365SecretValue
    scopes: Mail.Read Mail.Send

Microsoft 365 IMAP connections are covered in the Python IMAP email guide.

Odoo

Key: odoo

Name	Required	Description
name	Yes	Unique name of the connection
host	Yes	Odoo server host
user	Yes	Odoo username
database	Yes	Name of the Odoo database
port	---	Odoo server port (default is `8069`)
password	---	Password - can be set via an environment variable
protocol	---	Protocol to use (default is `jsonrpc`)
pool_size	---	Size of the connection pool (default is `10`)
is_active	---	Whether the connection is active (default is `true`)

odoo:
  - name: enmasse.odoo.1
    host: odoo.example.com
    port: 8069
    user: admin
    password: Zato_Enmasse_Env.OdooPassword
    database: enmasse_db

Code examples are in the Python Odoo integrations chapter.

Elasticsearch

Key: elastic_search

Name	Required	Description
name	Yes	Unique name of the connection
hosts	Yes	URL or newline-separated list of URLs of Elasticsearch nodes, e.g. `http://elasticsearch:9200`
timeout	---	Request timeout in seconds (default is `90`)
body_as	---	How to send the request body (default is `POST`)
is_active	---	Whether the connection is active (default is `true`)

elastic_search:
  - name: enmasse.elastic.1
    hosts: http://elasticsearch:9200
    timeout: 60
    body_as: json

Usage examples: Python ElasticSearch

Security groups

Key: groups

Each entry defines a named group of security definitions. Groups can then be referenced from REST channels to control access.

Name	Required	Description
name	Yes	Unique name of the group
members	---	List of security definition names that belong to this group

groups:
  - name: enmasse.group.1
    members:
      - enmasse.basic_auth.1
      - enmasse.basic_auth.2
      - enmasse.apikey.1

  - name: enmasse.group.2
    members:
      - enmasse.apikey.1
      - enmasse.apikey.2

Groups are used together with REST channels - see REST channels for details.

OpenAPI channels

Key: channel_openapi

Name	Required	Description
name	Yes	Unique name of the OpenAPI channel
url_path	Yes	URL path where the OpenAPI specification is served, e.g. `/openapi/my-api`
rest_channel_list	---	List of REST channel names to include in the specification
is_active	---	Whether the channel is active (default is `true`)

channel_openapi:
  - name: enmasse.channel.openapi.1
    url_path: /openapi/enmasse-1
    rest_channel_list:
      - enmasse.channel.rest.1
      - enmasse.channel.rest.2

The OpenAPI specifications chapter explains how OpenAPI channels work.

Pub/sub topics

Key: pubsub_topic

Name	Required	Description
name	Yes	Unique name of the topic
description	---	Optional description of the topic
is_active	---	Whether the topic is active (default is `true`)

pubsub_topic:
  - name: enmasse.topic.1
    description: Optional description for topic 1
  - name: enmasse.topic.2

Topics are part of the pub/sub system - the pub/sub API page has more.

Pub/sub permissions

Key: pubsub_permission

Name	Required	Description
security	Yes	Name of the security definition to grant permissions to
pub	---	List of topic name patterns the security definition is allowed to publish to
sub	---	List of topic name patterns the security definition is allowed to subscribe to

pubsub_permission:
  - security: enmasse.basic_auth.1
    pub:
      - enmasse.topic.1
      - enmasse.topic.2
    sub:
      - enmasse.topic.2
      - enmasse.topic.3

  - security: enmasse.basic_auth.2
    pub:
      - enmasse.topic.*
    sub:
      - enmasse.#

For background on pub/sub security, visit pub/sub security.

Pub/sub subscriptions

Key: pubsub_subscription

Name	Required	Description
security	Yes	Name of the security definition that owns the subscription
delivery_type	Yes	How messages are delivered - either `pull` or `push`
topic_list	Yes	List of topic names to subscribe to
push_rest_endpoint	---	Name of an outgoing REST connection to push messages to (required when `delivery_type` is `push` and pushing to a REST endpoint)
push_service	---	Name of a Zato service to push messages to (required when `delivery_type` is `push` and pushing to a service)
max_retry_time	---	How long to retry delivery before giving up, e.g. `365d`, `48h` or `30m`
is_delivery_active	---	Whether delivery is active (default is `true`)

pubsub_subscription:
  - security: enmasse.basic_auth.1
    delivery_type: pull
    max_retry_time: 365d
    topic_list:
      - enmasse.topic.1
      - enmasse.topic.2

  - security: enmasse.basic_auth.2
    delivery_type: push
    push_rest_endpoint: enmasse.outgoing.rest.1
    max_retry_time: 48h
    topic_list:
      - enmasse.topic.1

  - security: enmasse.basic_auth.3
    delivery_type: push
    push_service: demo.input-logger
    max_retry_time: 30m
    topic_list:
      - enmasse.topic.3

Endpoints and subscriptions are explained in the pub/sub endpoints chapter.

The enmasse overview explains how enmasse works and how to use it
This complete DevOps tutorial discusses how to deploy your services and projects