1# Sandbox Management
2
3## Overview
4### Function Introduction
5OpenHarmony supports two types of sandbox, namely, system sandbox and chipset sandbox.
6
7### Basic Concepts
8The 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).
9
10### Constraints
11
12The sandbox management module is available only for the standard system.
13
14## How to Develop
15### Parameter Description
16  **Table 1** Parameters in the sandbox configuration file
17
18  | JSON Prefix| Description|
19  | ---------- | ---------- |
20  | sandbox-root | Root directory of the sandbox.|
21  | mount-bind-paths | Directory to mount.|
22  | mount-bind-files | File to mount.|
23  | src-path | Source path of the directory or file to mount.|
24  | sandbox-path | Target path in the sandbox.|
25  | sandbox-flags | Mount flag. The default value is **bind rec**.|
26  | 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.|
27  | target-name | Directory to link.|
28  | link-name | Target link in the sandbox.|
29
30  **Table 2** Description of sandbox configuration files
31  | Sandbox Configuration File| Description|
32  | -------- | -------- |
33  | chipset-sandbox64.json | Chipset sandbox configuration file for the 64-bit system|
34  | chipset-sandbox.json | Chipset sandbox configuration file for the 32-bit system|
35  | system-sandbox64.json  | System sandbox configuration file for the 64-bit system|
36  | system-sandbox.json  | System sandbox configuration file for the 32-bit system|
37
38### Available APIs
39Logical storage structure of the sandbox:
40
41```c++
42// Main functions
43// name is "system" or "chipset"
44bool InitSandboxWithName(const char *name); // Parsing to the JSON structure
45
46typedef struct {
47    ListNode pathMountsHead;   // sandbox mount_path list head
48    ListNode fileMountsHead;   // sandbox mount_file list head
49    ListNode linksHead;        // sandbox symbolic link list head
50    char *rootPath;            // /mnt/sandbox/system|vendor|xxx
51    char name[MAX_BUFFER_LEN]; // name of sandbox. i.e system, chipset etc.
52    bool isCreated;            // sandbox already created or not
53    int ns;                    // namespace
54} sandbox_t;
55```
56### Procedure
571. Create a sandbox.
58      - 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).
59      - By default, the sandbox function of a service is enabled. If you do not want to move the service to the sandbox, set **sandbox** to **0** in the **.cfg** file. Otherwsie, set **sandbox** to **1**.
60        ```
61        "sandbox" : 1
62        ```
63
642.  Modify the JSON file configuration of the sandbox.
65    - Go to the **/system/etc/sandbox/** directory, and run **cat system-sandbox.json** and **cat chipset-sandbox.json**.
66     If you are using a 64-bit system, run **cat system-sandbox64.json** and **cat chipset-sandbox64.json** instead.
67    - Modify the sandbox configuration files in the **base/startup/init/interfaces/innerkits/sandbox** directory. After that, restart the system.
68
69### Development Example
70JSON file configuration of the sandbox:
71
72```json
73{
74    "sandbox-root" : "/mnt/sandbox/system",
75    "mount-bind-paths" : [{
76        "src-path" : "/system/lib/ndk",
77        "sandbox-path" : "/system/lib/ndk",
78        "sandbox-flags" : [ "bind", "rec", "private" ]
79    }],
80    "mount-bind-files" : [{
81        "src-path" : "/system/lib/ld-musl-aarch64.so.1",
82        "sandbox-path" : "/system/lib/ld-musl-aarch64.so.1",
83        "sandbox-flags" : [ "bind", "rec", "private" ]
84    }],
85    "symbol-links" : [{
86        "target-name" : "/vendor/lib",
87        "link-name" : "/lib"
88    }]
89}
90```
91
92## FAQs
93- **Cause Analysis**
94     Related services cannot access required resource files such as **.so** file.
95- **Solution**
96    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:
97
98    - Search for keyword **failed** or **.so** in hilog.
99
100      ```
101      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)
102      08-05 17:27:29.303   488   488 E C02500/devhost_service_full: DevHostServiceAddDevice failed and return -207
103      08-05 17:27:29.305   488   488 E C02500/devhost_service_stub: Dis patch failed, add service failed and ret is -207
104      08-05 17:27:29.307   488   488 I C02500/devhost_service_stub: add device 0x7000201
105      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
106      ```
107
108    - 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.
109
110      - Method 1: Mount the file in the sandbox for quick recovery. (Only local debugging is supported, and source code modification needs to be reviewed.)
111
112        - 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.
113
114        - 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.
115
116        - For the preceding case, add the following information to /system/etc/sandbox/chipset-sandbox.json:
117
118        ```
119        "mount-bind-files" : [
120        	{
121                "src-path" : "/system/lib/libdisplay_buffer_proxy_1.0.z.so",
122                "sandbox-path" : "/system/lib/libdisplay_buffer_proxy_1.0.z.so",
123                "sandbox-flags" : [ "bind", "rec", "private" ]
124            },{...}
125        ],
126        ```
127
128      - Method 2: Add **innerapi_tags** to the **BUILD.gn** file.
129
130        ```
131        ohos_shared_library("xxx") {
132        	...
133        	innerapi_tags = [
134            	"chipsetsdk",
135            ]
136        }
137        ```
138
139      - Description of **innerapi_tags**:
140
141        -   Tags related to sandbox permissions include **passthrough**, **chipsetsdk**, **passthrough_indirect**, and **chipsetsdk_indirect**.
142
143          -  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**.
144          -  For the **.so** files installed in the system directory, use **chipsetsdk** and **chipsetsdk_indirect** for access by chip components.
145          -  For the **.so** files installed in the chip directory, use **passthrough** and **passthrough_indirect** for access by system components.
146        -  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**.
147        ```gni
148        # auto set auto_relative_install_dir by innerapi_tags
149        if (defined(invoker.innerapi_tags)) {
150      	    is_chipsetsdk = false
151            is_platformsdk = false
152            is_passthrough = false
153            foreach(tag, filter_include(invoker.innerapi_tags, [ "chipsetsdk*" ])) {
154              is_chipsetsdk = true
155            }
156            foreach(tag, filter_include(invoker.innerapi_tags, [ "platformsdk*" ])) {
157              is_platformsdk = true
158            }
159            foreach(tag, filter_include(invoker.innerapi_tags, [ "passthrough*" ])) {
160              is_passthrough = true
161            }
162            if (is_chipsetsdk && is_platformsdk) {
163              auto_relative_install_dir = "chipset-pub-sdk"
164            } else if (is_chipsetsdk) {
165              auto_relative_install_dir = "chipset-sdk"
166            } else if (is_platformsdk) {
167              auto_relative_install_dir = "platformsdk"
168            }
169            if (is_passthrough) {
170              auto_relative_install_dir = chipset_passthrough_dir
171            }
172            ...
173        }
174