A listener resource represents a listener of a service in MaxScale. All listeners point to a service in MaxScale.
[TOC]
GET /v1/listeners/:name
Get a single listener. The :name in the URI must be the name of a listener in MaxScale.
Status: 200 OK
{
"data": {
"attributes": {
"parameters": {
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"port": 4006,
"protocol": "MariaDBProtocol",
"service": "RW-Split-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca_cert": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "RW-Split-Listener",
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/relationships/services/"
}
}
},
"type": "listeners"
},
"links": {
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/"
}
}
GET /v1/listeners
Get all listeners.
Status: 200 OK
{
"data": [
{
"attributes": {
"parameters": {
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"port": 4008,
"protocol": "MariaDBProtocol",
"service": "Read-Connection-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca_cert": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "Read-Connection-Listener",
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/Read-Connection-Listener/relationships/services/"
}
}
},
"type": "listeners"
},
{
"attributes": {
"parameters": {
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"port": 4006,
"protocol": "MariaDBProtocol",
"service": "RW-Split-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca_cert": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "RW-Split-Listener",
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"links": {
"self": "http://localhost:8989/v1/listeners/"
}
}
POST /v1/listeners
Creates a new listener. The request body must define the following fields.
-
data.id
- Name of the listener
-
data.type
- Type of the object, must be
listeners
- Type of the object, must be
-
data.attributes.parameters.port
ORdata.attributes.parameters.socket
- The TCP port or UNIX Domain Socket the listener listens on. Only one of the fields can be defined.
-
data.relationships.services.data
- The service relationships data, must define a JSON object with an
id
value that defines the service to use and atype
value set toservices
.
- The service relationships data, must define a JSON object with an
The following is the minimal required JSON object for defining a new listener.
{
"data": {
"id": "my-listener",
"type": "listeners",
"attributes": {
"parameters": {
"port": 3306
}
},
"relationships": {
"services": {
"data": [
{"id": "RW-Split-Router", "type": "services"}
]
}
}
}
}
Refer to the Configuration Guide for a full list of listener parameters.
Listener is created:
Status: 204 No Content
PATCH /v1/listeners/:name
The request body must be a JSON object which represents a set of new definitions for the listener.
All parameters marked as modifiable at runtime can be modified. Currently, all
TLS/SSL parameters and the connection_init_sql_file
and sql_mode
parameters
can be modified at runtime.
Parameters that affect the network address or the port the listener listens on cannot be modified at runtime. To modify these parameters, recreate the listener.
Listener is modified:
Status: 204 No Content
DELETE /v1/listeners/:name
The :name must be a valid listener name. When a listener is destroyed, the network port it listens on is available for reuse.
Listener is destroyed:
Status: 204 No Content
Listener cannot be deleted:
Status: 403 Forbidden
PUT /v1/listeners/:name/stop
Stops a started listener. When a listener is stopped, new connections are no longer accepted and are queued until the listener is started again.
This endpoint supports the following parameters:
-
force=yes
- Close all existing connections that were created through this listener.
Listener is stopped:
Status: 204 No Content
PUT /v1/listeners/:name/start
Starts a stopped listener.
Listener is started:
Status: 204 No Content