1# Sandbox Management 2 3## Overview 4 5### Function Introduction 6 7OpenHarmony supports two types of sandbox, namely, system sandbox and chipset sandbox. 8 9### Basic Concepts 10 11The system sandbox and chipset sandbox are created in the init module. Native services choose to enter the system sandbox or chipset sandbox based on their functions. Sandbox components can be isolated through the **mount** attribute if **mount-bind-paths** or **mount-bind-files** is set for them in configuration files such as **system-sandbox.json** and **chipset-sandbox.json**. In addition, a sandbox debugging tool is provided to facilitate sandbox debugging, verification, and optimization. For details about commands, see [Description of begetctl Commands](subsys-boot-init-plugin.md#parameters). 12 13### Constraints 14 15The sandbox management module is available only for the standard system. 16 17## How to Develop 18 19### Parameter Description 20 21 **Table 1** Parameters in the sandbox configuration file 22 23 | JSON Prefix| Description| 24 | ---------- | ---------- | 25 | sandbox-root | Root directory of the sandbox.| 26 | mount-bind-paths | Directory to mount.| 27 | mount-bind-files | File to mount.| 28 | src-path | Source path of the directory or file to mount.| 29 | sandbox-path | Target path in the sandbox.| 30 | sandbox-flags | Mount flag. The default value is **bind rec**.| 31 | ignore | Whether to ignore a mounting failure. If the value is set to **1**, the system ignores the mounting failure and proceeds with the subsequent step.| 32 | target-name | Directory to link.| 33 | link-name | Target link in the sandbox.| 34 35 **Table 2** Description of sandbox configuration files 36 | Sandbox Configuration File| Description| 37 | -------- | -------- | 38 | chipset-sandbox64.json | Chipset sandbox configuration file for the 64-bit system| 39 | chipset-sandbox.json | Chipset sandbox configuration file for the 32-bit system| 40 | system-sandbox64.json | System sandbox configuration file for the 64-bit system| 41 | system-sandbox.json | System sandbox configuration file for the 32-bit system| 42 43### Available APIs 44 45Logical storage structure of the sandbox: 46 47```c++ 48// Main functions 49// name is "system" or "chipset" 50bool InitSandboxWithName(const char *name); // Parsing to the JSON structure 51 52typedef struct { 53 ListNode pathMountsHead; // sandbox mount_path list head 54 ListNode fileMountsHead; // sandbox mount_file list head 55 ListNode linksHead; // sandbox symbolic link list head 56 char *rootPath; // /mnt/sandbox/system|vendor|xxx 57 char name[MAX_BUFFER_LEN]; // name of sandbox. i.e system, chipset etc. 58 bool isCreated; // sandbox already created or not 59 int ns; // namespace 60} sandbox_t; 61``` 62### Procedure 63 641. Create a sandbox. 65 - Create a system or chipset sandbox and configure the corresponding **system-sandbox.json** or **chipset-sandbox.json** file. For details about how to configure the JSON file, see [Sandbox JSON File Configuration](#sandbox). 66 - By default, the sandbox function of a service is enabled. To disable the sandbox function for a specific service, set **sandbox** to **0** in the **.cfg** file of the service. To enable the sandbox function for a specific service, set **sandbox** to **1**. 67 ``` 68 "sandbox" : 1 69 ``` 70 712. Modify the JSON file configuration of the sandbox. 72 - Go to the **/system/etc/sandbox/** directory, and run **cat system-sandbox.json** and **cat chipset-sandbox.json**. 73 If you are using a 64-bit system, run **cat system-sandbox64.json** and **cat chipset-sandbox64.json** instead. 74 - Modify the sandbox configuration files in the **base/startup/init/interfaces/innerkits/sandbox** directory. After that, restart the system. 75 76### Development Example 77 78JSON file configuration of the sandbox<a name = "sandbox"></a> 79 80```json 81{ 82 "sandbox-root" : "/mnt/sandbox/system", 83 "mount-bind-paths" : [{ 84 "src-path" : "/system/lib/ndk", 85 "sandbox-path" : "/system/lib/ndk", 86 "sandbox-flags" : [ "bind", "rec", "private" ] 87 }], 88 "mount-bind-files" : [{ 89 "src-path" : "/system/lib/ld-musl-aarch64.so.1", 90 "sandbox-path" : "/system/lib/ld-musl-aarch64.so.1", 91 "sandbox-flags" : [ "bind", "rec", "private" ] 92 }], 93 "symbol-links" : [{ 94 "target-name" : "/vendor/lib", 95 "link-name" : "/lib" 96 }] 97} 98``` 99 100## FAQs 101 102- **Cause Analysis** 103 Related services cannot access required resource files such as **.so** file. 104- **Solution** 105 Check the hilog information, analyze the failure cause, enter the path of the corresponding **.so** file on the device, and modify the **BUILD.gn** file as appropriate. The operation procedure is as follows: 106 107 - Search for keyword **failed** or **.so** in hilog. 108 109 ``` 110 08-05 17:27:29.302 488 488 E C02500/driver_loader_full: get driver entry failed, /vendor/lib/libcamera_host_service_1.0.z.so load fail, Error loading shared library libdisplay_buffer_proxy_1.0.z.so: No such file or directory (needed by /system/lib/chipset-pub-sdk/libdisplay_buffer_hdi_impl.z.so) 111 08-05 17:27:29.303 488 488 E C02500/devhost_service_full: DevHostServiceAddDevice failed and return -207 112 08-05 17:27:29.305 488 488 E C02500/devhost_service_stub: Dis patch failed, add service failed and ret is -207 113 08-05 17:27:29.307 488 488 I C02500/devhost_service_stub: add device 0x7000201 114 08-05 17:27:29.308 488 488 E C02500/driver_loader_full: /vendor/lib/libhdi_media_layer_service.z.so no valid, errno:2 115 ``` 116 117 - As shown in the preceding search result, the camera error is caused by the **libdisplay_buffer_proxy_1.0.z.so** loading failure. To rectify the fault, you can mount the file in the sandbox for quick recovery, or modify the corresponding **BUILD.gn** file. 118 119 - Method 1: Mount the file in the sandbox for quick recovery. (Only local debugging is supported, and source code modification needs to be reviewed.) 120 121 - System sandbox: Edit the **/system/etc/sandbox/system-sandbox.json** file on the device. By default, only some files in the **/vendor** directory are mounted. If an error is reported, mount the files separately. 122 123 - Chipset sandbox: Edit the **/system/etc/sandbox/chipset-sandbox.json** file on the device. By default, only some files in the **/system** directory are mounted. If an error is reported, mount the files separately. 124 125 - For the preceding case, add the following information to /system/etc/sandbox/chipset-sandbox.json: 126 127 ``` 128 "mount-bind-files" : [ 129 { 130 "src-path" : "/system/lib/libdisplay_buffer_proxy_1.0.z.so", 131 "sandbox-path" : "/system/lib/libdisplay_buffer_proxy_1.0.z.so", 132 "sandbox-flags" : [ "bind", "rec", "private" ] 133 },{...} 134 ], 135 ``` 136 137 - Method 2: Add **innerapi_tags** to the **BUILD.gn** file. 138 139 ``` 140 ohos_shared_library("xxx") { 141 ... 142 innerapi_tags = [ 143 "chipsetsdk", 144 ] 145 } 146 ``` 147 148 - Description of **innerapi_tags**: 149 150 - Tags related to sandbox permissions include **passthrough**, **chipsetsdk**, **passthrough_indirect**, and **chipsetsdk_indirect**. 151 152 - You can view the **so** information on the OpenHarmony website. For indirectly dependent modules, use **chipsetsdk_indirect** or **passthrough_indirect**. For other modules, use **chipsetsdk** or **passthrough**. 153 - For the **.so** files installed in the system directory, use **chipsetsdk** and **chipsetsdk_indirect** for access by chip components. 154 - For the **.so** files installed in the chip directory, use **passthrough** and **passthrough_indirect** for access by system components. 155 - You can add **innerapi_tags** to specify the installation path of **.so** files. For example, if **chipsetsdk** is set, **.so** files are installed in the **/lib/chipset-sdk/** directory. The source code is available at **build/templates/cxx/cxx.gni**. 156 ```gni 157 #auto set auto_relative_install_dir by innerapi_tags 158 if (defined(invoker.innerapi_tags)) { 159 is_chipsetsdk = false 160 is_platformsdk = false 161 is_passthrough = false 162 foreach(tag, filter_include(invoker.innerapi_tags, [ "chipsetsdk*" ])) { 163 is_chipsetsdk = true 164 } 165 foreach(tag, filter_include(invoker.innerapi_tags, [ "platformsdk*" ])) { 166 is_platformsdk = true 167 } 168 foreach(tag, filter_include(invoker.innerapi_tags, [ "passthrough*" ])) { 169 is_passthrough = true 170 } 171 if (is_chipsetsdk && is_platformsdk) { 172 auto_relative_install_dir = "chipset-pub-sdk" 173 } else if (is_chipsetsdk) { 174 auto_relative_install_dir = "chipset-sdk" 175 } else if (is_platformsdk) { 176 auto_relative_install_dir = "platformsdk" 177 } 178 if (is_passthrough) { 179 auto_relative_install_dir = chipset_passthrough_dir 180 } 181 ... 182 } 183