HiveMQ Swarm REST API Service

The HiveMQ Swarm REST API service enables monitoring via the /metrics endpoint and is required for the commander rest mode.

Enable HiveMQ Swarm REST API

To enable the HiveMQ Swarm REST API, set the enabled tag in the HiveMQ Swarm REST configuration to true.

The following example enables the commander in rest mode, enables the REST API, and configures an HTTP listener.

<swarm>
    <commander>
        <mode>rest</mode>
        <agents>
            <agent>
                <host>localhost</host>
                <port>3881</port>
            </agent>
        </agents>
    </commander>

    <rest>
        <enabled>true</enabled>
        <listeners>
            <http>
                <enabled>true</enabled>
                <bindAddress>0.0.0.0</bindAddress>
                <bindPort>8080</bindPort>
            </http>
        </listeners>
    </rest>
</swarm>

HiveMQ Swarm REST API Configuration Options

You can configure listeners for the HiveMQ Swarm REST API service with environment variables, or the config.xml file of your HiveMQ Swarm configuration.

Environment-variable Based REST API Configuration

The following environment variables are available for the HiveMQ Swarm REST API service:

Environment Variables for HTTP Listener Configuration

Variable

Definition

SWARM_REST_LISTENER_{id}_HTTP_ENABLED

Enables the HTTP listener with the specified {id}

SWARM_REST_LISTENER_{id}_HTTP_ADDRESS

The bind address for the HTTP listener with the specified {id}. The default HTTP bind address is 0.0.0.0.

SWARM_REST_LISTENER_{id}_HTTP_PORT

The bind port for the HTTP listener with the specified {id}. The default bind port for HTTP is 8080.

Environment Variables for HTTPS Listener Configuration

Variable

Definition

SWARM_REST_LISTENER_{id}_HTTPS_ENABLED

Enables the HTTPS listener with the specified {id}

SWARM_REST_LISTENER_{id}_HTTPS_ADDRESS

The bind address for the HTTPS listener with the specified {id}. The default HTTPS bind address is 0.0.0.0.

SWARM_REST_LISTENER_{id}_HTTPS_PORT

The bind port for the HTTPS listener with the specified {id}. The default bind port for HTTPS is 9090.

SWARM_REST_LISTENER_{id}_HTTPS_KEYSTORE_PATH

The keystore path for the HTTPS listener with the specified {id}.

SWARM_REST_LISTENER_{id}_HTTPS_KEYSTORE_PASSWORD

The keystore password for the HTTPS listener with the specified {id}.

SWARM_REST_LISTENER_{id}_HTTPS_PRIVATE_KEY_PASSWORD

The private key password for the HTTPS listener with the specified {id}.

SWARM_REST_LISTENER_{id}_HTTPS_TRUSTSTORE_PATH

The truststore path for the HTTPS listener with the specified {id}.

SWARM_REST_LISTENER_{id}_HTTPS_TRUSTSTORE_PASSWORD

The truststore password for the HTTPS listener with the specified {id}.

File-based REST API Configuration

If a listener configuration for the HiveMQ Swarm REST API is not obtained from environment variables, HiveMQ Swarm looks for the configuration in the HiveMQ Swarm config.xml configuration file.

File-based HTTP Listener Configuration

<swarm>
    <rest>
        <enabled>true</enabled>
        <listeners>
            <http>
                <enabled>true</enabled>
                <bindAddress>0.0.0.0</bindAddress>
                <bindPort>8181</bindPort>
            </http>
        </listeners>
    </rest>
</swarm>

File-based HTTPS Listener Configuration

<swarm>
    <rest>
        <enabled>true</enabled>
        <listeners>
            <https>
                <enabled>true</enabled>
                <bindAddress>0.0.0.0</bindAddress>
                <bindPort>8181</bindPort>
                <tls>
                    <keystore>
                        <path>/path/to/keystore.jks</path>
                        <password>keystorePassword</password>
                        <privateKeyPassword>privateKeyPassword</privateKeyPassword>
                    </keystore>
                    <truststore>
                        <path>/path/to/truststore.jks</path>
                        <password>trustStorePassword</password>
                    </truststore>
                </tls>
            </https>
        </listeners>
    </rest>
</swarm>

Next Steps

Familiarize yourself with the HiveMQ Swarm REST API. For more information, see HiveMQ Swarm REST API specification.