]>
Commit | Line | Data |
---|---|---|
953e611c JH |
1 | /*! \file |
2 | * | |
3 | * liblxcapi | |
250b1eec SG |
4 | * |
5 | * Copyright © 2012 Serge Hallyn <serge.hallyn@ubuntu.com>. | |
6 | * Copyright © 2012 Canonical Ltd. | |
7 | * | |
8 | * This library is free software; you can redistribute it and/or | |
9 | * modify it under the terms of the GNU Lesser General Public | |
10 | * License as published by the Free Software Foundation; either | |
11 | * version 2.1 of the License, or (at your option) any later version. | |
12 | ||
13 | * This library is distributed in the hope that it will be useful, | |
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
16 | * Lesser General Public License for more details. | |
17 | ||
18 | * You should have received a copy of the GNU Lesser General Public | |
19 | * License along with this library; if not, write to the Free Software | |
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
21 | */ | |
22 | ||
9be53773 SH |
23 | #ifndef __LXC_CONTAINER_H |
24 | #define __LXC_CONTAINER_H | |
72d0e1cb | 25 | #include <malloc.h> |
95ee490b | 26 | #include <semaphore.h> |
72d0e1cb | 27 | #include <stdbool.h> |
95ee490b | 28 | #include <stdlib.h> |
d659597e | 29 | #include <stdint.h> |
72d0e1cb | 30 | |
f2363e38 ÇO |
31 | #include <lxc/attach_options.h> |
32 | ||
579e783e AM |
33 | #ifdef __cplusplus |
34 | extern "C" { | |
35 | #endif | |
36 | ||
953e611c | 37 | #define LXC_CLONE_KEEPNAME (1 << 0) /*!< Do not edit the rootfs to change the hostname */ |
619256b5 ÇO |
38 | #define LXC_CLONE_KEEPMACADDR (1 << 1) /*!< Do not change the MAC address on network interfaces */ |
39 | #define LXC_CLONE_SNAPSHOT (1 << 2) /*!< Snapshot the original filesystem(s) */ | |
0a83cbbb SH |
40 | #define LXC_CLONE_KEEPBDEVTYPE (1 << 3) /*!< Use the same bdev type */ |
41 | #define LXC_CLONE_MAYBE_SNAPSHOT (1 << 4) /*!< Snapshot only if bdev supports it, else copy */ | |
42 | #define LXC_CLONE_MAXFLAGS (1 << 5) /*!< Number of \c LXC_CLONE_* flags */ | |
953e611c JH |
43 | #define LXC_CREATE_QUIET (1 << 0) /*!< Redirect \c stdin to \c /dev/zero and \c stdout and \c stderr to \c /dev/null */ |
44 | #define LXC_CREATE_MAXFLAGS (1 << 1) /*!< Number of \c LXC_CREATE* flags */ | |
dc23c1c8 | 45 | |
1897e3bc SH |
46 | struct bdev_specs; |
47 | ||
f5dd1d53 SH |
48 | struct lxc_snapshot; |
49 | ||
95ee490b SG |
50 | struct lxc_lock; |
51 | ||
953e611c JH |
52 | /*! |
53 | * An LXC container. | |
54 | */ | |
72d0e1cb SG |
55 | struct lxc_container { |
56 | // private fields | |
953e611c JH |
57 | /*! |
58 | * \private | |
59 | * Name of container. | |
60 | */ | |
72d0e1cb | 61 | char *name; |
953e611c JH |
62 | |
63 | /*! | |
64 | * \private | |
65 | * Full path to configuration file. | |
66 | */ | |
72d0e1cb | 67 | char *configfile; |
953e611c | 68 | |
72cf75fa QH |
69 | /*! |
70 | * \private | |
71 | * File to store pid. | |
72 | */ | |
73 | char *pidfile; | |
74 | ||
953e611c JH |
75 | /*! |
76 | * \private | |
77 | * Container semaphore lock. | |
78 | */ | |
df271a59 | 79 | struct lxc_lock *slock; |
953e611c JH |
80 | |
81 | /*! | |
82 | * \private | |
83 | * Container private lock. | |
84 | */ | |
df271a59 | 85 | struct lxc_lock *privlock; |
953e611c JH |
86 | |
87 | /*! | |
88 | * \private | |
89 | * Number of references to this container. | |
90 | * \note protected by privlock. | |
91 | */ | |
92 | int numthreads; | |
93 | ||
94 | /*! | |
95 | * \private | |
96 | * Container configuration. | |
97 | * | |
98 | * \internal FIXME: do we want the whole lxc_handler? | |
99 | */ | |
100 | struct lxc_conf *lxc_conf; | |
72d0e1cb SG |
101 | |
102 | // public fields | |
953e611c | 103 | /*! Human-readable string representing last error */ |
72d0e1cb | 104 | char *error_string; |
953e611c JH |
105 | |
106 | /*! Last error number */ | |
72d0e1cb | 107 | int error_num; |
953e611c JH |
108 | |
109 | /*! Whether container wishes to be daemonized */ | |
540f932a | 110 | bool daemonize; |
72d0e1cb | 111 | |
953e611c | 112 | /*! Full path to configuration file */ |
2a59a681 SH |
113 | char *config_path; |
114 | ||
953e611c JH |
115 | /*! |
116 | * \brief Determine if \c /var/lib/lxc/$name/config exists. | |
117 | * | |
118 | * \param c Container. | |
119 | * | |
120 | * \return \c true if container is defined, else \c false. | |
121 | */ | |
122 | bool (*is_defined)(struct lxc_container *c); | |
123 | ||
124 | /*! | |
125 | * \brief Determine state of container. | |
126 | * | |
127 | * \param c Container. | |
128 | * | |
129 | * \return Static upper-case string representing state of container. | |
130 | * | |
131 | * \note Returned string must not be freed. | |
132 | */ | |
72d0e1cb | 133 | const char *(*state)(struct lxc_container *c); |
953e611c JH |
134 | |
135 | /*! | |
136 | * \brief Determine if container is running. | |
137 | * | |
138 | * \param c Container. | |
139 | * | |
140 | * \return \c true on success, else \c false. | |
141 | */ | |
142 | bool (*is_running)(struct lxc_container *c); | |
143 | ||
144 | /*! | |
145 | * \brief Freeze running container. | |
146 | * | |
147 | * \param c Container. | |
148 | * | |
149 | * \return \c true on success, else \c false. | |
150 | */ | |
72d0e1cb | 151 | bool (*freeze)(struct lxc_container *c); |
953e611c JH |
152 | |
153 | /*! | |
154 | * \brief Thaw a frozen container. | |
155 | * | |
156 | * \param c Container. | |
157 | * | |
158 | * \return \c true on success, else \c false. | |
159 | */ | |
72d0e1cb | 160 | bool (*unfreeze)(struct lxc_container *c); |
953e611c JH |
161 | |
162 | /*! | |
163 | * \brief Determine process ID of the containers init process. | |
164 | * | |
165 | * \param c Container. | |
f7f1ba77 | 166 | * |
953e611c JH |
167 | * \return pid of init process as seen from outside the |
168 | * container. | |
169 | */ | |
72d0e1cb | 170 | pid_t (*init_pid)(struct lxc_container *c); |
953e611c JH |
171 | |
172 | /*! | |
173 | * \brief Load the specified configuration for the container. | |
174 | * | |
175 | * \param c Container. | |
176 | * \param alt_file Full path to alternate configuration file, or | |
177 | * \c NULL to use the default configuration file. | |
178 | * | |
179 | * \return \c true on success, else \c false. | |
180 | */ | |
12a50cc6 | 181 | bool (*load_config)(struct lxc_container *c, const char *alt_file); |
953e611c JH |
182 | |
183 | /*! | |
184 | * \brief Start the container. | |
185 | * | |
186 | * \param c Container. | |
187 | * \param useinit Use lxcinit rather than \c /sbin/init. | |
188 | * \param argv Array of arguments to pass to init. | |
189 | * | |
190 | * \return \c true on success, else \c false. | |
191 | */ | |
12a50cc6 | 192 | bool (*start)(struct lxc_container *c, int useinit, char * const argv[]); |
953e611c JH |
193 | |
194 | /*! | |
195 | * \brief Start the container (list variant). | |
196 | * | |
197 | * \param c Container. | |
198 | * \param useinit Use lxcinit rather than \c /sbin/init. | |
199 | * \param ... Command-line to pass to init (must end in \c NULL). | |
200 | * | |
201 | * \return \c true on success, else \c false. | |
202 | * | |
203 | * \note Identical to \ref start except that that the init | |
204 | * arguments are specified via a list rather than an array of | |
205 | * pointers. | |
206 | */ | |
72d0e1cb | 207 | bool (*startl)(struct lxc_container *c, int useinit, ...); |
953e611c JH |
208 | |
209 | /*! | |
210 | * \brief Stop the container. | |
211 | * | |
212 | * \param c Container. | |
213 | * | |
214 | * \return \c true on success, else \c false. | |
215 | */ | |
72d0e1cb | 216 | bool (*stop)(struct lxc_container *c); |
953e611c JH |
217 | |
218 | /*! | |
219 | * \brief Determine if the container wants to run disconnected | |
220 | * from the terminal. | |
221 | * | |
222 | * \param c Container. | |
c9d845b5 | 223 | * \param state Value for the daemonize bit (0 or 1). |
953e611c JH |
224 | * |
225 | * \return \c true if container wants to be daemonised, else \c false. | |
226 | */ | |
540f932a | 227 | bool (*want_daemonize)(struct lxc_container *c, bool state); |
953e611c JH |
228 | |
229 | /*! | |
230 | * \brief Determine whether container wishes all file descriptors | |
231 | * to be closed on startup. | |
232 | * | |
233 | * \param c Container. | |
c9d845b5 | 234 | * \param state Value for the close_all_fds bit (0 or 1). |
953e611c JH |
235 | * |
236 | * \return \c true if container wants all file descriptors closed, | |
237 | * else \c false. | |
238 | */ | |
540f932a | 239 | bool (*want_close_all_fds)(struct lxc_container *c, bool state); |
953e611c JH |
240 | |
241 | /*! | |
242 | * \brief Return current config file name. | |
243 | * | |
244 | * \param c Container. | |
245 | * | |
246 | * \return config file name, or \c NULL on error. | |
247 | * | |
248 | * \note The result is allocated, so the caller must free the result. | |
249 | */ | |
72d0e1cb | 250 | char *(*config_file_name)(struct lxc_container *c); |
953e611c JH |
251 | |
252 | /*! | |
253 | * \brief Wait for container to reach a particular state. | |
254 | * | |
255 | * \param c Container. | |
256 | * \param state State to wait for. | |
257 | * \param timeout Timeout in seconds. | |
258 | * | |
259 | * \return \c true if state reached within \p timeout, else \c false. | |
260 | * | |
261 | * \note A \p timeout of \c -1 means wait forever. A \p timeout | |
262 | * of \c 0 means do not wait. | |
263 | */ | |
12a50cc6 | 264 | bool (*wait)(struct lxc_container *c, const char *state, int timeout); |
953e611c JH |
265 | |
266 | /*! | |
267 | * \brief Set a key/value configuration option. | |
268 | * | |
269 | * \param c Container. | |
270 | * \param key Name of option to set. | |
271 | * \param value Value of \p name to set. | |
272 | * | |
273 | * \return \c true on success, else \c false. | |
274 | */ | |
12a50cc6 | 275 | bool (*set_config_item)(struct lxc_container *c, const char *key, const char *value); |
953e611c JH |
276 | |
277 | /*! | |
278 | * \brief Delete the container. | |
279 | * | |
280 | * \param c Container. | |
281 | * | |
282 | * \return \c true on success, else \c false. | |
283 | * | |
284 | * \note Container must be stopped and have no dependent snapshots. | |
285 | */ | |
72d0e1cb | 286 | bool (*destroy)(struct lxc_container *c); |
953e611c JH |
287 | |
288 | /*! | |
289 | * \brief Save configuaration to a file. | |
290 | * | |
291 | * \param c Container. | |
292 | * \param alt_file Full path to file to save configuration in. | |
293 | * | |
294 | * \return \c true on success, else \c false. | |
295 | */ | |
12a50cc6 | 296 | bool (*save_config)(struct lxc_container *c, const char *alt_file); |
953e611c JH |
297 | |
298 | /*! | |
299 | * \brief Create a container. | |
300 | * | |
301 | * \param c Container (with lxcpath, name and a starting | |
302 | * configuration set). | |
303 | * \param t Template to execute to instantiate the root | |
304 | * filesystem and adjust the configuration. | |
305 | * \param bdevtype Backing store type to use (if \c NULL, \c dir will be used). | |
306 | * \param specs Additional parameters for the backing store (for | |
307 | * example LVM volume group to use). | |
308 | * \param flags \c LXC_CREATE_* options (currently only \ref | |
309 | * LXC_CREATE_QUIET is supported). | |
310 | * \param argv Arguments to pass to the template, terminated by \c NULL (if no | |
311 | * arguments are required, just pass \c NULL). | |
312 | * | |
313 | * \return \c true on success, else \c false. | |
314 | */ | |
1897e3bc | 315 | bool (*create)(struct lxc_container *c, const char *t, const char *bdevtype, |
dc23c1c8 | 316 | struct bdev_specs *specs, int flags, char *const argv[]); |
953e611c JH |
317 | |
318 | /*! | |
319 | * \brief Create a container (list variant). | |
320 | * | |
321 | * \param c Container (with lxcpath, name and a starting | |
322 | * configuration set). | |
323 | * \param t Template to execute to instantiate the root | |
324 | * filesystem and adjust the configuration. | |
325 | * \param bdevtype Backing store type to use (if \c NULL, \c dir will be used). | |
326 | * \param specs Additional parameters for the backing store (for | |
327 | * example LVM volume group to use). | |
328 | * \param flags \c LXC_CREATE_* options (currently only \ref | |
329 | * LXC_CREATE_QUIET is supported). | |
330 | * \param ... Command-line to pass to init (must end in \c NULL). | |
331 | * | |
332 | * \return \c true on success, else \c false. | |
333 | * | |
334 | * \note Identical to \ref create except that the template | |
335 | * arguments are specified as a list rather than an array of | |
336 | * pointers. | |
337 | */ | |
1897e3bc | 338 | bool (*createl)(struct lxc_container *c, const char *t, const char *bdevtype, |
dc23c1c8 | 339 | struct bdev_specs *specs, int flags, ...); |
953e611c | 340 | |
06e5650e ÇO |
341 | /*! |
342 | * \brief Rename a container | |
343 | * | |
344 | * \param c Container. | |
345 | * \param newname New name to be used for the container. | |
346 | * | |
347 | * \return \c true on success, else \c false. | |
348 | */ | |
349 | bool (*rename)(struct lxc_container *c, const char *newname); | |
350 | ||
953e611c JH |
351 | /*! |
352 | * \brief Request the container reboot by sending it \c SIGINT. | |
353 | * | |
354 | * \param c Container. | |
355 | * | |
356 | * \return \c true if reboot request successful, else \c false. | |
357 | */ | |
3e625e2d | 358 | bool (*reboot)(struct lxc_container *c); |
953e611c JH |
359 | |
360 | /*! | |
361 | * \brief Request the container shutdown by sending it \c | |
362 | * SIGPWR. | |
363 | * | |
364 | * \param c Container. | |
0464b881 SG |
365 | * \param timeout Seconds to wait before returning false. |
366 | * (-1 to wait forever, 0 to avoid waiting). | |
953e611c | 367 | * |
0464b881 | 368 | * \return \c true if the container was shutdown successfully, else \c false. |
953e611c | 369 | */ |
72d0e1cb | 370 | bool (*shutdown)(struct lxc_container *c, int timeout); |
953e611c JH |
371 | |
372 | /*! | |
373 | * \brief Completely clear the containers in-memory configuration. | |
374 | * | |
375 | * \param c Container. | |
376 | */ | |
4df7f012 | 377 | void (*clear_config)(struct lxc_container *c); |
953e611c JH |
378 | |
379 | /*! | |
380 | * \brief Clear a configuration item. | |
381 | * | |
382 | * \param c Container. | |
383 | * \param key Name of option to clear. | |
384 | * | |
385 | * \return \c true on success, else \c false. | |
386 | * | |
387 | * \note Analog of \ref set_config_item. | |
388 | */ | |
12a50cc6 | 389 | bool (*clear_config_item)(struct lxc_container *c, const char *key); |
953e611c JH |
390 | |
391 | /*! | |
392 | * \brief Retrieve the value of a config item. | |
393 | * | |
394 | * \param c Container. | |
395 | * \param key Name of option to get. | |
396 | * \param[out] retv Caller-allocated buffer to write value of \p key | |
397 | * into (or \c NULL to determine length of value). | |
398 | * \param inlen Length of \p retv (may be zero). | |
399 | * | |
400 | * \return Length of config items value, or < 0 on error. | |
401 | * | |
402 | * \note The caller can (and should) determine how large a buffer to allocate for | |
403 | * \p retv by initially passing its value as \c NULL and considering the return value. | |
404 | * This function can then be called again passing a newly-allocated suitably-sized buffer. | |
405 | * \note If \p retv is NULL, \p inlen is ignored. | |
406 | * \note If \p inlen is smaller than required, the value written | |
407 | * to \p retv will be truncated. | |
408 | */ | |
12a50cc6 | 409 | int (*get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen); |
953e611c | 410 | |
8ac18377 ÇO |
411 | |
412 | /*! | |
413 | * \brief Retrieve the value of a config item from running container. | |
414 | * | |
415 | * \param c Container. | |
416 | * \param key Name of option to get. | |
417 | * | |
418 | * \return the item or NULL on error. | |
419 | * | |
420 | * \note Returned string must be freed by the caller. | |
421 | */ | |
422 | char* (*get_running_config_item)(struct lxc_container *c, const char *key); | |
423 | ||
953e611c JH |
424 | /*! |
425 | * \brief Retrieve a list of config item keys given a key | |
426 | * prefix. | |
427 | * | |
428 | * \param c Container. | |
429 | * \param key Name of option to get. | |
430 | * \param[out] retv Caller-allocated buffer to write list of keys to | |
431 | * (or \c NULL to determine overall length of keys list). | |
432 | * \param inlen Length of \p retv (may be zero). | |
433 | * | |
434 | * \return Length of keys list, or < 0 on error. | |
435 | * | |
436 | * \note The list values written to \p retv are separated by | |
437 | * a newline character ('\\n'). | |
438 | * \note The caller can (and should) determine how large a buffer to allocate for | |
439 | * \p retv by initially passing its value as \c NULL and considering the return value. | |
440 | * This function can then be called again passing a newly-allocated suitably-sized buffer. | |
441 | * \note If \p retv is NULL, \p inlen is ignored. | |
442 | * \note If \p inlen is smaller than required, the value written | |
443 | * to \p retv will be truncated. | |
444 | */ | |
12a50cc6 | 445 | int (*get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen); |
953e611c JH |
446 | |
447 | /*! | |
448 | * \brief Obtain a list of network interfaces. | |
449 | * \param c Container. | |
450 | * | |
451 | * \return Newly-allocated array of network interfaces, or \c | |
452 | * NULL on error. | |
453 | * | |
454 | * \note The returned array is allocated, so the caller must free it. | |
455 | * \note The returned array is terminated with a \c NULL entry. | |
456 | */ | |
799f29ab | 457 | char** (*get_interfaces)(struct lxc_container *c); |
953e611c JH |
458 | |
459 | /*! | |
460 | * \brief Determine the list of container IP addresses. | |
461 | * | |
462 | * \param c Container. | |
463 | * \param interface Network interface name to consider. | |
464 | * \param family Network family (for example "inet", "inet6"). | |
465 | * \param scope IPv6 scope id (ignored if \p family is not "inet6"). | |
466 | * | |
467 | * \return Newly-allocated array of network interfaces, or \c | |
468 | * NULL on error. | |
469 | * | |
470 | * \note The returned array is allocated, so the caller must free it. | |
471 | * \note The returned array is terminated with a \c NULL entry. | |
472 | */ | |
f0ca2726 | 473 | char** (*get_ips)(struct lxc_container *c, const char* interface, const char* family, int scope); |
953e611c JH |
474 | |
475 | /*! | |
476 | * \brief Retrieve the specified cgroup subsystem value for the container. | |
477 | * | |
478 | * \param c Container. | |
479 | * \param subsys cgroup subsystem to retrieve. | |
480 | * \param[out] retv Caller-allocated buffer to write value of \p | |
481 | * subsys into (or \c NULL to determine length of value). | |
482 | * \param inlen length of \p retv (may be zero). | |
483 | * | |
484 | * \return Length of \p subsys value, or < 0 on error. | |
485 | * | |
486 | * \note If \p retv is \c NULL, \p inlen is ignored. | |
487 | * \note If \p inlen is smaller than required, the value written | |
488 | * to \p retv will be truncated. | |
794dd120 SH |
489 | */ |
490 | int (*get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen); | |
953e611c JH |
491 | |
492 | /*! | |
493 | * \brief Set the specified cgroup subsystem value for the container. | |
494 | * | |
495 | * \param c Container. | |
496 | * \param subsys cgroup subsystem to consider. | |
497 | * \param value Value to set for \p subsys. | |
498 | * | |
499 | * \return \c true on success, else \c false. | |
500 | */ | |
794dd120 | 501 | bool (*set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value); |
72d0e1cb | 502 | |
953e611c JH |
503 | /*! |
504 | * \brief Determine full path to the containers configuration file. | |
505 | * Each container can have a custom configuration path. However | |
506 | * by default it will be set to either the \c LXCPATH configure | |
507 | * variable, or the lxcpath value in the \c LXC_GLOBAL_CONF configuration | |
508 | * file (i.e. \c /etc/lxc/lxc.conf). | |
509 | * The value for a specific container can be changed using | |
510 | * \ref set_config_path. There is no other way to specify this in general at the moment. | |
511 | * | |
512 | * \param c Container. | |
513 | * | |
514 | * \return Static string representing full path to configuration | |
515 | * file. | |
516 | * | |
517 | * \note Returned string must not be freed. | |
2a59a681 SH |
518 | */ |
519 | const char *(*get_config_path)(struct lxc_container *c); | |
953e611c JH |
520 | |
521 | /*! | |
522 | * \brief Set the full path to the containers configuration | |
523 | * file. | |
524 | * | |
525 | * \param c Container. | |
526 | * \param path Full path to configuration file. | |
527 | * | |
528 | * \return \c true on success, else \c false. | |
529 | */ | |
2a59a681 SH |
530 | bool (*set_config_path)(struct lxc_container *c, const char *path); |
531 | ||
953e611c JH |
532 | /*! |
533 | * \brief Copy a stopped container. | |
534 | * | |
535 | * \param c Original container. | |
536 | * \param newname New name for the container. If \c NULL, the same | |
537 | * name is used and a new lxcpath MUST be specified. | |
538 | * \param lxcpath lxcpath in which to create the new container. If | |
539 | * \c NULL, the original container's lxcpath will be used. | |
540 | * (XXX: should we use the default instead?) | |
541 | * \param flags Additional \c LXC_CLONE* flags to change the cloning behaviour: | |
542 | * - \ref LXC_CLONE_KEEPNAME | |
953e611c JH |
543 | * - \ref LXC_CLONE_KEEPMACADDR |
544 | * - \ref LXC_CLONE_SNAPSHOT | |
545 | * \param bdevtype Optionally force the cloned bdevtype to a specified plugin. | |
546 | * By default the original is used (subject to snapshot requirements). | |
547 | * \param bdevdata Information about how to create the new storage | |
548 | * (i.e. fstype and fsdata). | |
cf642e10 | 549 | * \param newsize In case of a block device backing store, an |
953e611c JH |
550 | * optional size. If \c 0, the original backing store's size will |
551 | * be used if possible. Note this only applies to the rootfs. For | |
552 | * any other filesystems, the original size will be duplicated. | |
553 | * \param hookargs Additional arguments to pass to the clone hook script. | |
554 | * | |
555 | * \return Newly-allocated copy of container \p c, or \p NULL on | |
556 | * error. | |
557 | * | |
558 | * \note If devtype was not specified, and \p flags contains \ref | |
559 | * LXC_CLONE_SNAPSHOT then use the native \p bdevtype if possible, | |
560 | * else use an overlayfs. | |
9be53773 SH |
561 | */ |
562 | struct lxc_container *(*clone)(struct lxc_container *c, const char *newname, | |
953e611c | 563 | const char *lxcpath, int flags, const char *bdevtype, |
d659597e | 564 | const char *bdevdata, uint64_t newsize, char **hookargs); |
9be53773 | 565 | |
953e611c JH |
566 | /*! |
567 | * \brief Allocate a console tty for the container. | |
0115f8fd | 568 | * |
953e611c JH |
569 | * \param c Container. |
570 | * \param[in,out] ttynum Terminal number to attempt to allocate, | |
571 | * or \c -1 to allocate the first available tty. | |
572 | * \param[out] masterfd File descriptor refering to the master side of the pty. | |
0115f8fd | 573 | * |
953e611c JH |
574 | * \return tty file descriptor number on success, or \c -1 on |
575 | * failure. | |
576 | * | |
577 | * \note On successful return, \p ttynum will contain the tty number | |
578 | * that was allocated. | |
579 | * \note The returned file descriptor is used to keep the tty | |
580 | * allocated. The caller should call close(2) on the returned file | |
581 | * descriptor when no longer required so that it may be allocated | |
582 | * by another caller. | |
0115f8fd | 583 | */ |
b5159817 DE |
584 | int (*console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd); |
585 | ||
953e611c JH |
586 | /*! |
587 | * \brief Allocate and run a console tty. | |
588 | * | |
589 | * \param c Container. | |
590 | * \param ttynum Terminal number to attempt to allocate, \c -1 to | |
591 | * allocate the first available tty or \c 0 to allocate the | |
592 | * console. | |
593 | * \param stdinfd File descriptor to read input from. | |
594 | * \param stdoutfd File descriptor to write output to. | |
595 | * \param stderrfd File descriptor to write error output to. | |
596 | * \param escape The escape character (1 == 'a', 2 == 'b', ...). | |
b5159817 | 597 | * |
953e611c | 598 | * \return \c 0 on success, \c -1 on failure. |
b5159817 | 599 | * |
953e611c JH |
600 | * \note This function will not return until the console has been |
601 | * exited by the user. | |
b5159817 DE |
602 | */ |
603 | int (*console)(struct lxc_container *c, int ttynum, | |
953e611c | 604 | int stdinfd, int stdoutfd, int stderrfd, int escape); |
0115f8fd | 605 | |
953e611c JH |
606 | /*! |
607 | * \brief Create a sub-process attached to a container and run | |
608 | * a function inside it. | |
609 | * | |
610 | * \param c Container. | |
611 | * \param exec_function Function to run. | |
612 | * \param exec_payload Data to pass to \p exec_function. | |
613 | * \param options \ref lxc_attach_options_t. | |
614 | * \param[out] attached_process Process ID of process running inside | |
615 | * container \p c that is running \p exec_function. | |
616 | * | |
617 | * \return \c 0 on success, \c -1 on error. | |
618 | */ | |
619 | int (*attach)(struct lxc_container *c, lxc_attach_exec_t exec_function, | |
620 | void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process); | |
a0e93eeb | 621 | |
953e611c JH |
622 | /*! |
623 | * \brief Run a program inside a container and wait for it to exit. | |
624 | * | |
625 | * \param c Container. | |
626 | * \param options See \ref attach options. | |
627 | * \param program Full path inside container of program to run. | |
628 | * \param argv Array of arguments to pass to \p program. | |
629 | * | |
630 | * \return \c waitpid(2) status of exited process that ran \p | |
631 | * program, or \c -1 on error. | |
632 | */ | |
a0e93eeb | 633 | int (*attach_run_wait)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char * const argv[]); |
f5dd1d53 | 634 | |
953e611c JH |
635 | /*! |
636 | * \brief Run a program inside a container and wait for it to exit (list variant). | |
637 | * | |
638 | * \param c Container. | |
639 | * \param options See \ref attach options. | |
640 | * \param program Full path inside container of program to run. | |
641 | * \param ... Command-line to pass to \p program (must end in \c NULL). | |
642 | * | |
643 | * \return \c waitpid(2) status of exited process that ran \p | |
644 | * program, or \c -1 on error. | |
645 | */ | |
646 | int (*attach_run_waitl)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *arg, ...); | |
f5dd1d53 | 647 | |
953e611c JH |
648 | /*! |
649 | * \brief Create a container snapshot. | |
650 | * | |
651 | * Assuming default paths, snapshots will be created as | |
652 | * \c /var/lib/lxcsnaps/\<c\>/snap\<n\> | |
653 | * where \c \<c\> represents the container name and \c \<n\> | |
654 | * represents the zero-based snapshot number. | |
655 | * | |
656 | * \param c Container. | |
657 | * \param commentfile Full path to file containing a description | |
658 | * of the snapshot. | |
659 | * | |
660 | * \return -1 on error, or zero-based snapshot number. | |
f5dd1d53 | 661 | * |
953e611c | 662 | * \note \p commentfile may be \c NULL but this is discouraged. |
f5dd1d53 | 663 | */ |
f0ca2726 | 664 | int (*snapshot)(struct lxc_container *c, const char *commentfile); |
f5dd1d53 | 665 | |
953e611c JH |
666 | /*! |
667 | * \brief Obtain a list of container snapshots. | |
668 | * | |
669 | * \param c Container. | |
670 | * \param[out] snapshots Dynamically-allocated Array of lxc_snapshot's. | |
f5dd1d53 | 671 | * |
953e611c | 672 | * \return Number of snapshots. |
f5dd1d53 | 673 | * |
953e611c JH |
674 | * \note The array returned in \p snapshots is allocated, so the caller must free it. |
675 | * \note To free an individual snapshot as returned in \p | |
676 | * snapshots, call the snapshots \c free function (see \c src/tests/snapshot.c for an example). | |
677 | */ | |
678 | int (*snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots); | |
679 | ||
680 | /*! | |
681 | * \brief Create a new container based on a snapshot. | |
f5dd1d53 | 682 | * |
953e611c JH |
683 | * The restored container will be a copy (not snapshot) of the snapshot, |
684 | * and restored in the lxcpath of the original container. | |
685 | * \param c Container. | |
686 | * \param snapname Name of snapshot. | |
687 | * \param newname Name to be used for the restored snapshot. | |
688 | * \return \c true on success, else \c false. | |
689 | * \warning If \p newname is the same as the current container | |
690 | * name, the container will be destroyed. However, this will | |
691 | * fail if the snapshot is overlayfs-based, since the snapshots | |
692 | * will pin the original container. | |
693 | * \note As an example, if the container exists as \c /var/lib/lxc/c1, snapname might be \c 'snap0' | |
694 | * (representing \c /var/lib/lxcsnaps/c1/snap0). If \p newname is \p c2, | |
695 | * then \c snap0 will be copied to \c /var/lib/lxc/c2. | |
f5dd1d53 | 696 | */ |
f0ca2726 | 697 | bool (*snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname); |
b494d2dd | 698 | |
953e611c JH |
699 | /*! |
700 | * \brief Destroy the specified snapshot. | |
771d96b3 | 701 | * |
953e611c JH |
702 | * \param c Container. |
703 | * \param snapname Name of snapshot. | |
704 | * | |
705 | * \return \c true on success, else \c false. | |
771d96b3 | 706 | */ |
f0ca2726 | 707 | bool (*snapshot_destroy)(struct lxc_container *c, const char *snapname); |
771d96b3 | 708 | |
953e611c JH |
709 | /*! |
710 | * \brief Determine if the caller may control the container. | |
711 | * | |
712 | * \param c Container. | |
713 | * | |
714 | * \return \c false if there is a control socket for the | |
715 | * container monitor and the caller may not access it, otherwise | |
716 | * returns \c true. | |
b494d2dd SH |
717 | */ |
718 | bool (*may_control)(struct lxc_container *c); | |
a9a0ed90 | 719 | |
953e611c JH |
720 | /*! |
721 | * \brief Add specified device to the container. | |
a9a0ed90 | 722 | * |
953e611c JH |
723 | * \param c Container. |
724 | * \param src_path Full path of the device. | |
725 | * \param dest_path Alternate path in the container (or \p NULL | |
726 | * to use \p src_path). | |
727 | * | |
728 | * \return \c true on success, else \c false. | |
a9a0ed90 | 729 | */ |
f0ca2726 | 730 | bool (*add_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path); |
953e611c JH |
731 | |
732 | /*! | |
733 | * \brief Remove specified device from the container. | |
a9a0ed90 | 734 | * |
953e611c JH |
735 | * \param c Container. |
736 | * \param src_path Full path of the device. | |
737 | * \param dest_path Alternate path in the container (or \p NULL | |
738 | * to use \p src_path). | |
739 | * | |
740 | * \return \c true on success, else \c false. | |
a9a0ed90 | 741 | */ |
f0ca2726 | 742 | bool (*remove_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path); |
f5dd1d53 SH |
743 | }; |
744 | ||
953e611c JH |
745 | /*! |
746 | * \brief An LXC container snapshot. | |
747 | */ | |
f5dd1d53 | 748 | struct lxc_snapshot { |
953e611c JH |
749 | char *name; /*!< Name of snapshot */ |
750 | char *comment_pathname; /*!< Full path to snapshots comment file (may be \c NULL) */ | |
751 | char *timestamp; /*!< Time snapshot was created */ | |
752 | char *lxcpath; /*!< Full path to LXCPATH for snapshot */ | |
753 | ||
754 | /*! | |
755 | * \brief De-allocate the snapshot. | |
756 | * \param s snapshot. | |
757 | */ | |
758 | void (*free)(struct lxc_snapshot *s); | |
72d0e1cb SG |
759 | }; |
760 | ||
953e611c JH |
761 | /*! |
762 | * \brief Create a new container. | |
763 | * | |
764 | * \param name Name to use for container. | |
765 | * \param configpath Full path to configuration file to use. | |
766 | * | |
767 | * \return Newly-allocated container, or \c NULL on error. | |
768 | */ | |
afeecbba | 769 | struct lxc_container *lxc_container_new(const char *name, const char *configpath); |
953e611c JH |
770 | |
771 | /*! | |
772 | * \brief Add a reference to the specified container. | |
773 | * | |
774 | * \param c Container. | |
775 | * | |
776 | * \return \c true on success, \c false on error. | |
777 | */ | |
72d0e1cb | 778 | int lxc_container_get(struct lxc_container *c); |
953e611c JH |
779 | |
780 | /*! | |
781 | * \brief Drop a reference to the specified container. | |
782 | * | |
783 | * \param c Container. | |
784 | * | |
785 | * \return \c 0 on success, \c 1 if reference was successfully dropped | |
786 | * and container has been freed, and \c -1 on error. | |
787 | * | |
788 | * \warning If \c 1 is returned, \p c is no longer valid. | |
789 | */ | |
72d0e1cb | 790 | int lxc_container_put(struct lxc_container *c); |
953e611c JH |
791 | |
792 | /*! | |
793 | * \brief Obtain a list of all container states. | |
794 | * \param[out] states Caller-allocated array to hold all states (may be \c NULL). | |
795 | * | |
796 | * \return Number of container states. | |
797 | * | |
798 | * \note Passing \c NULL for \p states allows the caller to first | |
799 | * calculate how many states there are before calling the function again, the second time | |
800 | * providing a suitably-sized array to store the static string pointers | |
801 | * in. | |
802 | * \note The \p states array should be freed by the caller, but not the strings the elements point to. | |
803 | */ | |
4a7c7daa | 804 | int lxc_get_wait_states(const char **states); |
953e611c | 805 | |
dbfa7128 | 806 | /*! |
593e8478 | 807 | * \brief Get the value for a global config key |
953e611c | 808 | * |
593e8478 | 809 | * \param key The name of the config key |
953e611c | 810 | * |
593e8478 | 811 | * \return String representing the current value for the key. |
953e611c | 812 | */ |
593e8478 | 813 | const char *lxc_get_global_config_item(const char *key); |
953e611c JH |
814 | |
815 | /*! | |
816 | * \brief Determine version of LXC. | |
817 | * \return Static string representing version of LXC in use. | |
818 | * | |
819 | * \note Returned string must not be freed. | |
820 | */ | |
b6b918a1 | 821 | const char *lxc_get_version(void); |
72d0e1cb | 822 | |
953e611c JH |
823 | /*! |
824 | * \brief Get a list of defined containers in a lxcpath. | |
a41f104b | 825 | * |
953e611c JH |
826 | * \param lxcpath lxcpath under which to look. |
827 | * \param names If not \c NULL, then a list of container names will be returned here. | |
828 | * \param cret If not \c NULL, then a list of lxc_containers will be returned here. | |
829 | * | |
830 | * \return Number of containers found, or \c -1 on error. | |
831 | * | |
832 | * \note Values returned in \p cret are sorted by container name. | |
a41f104b SH |
833 | */ |
834 | int list_defined_containers(const char *lxcpath, char ***names, struct lxc_container ***cret); | |
835 | ||
953e611c JH |
836 | /*! |
837 | * \brief Get a list of active containers for a given lxcpath. | |
838 | * | |
839 | * \param lxcpath Full \c LXCPATH path to consider. | |
840 | * \param[out] names Dynamically-allocated array of container names. | |
841 | * \param[out] cret Dynamically-allocated list of containers. | |
842 | * | |
843 | * \return Number of containers found, or -1 on error. | |
a41f104b | 844 | * |
953e611c JH |
845 | * \note Some of the containers may not be "defined". |
846 | * \note Values returned in \p cret are sorted by container name. | |
847 | * \note \p names and \p cret may both (or either) be specified as \c NULL. | |
848 | * \note \p names and \p cret must be freed by the caller. | |
a41f104b SH |
849 | */ |
850 | int list_active_containers(const char *lxcpath, char ***names, struct lxc_container ***cret); | |
851 | ||
953e611c JH |
852 | /*! |
853 | * \brief Get a complete list of all containers for a given lxcpath. | |
2871830a | 854 | * |
953e611c JH |
855 | * \param lxcpath Full \c LXCPATH path to consider. |
856 | * \param[out] names Dynamically-allocated array of container name. | |
857 | * \param[out] cret Dynamically-allocated list of containers. | |
858 | * | |
859 | * \return Number of containers, or -1 on error. | |
860 | * | |
861 | * \note Some of the containers may not be "defined". | |
862 | * \note Values returned in \p cret are sorted by container name. | |
863 | * \note \p names and \p cret may both (or either) be specified as \c NULL. | |
864 | * \note \p names and \p cret must be freed by the caller. | |
2871830a DE |
865 | */ |
866 | int list_all_containers(const char *lxcpath, char ***names, struct lxc_container ***cret); | |
867 | ||
579e783e AM |
868 | #ifdef __cplusplus |
869 | } | |
870 | #endif | |
871 | ||
9be53773 | 872 | #endif |