Container Configuration Files Guide¶

This document describes the per-container configuration files used by Container Manager.

Overview¶

Container Configuration Files contain detailed configuration for individual containers, specifying root filesystem, devices, network interfaces, resource limits, and other container-specific settings.

Each container has its own JSON configuration file (e.g., cluster-demo.json) stored in the directory specified by the global configdir setting.

Container manager recommend to crate these directories per container.

For rootfs mount point:

/opt/container/guests/my-container/rootfs

/opt/container/guests/my-container/nv

/opt/container/guests/my-container/shmounts

Container manager supports A/B boot. It controls by 'aglabboot' in kernel commandline. If it sets '0', container manager select 1st device. If it sets '1', container manager select 2nd device.

Container Configuration Files¶

Detailed configuration for individual containers.

Minimum Configuration Example¶

{
    "name": "my-container",
    "role": "service",
    "base": {
        "autoboot": true,
        "bootpriority": 100,
        "rootfs": {
            "path": "/opt/container/guests/my-container/rootfs",
            "filesystem": "ext4",
            "mode": "rw",
            "blockdev": [
                "/dev/mmcblk1p2",
                "/dev/mmcblk1p2"
            ]
        }
    }
}

Top-level Configuration Items¶

name (Required)¶

• Type: String
• Description: Container name
• Example: "cluster-demo","momi-ivi-demo"

role (Optional)¶

• Type: String
• Description: Container role (user-defined)
• Note: When it not set, role is set container name
• Example: "cluster", "ivi", "rse"

base (Required)¶

• Type: Object
• Description: Basic container configuration

fs (Optional)¶

• Type: Object
• Description: Filesystem configuration

device (Optional)¶

• Type: Object
• Description: Device configuration

network (Optional)¶

• Type: Object
• Description: Network configuration

resource (Optional)¶

• Type: Array
• Description: Resource limit configuration

Section 1: base (Basic Configuration)¶

"base": {
    "autoboot": true,
    "bootpriority": 1,
    "rootfs": { ... },
    "extradisk": [ ... ],
    "extended": { ... },
    "lifecycle": { ... },
    "cap": { ... },
    "tty": { ... },
    "idmap": { ... },
    "environment": [ ... ]
}

base Configuration Items¶

autoboot¶

• Type: Boolean
• Default: false
• Description: Whether to auto-start during boot
• Example: true, false

bootpriority¶

• Type: Number
• Default: 1000
• Description: Boot priority (lower values have higher priority)
• Example: 1, 100, 1000

rootfs (Required)¶

• Type: Object
• Description: Root filesystem configuration

rootfs Details:

Root filesystem use partition.

"rootfs": {
    "path": "/opt/container/guests/my-container/rootfs",
    "filesystem": "ext4",
    "mode": "rw",
    "option": "defaults",
    "blockdev": [
        "/dev/mmcblk1p2",
        "/dev/mmcblk1p2"
    ]
}

Or host filesystem bind mount:

"rootfs": {
    "path": "/container/rootfs",
    "mode": "ro",
    "hostpath": [
        "/host/rootfs",
        null
    ]
}

If you want to use block device mode.¶

Block device selection of blockdev is depend on 'aglabboot' settings.

If you do not use A/B mode, blockdev value should set 2nd value same as 1st value.

If you want to use host filesystem bind mode.¶

extradisk (Optional)¶

• Type: Array
• Description: Array of additional disk configurations

"extradisk": [
    {
        "from": "/opt/container/guests/my-container/nv",
        "to": "var/nonvolatile",
        "filesystem": "ext4",
        "mode": "rw",
        "option": "defaults",
        "redundancy": "failover",
        "blockdev": [
            "/dev/mmcblk1p4",
            null
        ]
    }
]

If you set failover to redundancy:
If mount operation is failed, it failover. It uses only first device on blockdev.

If you set ab to redundancy:
Block device selection of blockdev is depend on 'aglabboot' settings.

If you set fsck to redundancy:
If mount operation is failed, it execs fsck. It uses only first device on blockdev.

If you set mkfs to redundancy:
If mount operation is failed, it execs mkfs. It uses only first device on blockdev.

extended (Optional)¶

• Type: Object
• Description: Extended configuration

"extended": {
    "shmounts": "/opt/container/guests/xxx/shmounts"
}

shmounts: It sets to temporary directory for dynamic mount. If it is set "disable", the dynamic mount is disabled.

lifecycle (Optional)¶

• Type: Object
• Description: Container startup and shutdown signal configuration

"lifecycle": {
    "halt": "SIGRTMIN+3",
    "reboot": "SIGTERM",
    "timeout": 5000
}

cap (Optional)¶

• Type: Object
• Description: Linux capability configuration

"cap": {
    "drop": "sys_module mac_admin mac_override sys_time",
    "keep": "net_admin sys_admin"
}

Refer to man page for capabilities.

tty (Optional)¶

• Type: Object
• Description: TTY/PTY configuration

"tty": {
    "tty": 1,
    "pty": 1
}

idmap (Optional)¶

• Type: Object
• Description: UID/GID mapping configuration

"idmap": {
    "uid": {
        "guestroot": 0,
        "hostidstart": 100000,
        "num": 65536
    },
    "gid": {
        "guestroot": 0,
        "hostidstart": 100000,
        "num": 65536
    }
}

uid (Optional)¶

• Type: Object
• Description: UID mapping

gid (Optional)¶

• Type: Object
• Description: GID mapping

