207 lines
8.1 KiB
Markdown
207 lines
8.1 KiB
Markdown
# Occlum Configuration
|
||
|
||
Occlum can be configured easily via a configuration file named `Occlum.json`, which is generated by the `occlum init` command in the Occlum instance directory. The user can modify `Occlum.json` to configure Occlum.
|
||
|
||
The template of `Occlum.json` is shown below.
|
||
|
||
## Default Legacy Mode (without EDMM support)
|
||
|
||
```json
|
||
{
|
||
// Resource limits
|
||
"resource_limits": {
|
||
// The total size of enclave memory available to LibOS processes
|
||
"user_space_size": "256MB",
|
||
// The heap size of LibOS kernel
|
||
"kernel_space_heap_size": "32MB",
|
||
// The stack size of LibOS kernel
|
||
"kernel_space_stack_size": "1MB",
|
||
// The max number of LibOS threads/processes
|
||
"max_num_of_threads": 32
|
||
},
|
||
// Process
|
||
"process": {
|
||
// The stack size of the "main" thread
|
||
"default_stack_size": "4MB",
|
||
// The max size of memory allocated by brk syscall
|
||
"default_heap_size": "16MB",
|
||
// The max size of memory by mmap syscall (OBSOLETE. Users don't need to modify this field. Keep it only for compatibility)
|
||
"default_mmap_size": "32MB"
|
||
},
|
||
// Entry points
|
||
//
|
||
// Entry points specify all valid path prefixes for <path> in `occlum run
|
||
// <path> <args>`. This prevents outside attackers from executing arbitrary
|
||
// commands inside an Occlum-powered enclave.
|
||
"entry_points": [
|
||
"/bin"
|
||
],
|
||
// Environment variables
|
||
//
|
||
// This gives a list of environment variables for the "root"
|
||
// process started by `occlum exec` command.
|
||
"env": {
|
||
// The default env vars given to each "root" LibOS process. As these env vars
|
||
// are specified in this config file, they are considered trusted.
|
||
"default": [
|
||
"OCCLUM=yes"
|
||
],
|
||
// The untrusted env vars that are captured by Occlum from the host environment
|
||
// and passed to the "root" LibOS processes. These untrusted env vars can
|
||
// override the trusted, default envs specified above.
|
||
"untrusted": [
|
||
"EXAMPLE"
|
||
]
|
||
},
|
||
// Enclave metadata
|
||
"metadata": {
|
||
// Enclave signature structure's ISVPRODID field
|
||
"product_id": 0,
|
||
// Enclave signature structure's ISVSVN field
|
||
"version_number": 0,
|
||
// Whether the enclave is debuggable through special SGX instructions.
|
||
// For production enclave, it is IMPORTANT to set this value to false.
|
||
"debuggable": true,
|
||
// Whether the enclave is allowable to print Occlum log.
|
||
// Optional, if not set, in default it is false for debuggable enclave
|
||
// but true for production/release enclave for better security.
|
||
// Production/release enclave could explicitly set it false to have log
|
||
// output for debugging purpose. In this case, error log level is the
|
||
// only allowed log level.
|
||
"disable_log": false,
|
||
},
|
||
// Features
|
||
"feature": {
|
||
// Determines the use of the IO_Uring feature in Occlum for network I/O operations.
|
||
// Enabling IO_Uring feature can improve network I/O performance.
|
||
//
|
||
// "io_uring": 0 - Disables IO_Uring; network I/O uses Ocall instead.
|
||
// "io_uring": 1 - Enables IO_Uring with a single IO_Uring instance.
|
||
// "io_uring": n (1 < n <= 16) - Enables IO_Uring with 'n' IO_Uring instances.
|
||
"io_uring": 0,
|
||
// Whether to turn on AMX feature in Occlum
|
||
// Occlum supports AMX instruction running inside the enclave when user enables it
|
||
//
|
||
// "amx" = 0: AMX feature must be disabled
|
||
// "amx" = 1: AMX feature must be enabled
|
||
// "amx" = 2: AMX feature is enabled if the platform supports it
|
||
"amx": 0,
|
||
// Whether to turn on PKU feature in Occlum
|
||
// Occlum uses PKU for isolation between LibOS and userspace program,
|
||
// It is useful for developers to detect potential bugs.
|
||
//
|
||
// "pkru" = 0: PKU feature must be disabled
|
||
// "pkru" = 1: PKU feature must be enabled
|
||
// "pkru" = 2: PKU feature is enabled if the platform supports it
|
||
"pkru": 0,
|
||
// Whether to enable the EDMM feature
|
||
// Enabling EDMM feature can make the enclave initialize faster and sometimes can also
|
||
// bring performance benifit for the entire application
|
||
//
|
||
// Enabling EDMM feature will need more configuration on the memory related fields, for more information,
|
||
// please visit [EDMM Configuration Guide](https://github.com/occlum/occlum/blob/master/docs/edmm/edmm_config_guide.md)
|
||
"enable_edmm": false,
|
||
// Whether to enable POSIX shared memory feature
|
||
// Enabling POSIX shm allows processes to communicate by sharing a region of memory
|
||
//
|
||
// Set "enable_posix_shm" to true, the syscall `mmap` with flag `MAP_SHARED`
|
||
// is supported more comprehensively, implies that the file-backed memory mapping
|
||
// become shared among processes.
|
||
// More API information of POSIX shm is listed in [shm_overview](https://man7.org/linux/man-pages/man7/shm_overview.7.html).
|
||
"enable_posix_shm": false
|
||
},
|
||
// Mount points and their file systems
|
||
//
|
||
// The default configuration is shown below.
|
||
"mount": [
|
||
{
|
||
"target": "/",
|
||
"type": "unionfs",
|
||
"options": {
|
||
"layers": [
|
||
{
|
||
"target": "/",
|
||
"type": "sefs",
|
||
"source": "./build/mount/__ROOT",
|
||
"options": {
|
||
"MAC": ""
|
||
}
|
||
},
|
||
{
|
||
"target": "/",
|
||
"type": "sefs",
|
||
"source": "./run/mount/__ROOT"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
{
|
||
"target": "/host",
|
||
"type": "hostfs",
|
||
"source": "."
|
||
},
|
||
{
|
||
"target": "/proc",
|
||
"type": "procfs"
|
||
},
|
||
{
|
||
"target": "/dev",
|
||
"type": "devfs"
|
||
},
|
||
{
|
||
"target": "/ext2",
|
||
"type": "ext2",
|
||
"options": {
|
||
"disk_size": "10GB"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## EDMM Configuration Add-on
|
||
|
||
In general, three optional fields have been added to the existing Occlum.json configuration: `kernel_space_heap_max_size`, `user_space_max_size`, and `init_num_of_threads`. An example of the memory section configuration in `Occlum.json` when all the EDMM-related configurations are enabled:
|
||
|
||
```json
|
||
{
|
||
"resource_limits": {
|
||
"kernel_space_stack_size": "1MB", // (Legacy, Required)
|
||
"kernel_space_heap_size": "4MB", // (Legacy, Required)
|
||
"kernel_space_heap_max_size": "40MB", // !!! (Newly-Introduced，Optional)
|
||
"user_space_size": "1MB", // (Legacy, Required)
|
||
"user_space_max_size": "600MB", // !!! (Newly-Introduced，Optional)
|
||
"init_num_of_threads": 2, // !!! (Newly-Introduced，Optional)
|
||
"max_num_of_threads": 64 // (Legacy, Required)
|
||
},
|
||
"process": {
|
||
"default_stack_size": "4MB", // (Legacy, Required)
|
||
"default_heap_size": "8MB", // (Legacy, Required)
|
||
"default_mmap_size": "100MB" // (Legacy, Required, but inoperative)
|
||
},
|
||
}
|
||
```
|
||
|
||
More details please refer to [edmm_config_guide](./edmm_config_guide.md).
|
||
|
||
## Runtime Resource Configuration for Occlum process
|
||
|
||
Occlum has enabled per process resource configuration via [prlimit](https://man7.org/linux/man-pages//man2/prlimit.2.html) syscall and shell built-in command [ulimit](https://fishshell.com/docs/current/cmds/ulimit.html).
|
||
|
||
```shell
|
||
#! /usr/bin/bash
|
||
ulimit -a
|
||
|
||
# ulimit defined below will override configuration in Occlum.json
|
||
ulimit -Ss 10240 # stack size 10M
|
||
ulimit -Sd 40960 # heap size 40M
|
||
ulimit -Sv 102400 # virtual memory size 100M (including heap, stack, mmap size)
|
||
|
||
echo "ulimit result:"
|
||
ulimit -a
|
||
|
||
# Run applications with the new resource limits
|
||
...
|
||
```
|
||
|
||
For more info, please check [demos/fish](https://github.com/occlum/occlum/tree/master/demos/fish). |