blob: c3aae86297af936e146175f6fa1929a0bb3e7448 [file] [log] [blame]
Dylan Reid837c74a2016-01-22 17:25:21 -08001/* Copyright 2016 The Chromium OS Authors. All rights reserved.
2 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
4 */
5
Luis Hector Chavez479b95f2016-06-06 08:01:05 -07006#ifndef LIBCONTAINER_LIBCONTAINER_H_
7#define LIBCONTAINER_LIBCONTAINER_H_
Dylan Reid837c74a2016-01-22 17:25:21 -08008
Dylan Reid2bd9ea92016-04-07 20:57:47 -07009#include <stddef.h>
Luis Hector Chavezff5978f2017-06-27 12:52:58 -070010#include <stdint.h>
Dylan Reid0bb592b2016-11-09 13:34:11 -080011#include <sys/types.h>
Dylan Reid837c74a2016-01-22 17:25:21 -080012
13#ifdef __cplusplus
14extern "C" {
15#endif
16
17struct container_config;
18
19/* Create a container config. */
20struct container_config *container_config_create();
21
22/* Destroy a config create with container_config_create. */
23void container_config_destroy(struct container_config *c);
24
Mike Frysingerb22acdf2017-01-08 02:02:35 -050025/* config_root - Path to the root of the container itself. */
26int container_config_config_root(struct container_config *c,
27 const char *config_root);
28
29/* Get the configured container root path. */
30const char *container_config_get_config_root(const struct container_config *c);
31
Dylan Reid837c74a2016-01-22 17:25:21 -080032/* rootfs - Path to the root of the container's filesystem. */
33int container_config_rootfs(struct container_config *c, const char *rootfs);
34
Dylan Reid11456722016-05-02 11:24:50 -070035/* Get the configured rootfs path. */
36const char *container_config_get_rootfs(const struct container_config *c);
37
Luis Hector Chavezc240e7e2016-09-22 10:33:03 -070038/* rootfs_mount_flags - Flags that will be passed to the mount() call when
39 * mounting the root of the container's filesystem. */
40void container_config_rootfs_mount_flags(struct container_config *c,
41 unsigned long flags);
42
43/* Get the configured rootfs mount() flags. */
44unsigned long container_config_get_rootfs_mount_flags(
45 const struct container_config *c);
46
Keshav Santhanam0e4c3282016-07-14 10:25:16 -070047/* runfs - Path to where the container filesystem has been mounted. */
Luis Hector Chavezc32a2e62016-09-23 09:19:16 -070048int container_config_premounted_runfs(struct container_config *c,
49 const char *runfs);
Keshav Santhanam0e4c3282016-07-14 10:25:16 -070050
51/* Get the pre-mounted runfs path. */
Luis Hector Chavezc32a2e62016-09-23 09:19:16 -070052const char *container_config_get_premounted_runfs(
53 const struct container_config *c);
Keshav Santhanam0e4c3282016-07-14 10:25:16 -070054
55/* The pid of the program will be written here. */
56int container_config_pid_file(struct container_config *c, const char *path);
57
58/* Get the pid file path. */
59const char *container_config_get_pid_file(const struct container_config *c);
60
Dylan Reid837c74a2016-01-22 17:25:21 -080061/* The program to run and args, e.g. "/sbin/init", "--second-stage". */
62int container_config_program_argv(struct container_config *c,
Dylan Reid17fd53f2016-11-18 19:14:41 -080063 const char **argv, size_t num_args);
Dylan Reid837c74a2016-01-22 17:25:21 -080064
Dylan Reid11456722016-05-02 11:24:50 -070065/* Get the number of command line args for the program to be run. */
66size_t container_config_get_num_program_args(const struct container_config *c);
67
68/* Get the program argument at the given index. */
69const char *container_config_get_program_arg(const struct container_config *c,
70 size_t index);
71
Dylan Reid1874feb2016-06-22 17:53:50 -070072/* Sets/Gets the uid the container will run as. */
73void container_config_uid(struct container_config *c, uid_t uid);
74uid_t container_config_get_uid(const struct container_config *c);
75
Dylan Reid837c74a2016-01-22 17:25:21 -080076/* Mapping of UIDs in the container, e.g. "0 100000 1024" */
77int container_config_uid_map(struct container_config *c, const char *uid_map);
78
Dylan Reid1874feb2016-06-22 17:53:50 -070079/* Sets/Gets the gid the container will run as. */
80void container_config_gid(struct container_config *c, gid_t gid);
81gid_t container_config_get_gid(const struct container_config *c);
82
Dylan Reid837c74a2016-01-22 17:25:21 -080083/* Mapping of GIDs in the container, e.g. "0 100000 1024" */
84int container_config_gid_map(struct container_config *c, const char *gid_map);
85
86/* Alt-Syscall table to use or NULL if none. */
87int container_config_alt_syscall_table(struct container_config *c,
88 const char *alt_syscall_table);
89
90/*
91 * Add a filesystem to mount in the new VFS namespace.
92 *
93 * c - The container config in which to add the mount.
94 * source - Mount source, e.g. "tmpfs" or "/data".
95 * destination - Mount point in the container, e.g. "/dev".
96 * type - Mount type, e.g. "tmpfs", "selinuxfs", or "devpts".
97 * data - Mount data for extra options, e.g. "newinstance" or "ptmxmode=0000".
Mike Frysinger05e594e2017-01-10 02:11:08 -050098 * verity - dm-verity options (if used).
Mike Frysinger412dbd22017-01-06 01:50:34 -050099 * flags - Mount flags as defined in mount(2).
Dylan Reid837c74a2016-01-22 17:25:21 -0800100 * uid - uid to chown mount point to if created.
101 * gid - gid to chown mount point to if created.
102 * mode - Permissions of mount point if created.
103 * mount_in_ns - True if mount should happen in the process' vfs namespace.
104 * create - If true, create mount destination if it doesn't exist.
Mike Frysinger412dbd22017-01-06 01:50:34 -0500105 * loopback - If true, set up a loopback device and mount that.
Dylan Reid837c74a2016-01-22 17:25:21 -0800106 */
107int container_config_add_mount(struct container_config *c,
108 const char *name,
109 const char *source,
110 const char *destination,
111 const char *type,
112 const char *data,
Mike Frysinger05e594e2017-01-10 02:11:08 -0500113 const char *verity,
Dylan Reid837c74a2016-01-22 17:25:21 -0800114 int flags,
115 int uid,
116 int gid,
117 int mode,
118 int mount_in_ns,
Mike Frysinger412dbd22017-01-06 01:50:34 -0500119 int create,
120 int loopback);
Dylan Reid837c74a2016-01-22 17:25:21 -0800121
122/*
Dylan Reid4843d6b2017-03-31 18:14:30 -0700123 * Add a device cgroup permission.
124 *
125 * c - The container config in which to add the mount.
126 * allow - If true allow access to the specified r/w/m.
127 * type - 'c', 'b', or 'a' for char, block, or all respectively.
128 * major - Major device number.
129 * minor - Minor device number.
130 * read - If true set reading of device to |allow|.
131 * write - If true set writing of device to |allow|.
132 * modify - If true set modifying of device to |allow|.
133 */
134int container_config_add_cgroup_device(struct container_config *c,
135 int allow,
136 char type,
137 int major,
138 int minor,
139 int read,
140 int write,
141 int modify);
142
143/*
Dylan Reid837c74a2016-01-22 17:25:21 -0800144 * Add a device node to create.
145 *
146 * c - The container config in which to add the mount.
147 * type - 'c' or 'b' for char or block respectively.
148 * path - Where to mknod, "/dev/zero".
149 * fs_permissions - Permissions to set on the node.
150 * major - Major device number.
151 * minor - Minor device number.
Dylan Reid355d5e42016-04-29 16:53:31 -0700152 * copy_minor - Overwrite minor with the minor of the existing device node. If
153 * this is true minor will be copied from an existing node. The |minor| param
154 * should be set to -1 in this case.
Dylan Reid837c74a2016-01-22 17:25:21 -0800155 * uid - User to own the device.
156 * gid - Group to own the device.
157 * read_allowed - If true allow reading from the device via "devices" cgroup.
158 * write_allowed - If true allow writing to the device via "devices" cgroup.
159 * modify_allowed - If true allow creation of the device via "devices" cgroup.
160 */
161int container_config_add_device(struct container_config *c,
162 char type,
163 const char *path,
164 int fs_permissions,
165 int major,
166 int minor,
Dylan Reid355d5e42016-04-29 16:53:31 -0700167 int copy_minor,
Dylan Reid837c74a2016-01-22 17:25:21 -0800168 int uid,
169 int gid,
170 int read_allowed,
171 int write_allowed,
172 int modify_allowed);
173
Dylan Reid2bd9ea92016-04-07 20:57:47 -0700174/*
175 * Set to cause the given setfiles command to be run whenever a mount is made
176 * in the parent mount namespace.
177 */
Luis Hector Chavez479b95f2016-06-06 08:01:05 -0700178int container_config_run_setfiles(struct container_config *c,
179 const char *setfiles_cmd);
Dylan Reid837c74a2016-01-22 17:25:21 -0800180
Dylan Reid11456722016-05-02 11:24:50 -0700181/* Get the setfiles command that is configured to be run. */
182const char *container_config_get_run_setfiles(const struct container_config *c);
183
Chinyue Chenfac909e2016-06-24 14:17:42 +0800184/* Set the CPU shares cgroup param for container. */
185int container_config_set_cpu_shares(struct container_config *c, int shares);
186
187/* Set the CFS CPU cgroup params for container. */
188int container_config_set_cpu_cfs_params(struct container_config *c,
189 int quota,
190 int period);
191
192/* Set the RT CPU cgroup params for container. */
193int container_config_set_cpu_rt_params(struct container_config *c,
194 int rt_runtime,
195 int rt_period);
196
Chinyue Chen4f3fd682016-07-01 14:11:42 +0800197int container_config_get_cpu_shares(struct container_config *c);
198int container_config_get_cpu_quota(struct container_config *c);
199int container_config_get_cpu_period(struct container_config *c);
200int container_config_get_cpu_rt_runtime(struct container_config *c);
201int container_config_get_cpu_rt_period(struct container_config *c);
202
Dylan Reid9e724af2016-07-21 09:58:07 -0700203/*
204 * Configure the owner of cgroups created for the container.
205 *
206 * This is needed so the container's cgroup namespace rootdir is accessible
207 * inside the container.
208 *
209 * cgroup_parent - Parent directory under which to create the cgroup.
210 * cgroup_owner - The uid that should own the cgroups that are created.
Dmitry Torokhov14eef722016-09-27 16:40:37 -0700211 * cgroup_group - The gid that should own the cgroups that are created.
Dylan Reid9e724af2016-07-21 09:58:07 -0700212 */
213int container_config_set_cgroup_parent(struct container_config *c,
214 const char *parent,
Dmitry Torokhov14eef722016-09-27 16:40:37 -0700215 uid_t cgroup_owner,
216 gid_t cgroup_group);
Dylan Reid9e724af2016-07-21 09:58:07 -0700217
218/* Get the parent cgroup directory from the config. Here for UT only. */
219const char *container_config_get_cgroup_parent(struct container_config *c);
220
Keshav Santhanam1b6bf672016-08-10 18:35:12 -0700221/* Enable sharing of the host's network namespace with the container */
222void container_config_share_host_netns(struct container_config *c);
223int get_container_config_share_host_netns(struct container_config *c);
224
Dylan Reidc4335842016-11-11 10:24:52 -0800225/*
226 * Configures the container so that any FDs open in the parent process are still
227 * visible to the child. Useful for apps that need stdin/stdout/stderr. Use
228 * with caution to avoid leaking other FDs into the namespaced app.
229 */
230void container_config_keep_fds_open(struct container_config *c);
231
Luis Hector Chavezff5978f2017-06-27 12:52:58 -0700232/*
233 * Sets the capability mask of the container to |capmask|. If |ambient| is 1 it
234 * will additionally set the ambient capability set.
235 */
236void container_config_set_capmask(struct container_config *c,
237 uint64_t capmask,
238 int ambient);
239
Dylan Reid837c74a2016-01-22 17:25:21 -0800240/* Container manipulation. */
241struct container;
242
243/*
244 * Create a container based on the given config.
245 *
246 * name - Name of the directory holding the container config files.
247 * rundir - Where to build the temporary rootfs.
Dylan Reid837c74a2016-01-22 17:25:21 -0800248 */
249struct container *container_new(const char *name,
Dylan Reide040c6b2016-05-02 18:49:02 -0700250 const char *rundir);
Dylan Reid837c74a2016-01-22 17:25:21 -0800251
252/* Destroy a container created with container_new. */
253void container_destroy(struct container *c);
254
Dylan Reide040c6b2016-05-02 18:49:02 -0700255/* Start the container. Returns 0 on success.
256 * c - The container to run.
257 * config - Details of how the container should be run.
258 */
259int container_start(struct container *c,
260 const struct container_config *config);
Dylan Reid837c74a2016-01-22 17:25:21 -0800261
262/* Get the path to the root of the container. */
263const char *container_root(struct container *c);
264
265/* Get the pid of the init process in the container. */
266int container_pid(struct container *c);
267
268/* Wait for the container to exit. Returns 0 on success. */
269int container_wait(struct container *c);
270
271/* Kill the container's init process, then wait for it to exit. */
272int container_kill(struct container *c);
273
274#ifdef __cplusplus
275}; /* extern "C" */
276#endif
277
Luis Hector Chavez479b95f2016-06-06 08:01:05 -0700278#endif /* LIBCONTAINER_LIBCONTAINER_H_ */