blob: 1978aa369808dbb2477db50cf11490811afdbe98 [file] [log] [blame]
/* 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.
#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" {
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. */
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. */
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" */