environment (Optional)¶

• Type: Array
• Description: Environment variable configuration

"environment": [
    "HOME=/home/root",
    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
]

The array for environment variable to set in guest.

Section 2: fs (Filesystem Configuration)¶

"fs": {
    "mount": [
        {
            "type": "filesystem",
            "from": "tmpfs",
            "to": "run",
            "fstype": "tmpfs",
            "option": "defaults 0 0"
        },
        {
            "type": "directory",
            "from": "/sys/kernel/security",
            "to": "sys/kernel/security",
            "fstype": "none",
            "option": "ro,bind,optional 0 0"
        },
        {
            "type": "delayed",
            "from": "/run/user/1000",
            "to": "run/user"
        }
    ]
}

mount Configuration Items¶

type values: - "filesystem": Mount a new filesystem - "directory": Bind mount a directory - "delayed": Delayed mount (If 'from' directory will be detected, it mount at that time.). If you want to use it, you shall enable "shmounts" in "extended".

Section 3: device (Device Configuration)¶

"device": {
    "protection": "disable",
    "static": [ ... ],
    "dynamic": [ ... ]
}

protection¶

• Type: String
• Default: Enabled (cgroup device protection)
• Value: Set to "disable" to disable. Set to "enable" to enable.

3.1 static (Static Devices)¶

"static": [
    {
        "type": "devnode",
        "from": "/dev/pvr_sync",
        "to": "dev/pvr_sync",
        "devnode": "/dev/pvr_sync",
        "optional": 0,
        "wideallow": 0,
        "exclusive": 0
    },
    {
        "type": "devdir",
        "from": "/dev/dri",
        "to": "dev/dri",
        "devnode": "/dev/dri/card0",
        "optional": 0,
        "wideallow": 1,
        "exclusive": 0
    },
    {
        "type": "gpio",
        "port": 42,
        "direction": "out",
        "from": "/sys/devices/platform/soc/e6055400.gpio/gpiochip6/gpio/gpio381",
        "to": "sys/devices/platform/soc/e6055400.gpio/gpiochip6/gpio/gpio381"
    },
    {
        "type": "iio",
        "sysfrom": "/sys/bus/iio/devices/iio:device0",
        "systo": "sys/bus/iio/devices/iio:device0",
        "devfrom": "/dev/iio:device0",
        "devto": "dev/iio:device0",
        "devnode": "/dev/iio:device0",
        "optional": 0
    }
]

Details by type:

devnode (Device Node)¶

• Single device node

devdir (Device Directory)¶

- Entire device directory¶

gpio (GPIO)¶

• GPIO pin assignment

iio (Industrial I/O)¶

• Industrial I/O device

3.2 dynamic (Dynamic Devices)¶

T.B.D.

Section 4: network (Network Configuration)¶

"network": {
    "static": [
        {
            "type": "veth",
            "param": {
                "name": "veth0",
                "link": "lxcbr0",
                "flags": "up",
                "hwaddr": "00:16:3e:xx:xx:xx",
                "mode": "bridge",
                "address": "192.168.1.100/24",
                "gateway": "192.168.1.1"
            }
        },
        {
            "type": "vxcan",
            "param": {
                "name": "can0",
                "upstream": "can0"
            }
        }
    ]
}

static Network Interfaces¶

veth (Virtual Ethernet)¶

{
    "type": "veth",
    "param": {
        "name": "veth0",
        "link": "lxcbr0",
        "flags": "up",
        "hwaddr": "00:16:3e:xx:xx:xx",
        "mode": "bridge",
        "address": "192.168.1.100/24",
        "gateway": "192.168.1.1"
    }
}

vxcan (Virtual CAN)¶

{
    "type": "vxcan",
    "param": {
        "name": "can0",
        "upstream": "can0"
    }
}

TODO: Support CAN gateway filter.

Section 5: resource (Resource Limits)¶

"resource": [
    {
        "type": "cgroup",
        "object": "memory.max",
        "value": "512M"
    },
    {
        "type": "cgroupv2",
        "object": "memory.max",
        "value": "1G"
    },
    {
        "type": "prlimit",
        "object": "RLIMIT_NOFILE",
        "value": "4096"
    },
    {
        "type": "sysctl",
        "object": "net.ipv4.ip_forward",
        "value": "1"
    }
]

resource Configuration Items¶

type values: - "cgroup" / "cgroupv1": cgroup v1 limits - "cgroupv2": cgroup v2 limits - "prlimit": Process limits (getrlimit/setrlimit) - "sysctl": sysctl parameters

Complete Container Configuration Example¶

Refer to test/agl-data/*.json

Troubleshooting¶

Common Errors¶

1. "Json file error"¶

• JSON file format is invalid
• Verify that the file encoding is UTF-8
• Use a JSON validator to check the schema

2. "mandatory value"¶

• Required items are missing
• Check the "Required" column in the documentation

3. Device not found¶

• Verify the paths in blockdev, from, and to
• Check device existence: ls -la /dev/

4. Mount failure¶

• Verify the filesystem is correctly specified
• Ensure mount options are valid

5. Container not starting¶

• Verify the rootfs path exists and is accessible
• Check container name and role are set
• Verify boot priority is set correctly (lower = higher priority)

References¶

• Root Filesystem: The basic filesystem for containers
• Device Mapping: Exposing host devices to containers
• Network Isolation: Communication isolation via veth/vxcan
• Resource Limits: CPU/memory limits via cgroup
• cJSON: JSON parser library used internally