API Documentation

Documentation for developing SailfishOS applications

Sailfish OS MDM Framework

Mobile device management (MDM) is an important requirement for many use cases, allowing the functionality of a particular device or fleet of devices to be restricted or controlled in a variety of ways or in response to certain events (e.g. in the case of a lost or stolen device).

Sailfish OS provides the Sailfish OS MDM Framework to allow permitted MDM applications to apply restrictive policies or to manually enable, disable, or trigger specific functionality on the device.

Disclaimer! The 2nd party API provided by MDM Framework is still in active development and to some extent subject to change. Normal 3rd party API backward compatibility promises don't hold. Follow Together Jolla release notes and Sailfish OS Developers mailing list to get notified of API changes.

Using the Sailfish OS MDM Framework

There are two separate facets to the Sailfish OS MDM Framework. The first facet consists of policies which define whether the user can modify certain settings or access certain functionality, and is provided by libsailfishpolicy. The second facet consists of specific system functionality which is offered to MDM applications but may or may not be available via other system APIs, and this functionality is provided by libsailfishmdm.

To use these libraries, the MDM application should use the pkgconfig files "sailfishpolicy.pc" and "sailfishmdm.pc" respectively.

e.g. in a qmake-based project:

 CONFIG += link_pkgconfig
 PKGCONFIG += sailfishpolicy sailfishmdm

The APIs are intended to be executed as sailfish-mdm user. As an exception policy state reading with Sailfish OS Policy API can be done with any user.

Sailfish OS Policy API

The Sailfish OS Policy API allows the MDM application to write the current policies defined for specific settings or functionality. For example, the MDM application may want to prevent the user from changing the GPS settings.

There are some well-defined policy types which are fully implemented by libsailfishpolicy (that is, setting a policy value for one of these types will result in specific side-effects occurring on device which enforce the policy). These policy types are exposed via the Sailfish::PolicyValue class, with the Sailfish::AccessPolicy providing convenience API.

Sailfish OS MDM API

The Sailfish OS MDM API allows an MDM application to perform specific actions or trigger specific functionality on the device. For example the MDM application may want to turn on the GPS device so that it can track the current location of the device.

A wide variety of system functionality is offered via the Sailfish OS MDM API, encapsulated by the following classes:

Sailfish::Mdm::Accounts

API to provision accounts

Sailfish::Mdm::Applications

Information on installed applications and packages

Sailfish::Mdm::Autostart

Controls auto-starting of applications

Sailfish::Mdm::BatteryInfo

Battery charge information

Sailfish::Mdm::CallStatistics

Access to phone call statistics

Sailfish::Mdm::Certificates

Manages system CA certificates

Sailfish::Mdm::ConnectivitySettings

Controls network connectivity

Sailfish::Mdm::DateTimeSettings

Controls the system date and time

Sailfish::Mdm::DeviceLock

Controls security codes and device locking

Sailfish::Mdm::LocationInfo

Device location data

Sailfish::Mdm::LocationSettings

Controls device positioning features

Sailfish::Mdm::NetProxy

Controls the network proxy servers in use

Sailfish::Mdm::NetworkDataCounter

Monitors network data usage

Sailfish::Mdm::NotificationInfo

Creates user-visible notifications

Sailfish::Mdm::SecuritySettings

Controls the installation of insecure software

Sailfish::Mdm::SimInfo

Access to SIM card information

Sailfish::Mdm::SimMobileDataFilter

Controls filter rules for mobile data

Sailfish::Mdm::SimSmsFilter

Controls access to SMS features

Sailfish::Mdm::SimVoiceCallFilter

Controls access to voice-call features

Sailfish::Mdm::SoftwareUpdate

Triggers OS software updates

Sailfish::Mdm::SysInfo

Access to device information

Sailfish::AccessPolicyPlugin

Defines an interface for writing an access policy control plugin

WLAN provisioning and network access control is handled through Connman connection manager:

Allowed API and Access

MDM applications are meant to be run with sailfish-mdm user, which means both extra permissions and also extra restrictions on what can be done.

First, there is no access to the user's files under /home/nemo nor D-Bus session bus. This includes also libraries on top of D-Bus such as notifications and dconf. Because of that, user notification support is provided separately by the MDM API.

Second, the MDM application is run on the background without a user-visible UI. If such is needed, there needs to be a separate UI application that communicates with the background daemon. For example, a system or p2p D-Bus can be used for that.

Some environments also require inet group to allow network access. Unlike the nemo user, sailfish-mdm doesn't belong to that group, thus if an MDM application needs to have access, it should have the group included on execution manually. It should be noted that other environments might not include such a group at all.

Creating an MDM Application

An example daemon MDM application and a client which connects to it has been provided, however it is recommended that vendors implement their own MDM application in order be compatible with their own existing services and IT infrastructure.

In most cases, the MDM application will be a fully-fledged, persistent system daemon, started on boot by Systemd, which links against and uses the Sailfish OS MDM Framework libraries directly. Those libraries provide interfaces to allow or disallow actions (via libsailfishpolicy), and other interfaces to allow changing the system state (via libsailfishmdm).

Starting the MDM Application with Systemd

To ensure that the MDM daemon application will be started by Systemd, the MDM application must include a file /lib/systemd/system/mdm-application-name.service in the package and create a symbolic link to it under multi-user.target.wants, as the following example shows:

 [Unit]
 Description=An MDM application
 Requires=basic.target network.target
 After=basic.target network.target

 [Service]
 SupplementaryGroups=inet
 User=sailfish-mdm
 ExecStart=/usr/bin/mdm-application-name
 Restart=always

 [Install]
 WantedBy=multi-user.target

Automating startup on RPM packaging operations can be done on the .spec file as:

 [...]
 %install
 [...]
 mkdir -p %{buildroot}/lib/systemd/system/multi-user.target.wants/
 ln -sf ../mdm-application-name.service %{buildroot}/lib/systemd/system/multi-user.target.wants/

 %post
 if [ "$1" = "1" ]; then
   #install
   systemctl daemon-reload || :
   systemctl start mdm-application-name.service || :
 elif [ "$1" = "2" ]; then
   #upgrade
   systemctl daemon-reload || :
   systemctl restart mdm-application-name.service || :
 fi

 %preun
 if [ "$1" = "0" ]; then
   # remove
   systemctl daemon-reload || :
   systemctl stop mdm-application-name.service || :
 fi

 %files
 /lib/systemd/system/mdm-application-name.service
 /lib/systemd/system/multi-user.target.wants/mdm-application-name.service

MDM Application Files

Any configuration, cache or data files required by the MDM application can be stored under /var or /run as according to the Filesystem Hierarchy Standard, in MDM-application-specific subdirectories.

Specifically, cache data should be stored under /var/cache/, configuration, state data and databases should be stored under /var/lib/, lock files should be stored under /run/lock/, log files should be stored under /var/log/, and temporary files should be stored under /run/tmp/, in MDM-application-specific subdirectories.

We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.