]>
Commit | Line | Data |
---|---|---|
250b1eec SG |
1 | /* liblxcapi |
2 | * | |
3 | * Copyright © 2012 Serge Hallyn <serge.hallyn@ubuntu.com>. | |
4 | * Copyright © 2012 Canonical Ltd. | |
5 | * | |
6 | * This library is free software; you can redistribute it and/or | |
7 | * modify it under the terms of the GNU Lesser General Public | |
8 | * License as published by the Free Software Foundation; either | |
9 | * version 2.1 of the License, or (at your option) any later version. | |
10 | ||
11 | * This library is distributed in the hope that it will be useful, | |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
14 | * Lesser General Public License for more details. | |
15 | ||
16 | * You should have received a copy of the GNU Lesser General Public | |
17 | * License along with this library; if not, write to the Free Software | |
18 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
19 | */ | |
20 | ||
9be53773 SH |
21 | #ifndef __LXC_CONTAINER_H |
22 | #define __LXC_CONTAINER_H | |
72d0e1cb | 23 | #include "lxclock.h" |
a0e93eeb | 24 | #include "attach_options.h" |
72d0e1cb SG |
25 | #include <stdlib.h> |
26 | #include <malloc.h> | |
27 | ||
28 | #include <stdbool.h> | |
29 | ||
9be53773 SH |
30 | #define LXC_CLONE_KEEPNAME (1 << 0) |
31 | #define LXC_CLONE_COPYHOOKS (1 << 1) | |
32 | #define LXC_CLONE_KEEPMACADDR (1 << 2) | |
33 | #define LXC_CLONE_SNAPSHOT (1 << 3) | |
34 | #define LXC_CLONE_MAXFLAGS (1 << 4) | |
35 | ||
dc23c1c8 SH |
36 | #define LXC_CREATE_QUIET (1 << 0) |
37 | #define LXC_CREATE_MAXFLAGS (1 << 1) | |
38 | ||
1897e3bc SH |
39 | struct bdev_specs; |
40 | ||
f5dd1d53 SH |
41 | struct lxc_snapshot; |
42 | ||
72d0e1cb SG |
43 | struct lxc_container { |
44 | // private fields | |
45 | char *name; | |
46 | char *configfile; | |
df271a59 SH |
47 | struct lxc_lock *slock; |
48 | struct lxc_lock *privlock; | |
72d0e1cb SG |
49 | int numthreads; /* protected by privlock. */ |
50 | struct lxc_conf *lxc_conf; // maybe we'll just want the whole lxc_handler? | |
51 | ||
52 | // public fields | |
53 | char *error_string; | |
54 | int error_num; | |
55 | int daemonize; | |
56 | ||
2a59a681 SH |
57 | char *config_path; |
58 | ||
72d0e1cb SG |
59 | bool (*is_defined)(struct lxc_container *c); // did /var/lib/lxc/$name/config exist |
60 | const char *(*state)(struct lxc_container *c); | |
61 | bool (*is_running)(struct lxc_container *c); // true so long as defined and not stopped | |
62 | bool (*freeze)(struct lxc_container *c); | |
63 | bool (*unfreeze)(struct lxc_container *c); | |
64 | pid_t (*init_pid)(struct lxc_container *c); | |
12a50cc6 | 65 | bool (*load_config)(struct lxc_container *c, const char *alt_file); |
72d0e1cb | 66 | /* The '...' is the command line. If provided, it must be ended with a NULL */ |
12a50cc6 | 67 | bool (*start)(struct lxc_container *c, int useinit, char * const argv[]); |
72d0e1cb SG |
68 | bool (*startl)(struct lxc_container *c, int useinit, ...); |
69 | bool (*stop)(struct lxc_container *c); | |
70 | void (*want_daemonize)(struct lxc_container *c); | |
49badbbe | 71 | bool (*want_close_all_fds)(struct lxc_container *c); |
72d0e1cb SG |
72 | // Return current config file name. The result is strdup()d, so free the result. |
73 | char *(*config_file_name)(struct lxc_container *c); | |
74 | // for wait, timeout == -1 means wait forever, timeout == 0 means don't wait. | |
75 | // otherwise timeout is seconds to wait. | |
12a50cc6 DE |
76 | bool (*wait)(struct lxc_container *c, const char *state, int timeout); |
77 | bool (*set_config_item)(struct lxc_container *c, const char *key, const char *value); | |
72d0e1cb | 78 | bool (*destroy)(struct lxc_container *c); |
12a50cc6 | 79 | bool (*save_config)(struct lxc_container *c, const char *alt_file); |
1897e3bc | 80 | bool (*create)(struct lxc_container *c, const char *t, const char *bdevtype, |
dc23c1c8 | 81 | struct bdev_specs *specs, int flags, char *const argv[]); |
1897e3bc | 82 | bool (*createl)(struct lxc_container *c, const char *t, const char *bdevtype, |
dc23c1c8 | 83 | struct bdev_specs *specs, int flags, ...); |
3e625e2d SH |
84 | /* send SIGINT to ask container to reboot */ |
85 | bool (*reboot)(struct lxc_container *c); | |
72d0e1cb SG |
86 | /* send SIGPWR. if timeout is not 0 or -1, do a hard stop after timeout seconds */ |
87 | bool (*shutdown)(struct lxc_container *c, int timeout); | |
88 | /* clear all network or capability items in the in-memory configuration */ | |
12a50cc6 | 89 | bool (*clear_config_item)(struct lxc_container *c, const char *key); |
72d0e1cb SG |
90 | /* print a config item to a in-memory string allocated by the caller. Return |
91 | * the length which was our would be printed. */ | |
12a50cc6 DE |
92 | int (*get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen); |
93 | int (*get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen); | |
799f29ab ÇO |
94 | // Return interface names. The result is strdup()d, so free the result. |
95 | char** (*get_interfaces)(struct lxc_container *c); | |
96 | // Return IP addresses. The result is strdup()d, so free the result. | |
9c83a661 | 97 | char** (*get_ips)(struct lxc_container *c, char* interface, char* family, int scope); |
794dd120 SH |
98 | /* |
99 | * get_cgroup_item returns the number of bytes read, or an error (<0). | |
100 | * If retv NULL or inlen 0 is passed in, then the length of the cgroup | |
101 | * file will be returned. * Otherwise it will return the # of bytes read. | |
102 | * If inlen is less than the number of bytes available, then the returned | |
103 | * value will be inlen, not the full available size of the file. | |
104 | */ | |
105 | int (*get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen); | |
106 | bool (*set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value); | |
72d0e1cb | 107 | |
2a59a681 SH |
108 | /* |
109 | * Each container can have a custom configuration path. However | |
110 | * by default it will be set to either the LXCPATH configure | |
111 | * variable, or the lxcpath value in the LXC_GLOBAL_CONF configuration | |
112 | * file (i.e. /etc/lxc/lxc.conf). | |
113 | * You can change the value for a specific container with | |
114 | * set_config_path(). Note there is no other way to specify this in | |
115 | * general at the moment. | |
116 | */ | |
117 | const char *(*get_config_path)(struct lxc_container *c); | |
118 | bool (*set_config_path)(struct lxc_container *c, const char *path); | |
119 | ||
9be53773 SH |
120 | /* |
121 | * @c: the original container | |
122 | * @newname: new name for the container. If NULL, the same name is used, and | |
123 | * a new lxcpath MUST be specified. | |
124 | * @lxcpath: lxcpath in which to create the new container. If NULL, then the | |
125 | * original container's lxcpath will be used. (Shoudl we use the default | |
126 | * instead?) | |
127 | * @flags: additional flags to modify cloning behavior. | |
128 | * LXC_CLONE_KEEPNAME: don't edit the rootfs to change the hostname. | |
129 | * LXC_CLONE_COPYHOOKS: copy all hooks into the container dir | |
130 | * LXC_CLONE_KEEPMACADDR: don't change the mac address on network interfaces. | |
131 | * LXC_CLONE_SNAPSHOT: snapshot the original filesystem(s). If @devtype was not | |
132 | * specified, then do so with the native bdevtype if possible, else use an | |
133 | * overlayfs. | |
134 | * @bdevtype: optionally force the cloned bdevtype to a specified plugin. By | |
135 | * default the original is used (subject to snapshot requirements). | |
136 | * @bdevdata: information about how to create the new storage (i.e. fstype and | |
137 | * fsdata) | |
138 | * @newsize: in case of a block device backing store, an optional size. If 0, | |
139 | * then the original backing store's size will be used if possible. Note this | |
140 | * only applies to the rootfs. For any other filesystems, the original size | |
141 | * will be duplicated. | |
481624b3 | 142 | * @hookargs: additional arguments to pass to the clone hook script |
9be53773 SH |
143 | */ |
144 | struct lxc_container *(*clone)(struct lxc_container *c, const char *newname, | |
145 | const char *lxcpath, int flags, const char *bdevtype, | |
148e91f5 | 146 | const char *bdevdata, unsigned long newsize, char **hookargs); |
9be53773 | 147 | |
b5159817 | 148 | /* lxcapi_console_getfd: allocate a console tty from container @c |
0115f8fd DE |
149 | * |
150 | * @c : the running container | |
151 | * @ttynum : in : tty number to attempt to allocate or -1 to | |
152 | * allocate the first available tty | |
153 | * out: the tty number that was allocated | |
154 | * @masterfd : out: fd refering to the master side of pty | |
155 | * | |
156 | * Returns "ttyfd" on success, -1 on failure. The returned "ttyfd" is | |
157 | * used to keep the tty allocated. The caller should close "ttyfd" to | |
158 | * indicate that it is done with the allocated console so that it can | |
159 | * be allocated by another caller. | |
160 | */ | |
b5159817 DE |
161 | int (*console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd); |
162 | ||
163 | /* lxcapi_console: allocate and run a console tty from container @c | |
164 | * | |
165 | * @c : the running container | |
166 | * @ttynum : tty number to attempt to allocate, -1 to | |
167 | * allocate the first available tty, or 0 to allocate | |
168 | * the console | |
169 | * @stdinfd : fd to read input from | |
170 | * @stdoutfd : fd to write output to | |
171 | * @stderrfd : fd to write error output to | |
172 | * @escape : the escape character (1 == 'a', 2 == 'b', ...) | |
173 | * | |
174 | * Returns 0 on success, -1 on failure. This function will not return | |
175 | * until the console has been exited by the user. | |
176 | */ | |
177 | int (*console)(struct lxc_container *c, int ttynum, | |
178 | int stdinfd, int stdoutfd, int stderrfd, int escape); | |
0115f8fd | 179 | |
a0e93eeb CS |
180 | /* create subprocess and attach it to the container, run exec_function inside */ |
181 | int (*attach)(struct lxc_container *c, lxc_attach_exec_t exec_function, void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process); | |
182 | ||
183 | /* run program in container, wait for it to exit */ | |
184 | int (*attach_run_wait)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char * const argv[]); | |
185 | int (*attach_run_waitl)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *arg, ...); | |
f5dd1d53 SH |
186 | |
187 | /* | |
188 | * snapshot: | |
189 | * If you have /var/lib/lxc/c1 and call c->snapshot() the firs time, it | |
190 | * will return 0, and the container will be /var/lib/lxcsnaps/c1/snap0. | |
191 | * The second call will return 1, and the snapshot will be | |
192 | * /var/lib/lxcsnaps/c1/snap1. | |
193 | * | |
194 | * On error, returns -1. | |
195 | */ | |
196 | int (*snapshot)(struct lxc_container *c, char *commentfile); | |
197 | ||
198 | /* | |
199 | * snapshot_list() will return a description of all snapshots of c in | |
200 | * a simple array. See src/tests/snapshot.c for the proper way to | |
201 | * free the allocated results. | |
202 | * | |
203 | * Returns the number of snapshots. | |
204 | */ | |
205 | int (*snapshot_list)(struct lxc_container *, struct lxc_snapshot **); | |
206 | ||
207 | /* | |
208 | * snapshot_restore() will create a new container based on a snapshot. | |
209 | * c is the container whose snapshot we look for, and snapname is the | |
210 | * specific snapshot name (i.e. "snap0"). newname is the name to be | |
211 | * used for the restored container. If newname is the same as | |
212 | * c->name, then c will first be destroyed. That will fail if the | |
213 | * snapshot is overlayfs-based, since the snapshots will pin the | |
214 | * original container. | |
215 | * | |
216 | * The restored container will be a copy (not snapshot) of the snapshot, | |
217 | * and restored in the lxcpath of the original container. | |
218 | * | |
219 | * As an example, c might be /var/lib/lxc/c1, snapname might be 'snap0' | |
220 | * which stands for /var/lib/lxcsnaps/c1/snap0. If newname is c2, | |
221 | * then snap0 will be copied to /var/lib/lxc/c2. | |
222 | * | |
223 | * Returns true on success, false on failure. | |
224 | */ | |
225 | bool (*snapshot_restore)(struct lxc_container *c, char *snapname, char *newname); | |
b494d2dd | 226 | |
771d96b3 ÇO |
227 | /* |
228 | * snapshot_destroy() will destroy the given snapshot of c | |
229 | * | |
230 | * Returns true on success, false on failure. | |
231 | */ | |
232 | bool (*snapshot_destroy)(struct lxc_container *c, char *snapname); | |
233 | ||
b494d2dd SH |
234 | /* |
235 | * Return false if there is a control socket for the container monitor, | |
236 | * and the caller may not access it. Return true otherwise. | |
237 | */ | |
238 | bool (*may_control)(struct lxc_container *c); | |
f5dd1d53 SH |
239 | }; |
240 | ||
241 | struct lxc_snapshot { | |
242 | char *name; | |
243 | char *comment_pathname; | |
244 | char *timestamp; | |
245 | char *lxcpath; | |
246 | void (*free)(struct lxc_snapshot *); | |
72d0e1cb SG |
247 | }; |
248 | ||
afeecbba | 249 | struct lxc_container *lxc_container_new(const char *name, const char *configpath); |
72d0e1cb SG |
250 | int lxc_container_get(struct lxc_container *c); |
251 | int lxc_container_put(struct lxc_container *c); | |
4a7c7daa | 252 | int lxc_get_wait_states(const char **states); |
67e571de | 253 | const char *lxc_get_default_config_path(void); |
a8428dfa | 254 | const char *lxc_get_default_lvm_vg(void); |
f99c386b | 255 | const char *lxc_get_default_lvm_thin_pool(void); |
a8428dfa | 256 | const char *lxc_get_default_zfs_root(void); |
b6b918a1 | 257 | const char *lxc_get_version(void); |
72d0e1cb | 258 | |
a41f104b SH |
259 | /* |
260 | * Get a list of defined containers in a lxcpath. | |
261 | * @lxcpath: lxcpath under which to look. | |
262 | * @names: if not null, then a list of container names will be returned here. | |
263 | * @cret: if not null, then a list of lxc_containers will be returned here. | |
264 | * | |
265 | * Returns the number of containers found, or -1 on error. | |
266 | */ | |
267 | int list_defined_containers(const char *lxcpath, char ***names, struct lxc_container ***cret); | |
268 | ||
269 | /* | |
270 | * Get a list of active containers in a lxcpath. Note that some of these | |
271 | * containers may not be "defined". | |
272 | * @lxcpath: lxcpath under which to look | |
273 | * @names: if not null, then a list of container names will be returned here. | |
274 | * @cret: if not null, then a list of lxc_containers will be returned here. | |
275 | * | |
276 | * Returns the number of containers found, or -1 on error. | |
277 | */ | |
278 | int list_active_containers(const char *lxcpath, char ***names, struct lxc_container ***cret); | |
279 | ||
2871830a DE |
280 | /* |
281 | * Get an array sorted by name of defined and active containers in a lxcpath. | |
282 | * @lxcpath: lxcpath under which to look | |
283 | * @names: if not null, then an array of container names will be returned here. | |
284 | * @cret: if not null, then an array of lxc_containers will be returned here. | |
285 | * | |
286 | * Returns the number of containers found, or -1 on error. | |
287 | */ | |
288 | int list_all_containers(const char *lxcpath, char ***names, struct lxc_container ***cret); | |
289 | ||
72d0e1cb SG |
290 | #if 0 |
291 | char ** lxc_get_valid_keys(); | |
292 | char ** lxc_get_valid_values(char *key); | |
293 | #endif | |
9be53773 | 294 | #endif |