| /* Copyright 2016 The Chromium OS Authors. All rights reserved. |
| * Use of this source code is governed by a BSD-style license that can be |
| * found in the LICENSE file. |
| */ |
| |
| #ifndef LIBCONTAINER_LIBCONTAINER_H_ |
| #define LIBCONTAINER_LIBCONTAINER_H_ |
| |
| #include <stddef.h> |
| #include <stdint.h> |
| #include <sys/resource.h> |
| #include <sys/types.h> |
| |
| #include <brillo/brillo_export.h> |
| #include <libminijail.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| struct container_config; |
| |
| /* Create a container config. */ |
| BRILLO_EXPORT struct container_config* container_config_create(void); |
| |
| /* Destroy a config create with container_config_create. */ |
| BRILLO_EXPORT void container_config_destroy(struct container_config* c); |
| |
| /* config_root - Path to the root of the container itself. */ |
| BRILLO_EXPORT int container_config_config_root(struct container_config* c, |
| const char* config_root); |
| |
| /* Get the configured container root path. */ |
| BRILLO_EXPORT const char* container_config_get_config_root( |
| const struct container_config* c); |
| |
| /* rootfs - Path to the root of the container's filesystem. */ |
| BRILLO_EXPORT int container_config_rootfs(struct container_config* c, |
| const char* rootfs); |
| |
| /* Get the configured rootfs path. */ |
| BRILLO_EXPORT const char* container_config_get_rootfs( |
| const struct container_config* c); |
| |
| /* rootfs_mount_flags - Flags that will be passed to the mount() call when |
| * mounting the root of the container's filesystem. */ |
| BRILLO_EXPORT void container_config_rootfs_mount_flags( |
| struct container_config* c, unsigned long flags); |
| |
| /* Get the configured rootfs mount() flags. */ |
| BRILLO_EXPORT unsigned long container_config_get_rootfs_mount_flags( |
| const struct container_config* c); |
| |
| /* runfs - Path to where the container filesystem has been mounted. */ |
| BRILLO_EXPORT int container_config_premounted_runfs(struct container_config* c, |
| const char* runfs); |
| |
| /* Get the pre-mounted runfs path. */ |
| BRILLO_EXPORT const char* container_config_get_premounted_runfs( |
| const struct container_config* c); |
| |
| /* The pid of the program will be written here. */ |
| BRILLO_EXPORT int container_config_pid_file(struct container_config* c, |
| const char* path); |
| |
| /* Get the pid file path. */ |
| BRILLO_EXPORT const char* container_config_get_pid_file( |
| const struct container_config* c); |
| |
| /* The program to run and args, e.g. "/sbin/init", "--second-stage". */ |
| BRILLO_EXPORT int container_config_program_argv(struct container_config* c, |
| const char** argv, |
| size_t num_args); |
| |
| /* Get the number of command line args for the program to be run. */ |
| BRILLO_EXPORT size_t |
| container_config_get_num_program_args(const struct container_config* c); |
| |
| /* Get the program argument at the given index. */ |
| BRILLO_EXPORT const char* container_config_get_program_arg( |
| const struct container_config* c, size_t index); |
| |
| /* Sets/Gets the uid the container will run as. */ |
| BRILLO_EXPORT void container_config_uid(struct container_config* c, uid_t uid); |
| BRILLO_EXPORT uid_t container_config_get_uid(const struct container_config* c); |
| |
| /* Mapping of UIDs in the container, e.g. "0 100000 1024" */ |
| BRILLO_EXPORT int container_config_uid_map(struct container_config* c, |
| const char* uid_map); |
| |
| /* Sets/Gets the gid the container will run as. */ |
| BRILLO_EXPORT void container_config_gid(struct container_config* c, gid_t gid); |
| BRILLO_EXPORT gid_t container_config_get_gid(const struct container_config* c); |
| |
| /* Mapping of GIDs in the container, e.g. "0 100000 1024" */ |
| BRILLO_EXPORT int container_config_gid_map(struct container_config* c, |
| const char* gid_map); |
| |
| /* Sets the additional gids the container will run as. */ |
| BRILLO_EXPORT void container_config_additional_gids(struct container_config* c, |
| const gid_t* gids, |
| size_t num_gids); |
| |
| /* Alt-Syscall table to use or NULL if none. */ |
| BRILLO_EXPORT int container_config_alt_syscall_table( |
| struct container_config* c, const char* alt_syscall_table); |
| |
| /* Add a runtime limit for the contained process. */ |
| BRILLO_EXPORT int container_config_add_rlimit(struct container_config* c, |
| int type, |
| rlim_t cur, |
| rlim_t max); |
| |
| /* |
| * Add a filesystem to mount in the new VFS namespace. |
| * |
| * c - The container config in which to add the mount. |
| * source - Mount source, e.g. "tmpfs" or "/data". |
| * destination - Mount point in the container, e.g. "/dev". |
| * type - Mount type, e.g. "tmpfs", "selinuxfs", or "devpts". |
| * data - Mount data for extra options, e.g. "newinstance" or "ptmxmode=0000". |
| * verity - dm-verity options (if used). |
| * flags - Mount flags as defined in mount(2). |
| * uid - uid to chown mount point to if created. |
| * gid - gid to chown mount point to if created. |
| * mode - Permissions of mount point if created. |
| * mount_in_ns - True if mount should happen in the process' vfs namespace. |
| * create - If true, create mount destination if it doesn't exist. |
| * loopback - If true, set up a loopback device and mount that. |
| */ |
| BRILLO_EXPORT int container_config_add_mount(struct container_config* c, |
| const char* name, |
| const char* source, |
| const char* destination, |
| const char* type, |
| const char* data, |
| const char* verity, |
| int flags, |
| int uid, |
| int gid, |
| int mode, |
| int mount_in_ns, |
| int create, |
| int loopback); |
| |
| /* |
| * Add a device cgroup permission. |
| * |
| * c - The container config in which to add the mount. |
| * allow - If true allow access to the specified r/w/m. |
| * type - 'c', 'b', or 'a' for char, block, or all respectively. |
| * major - Major device number. |
| * minor - Minor device number. |
| * read - If true set reading of device to |allow|. |
| * write - If true set writing of device to |allow|. |
| * modify - If true set modifying of device to |allow|. |
| */ |
| BRILLO_EXPORT int container_config_add_cgroup_device(struct container_config* c, |
| int allow, |
| char type, |
| int major, |
| int minor, |
| int read, |
| int write, |
| int modify); |
| |
| /* |
| * Add a device node to create. |
| * |
| * c - The container config in which to add the mount. |
| * type - 'c' or 'b' for char or block respectively. |
| * path - Where to mknod, "/dev/zero". |
| * fs_permissions - Permissions to set on the node. |
| * major - Major device number. |
| * minor - Minor device number. |
| * copy_major - Overwrite major with the major of the existing device node. If |
| * this is true major will be copied from an existing node. The |major| param |
| * should be set to -1 in this case. |
| * copy_minor - Overwrite minor with the minor of the existing device node. If |
| * this is true minor will be copied from an existing node. The |minor| param |
| * should be set to -1 in this case. |
| * uid - User to own the device. |
| * gid - Group to own the device. |
| * read_allowed - If true allow reading from the device via "devices" cgroup. |
| * write_allowed - If true allow writing to the device via "devices" cgroup. |
| * modify_allowed - If true allow creation of the device via "devices" cgroup. |
| */ |
| BRILLO_EXPORT int container_config_add_device(struct container_config* c, |
| char type, |
| const char* path, |
| int fs_permissions, |
| int major, |
| int minor, |
| int copy_major, |
| int copy_minor, |
| int uid, |
| int gid, |
| int read_allowed, |
| int write_allowed, |
| int modify_allowed); |
| |
| /* Set the CPU shares cgroup param for container. */ |
| BRILLO_EXPORT int container_config_set_cpu_shares(struct container_config* c, |
| int shares); |
| |
| /* Set the CFS CPU cgroup params for container. */ |
| BRILLO_EXPORT int container_config_set_cpu_cfs_params( |
| struct container_config* c, int quota, int period); |
| |
| /* Set the RT CPU cgroup params for container. */ |
| BRILLO_EXPORT int container_config_set_cpu_rt_params(struct container_config* c, |
| int rt_runtime, |
| int rt_period); |
| |
| BRILLO_EXPORT int container_config_get_cpu_shares(struct container_config* c); |
| BRILLO_EXPORT int container_config_get_cpu_quota(struct container_config* c); |
| BRILLO_EXPORT int container_config_get_cpu_period(struct container_config* c); |
| BRILLO_EXPORT int container_config_get_cpu_rt_runtime( |
| struct container_config* c); |
| BRILLO_EXPORT int container_config_get_cpu_rt_period( |
| struct container_config* c); |
| |
| /* Set core scheduling policy to disable sibling core sharing. */ |
| BRILLO_EXPORT int container_config_set_core_sched(struct container_config* c, |
| int enable); |
| |
| /* |
| * Configure the owner of cgroups created for the container. |
| * |
| * This is needed so the container's cgroup namespace rootdir is accessible |
| * inside the container. |
| * |
| * cgroup_parent - Parent directory under which to create the cgroup. |
| * cgroup_owner - The uid that should own the cgroups that are created. |
| * cgroup_group - The gid that should own the cgroups that are created. |
| */ |
| BRILLO_EXPORT int container_config_set_cgroup_parent(struct container_config* c, |
| const char* parent, |
| uid_t cgroup_owner, |
| gid_t cgroup_group); |
| |
| /* Get the parent cgroup directory from the config. Here for UT only. */ |
| BRILLO_EXPORT const char* container_config_get_cgroup_parent( |
| struct container_config* c); |
| |
| /* Set namespaces to be used by the container. */ |
| BRILLO_EXPORT int container_config_namespaces(struct container_config* c, |
| const char** namespaces, |
| size_t num_ns); |
| |
| /* Get the number of namespaces to enter. */ |
| BRILLO_EXPORT size_t |
| container_config_get_num_namespaces(const struct container_config* c); |
| |
| /* Get the namespace at the given index. */ |
| BRILLO_EXPORT bool container_config_has_namespace( |
| const struct container_config* c, const char* ns); |
| |
| /* |
| * Configures the container so that any FDs open in the parent process are still |
| * visible to the child. Useful for apps that need stdin/stdout/stderr. Use |
| * with caution to avoid leaking other FDs into the namespaced app. |
| */ |
| BRILLO_EXPORT void container_config_keep_fds_open(struct container_config* c); |
| |
| /* |
| * Sets the capability mask of the container to |capmask|. If |ambient| is 1 it |
| * will additionally set the ambient capability set. |
| */ |
| BRILLO_EXPORT void container_config_set_capmask(struct container_config* c, |
| uint64_t capmask, |
| int ambient); |
| |
| /* |
| * Skips settings the securebits in |securebits_skip_mask| when restricting |
| * capabilities. This is only used when container_config_set_capmask() is used. |
| */ |
| BRILLO_EXPORT void container_config_set_securebits_skip_mask( |
| struct container_config* c, uint64_t securebits_skip_mask); |
| |
| /* |
| * Sets whether the container's entry point should run as init. An init process |
| * is responsible for setting up certain paths within the container (such as |
| * /proc) and performing explicit reaping of zombie processes. The container |
| * will also be torn down if the init process is killed. |
| * The default is true. |
| */ |
| BRILLO_EXPORT void container_config_set_run_as_init(struct container_config* c, |
| int run_as_init); |
| |
| /* |
| * Sets the SELinux context under which the container will run. |
| */ |
| BRILLO_EXPORT int container_config_set_selinux_context( |
| struct container_config* c, const char* context); |
| |
| /* |
| * Sets a pre-execve hook that is run in the child process just before the |
| * container invokes execve(2). If this is used to run a pre-start hook which |
| * should run in the caller's context, a synchronization mechanism (such as a |
| * pair of pipes or sending messages through a unix domain pipe) should be used |
| * to ensure this hook blocks until the pre-start hook finishes running. The |
| * file descriptors used to synchronize this can be passed using |
| * container_config_inherit_fds(). |
| */ |
| BRILLO_EXPORT void container_config_set_pre_execve_hook( |
| struct container_config* c, int (*hook)(void*), void* payload); |
| |
| /* |
| * Adds a hook that will be run, execve(2)-style. This new process will be run |
| * outside the container in the original namespace. Any parameters that are |
| * equal to the magic value "$PID" will be replaced with the container's PID. If |
| * |pstdin_fd|, |pstdout_fd|, or |pstderr_fd| are set to non-null values, they |
| * will contain valid file descriptors that can be used to communicate with the |
| * process. |
| */ |
| BRILLO_EXPORT int container_config_add_hook(struct container_config* c, |
| minijail_hook_event_t event, |
| const char* filename, |
| const char** argv, |
| size_t num_args, |
| int* pstdin_fd, |
| int* pstdtout_fd, |
| int* pstderr_fd); |
| |
| /* |
| * Sets the set of file descriptors to inherit. |
| */ |
| BRILLO_EXPORT int container_config_inherit_fds(struct container_config* c, |
| const int* inherited_fds, |
| size_t inherited_fd_count); |
| |
| /* Container manipulation. */ |
| struct container; |
| |
| /* |
| * Create a container based on the given config. |
| * |
| * name - Name of the directory holding the container config files. |
| * rundir - Where to build the temporary rootfs. |
| */ |
| BRILLO_EXPORT struct container* container_new(const char* name, |
| const char* rundir); |
| |
| /* Destroy a container created with container_new. */ |
| BRILLO_EXPORT void container_destroy(struct container* c); |
| |
| /* Start the container. Returns 0 on success. |
| * c - The container to run. |
| * config - Details of how the container should be run. |
| */ |
| BRILLO_EXPORT int container_start(struct container* c, |
| const struct container_config* config); |
| |
| /* Get the path to the root of the container. */ |
| BRILLO_EXPORT const char* container_root(struct container* c); |
| |
| /* Get the pid of the init process in the container. */ |
| BRILLO_EXPORT int container_pid(struct container* c); |
| |
| /* Wait for the container to exit. Returns 0 on success. */ |
| BRILLO_EXPORT int container_wait(struct container* c); |
| |
| /* Kill the container's init process, then wait for it to exit. */ |
| BRILLO_EXPORT int container_kill(struct container* c); |
| |
| /* Dumps the container config. The returned string has to be passed to free() |
| when it is no longer needed. |
| c - The config to dump. |
| sort_vectors - When not 0, the function sorts the list of mount points, |
| devices, and cgroups before dumping to make it easier to |
| compare two dumps side by side. |
| */ |
| BRILLO_EXPORT char* container_config_dump(struct container_config* c, |
| int sort_vectors); |
| |
| #ifdef __cplusplus |
| }; /* extern "C" */ |
| #endif |
| |
| #endif /* LIBCONTAINER_LIBCONTAINER_H_ */ |
