diff --git a/en/device-dev/subsystems/Readme-EN.md b/en/device-dev/subsystems/Readme-EN.md index e40ac223f95726881f4d99a3b8b531ec5b672303..10fa420829ca9719fa7b64437fcfb28d01bf4736 100644 --- a/en/device-dev/subsystems/Readme-EN.md +++ b/en/device-dev/subsystems/Readme-EN.md @@ -76,8 +76,7 @@ - [Startup](subsys-boot-overview.md) - [init Module](subsys-boot-init.md) - [appspawn Module](subsys-boot-appspawn.md) - - [appspawn Module for the Standard System](subsys-boot-appspawn-standard.md) - - [bootstrap Module](subsys-boot-bootstrap.md) + - [bootstrap Module](subsys-boot-bootstrap.md) - [syspara Module](subsys-boot-syspara.md) - [FAQs](subsys-boot-faqs.md) - [Reference](subsys-boot-ref.md) diff --git a/en/device-dev/subsystems/subsys-boot-appspawn-standard.md b/en/device-dev/subsystems/subsys-boot-appspawn-standard.md deleted file mode 100644 index 1defe3cf035c92647a870b72f6c73c5cf3e7418c..0000000000000000000000000000000000000000 --- a/en/device-dev/subsystems/subsys-boot-appspawn-standard.md +++ /dev/null @@ -1,158 +0,0 @@ -# appspawn Module for the Standard System - -## Overview - -After being started by the init process, the appspawn process waits for inter-process communication (IPC) messages. Upon receiving a message, the appspawn process starts an application service based on the message content, and grants the corresponding permission to the application service. - -### Introduction - -- Security control -
Support for setting of SELinux tags for applications - -- Application process control - - - Support for setting of AccessToken for applications - - Support for simultaneous stopping of all spawn application processes (after stopping of the appspawn process and before a restart) - -- Cold start -
Support for cold start of applications by using the **aa** command - - ``` - param set appspawn.cold.boot true // Enable cold start. - aa start -d 12345 -a $name -b $package -C - Example: - aa start -d 12345 -a ohos.acts.startup.sysparam.function.MainAbility -b ohos.acts.startup.sysparam.function -C - -### Basic Concepts - -**appspawn** is a registered service name. The appspawn process receives requests from the client by listening to messages over the local socket. The message type is an **AppProperty** structure. It is defined in **base/startup/appspawn_standard/interfaces/innerkits/include/sclient_socket.h**. - -**Table 1** Field description - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Field

-

Description

-

processName

-

Name of the service process to be started. The value contains a maximum of 256 bytes.

-

bundleName

-

Bundle name of the application to be started. The value contains a maximum of 256 bytes.

-

soPath

-

Path of the dynamic library specified by the application. The value contains a maximum of 256 bytes.

-

uid

-

UID of the application process to be started. The value must be a positive number.

-

gid

-

GID of the application process to be started. The value must be a positive number.

-

gidTable

-

Information about the application process group to be started. Its length is specified by gidCount. A maximum of 64 process groups are supported. The value must be a positive number.

-

gidCount

-

Number of application process groups to be started.

-

accessTokenId

-

Token ID for application process permission control.

-

apl

-

APL for application process permission control. The value contains a maximum of 32 bytes.

-
- -## Development Guidelines - - The API definitions are provided in **base/startup/appspawn_standard/interfaces/innerkits/include/client_socket.h**. Table 2 is a list of available APIs. - -### Available APIs - -**Table 2** API description - - - - - - - - - - - - - - - - - - - - -

API

-

Description

-

CreateClient

-

Creates a client.

-

CloseClient

-

Closes a client.

-

ConnectSocket

-

Sends a connection request to the appspawn service.

-

WriteSocketMessage

-

Sends a message to the appspawn service.

-

ReadSocketMessage

-

Receives a message from the appspawn service.

-
- -### Development Example - -
The following is an example of using related APIs: -``` - std::shared_ptr clientSocket = std::make_unique("AppSpawn"); - if (clientSocket == nullptr) { - return -1; - } - if (clientSocket->CreateClient() != ERR_OK) { - return -1; - } - if (clientSocket->ConnectSocket() != ERR_OK) { - return -1;; - } - // Construct AppProperty based on the specified property. - clientSocket->WriteSocketMessage((void *)&property, sizeof(AppSpawn::AppProperty)); - // Read the result. - int pid; - clientSocket->ReadSocketMessage((void *)&pid, sizeof(pid)); - // Normally, the process ID of the application is returned. If the PID is less than or equal to 0, an error has occurred. -``` - -## FAQ - -### Cold Start Failure - -   **Symptom** -
    Cold start failed because of a command execution failure. - -   **Solution** -
    1. Check whether cold start is enabled. -
    2. Check whether the cold start command is correct. diff --git a/en/device-dev/subsystems/subsys-boot-appspawn.md b/en/device-dev/subsystems/subsys-boot-appspawn.md index a8f9025c884e5ddcf25a36ed73ced8f676c75108..7b9e10bb654aa3412615cef43a1ba86a78dc23e2 100644 --- a/en/device-dev/subsystems/subsys-boot-appspawn.md +++ b/en/device-dev/subsystems/subsys-boot-appspawn.md @@ -1,47 +1,170 @@ # appspawn Module -After appspawn is started by init, its service name \(appspawn\) is registered with the IPC framework. Upon receiving inter-process messages, appspawn starts the application service based on the message parsing result, and grants the corresponding permission to the application service. - -You can obtain the macro definition **APPSPAWN\_SERVICE\_NAME** corresponding to **appspawn** by including the header file **base\\startup\\appspawn\_lite\\services\\include\\appspawn\_service.h**. Due to some constraints on the security subsystem, only Ability Manager Service \(AMS\) has the permission to send inter-process messages to appspawn. - -The messages are in JSON format, as shown in the following: - -"\{\\"bundleName\\":\\"testvalid1\\",\\"identityID\\":\\"1234\\",\\"uID\\":1000,\\"gID\\":1000,\\"capability\\":\[0\]\}" - -**Table 1** Keys in messages - - - - - - - - - - - - - - - - - - - - - - -

