{"owner":"eclipse-mosquitto","repo":"mosquitto","hasSkills":true,"totalSkillsCount":6,"totalTokensCount":5250,"categories":["plugin-manifest","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":["plugins/dynamic-security/README.md","www/pages/documentation/plugins/acl-file.md","www/pages/documentation/plugins/sparkplug-aware.md","plugins/sparkplug-aware/README.md","www/pages/documentation/plugins/password-file.md","plugins/README.md"],"skills":{"plugins/dynamic-security/README.md":"# Mosquitto Dynamic Security\n\nThis document describes a topic based mechanism for controlling security in\nMosquitto. JSON commands are published to topics like `$CONTROL/<feature>/v1`\n\n## Clients\n\nWhen a client connects to Mosquitto, it can optionally provide a username. The\nusername maps the client instance to a client on the broker, if it exists.\nMultiple clients can make use of the same username, and hence the same broker\nclient.\n\n## Groups\n\nBroker clients can be defined as belonging to zero or more broker groups.\n\n## Roles\n\nRoles can be applied to a client or a group, and define what that client/group\nis allowed to do, for example what topics it may or may not publish or\nsubscribe to.\n\n## Commands\n\n### Set default ACL access\n\nSets the default access behaviour for the different ACL types, assuming there\nare no matching ACLs for a topic.\n\nBy default, publishClientSend and subscribe default to deny, and\npublishClientReceive and unsubscribe default to allow.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setDefaultACLAccess\",\n\t\t\t\"acls\":[\n\t\t\t\t{ \"acltype\": \"publishClientSend\", \"allow\": false },\n\t\t\t\t{ \"acltype\": \"publishClientReceive\", \"allow\": true },\n\t\t\t\t{ \"acltype\": \"subscribe\", \"allow\": false },\n\t\t\t\t{ \"acltype\": \"unsubscribe\", \"allow\": true }\n\t\t\t]\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setDefaultACLAccess subscribe deny\n```\n\n### Get default ACL access\n\nGets the default access behaviour for the different ACL types.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getDefaultACLAccess\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getDefaultACLAccess\n```\n\n## Create Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createClient\",\n\t\t\t\"username\": \"new username\",\n\t\t\t\"password\": \"new password\",\n\t\t\t\"clientid\": \"\", # Optional\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"groups\": [\n\t\t\t\t{ \"groupname\": \"group\", \"priority\": 1 }\n\t\t\t], # Optional, groups must exist\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": -1 }\n\t\t\t] # Optional, roles must exist\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createClient username password\n```\n\n## Delete Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteClient\",\n\t\t\t\"username\": \"username to delete\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteClient username\n```\n\n## Enable Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"enableClient\",\n\t\t\t\"username\": \"username to enable\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec enableClient username\n```\n\n## Disable Client\n\nStop a client from being able to log in, and kick any clients with matching\nusername that are currently connected.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"disableClient\",\n\t\t\t\"username\": \"username to disable\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec disableClient username\n```\n\n## Get Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getClient\",\n\t\t\t\"username\": \"required username\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getClient username\n```\n\n## List Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listClients\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listClients 10 20\n```\n\n## Modify Existing Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyClient\",\n\t\t\t\"username\": \"username to modify\"\n\t\t\t\"clientid\": \"new clientid, or empty string to clear\", # Optional\n\t\t\t\"password\": \"new password\", # Optional\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t\t\"groups\": [\n\t\t\t\t{ \"groupname\": \"group\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t}\n\t]\n}\n```\n\nModifying clients isn't currently possible with mosquitto_ctrl.\n\n## Set Client id\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setClientId\",\n\t\t\t\"username\": \"username to change\",\n\t\t\t\"clientid\": \"new clientid\" # Optional, if blank or missing then client id will be removed.\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setClientId username clientId\n```\n\n## Set Client Password\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setClientPassword\",\n\t\t\t\"username\": \"username to change\",\n\t\t\t\"password\": \"new password\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setClientPassword username password\n```\n\n## Add Client Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addClientRole\",\n\t\t\t\"username\": \"client to add role to\",\n\t\t\t\"rolename\": \"role to add\",\n\t\t\t\"priority\": -1 # Optional priority\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addClientRole username rolename\n```\n\n## Remove Client Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeClientRole\",\n\t\t\t\"username\": \"client to remove role from\",\n\t\t\t\"rolename\": \"role to remove\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeClientRole username rolename\n```\n\n## Add Client to a Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addGroupClient\",\n\t\t\t\"groupname\": \"group to add client to\",\n\t\t\t\"username\": \"client to add to group\",\n\t\t\t\"priority\": -1 # Priority of the group for the client\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addGroupClient groupname username\n```\n\n## Create Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createGroup\",\n\t\t\t\"groupname\": \"new group\",\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t] # Optional, roles must exist\n\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createGroup groupname\n```\n\n## Delete Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteGroup\",\n\t\t\t\"groupname: \"group to delete\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteGroup groupname\n```\n\n## Get Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getGroup\",\n\t\t\t\"groupname: \"group to get\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getGroup groupname\n```\n\n## List Groups\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listGroups\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listGroups\n```\n\n## Modify Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyGroup\",\n\t\t\t\"groupname\": \"group to modify\",\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t\t\"clients\": [\n\t\t\t\t{ \"username\": \"client\", \"priority\": 1 }\n\t\t\t] # Optional\n\n\t\t}\n\t]\n}\n```\n\nModifying groups isn't currently possible with mosquitto_ctrl.\n\n## Remove Client from a Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeGroupClient\",\n\t\t\t\"groupname\": \"group to remove client from\",\n\t\t\t\"username\": \"client to remove from group\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeGroupClient groupname username\n```\n\n## Add Group Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addGroupRole\",\n\t\t\t\"groupname\": \"group to add role to\",\n\t\t\t\"rolename\": \"role to add\",\n\t\t\t\"priority\": -1 # Optional priority\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addGroupRole groupname rolename\n```\n\n## Remove Group Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeGroupRole\",\n\t\t\t\"groupname\": \"group\",\n\t\t\t\"rolename\": \"role\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeGroupRole groupname rolename\n```\n\n## Set Group for Anonymous Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setAnonymousGroup\",\n\t\t\t\"groupname\": \"group\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setAnonymousGroup groupname\n```\n\n## Get Group for Anonymous Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getAnonymousGroup\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getAnonymousGroup\n```\n\n## Create Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createRole\",\n\t\t\t\"rolename\": \"new role\",\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"acls\": [\n\t\t\t\t{ \"acltype\": \"subscribePattern\", \"topic\": \"topic/#\", \"priority\": -1, \"allow\": true}\n\t\t\t] # Optional\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createRole rolename\n```\n\n## Get Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getRole\",\n\t\t\t\"rolename\": \"role\",\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getRole rolename\n```\n\n## List Roles\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listRoles\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listRoles\n```\n\n## Modify Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyRole\",\n\t\t\t\"rolename\": \"role to modify\"\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"acls\": [\n\t\t\t\t{ \"acltype\": \"subscribePattern\", \"topic\": \"topic/#\", \"priority\": -1, \"allow\": true }\n\t\t\t] # Optional\n\t\t}\n\t]\n}\n```\n\nModifying roles isn't currently possible with mosquitto_ctrl.\n\n## Delete Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteRole\",\n\t\t\t\"rolename\": \"role\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteRole rolename\n```\n\n## Add Role ACL\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addRoleACL\",\n\t\t\t\"rolename\": \"role\",\n\t\t\t\"acltype\": \"subscribePattern\",\n\t\t\t\"topic\": \"topic/#\",\n\t\t\t\"priority\": -1,\n\t\t\t\"allow\": true\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addRoleACL rolename subscribeLiteral topic/# deny\n```\n\n## Remove Role ACL\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeRoleACL\",\n\t\t\t\"rolename\": \"role\",\n\t\t\t\"acltype\": \"subscribePattern\",\n\t\t\t\"topic\": \"topic/#\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeRoleACL rolename subscribeLiteral topic/#\n```\n","www/pages/documentation/plugins/acl-file.md":"<!--\n.. title: ACL file Plugin\n.. slug: acl-file\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\n## Introduction\n\nAvailable since version 2.1.\n\nThis plugin provides the same functionality as the `acl_file` option, and\nshould be the preferred way of using an ACL file.\n\nThe [dynamic-security plugin](/documentation/dynamic-security/) provides a more\npowerful approach to authentication and authorisation.\n\n## Usage\n\nControl access to topics on the broker using an access control list file. If\nthis parameter is defined then only the topics listed will have access.  If the\nfirst character of a line of the ACL file is a `#` it is treated as a comment.\n\nTopic access is added with lines of the format:\n\n```\ntopic [read|write|readwrite|deny] <topic>\n```\n\nThe access type is controlled using `read`, `write`, `readwrite` or `deny`.\nThis parameter is optional (unless `<topic>` contains a space character) - if\nnot given then the access is read/write.  `<topic>` can contain the `+` or `#` \nwildcards as in subscriptions.\n\nThe `deny` option can used to explicitly deny access to a topic that would\notherwise be granted by a broader read/write/readwrite statement. Any `deny`\ntopics are handled before topics that grant read/write access.\n\nThe first set of topics are applied to anonymous clients, assuming anonymous\naccess is allowed. User specific topic ACLs are added after a user line as\nfollows:\n\n```\nuser <username>\n```\n\nThe username referred to here is the same as provided in the CONNECT packet. It\nis not the clientid.\n\nIf is also possible to define ACLs based on pattern substitution within the\ntopic.\n\n```\npattern [read|write|readwrite] <topic>\n```\n\nThe patterns available for substitution are:\n\n* %c to match the client id of the client\n* %u to match the username of the client\n\nThe substitution pattern must be the only text for that level of hierarchy.\n\nThe form is the same as for the topic keyword, but using pattern as the\nkeyword.\n\nPattern ACLs apply to all users even if the `user` keyword has previously\nbeen given.\n\nIf using bridges with usernames and ACLs, connection messages can be allowed\nwith the following pattern:\n\n```\npattern write $SYS/broker/connection/%c/state\n```\n\n\nExample:\n\n```\npattern write sensor/%u/data\n```\n\n# Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_acl_file.dll\nplugin_opt_acl_file <my acl file path>\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_acl_file.so\nplugin_opt_acl_file <my acl file path>\n```\n","www/pages/documentation/plugins/sparkplug-aware.md":"<!--\n.. title: Sparkplug Aware Plugin\n.. slug: sparkplug-aware\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\nAvailable since version 2.1.\n\nThe [Sparkplug protocol](https://sparkplug.eclipse.org/) provides a unified way\nto manage topics, device lifetime, and payload format. It is typically intended\nfor use in Industrial Internet of Things applications, such as in factories.\n\nThe Sparkplug specification makes certain requirements on clients and brokers.\nFor brokers there are two levels of conformance: Sparkplug Compliant and\nSparkplug Aware.\n\nAny MQTT broker that conforms to the MQTT v3.1.1 or v5.0 protocol meets the\nrequirements to be Sparkplug Compliant.\n\nA Sparkplug Aware broker also needs to monitor birth messages from Sparkplug\nnodes and devices, and republish them to the appropriate topic within\n`$sparkplug/certificates/spBv1.0/`\n\nLoading this plugin makes provides Sparkplug Aware support for Mosquitto.\n\n## Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_sparkplug_aware.dll\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_sparkplug_aware.so\n```\n","plugins/sparkplug-aware/README.md":"# Mosquitto Sparkplug Aware\n\nThis plugin implements the requirements of the Sparkplug 3.0 specification\n\"awareness\".\n\nIt is not tested with the official TCK, because that is only capable of testing\none brand of broker, and hence it is not possible to validate any other broker.\nSee https://github.com/eclipse-sparkplug/sparkplug/issues/478\n","www/pages/documentation/plugins/password-file.md":"<!--\n.. title: Password file Plugin\n.. slug: password-file\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\n## Introduction\n\nAvailable since version 2.1.\n\nThis plugin provides the same functionality as the `password_file` option, and\nshould be the preferred way of using an password file.\n\nThe [dynamic-security plugin](/documentation/dynamic-security/) provides a more\npowerful approach to authentication and authorisation.\n\n## Usage\n\nGenerate password files using the [mosquitto_passwd](/man/mosquitto_passwd-1.html) utility.\n\n# Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_password_file.dll\nplugin_opt_password_file <my password file path>\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_password_file.so\nplugin_opt_password_file <my password file path>\n```\n","plugins/README.md":"# Plugins\n\nThis directory contains plugins for use with Mosquitto.\n\n## Dynamic security\nThis is a fully functioning plugin that implements authentication and access\ncontrol, with configuration via a $CONTROL topic. See the readme in\ndynamic-security for more information.\n\n## Examples / Add properties\nThis is an **example** plugin that demonstrates adding MQTT v5 properties to\nmessages, and how to get client information.\n\n## Examples / Authenticate by IP address\nThis is an **example** plugin that demonstrates a basic authentication callback\nthat allows clients based on their IP address. Password based authentication is\npreferred over this very simple type of access control.\n\n## Examples / Client lifetime stats\nThis is an **example** plugin that collects counts of how long client sessions\nlast, in different time buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k,\n2k, 5k, 10k, 20k, 50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M,\n500M seconds. It periodically publishes the counts at\n`$SYS/broker/client/lifetimes/<bucket>`.\n\n## Examples / Client properties\nThis is an **example** plugin that demonstrates some of the functions for\nretrieving client information such as client id and username.\n\n## Examples / Connection state\nThis is an **example** plugin to demonstrate the use of the connect and\ndisconnect events. It publishes messages to\n$SYS/broker/connection/client/<client id>/state for every client that connects\nto the broker, to indicate the connection state of that client.\n\n## Examples / Deferred authentication\nThis is an **example** plugin to demonstrate how a plugin can carry out\ndelayed basic authentication. This method should be used where the plugin\nsends an authentication request to an external server so that if there is a\ndelay in getting a response it does not block the broker. The plugin may spawn\nextra threads to handle the authentication requests, but the call to\n`mosquitto_complete_basic_auth()` must happen in the main Mosquitto thread.\n\n## Examples / Message timestamp\nThis is an **example** plugin to demonstrate how it is possible to attach MQTT\nv5 properties to messages after they have been received, and before they are\nsent on to subscribers.\n\nThis plugin attaches a user-property property to each message which contains\nthe ISO-8601 timestamp of the time the message was received by the broker. This\nmeans it is possible for MQTT v5 clients to see how old a retained message is,\nfor example.\n\n## Examples / Payload modification\nThis is an **example** plugin to demonstrate how it is possible to modify the\npayload of messages after they have been received, and before they are sent on\nto subscribers.\n\nIf you are considering using this feature, you should be very certain you have\nverified the payload is the correct format before modifying it.\n\nThis plugin adds the text string \"hello \" to the beginning of each payload, so\nwith anything other than simple plain text messages it will corrupt the payload\ncontents.\n\n## Examples / Payload size stats\nThis is an **example** plugin that collects counts of payload message sizes, in\ntime buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k, 2k, 5k, 10k, 20k,\n50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M, 500M bytes. It\nperiodically publishes the counts at `$SYS/broker/publish/sizes/<bucket>`.\n\n## Examples / Print IP on publish\nThis is an **example** plugin that prints out client ID and IP address of any\nclient that publishes on a particular topic.\n\n## Examples / Topic modification\nThis is an **example** plugin to demonstrate how it is possible to modify the\ntopic of messages after they have been received, and before they are sent on\nto subscribers.\n\nThis plugin removes the `/uplink` end part of topics that match the pattern\n`device/+/data/uplink`, so devices publishing to `device/0001/data/uplink` will\neffectively be publishing to `device/0001/data`.\n\n## Examples / Wildcard temp\nThis is an **example** plugin that denies access to the `#` subscription topic\nonly. This prevents clients from discovering which topics are active and\nreduces outgoing bandwidth. If clients connect with username `wildcard` and\nsubscribes to `#` they will be allowed 20 seconds of access, after which the\nsubscription will be silently removed.\n"},"files":{"plugins/dynamic-security/README.md":"# Mosquitto Dynamic Security\n\nThis document describes a topic based mechanism for controlling security in\nMosquitto. JSON commands are published to topics like `$CONTROL/<feature>/v1`\n\n## Clients\n\nWhen a client connects to Mosquitto, it can optionally provide a username. The\nusername maps the client instance to a client on the broker, if it exists.\nMultiple clients can make use of the same username, and hence the same broker\nclient.\n\n## Groups\n\nBroker clients can be defined as belonging to zero or more broker groups.\n\n## Roles\n\nRoles can be applied to a client or a group, and define what that client/group\nis allowed to do, for example what topics it may or may not publish or\nsubscribe to.\n\n## Commands\n\n### Set default ACL access\n\nSets the default access behaviour for the different ACL types, assuming there\nare no matching ACLs for a topic.\n\nBy default, publishClientSend and subscribe default to deny, and\npublishClientReceive and unsubscribe default to allow.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setDefaultACLAccess\",\n\t\t\t\"acls\":[\n\t\t\t\t{ \"acltype\": \"publishClientSend\", \"allow\": false },\n\t\t\t\t{ \"acltype\": \"publishClientReceive\", \"allow\": true },\n\t\t\t\t{ \"acltype\": \"subscribe\", \"allow\": false },\n\t\t\t\t{ \"acltype\": \"unsubscribe\", \"allow\": true }\n\t\t\t]\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setDefaultACLAccess subscribe deny\n```\n\n### Get default ACL access\n\nGets the default access behaviour for the different ACL types.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getDefaultACLAccess\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getDefaultACLAccess\n```\n\n## Create Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createClient\",\n\t\t\t\"username\": \"new username\",\n\t\t\t\"password\": \"new password\",\n\t\t\t\"clientid\": \"\", # Optional\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"groups\": [\n\t\t\t\t{ \"groupname\": \"group\", \"priority\": 1 }\n\t\t\t], # Optional, groups must exist\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": -1 }\n\t\t\t] # Optional, roles must exist\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createClient username password\n```\n\n## Delete Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteClient\",\n\t\t\t\"username\": \"username to delete\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteClient username\n```\n\n## Enable Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"enableClient\",\n\t\t\t\"username\": \"username to enable\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec enableClient username\n```\n\n## Disable Client\n\nStop a client from being able to log in, and kick any clients with matching\nusername that are currently connected.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"disableClient\",\n\t\t\t\"username\": \"username to disable\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec disableClient username\n```\n\n## Get Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getClient\",\n\t\t\t\"username\": \"required username\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getClient username\n```\n\n## List Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listClients\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listClients 10 20\n```\n\n## Modify Existing Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyClient\",\n\t\t\t\"username\": \"username to modify\"\n\t\t\t\"clientid\": \"new clientid, or empty string to clear\", # Optional\n\t\t\t\"password\": \"new password\", # Optional\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t\t\"groups\": [\n\t\t\t\t{ \"groupname\": \"group\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t}\n\t]\n}\n```\n\nModifying clients isn't currently possible with mosquitto_ctrl.\n\n## Set Client id\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setClientId\",\n\t\t\t\"username\": \"username to change\",\n\t\t\t\"clientid\": \"new clientid\" # Optional, if blank or missing then client id will be removed.\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setClientId username clientId\n```\n\n## Set Client Password\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setClientPassword\",\n\t\t\t\"username\": \"username to change\",\n\t\t\t\"password\": \"new password\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setClientPassword username password\n```\n\n## Add Client Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addClientRole\",\n\t\t\t\"username\": \"client to add role to\",\n\t\t\t\"rolename\": \"role to add\",\n\t\t\t\"priority\": -1 # Optional priority\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addClientRole username rolename\n```\n\n## Remove Client Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeClientRole\",\n\t\t\t\"username\": \"client to remove role from\",\n\t\t\t\"rolename\": \"role to remove\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeClientRole username rolename\n```\n\n## Add Client to a Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addGroupClient\",\n\t\t\t\"groupname\": \"group to add client to\",\n\t\t\t\"username\": \"client to add to group\",\n\t\t\t\"priority\": -1 # Priority of the group for the client\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addGroupClient groupname username\n```\n\n## Create Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createGroup\",\n\t\t\t\"groupname\": \"new group\",\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t] # Optional, roles must exist\n\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createGroup groupname\n```\n\n## Delete Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteGroup\",\n\t\t\t\"groupname: \"group to delete\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteGroup groupname\n```\n\n## Get Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getGroup\",\n\t\t\t\"groupname: \"group to get\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getGroup groupname\n```\n\n## List Groups\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listGroups\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listGroups\n```\n\n## Modify Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyGroup\",\n\t\t\t\"groupname\": \"group to modify\",\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t\t\"clients\": [\n\t\t\t\t{ \"username\": \"client\", \"priority\": 1 }\n\t\t\t] # Optional\n\n\t\t}\n\t]\n}\n```\n\nModifying groups isn't currently possible with mosquitto_ctrl.\n\n## Remove Client from a Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeGroupClient\",\n\t\t\t\"groupname\": \"group to remove client from\",\n\t\t\t\"username\": \"client to remove from group\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeGroupClient groupname username\n```\n\n## Add Group Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addGroupRole\",\n\t\t\t\"groupname\": \"group to add role to\",\n\t\t\t\"rolename\": \"role to add\",\n\t\t\t\"priority\": -1 # Optional priority\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addGroupRole groupname rolename\n```\n\n## Remove Group Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeGroupRole\",\n\t\t\t\"groupname\": \"group\",\n\t\t\t\"rolename\": \"role\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeGroupRole groupname rolename\n```\n\n## Set Group for Anonymous Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setAnonymousGroup\",\n\t\t\t\"groupname\": \"group\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setAnonymousGroup groupname\n```\n\n## Get Group for Anonymous Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getAnonymousGroup\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getAnonymousGroup\n```\n\n## Create Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createRole\",\n\t\t\t\"rolename\": \"new role\",\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"acls\": [\n\t\t\t\t{ \"acltype\": \"subscribePattern\", \"topic\": \"topic/#\", \"priority\": -1, \"allow\": true}\n\t\t\t] # Optional\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createRole rolename\n```\n\n## Get Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getRole\",\n\t\t\t\"rolename\": \"role\",\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getRole rolename\n```\n\n## List Roles\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listRoles\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listRoles\n```\n\n## Modify Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyRole\",\n\t\t\t\"rolename\": \"role to modify\"\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"acls\": [\n\t\t\t\t{ \"acltype\": \"subscribePattern\", \"topic\": \"topic/#\", \"priority\": -1, \"allow\": true }\n\t\t\t] # Optional\n\t\t}\n\t]\n}\n```\n\nModifying roles isn't currently possible with mosquitto_ctrl.\n\n## Delete Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteRole\",\n\t\t\t\"rolename\": \"role\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteRole rolename\n```\n\n## Add Role ACL\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addRoleACL\",\n\t\t\t\"rolename\": \"role\",\n\t\t\t\"acltype\": \"subscribePattern\",\n\t\t\t\"topic\": \"topic/#\",\n\t\t\t\"priority\": -1,\n\t\t\t\"allow\": true\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addRoleACL rolename subscribeLiteral topic/# deny\n```\n\n## Remove Role ACL\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeRoleACL\",\n\t\t\t\"rolename\": \"role\",\n\t\t\t\"acltype\": \"subscribePattern\",\n\t\t\t\"topic\": \"topic/#\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeRoleACL rolename subscribeLiteral topic/#\n```\n","www/pages/documentation/plugins/acl-file.md":"<!--\n.. title: ACL file Plugin\n.. slug: acl-file\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\n## Introduction\n\nAvailable since version 2.1.\n\nThis plugin provides the same functionality as the `acl_file` option, and\nshould be the preferred way of using an ACL file.\n\nThe [dynamic-security plugin](/documentation/dynamic-security/) provides a more\npowerful approach to authentication and authorisation.\n\n## Usage\n\nControl access to topics on the broker using an access control list file. If\nthis parameter is defined then only the topics listed will have access.  If the\nfirst character of a line of the ACL file is a `#` it is treated as a comment.\n\nTopic access is added with lines of the format:\n\n```\ntopic [read|write|readwrite|deny] <topic>\n```\n\nThe access type is controlled using `read`, `write`, `readwrite` or `deny`.\nThis parameter is optional (unless `<topic>` contains a space character) - if\nnot given then the access is read/write.  `<topic>` can contain the `+` or `#` \nwildcards as in subscriptions.\n\nThe `deny` option can used to explicitly deny access to a topic that would\notherwise be granted by a broader read/write/readwrite statement. Any `deny`\ntopics are handled before topics that grant read/write access.\n\nThe first set of topics are applied to anonymous clients, assuming anonymous\naccess is allowed. User specific topic ACLs are added after a user line as\nfollows:\n\n```\nuser <username>\n```\n\nThe username referred to here is the same as provided in the CONNECT packet. It\nis not the clientid.\n\nIf is also possible to define ACLs based on pattern substitution within the\ntopic.\n\n```\npattern [read|write|readwrite] <topic>\n```\n\nThe patterns available for substitution are:\n\n* %c to match the client id of the client\n* %u to match the username of the client\n\nThe substitution pattern must be the only text for that level of hierarchy.\n\nThe form is the same as for the topic keyword, but using pattern as the\nkeyword.\n\nPattern ACLs apply to all users even if the `user` keyword has previously\nbeen given.\n\nIf using bridges with usernames and ACLs, connection messages can be allowed\nwith the following pattern:\n\n```\npattern write $SYS/broker/connection/%c/state\n```\n\n\nExample:\n\n```\npattern write sensor/%u/data\n```\n\n# Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_acl_file.dll\nplugin_opt_acl_file <my acl file path>\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_acl_file.so\nplugin_opt_acl_file <my acl file path>\n```\n","www/pages/documentation/plugins/sparkplug-aware.md":"<!--\n.. title: Sparkplug Aware Plugin\n.. slug: sparkplug-aware\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\nAvailable since version 2.1.\n\nThe [Sparkplug protocol](https://sparkplug.eclipse.org/) provides a unified way\nto manage topics, device lifetime, and payload format. It is typically intended\nfor use in Industrial Internet of Things applications, such as in factories.\n\nThe Sparkplug specification makes certain requirements on clients and brokers.\nFor brokers there are two levels of conformance: Sparkplug Compliant and\nSparkplug Aware.\n\nAny MQTT broker that conforms to the MQTT v3.1.1 or v5.0 protocol meets the\nrequirements to be Sparkplug Compliant.\n\nA Sparkplug Aware broker also needs to monitor birth messages from Sparkplug\nnodes and devices, and republish them to the appropriate topic within\n`$sparkplug/certificates/spBv1.0/`\n\nLoading this plugin makes provides Sparkplug Aware support for Mosquitto.\n\n## Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_sparkplug_aware.dll\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_sparkplug_aware.so\n```\n","plugins/sparkplug-aware/README.md":"# Mosquitto Sparkplug Aware\n\nThis plugin implements the requirements of the Sparkplug 3.0 specification\n\"awareness\".\n\nIt is not tested with the official TCK, because that is only capable of testing\none brand of broker, and hence it is not possible to validate any other broker.\nSee https://github.com/eclipse-sparkplug/sparkplug/issues/478\n","www/pages/documentation/plugins/password-file.md":"<!--\n.. title: Password file Plugin\n.. slug: password-file\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\n## Introduction\n\nAvailable since version 2.1.\n\nThis plugin provides the same functionality as the `password_file` option, and\nshould be the preferred way of using an password file.\n\nThe [dynamic-security plugin](/documentation/dynamic-security/) provides a more\npowerful approach to authentication and authorisation.\n\n## Usage\n\nGenerate password files using the [mosquitto_passwd](/man/mosquitto_passwd-1.html) utility.\n\n# Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_password_file.dll\nplugin_opt_password_file <my password file path>\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_password_file.so\nplugin_opt_password_file <my password file path>\n```\n","plugins/README.md":"# Plugins\n\nThis directory contains plugins for use with Mosquitto.\n\n## Dynamic security\nThis is a fully functioning plugin that implements authentication and access\ncontrol, with configuration via a $CONTROL topic. See the readme in\ndynamic-security for more information.\n\n## Examples / Add properties\nThis is an **example** plugin that demonstrates adding MQTT v5 properties to\nmessages, and how to get client information.\n\n## Examples / Authenticate by IP address\nThis is an **example** plugin that demonstrates a basic authentication callback\nthat allows clients based on their IP address. Password based authentication is\npreferred over this very simple type of access control.\n\n## Examples / Client lifetime stats\nThis is an **example** plugin that collects counts of how long client sessions\nlast, in different time buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k,\n2k, 5k, 10k, 20k, 50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M,\n500M seconds. It periodically publishes the counts at\n`$SYS/broker/client/lifetimes/<bucket>`.\n\n## Examples / Client properties\nThis is an **example** plugin that demonstrates some of the functions for\nretrieving client information such as client id and username.\n\n## Examples / Connection state\nThis is an **example** plugin to demonstrate the use of the connect and\ndisconnect events. It publishes messages to\n$SYS/broker/connection/client/<client id>/state for every client that connects\nto the broker, to indicate the connection state of that client.\n\n## Examples / Deferred authentication\nThis is an **example** plugin to demonstrate how a plugin can carry out\ndelayed basic authentication. This method should be used where the plugin\nsends an authentication request to an external server so that if there is a\ndelay in getting a response it does not block the broker. The plugin may spawn\nextra threads to handle the authentication requests, but the call to\n`mosquitto_complete_basic_auth()` must happen in the main Mosquitto thread.\n\n## Examples / Message timestamp\nThis is an **example** plugin to demonstrate how it is possible to attach MQTT\nv5 properties to messages after they have been received, and before they are\nsent on to subscribers.\n\nThis plugin attaches a user-property property to each message which contains\nthe ISO-8601 timestamp of the time the message was received by the broker. This\nmeans it is possible for MQTT v5 clients to see how old a retained message is,\nfor example.\n\n## Examples / Payload modification\nThis is an **example** plugin to demonstrate how it is possible to modify the\npayload of messages after they have been received, and before they are sent on\nto subscribers.\n\nIf you are considering using this feature, you should be very certain you have\nverified the payload is the correct format before modifying it.\n\nThis plugin adds the text string \"hello \" to the beginning of each payload, so\nwith anything other than simple plain text messages it will corrupt the payload\ncontents.\n\n## Examples / Payload size stats\nThis is an **example** plugin that collects counts of payload message sizes, in\ntime buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k, 2k, 5k, 10k, 20k,\n50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M, 500M bytes. It\nperiodically publishes the counts at `$SYS/broker/publish/sizes/<bucket>`.\n\n## Examples / Print IP on publish\nThis is an **example** plugin that prints out client ID and IP address of any\nclient that publishes on a particular topic.\n\n## Examples / Topic modification\nThis is an **example** plugin to demonstrate how it is possible to modify the\ntopic of messages after they have been received, and before they are sent on\nto subscribers.\n\nThis plugin removes the `/uplink` end part of topics that match the pattern\n`device/+/data/uplink`, so devices publishing to `device/0001/data/uplink` will\neffectively be publishing to `device/0001/data`.\n\n## Examples / Wildcard temp\nThis is an **example** plugin that denies access to the `#` subscription topic\nonly. This prevents clients from discovering which topics are active and\nreduces outgoing bandwidth. If clients connect with username `wildcard` and\nsubscribes to `#` they will be allowed 20 seconds of access, after which the\nsubscription will be silently removed.\n"},"items":[{"name":"acl-file.md","path":"www/pages/documentation/plugins/acl-file.md","rawUrl":"https://raw.githubusercontent.com/eclipse-mosquitto/mosquitto/HEAD/www/pages/documentation/plugins/acl-file.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"<!--\n.. title: ACL file Plugin\n.. slug: acl-file\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\n## Introduction\n\nAvailable since version 2.1.\n\nThis plugin provides the same functionality as the `acl_file` option, and\nshould be the preferred way of using an ACL file.\n\nThe [dynamic-security plugin](/documentation/dynamic-security/) provides a more\npowerful approach to authentication and authorisation.\n\n## Usage\n\nControl access to topics on the broker using an access control list file. If\nthis parameter is defined then only the topics listed will have access.  If the\nfirst character of a line of the ACL file is a `#` it is treated as a comment.\n\nTopic access is added with lines of the format:\n\n```\ntopic [read|write|readwrite|deny] <topic>\n```\n\nThe access type is controlled using `read`, `write`, `readwrite` or `deny`.\nThis parameter is optional (unless `<topic>` contains a space character) - if\nnot given then the access is read/write.  `<topic>` can contain the `+` or `#` \nwildcards as in subscriptions.\n\nThe `deny` option can used to explicitly deny access to a topic that would\notherwise be granted by a broader read/write/readwrite statement. Any `deny`\ntopics are handled before topics that grant read/write access.\n\nThe first set of topics are applied to anonymous clients, assuming anonymous\naccess is allowed. User specific topic ACLs are added after a user line as\nfollows:\n\n```\nuser <username>\n```\n\nThe username referred to here is the same as provided in the CONNECT packet. It\nis not the clientid.\n\nIf is also possible to define ACLs based on pattern substitution within the\ntopic.\n\n```\npattern [read|write|readwrite] <topic>\n```\n\nThe patterns available for substitution are:\n\n* %c to match the client id of the client\n* %u to match the username of the client\n\nThe substitution pattern must be the only text for that level of hierarchy.\n\nThe form is the same as for the topic keyword, but using pattern as the\nkeyword.\n\nPattern ACLs apply to all users even if the `user` keyword has previously\nbeen given.\n\nIf using bridges with usernames and ACLs, connection messages can be allowed\nwith the following pattern:\n\n```\npattern write $SYS/broker/connection/%c/state\n```\n\n\nExample:\n\n```\npattern write sensor/%u/data\n```\n\n# Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_acl_file.dll\nplugin_opt_acl_file <my acl file path>\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_acl_file.so\nplugin_opt_acl_file <my acl file path>\n```\n","isInternal":false,"tokens":604,"sizeBytes":2522},{"name":"password-file.md","path":"www/pages/documentation/plugins/password-file.md","rawUrl":"https://raw.githubusercontent.com/eclipse-mosquitto/mosquitto/HEAD/www/pages/documentation/plugins/password-file.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"<!--\n.. title: Password file Plugin\n.. slug: password-file\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\n## Introduction\n\nAvailable since version 2.1.\n\nThis plugin provides the same functionality as the `password_file` option, and\nshould be the preferred way of using an password file.\n\nThe [dynamic-security plugin](/documentation/dynamic-security/) provides a more\npowerful approach to authentication and authorisation.\n\n## Usage\n\nGenerate password files using the [mosquitto_passwd](/man/mosquitto_passwd-1.html) utility.\n\n# Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_password_file.dll\nplugin_opt_password_file <my password file path>\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_password_file.so\nplugin_opt_password_file <my password file path>\n```\n","isInternal":false,"tokens":206,"sizeBytes":839},{"name":"sparkplug-aware.md","path":"www/pages/documentation/plugins/sparkplug-aware.md","rawUrl":"https://raw.githubusercontent.com/eclipse-mosquitto/mosquitto/HEAD/www/pages/documentation/plugins/sparkplug-aware.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"<!--\n.. title: Sparkplug Aware Plugin\n.. slug: sparkplug-aware\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\nAvailable since version 2.1.\n\nThe [Sparkplug protocol](https://sparkplug.eclipse.org/) provides a unified way\nto manage topics, device lifetime, and payload format. It is typically intended\nfor use in Industrial Internet of Things applications, such as in factories.\n\nThe Sparkplug specification makes certain requirements on clients and brokers.\nFor brokers there are two levels of conformance: Sparkplug Compliant and\nSparkplug Aware.\n\nAny MQTT broker that conforms to the MQTT v3.1.1 or v5.0 protocol meets the\nrequirements to be Sparkplug Compliant.\n\nA Sparkplug Aware broker also needs to monitor birth messages from Sparkplug\nnodes and devices, and republish them to the appropriate topic within\n`$sparkplug/certificates/spBv1.0/`\n\nLoading this plugin makes provides Sparkplug Aware support for Mosquitto.\n\n## Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_sparkplug_aware.dll\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_sparkplug_aware.so\n```\n","isInternal":false,"tokens":281,"sizeBytes":1142},{"name":"README.md","path":"plugins/dynamic-security/README.md","rawUrl":"https://raw.githubusercontent.com/eclipse-mosquitto/mosquitto/HEAD/plugins/dynamic-security/README.md","title":"dynamic-security Documentation","category":"plugin-manifest","format":"markdown","content":"# Mosquitto Dynamic Security\n\nThis document describes a topic based mechanism for controlling security in\nMosquitto. JSON commands are published to topics like `$CONTROL/<feature>/v1`\n\n## Clients\n\nWhen a client connects to Mosquitto, it can optionally provide a username. The\nusername maps the client instance to a client on the broker, if it exists.\nMultiple clients can make use of the same username, and hence the same broker\nclient.\n\n## Groups\n\nBroker clients can be defined as belonging to zero or more broker groups.\n\n## Roles\n\nRoles can be applied to a client or a group, and define what that client/group\nis allowed to do, for example what topics it may or may not publish or\nsubscribe to.\n\n## Commands\n\n### Set default ACL access\n\nSets the default access behaviour for the different ACL types, assuming there\nare no matching ACLs for a topic.\n\nBy default, publishClientSend and subscribe default to deny, and\npublishClientReceive and unsubscribe default to allow.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setDefaultACLAccess\",\n\t\t\t\"acls\":[\n\t\t\t\t{ \"acltype\": \"publishClientSend\", \"allow\": false },\n\t\t\t\t{ \"acltype\": \"publishClientReceive\", \"allow\": true },\n\t\t\t\t{ \"acltype\": \"subscribe\", \"allow\": false },\n\t\t\t\t{ \"acltype\": \"unsubscribe\", \"allow\": true }\n\t\t\t]\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setDefaultACLAccess subscribe deny\n```\n\n### Get default ACL access\n\nGets the default access behaviour for the different ACL types.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getDefaultACLAccess\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getDefaultACLAccess\n```\n\n## Create Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createClient\",\n\t\t\t\"username\": \"new username\",\n\t\t\t\"password\": \"new password\",\n\t\t\t\"clientid\": \"\", # Optional\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"groups\": [\n\t\t\t\t{ \"groupname\": \"group\", \"priority\": 1 }\n\t\t\t], # Optional, groups must exist\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": -1 }\n\t\t\t] # Optional, roles must exist\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createClient username password\n```\n\n## Delete Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteClient\",\n\t\t\t\"username\": \"username to delete\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteClient username\n```\n\n## Enable Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"enableClient\",\n\t\t\t\"username\": \"username to enable\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec enableClient username\n```\n\n## Disable Client\n\nStop a client from being able to log in, and kick any clients with matching\nusername that are currently connected.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"disableClient\",\n\t\t\t\"username\": \"username to disable\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec disableClient username\n```\n\n## Get Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getClient\",\n\t\t\t\"username\": \"required username\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getClient username\n```\n\n## List Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listClients\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listClients 10 20\n```\n\n## Modify Existing Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyClient\",\n\t\t\t\"username\": \"username to modify\"\n\t\t\t\"clientid\": \"new clientid, or empty string to clear\", # Optional\n\t\t\t\"password\": \"new password\", # Optional\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t\t\"groups\": [\n\t\t\t\t{ \"groupname\": \"group\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t}\n\t]\n}\n```\n\nModifying clients isn't currently possible with mosquitto_ctrl.\n\n## Set Client id\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setClientId\",\n\t\t\t\"username\": \"username to change\",\n\t\t\t\"clientid\": \"new clientid\" # Optional, if blank or missing then client id will be removed.\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setClientId username clientId\n```\n\n## Set Client Password\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setClientPassword\",\n\t\t\t\"username\": \"username to change\",\n\t\t\t\"password\": \"new password\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setClientPassword username password\n```\n\n## Add Client Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addClientRole\",\n\t\t\t\"username\": \"client to add role to\",\n\t\t\t\"rolename\": \"role to add\",\n\t\t\t\"priority\": -1 # Optional priority\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addClientRole username rolename\n```\n\n## Remove Client Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeClientRole\",\n\t\t\t\"username\": \"client to remove role from\",\n\t\t\t\"rolename\": \"role to remove\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeClientRole username rolename\n```\n\n## Add Client to a Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addGroupClient\",\n\t\t\t\"groupname\": \"group to add client to\",\n\t\t\t\"username\": \"client to add to group\",\n\t\t\t\"priority\": -1 # Priority of the group for the client\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addGroupClient groupname username\n```\n\n## Create Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createGroup\",\n\t\t\t\"groupname\": \"new group\",\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t] # Optional, roles must exist\n\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createGroup groupname\n```\n\n## Delete Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteGroup\",\n\t\t\t\"groupname: \"group to delete\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteGroup groupname\n```\n\n## Get Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getGroup\",\n\t\t\t\"groupname: \"group to get\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getGroup groupname\n```\n\n## List Groups\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listGroups\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listGroups\n```\n\n## Modify Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyGroup\",\n\t\t\t\"groupname\": \"group to modify\",\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t\t\"clients\": [\n\t\t\t\t{ \"username\": \"client\", \"priority\": 1 }\n\t\t\t] # Optional\n\n\t\t}\n\t]\n}\n```\n\nModifying groups isn't currently possible with mosquitto_ctrl.\n\n## Remove Client from a Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeGroupClient\",\n\t\t\t\"groupname\": \"group to remove client from\",\n\t\t\t\"username\": \"client to remove from group\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeGroupClient groupname username\n```\n\n## Add Group Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addGroupRole\",\n\t\t\t\"groupname\": \"group to add role to\",\n\t\t\t\"rolename\": \"role to add\",\n\t\t\t\"priority\": -1 # Optional priority\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addGroupRole groupname rolename\n```\n\n## Remove Group Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeGroupRole\",\n\t\t\t\"groupname\": \"group\",\n\t\t\t\"rolename\": \"role\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeGroupRole groupname rolename\n```\n\n## Set Group for Anonymous Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setAnonymousGroup\",\n\t\t\t\"groupname\": \"group\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setAnonymousGroup groupname\n```\n\n## Get Group for Anonymous Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getAnonymousGroup\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getAnonymousGroup\n```\n\n## Create Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createRole\",\n\t\t\t\"rolename\": \"new role\",\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"acls\": [\n\t\t\t\t{ \"acltype\": \"subscribePattern\", \"topic\": \"topic/#\", \"priority\": -1, \"allow\": true}\n\t\t\t] # Optional\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createRole rolename\n```\n\n## Get Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getRole\",\n\t\t\t\"rolename\": \"role\",\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getRole rolename\n```\n\n## List Roles\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listRoles\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listRoles\n```\n\n## Modify Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyRole\",\n\t\t\t\"rolename\": \"role to modify\"\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"acls\": [\n\t\t\t\t{ \"acltype\": \"subscribePattern\", \"topic\": \"topic/#\", \"priority\": -1, \"allow\": true }\n\t\t\t] # Optional\n\t\t}\n\t]\n}\n```\n\nModifying roles isn't currently possible with mosquitto_ctrl.\n\n## Delete Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteRole\",\n\t\t\t\"rolename\": \"role\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteRole rolename\n```\n\n## Add Role ACL\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addRoleACL\",\n\t\t\t\"rolename\": \"role\",\n\t\t\t\"acltype\": \"subscribePattern\",\n\t\t\t\"topic\": \"topic/#\",\n\t\t\t\"priority\": -1,\n\t\t\t\"allow\": true\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addRoleACL rolename subscribeLiteral topic/# deny\n```\n\n## Remove Role ACL\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeRoleACL\",\n\t\t\t\"rolename\": \"role\",\n\t\t\t\"acltype\": \"subscribePattern\",\n\t\t\t\"topic\": \"topic/#\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeRoleACL rolename subscribeLiteral topic/#\n```\n","isInternal":false,"tokens":3049,"sizeBytes":10027},{"name":"README.md","path":"plugins/README.md","rawUrl":"https://raw.githubusercontent.com/eclipse-mosquitto/mosquitto/HEAD/plugins/README.md","title":"plugins Documentation","category":"plugin-manifest","format":"markdown","content":"# Plugins\n\nThis directory contains plugins for use with Mosquitto.\n\n## Dynamic security\nThis is a fully functioning plugin that implements authentication and access\ncontrol, with configuration via a $CONTROL topic. See the readme in\ndynamic-security for more information.\n\n## Examples / Add properties\nThis is an **example** plugin that demonstrates adding MQTT v5 properties to\nmessages, and how to get client information.\n\n## Examples / Authenticate by IP address\nThis is an **example** plugin that demonstrates a basic authentication callback\nthat allows clients based on their IP address. Password based authentication is\npreferred over this very simple type of access control.\n\n## Examples / Client lifetime stats\nThis is an **example** plugin that collects counts of how long client sessions\nlast, in different time buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k,\n2k, 5k, 10k, 20k, 50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M,\n500M seconds. It periodically publishes the counts at\n`$SYS/broker/client/lifetimes/<bucket>`.\n\n## Examples / Client properties\nThis is an **example** plugin that demonstrates some of the functions for\nretrieving client information such as client id and username.\n\n## Examples / Connection state\nThis is an **example** plugin to demonstrate the use of the connect and\ndisconnect events. It publishes messages to\n$SYS/broker/connection/client/<client id>/state for every client that connects\nto the broker, to indicate the connection state of that client.\n\n## Examples / Deferred authentication\nThis is an **example** plugin to demonstrate how a plugin can carry out\ndelayed basic authentication. This method should be used where the plugin\nsends an authentication request to an external server so that if there is a\ndelay in getting a response it does not block the broker. The plugin may spawn\nextra threads to handle the authentication requests, but the call to\n`mosquitto_complete_basic_auth()` must happen in the main Mosquitto thread.\n\n## Examples / Message timestamp\nThis is an **example** plugin to demonstrate how it is possible to attach MQTT\nv5 properties to messages after they have been received, and before they are\nsent on to subscribers.\n\nThis plugin attaches a user-property property to each message which contains\nthe ISO-8601 timestamp of the time the message was received by the broker. This\nmeans it is possible for MQTT v5 clients to see how old a retained message is,\nfor example.\n\n## Examples / Payload modification\nThis is an **example** plugin to demonstrate how it is possible to modify the\npayload of messages after they have been received, and before they are sent on\nto subscribers.\n\nIf you are considering using this feature, you should be very certain you have\nverified the payload is the correct format before modifying it.\n\nThis plugin adds the text string \"hello \" to the beginning of each payload, so\nwith anything other than simple plain text messages it will corrupt the payload\ncontents.\n\n## Examples / Payload size stats\nThis is an **example** plugin that collects counts of payload message sizes, in\ntime buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k, 2k, 5k, 10k, 20k,\n50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M, 500M bytes. It\nperiodically publishes the counts at `$SYS/broker/publish/sizes/<bucket>`.\n\n## Examples / Print IP on publish\nThis is an **example** plugin that prints out client ID and IP address of any\nclient that publishes on a particular topic.\n\n## Examples / Topic modification\nThis is an **example** plugin to demonstrate how it is possible to modify the\ntopic of messages after they have been received, and before they are sent on\nto subscribers.\n\nThis plugin removes the `/uplink` end part of topics that match the pattern\n`device/+/data/uplink`, so devices publishing to `device/0001/data/uplink` will\neffectively be publishing to `device/0001/data`.\n\n## Examples / Wildcard temp\nThis is an **example** plugin that denies access to the `#` subscription topic\nonly. This prevents clients from discovering which topics are active and\nreduces outgoing bandwidth. If clients connect with username `wildcard` and\nsubscribes to `#` they will be allowed 20 seconds of access, after which the\nsubscription will be silently removed.\n","isInternal":false,"tokens":1031,"sizeBytes":4267},{"name":"README.md","path":"plugins/sparkplug-aware/README.md","rawUrl":"https://raw.githubusercontent.com/eclipse-mosquitto/mosquitto/HEAD/plugins/sparkplug-aware/README.md","title":"sparkplug-aware Documentation","category":"plugin-manifest","format":"markdown","content":"# Mosquitto Sparkplug Aware\n\nThis plugin implements the requirements of the Sparkplug 3.0 specification\n\"awareness\".\n\nIt is not tested with the official TCK, because that is only capable of testing\none brand of broker, and hence it is not possible to validate any other broker.\nSee https://github.com/eclipse-sparkplug/sparkplug/issues/478\n","isInternal":false,"tokens":79,"sizeBytes":340}],"systemPromptSnippet":"<yakaai_skills repo=\"eclipse-mosquitto/mosquitto\">\n<!-- File: www/pages/documentation/plugins/acl-file.md (Tokens: ~604 | Category: anthropic-skill) -->\n<!--\n.. title: ACL file Plugin\n.. slug: acl-file\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\n## Introduction\n\nAvailable since version 2.1.\n\nThis plugin provides the same functionality as the `acl_file` option, and\nshould be the preferred way of using an ACL file.\n\nThe [dynamic-security plugin](/documentation/dynamic-security/) provides a more\npowerful approach to authentication and authorisation.\n\n## Usage\n\nControl access to topics on the broker using an access control list file. If\nthis parameter is defined then only the topics listed will have access.  If the\nfirst character of a line of the ACL file is a `#` it is treated as a comment.\n\nTopic access is added with lines of the format:\n\n```\ntopic [read|write|readwrite|deny] <topic>\n```\n\nThe access type is controlled using `read`, `write`, `readwrite` or `deny`.\nThis parameter is optional (unless `<topic>` contains a space character) - if\nnot given then the access is read/write.  `<topic>` can contain the `+` or `#` \nwildcards as in subscriptions.\n\nThe `deny` option can used to explicitly deny access to a topic that would\notherwise be granted by a broader read/write/readwrite statement. Any `deny`\ntopics are handled before topics that grant read/write access.\n\nThe first set of topics are applied to anonymous clients, assuming anonymous\naccess is allowed. User specific topic ACLs are added after a user line as\nfollows:\n\n```\nuser <username>\n```\n\nThe username referred to here is the same as provided in the CONNECT packet. It\nis not the clientid.\n\nIf is also possible to define ACLs based on pattern substitution within the\ntopic.\n\n```\npattern [read|write|readwrite] <topic>\n```\n\nThe patterns available for substitution are:\n\n* %c to match the client id of the client\n* %u to match the username of the client\n\nThe substitution pattern must be the only text for that level of hierarchy.\n\nThe form is the same as for the topic keyword, but using pattern as the\nkeyword.\n\nPattern ACLs apply to all users even if the `user` keyword has previously\nbeen given.\n\nIf using bridges with usernames and ACLs, connection messages can be allowed\nwith the following pattern:\n\n```\npattern write $SYS/broker/connection/%c/state\n```\n\n\nExample:\n\n```\npattern write sensor/%u/data\n```\n\n# Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_acl_file.dll\nplugin_opt_acl_file <my acl file path>\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_acl_file.so\nplugin_opt_acl_file <my acl file path>\n```\n\n<!-- File: www/pages/documentation/plugins/password-file.md (Tokens: ~206 | Category: anthropic-skill) -->\n<!--\n.. title: Password file Plugin\n.. slug: password-file\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\n## Introduction\n\nAvailable since version 2.1.\n\nThis plugin provides the same functionality as the `password_file` option, and\nshould be the preferred way of using an password file.\n\nThe [dynamic-security plugin](/documentation/dynamic-security/) provides a more\npowerful approach to authentication and authorisation.\n\n## Usage\n\nGenerate password files using the [mosquitto_passwd](/man/mosquitto_passwd-1.html) utility.\n\n# Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_password_file.dll\nplugin_opt_password_file <my password file path>\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_password_file.so\nplugin_opt_password_file <my password file path>\n```\n\n<!-- File: www/pages/documentation/plugins/sparkplug-aware.md (Tokens: ~281 | Category: anthropic-skill) -->\n<!--\n.. title: Sparkplug Aware Plugin\n.. slug: sparkplug-aware\n.. date: 2026-01-30 09:00:00 UTC\n.. tags:\n.. category:\n.. link:\n.. description:\n.. type: text\n-->\n\nAvailable since version 2.1.\n\nThe [Sparkplug protocol](https://sparkplug.eclipse.org/) provides a unified way\nto manage topics, device lifetime, and payload format. It is typically intended\nfor use in Industrial Internet of Things applications, such as in factories.\n\nThe Sparkplug specification makes certain requirements on clients and brokers.\nFor brokers there are two levels of conformance: Sparkplug Compliant and\nSparkplug Aware.\n\nAny MQTT broker that conforms to the MQTT v3.1.1 or v5.0 protocol meets the\nrequirements to be Sparkplug Compliant.\n\nA Sparkplug Aware broker also needs to monitor birth messages from Sparkplug\nnodes and devices, and republish them to the appropriate topic within\n`$sparkplug/certificates/spBv1.0/`\n\nLoading this plugin makes provides Sparkplug Aware support for Mosquitto.\n\n## Config\n\nWindows:\n```\nglobal_plugin C:\\Program Files\\Mosquitto\\mosquitto_sparkplug_aware.dll\n```\n\nOther:\n```\nglobal_plugin /path/to/mosquitto_sparkplug_aware.so\n```\n\n<!-- File: plugins/dynamic-security/README.md (Tokens: ~3049 | Category: plugin-manifest) -->\n# Mosquitto Dynamic Security\n\nThis document describes a topic based mechanism for controlling security in\nMosquitto. JSON commands are published to topics like `$CONTROL/<feature>/v1`\n\n## Clients\n\nWhen a client connects to Mosquitto, it can optionally provide a username. The\nusername maps the client instance to a client on the broker, if it exists.\nMultiple clients can make use of the same username, and hence the same broker\nclient.\n\n## Groups\n\nBroker clients can be defined as belonging to zero or more broker groups.\n\n## Roles\n\nRoles can be applied to a client or a group, and define what that client/group\nis allowed to do, for example what topics it may or may not publish or\nsubscribe to.\n\n## Commands\n\n### Set default ACL access\n\nSets the default access behaviour for the different ACL types, assuming there\nare no matching ACLs for a topic.\n\nBy default, publishClientSend and subscribe default to deny, and\npublishClientReceive and unsubscribe default to allow.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setDefaultACLAccess\",\n\t\t\t\"acls\":[\n\t\t\t\t{ \"acltype\": \"publishClientSend\", \"allow\": false },\n\t\t\t\t{ \"acltype\": \"publishClientReceive\", \"allow\": true },\n\t\t\t\t{ \"acltype\": \"subscribe\", \"allow\": false },\n\t\t\t\t{ \"acltype\": \"unsubscribe\", \"allow\": true }\n\t\t\t]\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setDefaultACLAccess subscribe deny\n```\n\n### Get default ACL access\n\nGets the default access behaviour for the different ACL types.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getDefaultACLAccess\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getDefaultACLAccess\n```\n\n## Create Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createClient\",\n\t\t\t\"username\": \"new username\",\n\t\t\t\"password\": \"new password\",\n\t\t\t\"clientid\": \"\", # Optional\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"groups\": [\n\t\t\t\t{ \"groupname\": \"group\", \"priority\": 1 }\n\t\t\t], # Optional, groups must exist\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": -1 }\n\t\t\t] # Optional, roles must exist\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createClient username password\n```\n\n## Delete Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteClient\",\n\t\t\t\"username\": \"username to delete\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteClient username\n```\n\n## Enable Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"enableClient\",\n\t\t\t\"username\": \"username to enable\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec enableClient username\n```\n\n## Disable Client\n\nStop a client from being able to log in, and kick any clients with matching\nusername that are currently connected.\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"disableClient\",\n\t\t\t\"username\": \"username to disable\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec disableClient username\n```\n\n## Get Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getClient\",\n\t\t\t\"username\": \"required username\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getClient username\n```\n\n## List Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listClients\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listClients 10 20\n```\n\n## Modify Existing Client\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyClient\",\n\t\t\t\"username\": \"username to modify\"\n\t\t\t\"clientid\": \"new clientid, or empty string to clear\", # Optional\n\t\t\t\"password\": \"new password\", # Optional\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t\t\"groups\": [\n\t\t\t\t{ \"groupname\": \"group\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t}\n\t]\n}\n```\n\nModifying clients isn't currently possible with mosquitto_ctrl.\n\n## Set Client id\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setClientId\",\n\t\t\t\"username\": \"username to change\",\n\t\t\t\"clientid\": \"new clientid\" # Optional, if blank or missing then client id will be removed.\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setClientId username clientId\n```\n\n## Set Client Password\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setClientPassword\",\n\t\t\t\"username\": \"username to change\",\n\t\t\t\"password\": \"new password\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setClientPassword username password\n```\n\n## Add Client Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addClientRole\",\n\t\t\t\"username\": \"client to add role to\",\n\t\t\t\"rolename\": \"role to add\",\n\t\t\t\"priority\": -1 # Optional priority\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addClientRole username rolename\n```\n\n## Remove Client Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeClientRole\",\n\t\t\t\"username\": \"client to remove role from\",\n\t\t\t\"rolename\": \"role to remove\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeClientRole username rolename\n```\n\n## Add Client to a Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addGroupClient\",\n\t\t\t\"groupname\": \"group to add client to\",\n\t\t\t\"username\": \"client to add to group\",\n\t\t\t\"priority\": -1 # Priority of the group for the client\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addGroupClient groupname username\n```\n\n## Create Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createGroup\",\n\t\t\t\"groupname\": \"new group\",\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t] # Optional, roles must exist\n\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createGroup groupname\n```\n\n## Delete Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteGroup\",\n\t\t\t\"groupname: \"group to delete\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteGroup groupname\n```\n\n## Get Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getGroup\",\n\t\t\t\"groupname: \"group to get\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getGroup groupname\n```\n\n## List Groups\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listGroups\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listGroups\n```\n\n## Modify Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyGroup\",\n\t\t\t\"groupname\": \"group to modify\",\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"roles\": [\n\t\t\t\t{ \"rolename\": \"role\", \"priority\": 1 }\n\t\t\t], # Optional\n\t\t\t\"clients\": [\n\t\t\t\t{ \"username\": \"client\", \"priority\": 1 }\n\t\t\t] # Optional\n\n\t\t}\n\t]\n}\n```\n\nModifying groups isn't currently possible with mosquitto_ctrl.\n\n## Remove Client from a Group\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeGroupClient\",\n\t\t\t\"groupname\": \"group to remove client from\",\n\t\t\t\"username\": \"client to remove from group\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeGroupClient groupname username\n```\n\n## Add Group Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addGroupRole\",\n\t\t\t\"groupname\": \"group to add role to\",\n\t\t\t\"rolename\": \"role to add\",\n\t\t\t\"priority\": -1 # Optional priority\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addGroupRole groupname rolename\n```\n\n## Remove Group Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeGroupRole\",\n\t\t\t\"groupname\": \"group\",\n\t\t\t\"rolename\": \"role\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeGroupRole groupname rolename\n```\n\n## Set Group for Anonymous Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"setAnonymousGroup\",\n\t\t\t\"groupname\": \"group\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec setAnonymousGroup groupname\n```\n\n## Get Group for Anonymous Clients\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getAnonymousGroup\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getAnonymousGroup\n```\n\n## Create Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"createRole\",\n\t\t\t\"rolename\": \"new role\",\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"acls\": [\n\t\t\t\t{ \"acltype\": \"subscribePattern\", \"topic\": \"topic/#\", \"priority\": -1, \"allow\": true}\n\t\t\t] # Optional\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec createRole rolename\n```\n\n## Get Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"getRole\",\n\t\t\t\"rolename\": \"role\",\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec getRole rolename\n```\n\n## List Roles\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"listRoles\",\n\t\t\t\"verbose\": false,\n\t\t\t\"count\": -1, # -1 for all, or a positive integer for a limited count\n\t\t\t\"offset\": 0 # Where in the list to start\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec listRoles\n```\n\n## Modify Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"modifyRole\",\n\t\t\t\"rolename\": \"role to modify\"\n\t\t\t\"textname\": \"\", # Optional\n\t\t\t\"textdescription\": \"\", # Optional\n\t\t\t\"acls\": [\n\t\t\t\t{ \"acltype\": \"subscribePattern\", \"topic\": \"topic/#\", \"priority\": -1, \"allow\": true }\n\t\t\t] # Optional\n\t\t}\n\t]\n}\n```\n\nModifying roles isn't currently possible with mosquitto_ctrl.\n\n## Delete Role\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"deleteRole\",\n\t\t\t\"rolename\": \"role\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec deleteRole rolename\n```\n\n## Add Role ACL\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"addRoleACL\",\n\t\t\t\"rolename\": \"role\",\n\t\t\t\"acltype\": \"subscribePattern\",\n\t\t\t\"topic\": \"topic/#\",\n\t\t\t\"priority\": -1,\n\t\t\t\"allow\": true\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec addRoleACL rolename subscribeLiteral topic/# deny\n```\n\n## Remove Role ACL\n\nCommand:\n```\n{\n\t\"commands\":[\n\t\t{\n\t\t\t\"command\": \"removeRoleACL\",\n\t\t\t\"rolename\": \"role\",\n\t\t\t\"acltype\": \"subscribePattern\",\n\t\t\t\"topic\": \"topic/#\"\n\t\t}\n\t]\n}\n```\n\nmosquitto_ctrl example:\n```\nmosquitto_ctrl dynsec removeRoleACL rolename subscribeLiteral topic/#\n```\n\n<!-- File: plugins/README.md (Tokens: ~1031 | Category: plugin-manifest) -->\n# Plugins\n\nThis directory contains plugins for use with Mosquitto.\n\n## Dynamic security\nThis is a fully functioning plugin that implements authentication and access\ncontrol, with configuration via a $CONTROL topic. See the readme in\ndynamic-security for more information.\n\n## Examples / Add properties\nThis is an **example** plugin that demonstrates adding MQTT v5 properties to\nmessages, and how to get client information.\n\n## Examples / Authenticate by IP address\nThis is an **example** plugin that demonstrates a basic authentication callback\nthat allows clients based on their IP address. Password based authentication is\npreferred over this very simple type of access control.\n\n## Examples / Client lifetime stats\nThis is an **example** plugin that collects counts of how long client sessions\nlast, in different time buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k,\n2k, 5k, 10k, 20k, 50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M,\n500M seconds. It periodically publishes the counts at\n`$SYS/broker/client/lifetimes/<bucket>`.\n\n## Examples / Client properties\nThis is an **example** plugin that demonstrates some of the functions for\nretrieving client information such as client id and username.\n\n## Examples / Connection state\nThis is an **example** plugin to demonstrate the use of the connect and\ndisconnect events. It publishes messages to\n$SYS/broker/connection/client/<client id>/state for every client that connects\nto the broker, to indicate the connection state of that client.\n\n## Examples / Deferred authentication\nThis is an **example** plugin to demonstrate how a plugin can carry out\ndelayed basic authentication. This method should be used where the plugin\nsends an authentication request to an external server so that if there is a\ndelay in getting a response it does not block the broker. The plugin may spawn\nextra threads to handle the authentication requests, but the call to\n`mosquitto_complete_basic_auth()` must happen in the main Mosquitto thread.\n\n## Examples / Message timestamp\nThis is an **example** plugin to demonstrate how it is possible to attach MQTT\nv5 properties to messages after they have been received, and before they are\nsent on to subscribers.\n\nThis plugin attaches a user-property property to each message which contains\nthe ISO-8601 timestamp of the time the message was received by the broker. This\nmeans it is possible for MQTT v5 clients to see how old a retained message is,\nfor example.\n\n## Examples / Payload modification\nThis is an **example** plugin to demonstrate how it is possible to modify the\npayload of messages after they have been received, and before they are sent on\nto subscribers.\n\nIf you are considering using this feature, you should be very certain you have\nverified the payload is the correct format before modifying it.\n\nThis plugin adds the text string \"hello \" to the beginning of each payload, so\nwith anything other than simple plain text messages it will corrupt the payload\ncontents.\n\n## Examples / Payload size stats\nThis is an **example** plugin that collects counts of payload message sizes, in\ntime buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k, 2k, 5k, 10k, 20k,\n50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M, 500M bytes. It\nperiodically publishes the counts at `$SYS/broker/publish/sizes/<bucket>`.\n\n## Examples / Print IP on publish\nThis is an **example** plugin that prints out client ID and IP address of any\nclient that publishes on a particular topic.\n\n## Examples / Topic modification\nThis is an **example** plugin to demonstrate how it is possible to modify the\ntopic of messages after they have been received, and before they are sent on\nto subscribers.\n\nThis plugin removes the `/uplink` end part of topics that match the pattern\n`device/+/data/uplink`, so devices publishing to `device/0001/data/uplink` will\neffectively be publishing to `device/0001/data`.\n\n## Examples / Wildcard temp\nThis is an **example** plugin that denies access to the `#` subscription topic\nonly. This prevents clients from discovering which topics are active and\nreduces outgoing bandwidth. If clients connect with username `wildcard` and\nsubscribes to `#` they will be allowed 20 seconds of access, after which the\nsubscription will be silently removed.\n\n<!-- File: plugins/sparkplug-aware/README.md (Tokens: ~79 | Category: plugin-manifest) -->\n# Mosquitto Sparkplug Aware\n\nThis plugin implements the requirements of the Sparkplug 3.0 specification\n\"awareness\".\n\nIt is not tested with the official TCK, because that is only capable of testing\none brand of broker, and hence it is not possible to validate any other broker.\nSee https://github.com/eclipse-sparkplug/sparkplug/issues/478\n</yakaai_skills>"}