MQTT Specifications

Introduction

MQTT messages are JSON strings.

MQTT Topic hierarchy

<FlyvemdmManifest>
+- Status
|   +- Version

<1st entity-ID>
+- agent
|  +- <1st Device's serial>
|  |  +- Command/Subscribe
|  |  +- Command/Ping
|  |  +- Command/Geolocate
|  |  +- Command/Lock
|  |  +- Command/Wipe
|  |  +- Command/Inventory
|  |  +- Command/Unenroll
|  |
|  |  +- Status/Ping
|  |  +- Status/Geolocation
|  |  +- Status/Inventory
|  |  +- Status/Install
|  |  +- Status/Unenroll
|  |  +- Status/Task
|  |  +- Status/Online
|  |
|  +- <2nd Device's serial ...>
|  +- <Nth Device's serial >
|
+- fleet
   +- <1st fleet ID>
   |  +- <Policy>
   |     +- <1st policySymbol>
   |     |  +- Task
   |     |     +- <task ID>
   |     +- <2nd policySymbol>
   |     |  +- Task
   |     |     +- <task ID>
   |     +- <Nth policySymbol>
   |        +- Task
   |           +- <task ID>
   |
   |
   +- <2nd fleet ID ...>
   +- <Nth fleet ID>

+- <2nd Entity-ID...>
+- <Nth entity-ID>

MQTT message for policy deployment

There are many policies available. Some may be applied, some not.

When the backend needs to notify a fleet or an agent about new policy settings, the backends send all policies actually applied, in a single message.

Example:

{
   "storageEncryption":"false",
   "taskId":37
}

MQTT messages sent by the backend

Subscription to topics

Subscription to a fleet occurs when a device enrolls, and when an administrator moves a device from a fleet to another.

The database model makes sure a device is assigned to one and only one fleet. However the JSON format in the message allows a possible removal of this constraint in the future.

Sub topic /Command/Subscribe

{
    "subscribe" : [
        {"topic": "topic_1"},
        {"topic": "topic_2"},
        {"topic": "topic_3"}
    ]
}

QoS of the message = 1

Device status policies

Ping query

Sub topic Command/Ping

{
    "query" : "Ping"
}

Expected answer:

Sub topic Status/Ping !

Geolocation query

Sub topic Command/Geolocate

{
    "query" : "Geolocate"
}

Expected answer:

Sub topic Status/Geolocation

{"latitude":48.1054276,"longitude":-1.67820699,"datetime":1476345332}

Note: the datetime is in Unix time format, and must be on UTC timezone for proper save in DB by the backend.

Unenroll query

Sub topic Command/Unenroll

{
    "unenroll": "Now"
}

Expected answer:

Subtopic Status/Unenroll

{
    "unenroll": "unenrolled"
}

Password settings policies

There are several password policies to setup the type of password required on a device and the complexity of the challenge.

Topic: 0/fleet/1/Policy/passwordEnabled/Task/2

{ "passwordEnabled": "true|false", "taskId": "2"},

Topic: 0/fleet/1/Policy/passwordQuality/Task/3

{ "passwordQuality" : "PASSWORD_QUALITY_NUMERIC|PASSWORD_QUALITY_ALPHABETIC|PASSWORD_QUALITY_ALPHANUMERIC|PASSWORD_QUALITY_COMPLEX|PASSWORD_QUALITY_SOMETHING|PASSWORD_QUALITY_UNSPECIFIED", "taskId": "3"},

Topic: 0/fleet/1/Policy/passwordMinLetters/Task/4

{ "passwordMinLetters" : "0|1|2|..", "taskId": "4"},

Topic: 0/fleet/1/Policy/passwordMinLowerCase/Task/5

{ "passwordMinLowerCase" : "0|1|2|..", "taskId": "5"},

Topic: 0/fleet/1/Policy/passwordMinUpperCase/Task/6

{ "passwordMinUpperCase" : "0|1|2|..", "taskId": "6"},

Topic: 0/fleet/1/Policy/passwordMinNonLetter/Task/7

{ "passwordMinNonLetter" : "0|1|2|..", "taskId": "7"},

Topic: 0/fleet/1/Policy/passwordMinNumeric/Task/8