Key

-

Description

-

bundleName

-

Name of the application service process to be started. The length ranges from 7 bytes to 127 bytes.

-

identityID

-

Identifier generated by the AMS for the new process. The length ranges from 1 byte to 24 bytes. The appspawn process passes the value to the new process.

-

uID

-

UID of the application service process to be started. The value must be a positive number.

-

gID

-

GID of the application service process to be started. The value must be a positive number.

-

capability

-

Capability permissions required by the application service process to be started. A maximum of 10 capability permissions are allowed.

-
+## Overview +### Introduction + + The appspawn module spawns application processes upon receiving commands from the application framework, configures permissions for new processes, and calls the entry function of the application framework. + +### Basic Concepts + + **appspawn** is a registered service name. The appspawn process receives requests from the client by listening to messages over the local socket. The message type is an **AppParameter** structure. It is defined in **interfaces/innerkits/include/appspawn_msg.h**. + + **Table 1** Field description + | Field| Description| + | -------- | -------- | + | processName | Name of the service process to be started. The value contains a maximum of 256 bytes.| + | bundleName | Bundle name of the application to be started. The value contains a maximum of 256 bytes.| + | soPath | Path of the dynamic library specified by the application. The value contains a maximum of 256 bytes.| + | uid | UID of the application process to be started.| + | gid | GID of the application process to be started.| + | gidTable | Information about the application process group to be started. Its length is specified by **gidCount**. A maximum of 64 process groups are supported. The value must be a positive number.| + | gidCount | Number of application process groups to be started.| + | accessTokenId | Token ID for application process permission control.| + | apl | APL for application process permission control. The value contains a maximum of 32 bytes.| + | renderCmd | Image rendering command. The value contains a maximum of 1024 bytes.| + | flags | Cold start flag.| + | pid | PID of the rendering process, which is used to query the process exit status.| + | AppOperateType | Application operation type. The value **0** means to obtain the default status, and the value **1** means to obtain the rendering termination status.| + +### Constraints +The appspawn module is used only for the standard system. + +## Development Guidelines + +### Use Cases + +- Application security control based on SELinux tags + + Example code: + ```c++ + AppSpawnClientExt *appProperty = (AppSpawnClientExt *)client; + HapContext hapContext; + ret = hapContext.HapDomainSetcontext(appProperty->property.apl, appProperty->property.processName); + if (ret != 0) { + APPSPAWN_LOGE("AppSpawnServer::Failed to hap domain set context, errno = %d %s", + errno, appProperty->property.apl); + } else { + APPSPAWN_LOGI("AppSpawnServer::Success to hap domain set context, ret = %d", ret); + } + ``` +- Application process control + + - Support for setting of AccessToken for applications + - Support for simultaneous stopping of all spawn application processes (after stopping of the appspawn process and before a restart) + + Example code: + ``` + AppSpawnClientExt *appProperty = (AppSpawnClientExt *)client; + int32_t ret = SetSelfTokenID(appProperty->property.accessTokenId); + APPSPAWN_LOGI("AppSpawnServer::set access token id = %d, ret = %d %d", appProperty->property.accessTokenId, ret, getuid()); + ``` + +- Support for cold start of applications by using the aa command + + ``` + param set appspawn.cold.boot true // Enable cold start. + aa start -d 12345 -a $name -b $package -C + Reference command: + aa start -d 12345 -a ohos.acts.startup.sysparam.function.MainAbility -b ohos.acts.startup.sysparam.function -C + ``` + +- Application sandbox + + Applications run independently in their own sandbox environments. In an application sandbox, only necessary libraries or files of applications are retained and data of different applications is isolated. + +### Available APIs + + The API definitions are provided in **/interfaces/innerkits/include/client_socket.h**. Table 2 is a list of available APIs. + + **Table 2** API description + | API| Description| + | -------- | -------- | + | CreateClient | Creates a client.| + | CloseClient | Closes a client.| + | ConnectSocket | Sends a connection request to the appspawn service.| + | WriteSocketMessage | Sends a message to the appspawn service.| + | ReadSocketMessage | Receives a message from the appspawn service.| + +### How to Develop + + Sandbox configuration description: + + ``` + { + "common" : [{ // Common mount options of the application sandbox + "top-sandbox-switch": "ON", // Application sandbox switch. The value ON means to enable the applicable sandbox, and the value OFF means the opposite. + "app-base" : [{ + "sandbox-root" : "/mnt/sandbox/", // Root path of the application sandbox + "mount-paths" : [{ + "src-path" : "/config", // Source mount path + "sandbox-path" : "/config", // Sandbox mount path + "sandbox-flags" : [ "bind", "rec" ], // Mount mode + "check-action-status": "false" // Whether to check the mount result. The value true means to check the mount result, and the value false means the opposite. + } + ], + "symbol-links" : [{ // Link path + "target-name" : "/system/bin", // Source link path + "link-name" : "/bin", // Link name + "check-action-status": "false" + } + ] + }], + // Reference application-specific configuration + "individual" : [{ // Independent mount options of an application + "com.ohos.medialibrary.MediaLibraryDataA" : [{ // Application name + "sandbox-switch": "ON", // Application sandbox switch. The value ON means to enable the applicable sandbox, and the value OFF means the opposite. + "sandbox-root" : "/mnt/sandbox/", // Root path of the application sandbox + "mount-paths" : [{ + "src-path" : "/storage/media/", + "sandbox-path" : "/storage/media", + "sandbox-flags" : [ "bind", "rec" ], + "check-action-status": "false" + } + ], + "symbol-links" : [] + }] + }] + } + ``` + + Modify configuration files by referring to the sandbox configuration description. + + - On the device, go to **/system/etc/sandbox/**, modify the sandbox configuration files, and restart the device. + - In the code path, go to **base/startup/appspawn_standard**, and modify the sandbox configuration files. + + **Table 3** Description of sandbox configuration files + + | Sandbox Configuration File| Description| + | -------- | -------- | + | appdata-sandbox64.json | Sandbox configuration for the 64-bit OS| + | appdata-sandbox.json | Sandbox configuration for the 32-bit OS| + | product-sandbox.json | Product-specific configuration for the application sandbox| + +### Development Example +The following is the sample code for adding product-specific configuration for the launcher application: + ```c++ + "com.ohos.launcher" : [{ + "sandbox-switch": "ON", + "sandbox-root" : "/mnt/sandbox/", + "mount-paths" : [{ + "src-path" : "/data/app/el1/bundle/public/", + "sandbox-path" : "/data/bundles/", + "sandbox-flags" : [ "bind", "rec" ], + "check-action-status": "true" + } + ], + "symbol-links" : [] + }], + ``` + +## FAQ + +### Cold Start of Applications Failed + + **Symptom** +
Applications fail to be started by running the cold start command. + + **Solution** +
1. Enable cold start by setting **param set appspawn.cold.boot true**. +
2. Make sure that the cold start command is correct.