occlum/docs/readthedocs/docs/source/occlum_configuration.md

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)

{
    // 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:

{
  "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.

Runtime Resource Configuration for Occlum process

Occlum has enabled per process resource configuration via prlimit syscall and shell built-in command ulimit.

#! /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.