{ "passwordMinNumeric" : "0|1|2|..", "taskId": "8"},

Topic: 0/fleet/1/Policy/passwordMinLength/Task/9

{ "passwordMinLength" : "0|1|2|..", "taskId": "9"},

Topic: 0/fleet/1/Policy/MaximumFailedPasswordsForWipe/Task/10

{ "MaximumFailedPasswordsForWipe" : "0|1|2|..", "taskId": "10"},

Topic: 0/fleet/1/Policy/MaximumTimeToLock/Task/11

{ "MaximumTimeToLock" : "time in MS", "taskId": "11"},

Topic: 0/fleet/1/Policy/passwordMinSymbols/Task/12

{ "passwordMinSymbols" : "0|1|2|..", "taskId": "12"}

Application deployment policies

There are two application deployment policies. One policy actually deploys an application, the other one removes an application. These policies may both apply multiple times on the same fleet target.

The deployment policy retains a remove_on_delete flag. If this flag is set, removal of the deployment policy will create a policy in charge of the deletion of the same application, applied to the same fleet target.

Example

Three deployment policies are applied to a single fleet target

Topic: 0/fleet/1/Policy/deployApp/Task/11

{"deployApp" : "org.fdroid.fdroid", "id" : "1", "version": "18", "taskId": "11"},

Topic: 0/fleet/1/Policy/deployApp/Task/14

{"deployApp" : "com.domain.application", "id" : "42", "version": "2", "taskId": "14"},

Topic: 0/fleet/1/Policy/deployApp/Task/19

{"deployApp" : "com.domain.application", "id" : "5", "version": "42", "taskId": "19"}
One application removal policies is applied to a fleet target

Topic: 0/fleet/1/Policy/removeApp/Task/16

{
   "removeApp" : "org.fdroid.fdroid",
   "taskId": "16"
}

File deployment policies

Example of file deployment policy

Topic: 0/fleet/1/Policy/deployFile/Task/23

{
  "deployFile": "%SDCARD%/path/to/file.ext",
  "version": "18",
  "taskId": "23"
}

Device access policies

Lock a device

To lock a device as soon as possible

{
    "lock": "now"
}

Unlock a device

To unlock a device

{
    "lock": "unlock"
}

Wipe a device

Sub topic /Command/Wipe

{
    "wipe" : "now"
}

QoS of the message = 2

Connectivity policies

3 policies are available, a registered user can choose to apply only some of them. This means the array in the JSON may contain a subset of the JSON array below.

Topic: 0/fleet/1/Policy/disableWifi/Task/25

{
   "disableWifi" : "true|false",
   "taskId": "25"
}

Topic: 0/fleet/1/Policy/disableGPS/Task/27

{
        "disableGPS" : "true|false",
        "taskId": "27"
}

Topic: 0/fleet/1/Policy/disableBluetooth/Task/28

{
        "disableBluetooth" : "true|false",
        "taskId": "28"
}

(Uhuru Mobile) Applications available from the launcher

(specification only, not implemented)

{
    "launcher":
        { "code" : "update|start|unlock",
          "data" : [
            {"name" : "com.android.contacts"},
            {"name" : "com.android.mms"},
            {"name" : "com.android.settings"}
        ]}
}

Property:

  • code: command identifier
  • _start_: starts the application launcher
  • _update_: updates the application launcher
  • _unlock_: unlocks the ‘screen pinning’
  • data: applications’ list
  • _name_: application package to autorise on terminal

Ps1: In the case only one applications is referenced, it will be executed automatically (self-launch)

Ps2: In the case it is an applications’ list, they will be displayed on desk.

MQTT messages sent by a device

FlyveMDM version manifest

This subtopic contains metadata about Flyve MDM published to each device. This is the current version of the backend.

Sub topic /FlyvemdmManifest/Status/Version

{
    "version":"0.6.0"
}

Task status

This subtopic is used by agents to feedback the progress of a policy deployment.

Sub topic /Status/Task/<task ID>

{
        "status": "in progress"
},

The status value may be any string up to 255 chars except the reserved statuses (see below). The status should be a short string. In the future, statuses will be normalized.

Reserved statuses:
  • queued (when a task is created, this value is used to initialize the task status)
  • pushed (when a message is sent by the backend, this value is used to update the status)