From bfd2802190a0bf15c8551e0369f8ff9d8c997a45 Mon Sep 17 00:00:00 2001 From: Jan-Simon Moeller Date: Tue, 19 Nov 2024 15:56:45 +0100 Subject: Update documentation Update names of images. Remove out-of-date sections and streamline page. Bug-AGL: SPEC- Signed-off-by: Jan-Simon Moeller Change-Id: I140cc290204564c4d1f026b2e975f3ce04e2afb9 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/30528 --- .../Application_Framework/01_Introduction.md | 164 -------------- .../02_Application_Startup.md | 248 --------------------- .../03_Creating_a_New_Application.md | 233 ------------------- .../04_Application_Sandboxing.md | 92 -------- .../images/application_switching.msc | 29 --- .../images/application_switching.png | Bin 31633 -> 0 bytes .../images/start_and_activation.msc | 30 --- .../images/start_and_activation.png | Bin 36479 -> 0 bytes 8 files changed, 796 deletions(-) delete mode 100644 docs/06_Component_Documentation/Application_Framework/01_Introduction.md delete mode 100644 docs/06_Component_Documentation/Application_Framework/02_Application_Startup.md delete mode 100644 docs/06_Component_Documentation/Application_Framework/03_Creating_a_New_Application.md delete mode 100644 docs/06_Component_Documentation/Application_Framework/04_Application_Sandboxing.md delete mode 100755 docs/06_Component_Documentation/Application_Framework/images/application_switching.msc delete mode 100644 docs/06_Component_Documentation/Application_Framework/images/application_switching.png delete mode 100755 docs/06_Component_Documentation/Application_Framework/images/start_and_activation.msc delete mode 100644 docs/06_Component_Documentation/Application_Framework/images/start_and_activation.png (limited to 'docs/06_Component_Documentation/Application_Framework') diff --git a/docs/06_Component_Documentation/Application_Framework/01_Introduction.md b/docs/06_Component_Documentation/Application_Framework/01_Introduction.md deleted file mode 100644 index 32c6bb0..0000000 --- a/docs/06_Component_Documentation/Application_Framework/01_Introduction.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: Introduction ---- - -# Foreword - -AGL has worked at providing the components of an application framework for many -years. However, the implementation used up until the `lamprey` release was retired -starting with the `marlin` release, and replaced with a redesigned one. -However, this new implementation does not aim to be a 1:1 replacement, and as such -it does not provide all of the features of the previous framework. Some of those -will be added back over time, while others have been discarded in favor of more -modern and/or widely-used alternatives. - -With the `needlefish` release, further evolution of the replacement framework included: - -- Using [gRPC IPC](https://grpc.io/about) for the application launcher API. - The interim D-Bus based API was deprecated at this time, and removed in the - `ricefish` release. -- Using only systemd unit metadata in the application launcher instead of using - [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) - to list applications, and relying entirely on systemd for the application - lifecycle, rather than spawning them directly. - -# Introduction - -With a goal of being the provider of an integrated solution to build up on, it -is useful for AGL to define a reliable and well-specified method for managing -the deployment and integration of applications and services, as well as the way -they can interact with the rest of the system. - -This is achieved by providing a common set of rules and components, known as -the application framework. By documenting those rules, application developers can -have a good understanding of the requirements for creating and packaging applications -targeting AGL-based systems that leverage the upstream application framework components. -Likewise, system developers and integrators have a clear path for including such -applications in AGL-based products. - -The application framework's scope extends to the following areas: - -- system services integration and lifecycle management -- user-level application lifecycle management -- inter-process communication - -In order to be as simple as possible and avoid any unneeded custom -implementation, the application framework relies mainly on third-party -technologies and/or software components. They include: - -- [systemd](https://www.freedesktop.org/wiki/Software/systemd/): system - services and user session services management - -- [gRPC](https://grpc.io/about): inter-process communication, new recommmended - system-wide IPC, which should be used instead of D-Bus. - -Note that while there are many open source software projects in the desktop Linux -space using [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) for inter-process -communication, AGL has decided to avoid using it for new development projects for the -following reasons: - -- It has proven challenging in the past to manage dependencies between and the - start-up of system and per-user D-Bus services in AGL. -- Managing the security of D-Bus APIs involves the use of PolicyKit, which is - somewhat heavyweight and not widely understood. As well, providing D-Bus - access to applications running inside containers or other sandbox schemes can - be significantly more complicated than e.g. using gRPC with authorization token - access control. -- D-Bus is not widely used in application development ecosystems outside of desktop - Linux. This matters when engaging with application developers in newer ecosystems - such as web applications or Flutter. - -AGL also provides reference implementations whenever possible and relevant, -located in the [meta-agl](../../04_Developer_Guides/02_AGL_Layers/02_meta_agl.md) -layer under `meta-app-framework`. At the moment, the application framework -contains two such components: - -- `agl-session`: `systemd` unit files for user sessions management -- `applaunchd`: application launcher service - -# Service Management - -Both system and user services are managed by `systemd`, which provides a number -of important features, such as dependency management or service monitoring: -when starting a service, `systemd` will ensure any other units this service -depends on are available, and otherwise start those dependencies. Similarly, -`systemd` can automatically restart a crashed service, ensuring minimal -downtime. - -`systemd` also provides an efficient first layer of security through its -[sandboxing](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing) -and other security-related options. - -It is also well integrated with D-Bus and can be used for a more fine-grained -control over D-Bus activated services. By delegating the actual service start-up -to `systemd`, developers can take advantage of its advanced features, allowing -for improved reliability and security. - -Each service should be represented by a `systemd` unit file installed to the -appropriate location. More details can be obtained from the [Creating a New -Service](../../04_Developer_Guides/03_Creating_a_New_Service.md) document. - -# User Session Management - -Similarly, user sessions and the services they rely on are also managed by -`systemd`. Prior to the `ricefish` release, AGL used a user session for the -`agl-driver` user for the running of user facing applications, including the -compositor. This has been replaced with using system units that use the -`User` directive. The reason for this is two-fold: - -- Several useful systemd sandboxing features are unavailable to user session - units, or would require the use of unprivileged namespace mounting. The - latter is not necessarily available in vendor BSP kernels, and the security - characteristics of it are still a matter of some debate. -- Encoding dependencies between user session and system units is sometimes - not straightforward or impossible. - -# Inter-process Communication - -In order to provide a language-independent, "standard", IPC mechanism and avoid -the need for maintaining custom bindings for each programming language to be -used on top of AGL, the application framework previously promoted the use of -[D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) as the preferred way -for applications to interact with services. Starting with `needlefish` release, -this has changed to recommending [gRPC](https://grpc.io) for our system-wide IPC, -with D-Bus being kept to provide functionality to services and applications -which haven't transitioned yet to using gRPC. - -Most services already included in AGL provide one or several D-Bus interfaces, -and can therefore interact with D-Bus capable applications and services -without requiring any additional component. Those services include, among -others: - -- [ConnMan](https://git.kernel.org/pub/scm/network/connman/connman.git/): - network connectivity - -- [BlueZ](http://www.bluez.org/): Bluetooth connectivity - -- [oFono](https://git.kernel.org/pub/scm/network/ofono/ofono.git): telephony - and modem management - -- [GeoClue](https://gitlab.freedesktop.org/geoclue/geoclue/-/wikis/home): - geolocation - -Similarly, ongoing work involves expanding various services to expose a -gRPC interface. - -# Application Launcher Service - -The Application Framework used to follow the guidelines of the [Desktop Entry -specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) -for application enumeration and start-up, but with the `needlefish` release -instead it relies on systemd to provide that functionality, indirectly, by -using the `applaunchd` application. - -As no simple reference implementation exists for this part of the -specification, AGL provides an application launcher service named `applaunchd`. -This service is part of the default user session, and as such is automatically -started on session start-up. It can therefore be considered always available. - -`applaunchd` enumerates applications installed on the system and provides a -gRPC interface for services and applications to: - -- query the list of available applications -- request the start-up of a specific application -- be notified when applications are started or terminated diff --git a/docs/06_Component_Documentation/Application_Framework/02_Application_Startup.md b/docs/06_Component_Documentation/Application_Framework/02_Application_Startup.md deleted file mode 100644 index 8594426..0000000 --- a/docs/06_Component_Documentation/Application_Framework/02_Application_Startup.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -title: Application Launcher ---- - -# Introduction - -At system runtime, it may be necessary for applications to start other -applications on demand. Such actions can be executed in reaction to a user -request, or they may be needed to perform a specific task. - -In order to do so, running applications and services need an established way of -discovering installed applications and executing those. - -In order to provide a language-independent interface for applications and -service to use, AGL includes `applaunchd`, a system service. - -# Application Launcher Service - -The purpose of `applaunchd` is to enumerate applications available on the -system and provide a way for other applications to query this list and start -those on demand. It is also able to notify clients of the start-up and -termination of applications it manages. - -To that effect, `applaunchd` provides a gRPC interface which other applications -can use in order to execute those actions. - -*Note: `applaunchd` will only send notifications for applications it started; -it isn't aware of applications started by other means (`systemd`, direct -executable call...), and therefore can't send notifications for those.* - -## Application Discovery - -Applications are enumerated from systemd's list of available units based on the -pattern `agl-app*@*.service`, and are started and controled using their systemd -unit. Please note `applaunchd` allows only one instance of a given -application. - -## Application Identifiers - -Each application is identified by a unique Application ID. Although this ID can -be any valid string, it is highly recommended to use the "reverse DNS" -convention in order to avoid potential name collisions. - -## gRPC Interface - -The interface provides methods for the following actions: - -- retrieve the list of available applications -- request an application to be started -- subscribe to status events - -Moreover, with the gRPC the client subscribes to a status signal to be notified -when an application has successfully started or its execution terminated. - -The gRPC protobuf file provides a Request and Response arguments to RPC methods -even though in some cases these might be empty in order to allow forward -compatibility in case additional fields are required. -It is a good standard practice to follow up with these recommendation when -developing a new protobuf specification. - -### Application Enumeration - -The `ListApplications` method allows clients to retrieve the list of available -applications. - -The `ListRequest` is an empty message, while `ListResponse` contains the following: - -``` -message AppInfo { - string id = 1; - string name = 2; - string icon_path = 3; -} - -message ListResponse { - repeated AppInfo apps = 1; -} -``` - -### Application Start-up - -Applications can be started by using the `StartApplication` method, passing the -`StartRequest` message, defined as: - -``` -message StartRequest { - string id = 1; -} -``` - -In reply, the following `StartResponse` will be returned: - -``` -message StartResponse { - bool status = 1; - string message = 2; -} -``` - -The "message" string of `StartResponse` message will contain an error message -in case we couldn't start the application for whatever reason, or if the "id" -isn't a known application ID. The "status" string would be boolean set to -boolean `TRUE` otherwise. - -If the application is already running, `applaunchd` won't start another -instance, but instead reply with a `AppStatus` message setting the `status` -string to "started". - -### Status Notifications - -The gRPC interface provides clients with a subscription model to receive -status events. Client should subscribe to `GetStatusEvents` method to receive -them. - -The `StatusRequest` is empty, while the `StatusResponse` is defined as -following: - -``` -message AppStatus { - string id = 1; - string status = 2; -} - -message LauncherStatus { -} - -message StatusResponse { - oneof status { - AppStatus app = 1; - LauncherStatus launcher = 2; - } -} -``` - -As mentioned above, the `status` string is set to "started" and is also emitted -if `applaunchd` receives a request to start an already running application. -This can be useful, for example, when switching between graphical applications: - -- the application switcher doesn't need to track the state of each application; - instead, it can simply send a `StartApplication` request to `applaunchd` - every time the user requests to switch to another application. Obviously, the - client needs to subscribe to get these events and act accordingly. -- the shell client then receives the `StatusResponse` with the message `status` - string set to "started" indicating it that it should activate the window with - the corresponding `id` string, or alternatively the string `status` is - set to "terminated" to denote that the application has been terminated, - forcibly or not - -## Start-up, Activation, and Application Switching - -Application start-up, activation and application switching are sometimes -conflated into a single operation but underneath some of these are distinct -steps, and a bit flaky in some circumstances. -The [AGL compositor](../02_agl_compositor.md) has -some additional events which one can use when creating an application -start-up & switching scheme in different run-times. - -Start-up of application is handled entirely by `applaunchd` service while -activation -- the window which I want to display, but which has never been -shown, and application switching -- bring forward an application already -shown/displayed in the past, are operations handled entirely by the -AGL compositor. - -The issue stems from the fact that underneath `applaunchd` can't make any -guarantees when the application actually started, as it calls into libsystemd -API to start the specific application systemd unit. - -If `StartApplication` can't start the systemd unit, it returns a false -`status` boolean value and a error message in `StartResponse` message, but if -the application is indeed started we doesn't really know the *moment* when the -application is ready to be displayed. Additionally, the AGL compositor -performed the activation on its own when it detected that a new application -has been started, but that implicit activation can now be handled outside -by the desktop run-time/shell client. - -*Note: Some of the run-times still rely on the compositor to perform activation -as this synchronization part between `applaunchd` has not been implemented. The -plan is to migrate all of remaining run-times to using this approach.* - -### Start-up and Activation - -This means that we require some sort of interaction between `StartApplication` -method and the events sent by the AGL compositor in order to correctly handle -start-up & activation of application. - -There are couple of ways of achieving that, either using Wayland native calls, -or using the gRPC proxy interface, which underneath is using the same Wayland -native calls. - -For the first approach, the AGL compositor has an `app_state` Wayland event -which contains the application ID, and an enum `app_state` that will propagate -the following application state events: - -``` - - - - - - -``` - -The `started` event can be used in correlation with the `StartApplication` -method from `applaunchd` such that upon received the `started` even, it can -explicitly activate that particular appid in order for the compositor to -display it. See [AGL compositor](../02_agl_compositor.md) -about how activation should be handled. - -*Note: These can only be received if by the client shell which binds to the -agl_shell interface*. - -Alternatively, when using the gRPC proxy one can register to receive these -status events similar to the `applaunchd` events, subscribing to -`AppStatusState` method from the grpc-proxy helper application, which has the -following protobuf messages: - -``` -message AppStateRequest { -} -message AppStateResponse { - int32 state = 1; - string app_id = 2; -} -``` - -The integer state maps to the `enum app_state` from the Wayland protocol, so -they are a 1:1 match. - -Here's the state diagram for the Qt homescreen implementation of the -application start-up: - -![Application_start](images/start_and_activation.png) - -### Application Switching - -With the compositor providing application status events, it might seem that the -`applaunchd`'s, `GetStatusEvents` might be redundant, but in fact it is being -used to perform application switching. The run-time/shell client would in fact -subscribe to `GetStatusEvents` and each application wanting to switch to another -application would basically call `StartApplication`. That would eventually reach -the run-time/shell-client and have a handler that would ultimately activate the -application ID. - -![Application_switching](images/application_switching.png) - -*Note: In practice, the run-time/shell-client would subscribe to both `applaunchd` -and to the AGL compositor, either Wayland native events, or using the gPRC-proxy -helper client, although the diagrams show them partly decoupled*. diff --git a/docs/06_Component_Documentation/Application_Framework/03_Creating_a_New_Application.md b/docs/06_Component_Documentation/Application_Framework/03_Creating_a_New_Application.md deleted file mode 100644 index aa528b1..0000000 --- a/docs/06_Component_Documentation/Application_Framework/03_Creating_a_New_Application.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: Creating a New Application ---- - -In the context of AGL, "applications" are usually considered to be standalone -user facing infotainment applications that can be started in addition to the -default "homescreen" or similar user interface that will always be present. -Such applications can be enumerated and executed with `applaunchd`, the AGL -[application launcher service](02_Application_Startup.md). The following -sections walk through what is required to add an application to an AGL image -that uses applaunchd, as well as discussion of developer conveniences that -AGL provides to simplify doing so in the Yocto build environment. - -# Basic Requirements - -As described in the [applaunchd documentation](02_Application_Startup.md#application-discovery), -applications need to have a systemd system unit with a name matching the pattern `agl-app*@*.service`. -The portion of the unit name between `@` and `.service` is used as the application identifier -(see [Application Identifiers](02_Application_Startup.md#application-identifiers)). -The use of `@` in the unit filename indicates the use of a template unit, which `applaunchd` -assumes will be used for applications (see below). Template unit files are discussed in the -systemd unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description). - -The requirements on the unit file contents are: - -- The `Description` field is used as the desired display name of the application. - It is recommended that this be kept short, ideally to one or two words, in order to - avoid issues when applications are listed in a UI. -- While not a hard requirement, ideally the `User` field is used to specify running - the application as a non-privileged user. In the AGL demonstration images, the - `agl-driver` user is used. - -Blah blah icon... - -# Graphical Application Requirements - -In addition, graphical applications need to comply with a few more requirements: - -1. Each application must set a Wayland application ID appropriately as soon as its main window -is created. -2. The `app-id` used must match the application identifier specified in the systemd unit filename. - -Doing so will ensure other software can associate the actual `app-id` to the proper application. - -*Note: application ID's are set using the [XDG toplevel](https://wayland-book.com/xdg-shell-basics/xdg-toplevel.html) -Wayland interface.* - -# Application Templates - -To provide a working example of application template units, AGL includes templates -for generic, Flutter, and web applications as part of the `applaunchd` recipe in the -`meta-app-framework` layer in [meta-agl](../../04_Developer_Guides/02_AGL_Layers/02_meta_agl.md). -If applaunchd is built into an image using the recipe, these templates will be available -for applications to use for their systemd units by creating a symlink that includes the -application identifier. To simplify this, a `BitBake` class named `agl-app` is included in -the layer for use in application recipes. The different templates and their configuration -will be discussed further in the following sections. - -## Generic Graphical Application Template - -The `agl-app@.service` template unit is intended for simple standalone graphical applications. -It makes the following assumptions by default: - -- The application executable name is the same as the application identifier, and the - executable is available via the default `PATH`. -- The application `Description` will be the application identifier. -- The application should run as the `agl-driver` user. - -If using the `agl-app` class in a recipe (with `inherit agl-app`), these defaults can be -changed via the variables: - -- `AGL_APP_NAME`: overrides the value of the `Description` field to set the desired - application display name. -- `AGL_APP_EXEC`: overrides the application executable name. - -If set, these variables will trigger the generation of one or more systemd `drop-in` -override files by the logic in the `agl-app` class. The use of `drop-in` configuration -files is discussed in the systemd unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description). - -Additionally, the variable `AGL_APP_ID` may be used to override the assumption that the -application identifier is the same as the recipe name. If specified, its value should be -the desired application identifier. - -The following is a partial example BitBake recipe using the template for an application named -`foo`: - -```text - -SUMMARY = "foo application" -HOMEPAGE = "https://git.automotivelinux.org/apps/foo" -LICENSE = "Apache-2.0" -LIC_FILES_CHKSUM = "file://LICENSE;md5=ae6497158920d9524cf208c09cc4c984" - -PV = "1.0+git${SRCREV}" - -SRC_URI = "git://git.automotivelinux.org/apps/foo;protocol=https;branch=master" -SRCREV = "abcdef012" - -S = "${WORKDIR}/git" - -inherit agl-app - -AGL_APP_NAME = "Foo" - - -``` - -Note that this assumes that the recipe is named `foo_git.bb`. If the recipe was instead named -something like `foo-app_git.bb`, then `AGL_APP_ID = "foo"` would need to be added. - -## Flutter Application Template - -The `agl-app-flutter@.service` template unit is intended for Flutter graphical applications -that use the `flutter-auto` Flutter embedder. It makes the following assumptions by default: - -- The Flutter application name in `pubspec.yaml` is the same as the application identifier, -and the application bundle will be installed under the directory: - ```text - /usr/share/flutter/// - ``` - For example: - ```text - /usr/share/flutter/flutter_hvac/3.3.7/release - ``` - -- The application `Description` will be the application identifier. -- The application should run as the `agl-driver` user. - -If using the `agl-app` class in a recipe (with `inherit agl-app`), the use of the Flutter -template can be triggered by setting the variable `AGL_APP_TEMPLATE` to `agl-app-flutter`, -and the above defaults can be changed via the variables: - -- `AGL_APP_NAME`: overrides the value of the `Description` field to set the desired - application display name. - -If set, this will trigger the generation of a systemd `drop-in` override file by the logic -in the `agl-app` class. The use of `drop-in` configuration files is discussed in the systemd -unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description). - -Additionally, the variable `AGL_APP_ID` may be used to override the assumption that the -application identifier is the same as the recipe name. If specified, its value should be -the desired application identifier and Flutter application / bundle name. - -The following is an example BitBake recipe using the template for a Flutter application -named `foo`: - -```text - -SUMMARY = "Flutter foo application" -HOMEPAGE = "https://git.automotivelinux.org/apps/flutter-foo" -LICENSE = "Apache-2.0" -LIC_FILES_CHKSUM = "file://License.md;md5=f712ede8d4f845976061925d1416fc40" - -PV = "1.0+git${SRCREV}" - -SRC_URI = "git://git.automotivelinux.org/apps/flutter-foo;protocol=https;branch=master" -SRCREV = "abcdef012" - -S = "${WORKDIR}/git" - -inherit flutter-app agl-app - -PUBSPEC_APPNAME = "foo" -FLUTTER_APPLICATION_INSTALL_PREFIX = "/flutter" - -AGL_APP_TEMPLATE = "agl-app-flutter" -AGL_APP_NAME = "Foo" -``` - -Note that this assumes that the recipe is named `foo_git.bb`, and that the application name -in the Flutter `pubspec.yaml` is `foo`. If the recipe was instead named something like -`flutter-foo_git.bb`, then `AGL_APP_ID = "foo"` would need to be added. - -## Web Application Template - -The `agl-app-web@.service` template unit is intended for web applications run using the -Web Application Manager (WAM) service. It makes the following assumptions by default: - -- The web application bundle directory name is the same as the application identifier, and the - bundle will be installed in the directory hierarchy: - ``` - /usr/lib/wam_apps/ - ``` - For example: - ``` - /usr/lib/wam_apps/webapps-hvac - ``` -- The application `Description` will be the application identifier. -- The application should run as the `agl-driver` user. - -If using the `agl-app` class in a recipe (with `inherit agl-app`), the use of the Flutter -template can be triggered by setting the variable `AGL_APP_TEMPLATE` to `agl-app-web`, -and the above defaults can be changed via the variables: - -- `AGL_APP_NAME`: overrides the value of the `Description` field to set the desired - application display name. -- `AGL_APP_WAM_DIR`: overrides the application bundle directory name. This can be used if - the application bundle name does not match the application identifier. - -If set, these variables will trigger the generation of one or more systemd `drop-in` -override files by the logic in the `agl-app` class. The use of `drop-in` configuration -files is discussed in the systemd unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description). - -Additionally, the variable `AGL_APP_ID` may be used to override the assumption that the -application identifier is the same as the recipe name. - -The following is a partial example BitBake recipe using the template for a web application -named `foo`: - -```text - -SUMMARY = "Web foo application" -HOMEPAGE = "https://git.automotivelinux.org/apps/web-foo" -LICENSE = "Apache-2.0" -LIC_FILES_CHKSUM = "file://LICENSE;md5=3b83ef96387f14655fc854ddc3c6bd57" - -PV = "1.0+git${SRCREV}" - -SRC_URI = "git://git.automotivelinux.org/apps/web-foo;protocol=https;branch=master" -SRCREV = "abcdef012" - -S = "${WORKDIR}/git" - -inherit agl-app - -AGL_APP_TEMPLATE = "agl-app-web" -AGL_APP_NAME = "Foo" - - -``` - -Note that this assumes that the recipe is named `foo_git.bb`. If the recipe was instead named -something like `foo-web_git.bb`, then `AGL_APP_ID = "foo"` would need to be added. diff --git a/docs/06_Component_Documentation/Application_Framework/04_Application_Sandboxing.md b/docs/06_Component_Documentation/Application_Framework/04_Application_Sandboxing.md deleted file mode 100644 index 356c0eb..0000000 --- a/docs/06_Component_Documentation/Application_Framework/04_Application_Sandboxing.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Application Sandboxing ---- - -One of the motivations for leveraging systemd in `applaunchd` was to allow the use of its -advanced features such as [sandboxing](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing), -[system call filtering](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#System%20Call%20Filtering), -[process limits](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Process%20Properties), and -Linux CGroup configuration via [slices](https://www.freedesktop.org/software/systemd/man/systemd.slice.html). -The scope of potential systemd configurations involving these options is broad, and so far AGL has focused on providing -some simple examples of basic sandboxing integrated with the application templates discussed above. - -## Network Access Restriction - -The systemd [`PrivateNetwork`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#PrivateNetwork=) -service configuration option can be used to disable network access for the service started by a unit file. -The `applaunchd` packaging installs a systemd drop-in configuration file named `no-network.conf` in the -directory `/usr/lib/systemd/system/sandboxing` that may be used to disable network access with `PrivateNetwork`. -To use it, `no-network.conf` should be symlinked in an appropriate unit file drop-in override directory per -systemd naming expectations (see systemd unit file -[man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description)). -The following is a `BitBake` recipe snippet showing installation of the drop-in for an application named `foo` -that is using the generic application template: - -```text -... - -inherit agl-app - -AGL_APP_NAME = "Foo" - -do_install() { - # Enable systemd sandboxing override as a demonstration - install -d ${D}${systemd_system_unitdir}/agl-app@${AGL_APP_ID}.service.d/ - ln -sf ${systemd_system_unitdir}/sandboxing/no-network.conf ${D}${systemd_system_unitdir}/agl-app@${AGL_APP_ID}.service.d/ -} - -FILES:${PN} = " \ - ${sysconfdir}/systemd/system/agl-app@${AGL_APP_ID}.service.d \ -" - -... -``` - -This results in a `/usr/lib/systemd/system/agl-app@foo.service.d/no-network.conf` symlink being created -in the `foo` packaging, disabling network access when `foo` is started by `applaunchd` or directly via -`systemctl` on the command line. - -## Private Temporary Directories - -The systemd [`PrivateTmp`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#PrivateTmp=) -service configuration option can be used to prevent access to the host `/tmp` and `/var/tmp` directories -for the service started by a unit file. The service will instead have private temporary mounts of these -directories in a new mount namespace. The `applaunchd` packaging installs a systemd drop-in configuration -file named `private-tmp.conf` in the directory `/usr/lib/systemd/system/sandboxing` that may be used to -create private temporary directory mounts with `PrivateTmp`. To use it, `private-tmp.conf` should be -symlinked in an appropriate unit file drop-in override directory per systemd naming expectations (see -systemd unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description)). -See above for an example `BitBake` recipe snippet showing installation of a drop-in file when using the -generic application template. - -## Other Sandboxing Options - -In addition to the above, some other notable systemd sandbox options worth further consideration for -applications include: - -- [PrivateDevices](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#PrivateDevices=) - This option could be used to remove access to device files in /dev for applications that do not - require them, but it is likely that `DeviceAllow` may also need to be used to enable functionality in - some applications. -- [ProtectSystem](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#ProtectSystem=) - The default and `full` modes of this option likely can be enabled with little impact to most - applications, as they should not need write access to the directories that are made read-only. - Using the `strict` option would need investigation into interactions with usage of directory - hierarchies like `/run`. -- [ProtectHome](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#ProtectHome=) - This option seems worthwhile if the system ends up with more than one active user for running - applications, but interactions with default application caching and configuration locations - needs to be investigated. It is likely that enforcing use of locations outside of `/home` - for these would need to be settled upon and documented for application developers. For - example using the [XDG directory scheme](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) - similar to the previous AGL application framework. -- [ReadWritePaths, etc.](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#ReadWritePaths=) - These options provide a more fine-grained approach to some of the above ones, and could be - used to enable something like an application only seeing its own files and the contents of - a specific set of directories like `/etc` and `/usr/lib`. Implementing such would likely - require settling on a custom application installation hierarchy as was done in the previous - AGL application framework. - -The above list is not exhaustive, and does not include some other likely possibilities involving -system call filtering and resource limits. Future AGL releases may expand the examples provided -with `applaunchd` along these lines. diff --git a/docs/06_Component_Documentation/Application_Framework/images/application_switching.msc b/docs/06_Component_Documentation/Application_Framework/images/application_switching.msc deleted file mode 100755 index ceeab7c..0000000 --- a/docs/06_Component_Documentation/Application_Framework/images/application_switching.msc +++ /dev/null @@ -1,29 +0,0 @@ -#!/usr/bin/mscgen -Tpng - -msc { - hscale="1.5"; - - u [label = "touch/pointer event" ], - l [label = "launcher app" ], - s [label = "runtime/shell-client"], - a [label = "applaunchd" ], - g [label = "gRPC-proxy" ], - c [label = "compositor" ], - d [label = "libsystemd"]; - - |||; - - --- [label = "initial phase - subscribe for signal/status events, assume app_id already started" ]; - - s >> a [label = "subscribe for applaunchd GetStatusEvents"]; - - --- [label = "handling of application switching" ]; - - u => l [label = "tapShortCut(appid)" ]; - l => a [label = "StartApplication(appid)"]; - a => d [label = "start application's systemd unit"]; - d => a [label = "return status from starting systemd unit"]; - a => s [label = "StartResponse(status = TRUE)"]; - a => s [label = "StatusResponse(app_id, 'started')"]; - s => c [label = "activate_app(app_id)"]; -} diff --git a/docs/06_Component_Documentation/Application_Framework/images/application_switching.png b/docs/06_Component_Documentation/Application_Framework/images/application_switching.png deleted file mode 100644 index 0b5584a..0000000 Binary files a/docs/06_Component_Documentation/Application_Framework/images/application_switching.png and /dev/null differ diff --git a/docs/06_Component_Documentation/Application_Framework/images/start_and_activation.msc b/docs/06_Component_Documentation/Application_Framework/images/start_and_activation.msc deleted file mode 100755 index d835f8b..0000000 --- a/docs/06_Component_Documentation/Application_Framework/images/start_and_activation.msc +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/mscgen -Tpng - -msc { - hscale="1.5"; - - u [label = "touch/pointer event" ], - s [label = "runtime/shell-client"], - a [label = "applaunchd" ], - g [label = "gRPC-proxy" ], - c [label = "compositor" ], - d [label = "libsystemd"]; - - |||; - - --- [label = "initial phase - subscribe for signal/status events" ]; - - s >> g [label = "subscribe for AGL compositor AppStatusState"]; - g >> c [label = "listen for app_state Wayland events"]; - - --- [label = "handling start-up & activation" ]; - - u => s [label = "tapShortCut(appid)" ]; - s => a [label = "StartApplication(appid)"]; - a => d [label = "start application's systemd unit"]; - d => a [label = "return status from starting systemd unit"]; - a => s [label = "StartResponse(status = TRUE)"]; - c => g [label = "app_state(app_state = APP_STARTED)"]; - g => s [label = "AppStatusResponse(app_id, APP_STARTED)"]; - s => c [label = "activate_app(app_id)"]; -} diff --git a/docs/06_Component_Documentation/Application_Framework/images/start_and_activation.png b/docs/06_Component_Documentation/Application_Framework/images/start_and_activation.png deleted file mode 100644 index 593fc0e..0000000 Binary files a/docs/06_Component_Documentation/Application_Framework/images/start_and_activation.png and /dev/null differ -- cgit