src/lxc/lxccontainer.h

   1 /*! \file
   2  *
   3  * liblxcapi
   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
  23 #ifndef __LXC_CONTAINER_H
  24 #define __LXC_CONTAINER_H
  25
  26 #include <malloc.h>
  27 #include <semaphore.h>
  28 #include <stdbool.h>
  29 #include <stdint.h>
  30 #include <stdlib.h>
  31
  32 #include <lxc/attach_options.h>
  33
  34 #ifdef  __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #define LXC_CLONE_KEEPNAME        (1 << 0) /*!< Do not edit the rootfs to change the hostname */
  39 #define LXC_CLONE_KEEPMACADDR     (1 << 1) /*!< Do not change the MAC address on network interfaces */
  40 #define LXC_CLONE_SNAPSHOT        (1 << 2) /*!< Snapshot the original filesystem(s) */
  41 #define LXC_CLONE_KEEPBDEVTYPE    (1 << 3) /*!< Use the same bdev type */
  42 #define LXC_CLONE_MAYBE_SNAPSHOT  (1 << 4) /*!< Snapshot only if bdev supports it, else copy */
  43 #define LXC_CLONE_MAXFLAGS        (1 << 5) /*!< Number of \c LXC_CLONE_* flags */
  44 #define LXC_CLONE_ALLOW_RUNNING   (1 << 6) /*!< allow snapshot creation even if source container is running */
  45 #define LXC_CREATE_QUIET          (1 << 0) /*!< Redirect \c stdin to \c /dev/zero and \c stdout and \c stderr to \c /dev/null */
  46 #define LXC_CREATE_MAXFLAGS       (1 << 1) /*!< Number of \c LXC_CREATE* flags */
  47 #define LXC_MOUNT_API_V1                   1
  48
  49 struct bdev_specs;
  50
  51 struct lxc_snapshot;
  52
  53 struct lxc_lock;
  54
  55 struct migrate_opts;
  56
  57 struct lxc_console_log;
  58
  59 struct lxc_mount {
  60         int version;
  61 };
  62
  63 enum {
  64         LXC_SECCOMP_NOTIFY_GET_FD = 0,
  65         LXC_SECCOMP_NOTIFY_MAX,
  66 };
  67
  68 /*!
  69  * An LXC container.
  70  *
  71  * Note that changing the order of struct members is an API change, as callers
  72  * will end up having the wrong offset when calling a function.  So when making
  73  * changes, whenever possible stick to simply appending new members.
  74  */
  75 struct lxc_container {
  76         /* private fields */
  77         /*!
  78          * \private
  79          * Name of container.
  80          */
  81         char *name;
  82
  83         /*!
  84          * \private
  85          * Full path to configuration file.
  86          */
  87         char *configfile;
  88
  89         /*!
  90          * \private
  91          * File to store pid.
  92          */
  93         char *pidfile;
  94
  95         /*!
  96          * \private
  97          * Container semaphore lock.
  98          */
  99         struct lxc_lock *slock;
 100
 101         /*!
 102          * \private
 103          * Container private lock.
 104          */
 105         struct lxc_lock *privlock;
 106
 107         /*!
 108          * \private
 109          * Number of references to this container.
 110          * \note protected by privlock.
 111          */
 112         int numthreads;
 113
 114         /*!
 115          * \private
 116          * Container configuration.
 117          *
 118          * \internal FIXME: do we want the whole lxc_handler?
 119          */
 120         struct lxc_conf *lxc_conf;
 121
 122         /* public fields */
 123         /*! Human-readable string representing last error */
 124         char *error_string;
 125
 126         /*! Last error number */
 127         int error_num;
 128
 129         /*! Whether container wishes to be daemonized */
 130         bool daemonize;
 131
 132         /*! Full path to configuration file */
 133         char *config_path;
 134
 135         /*!
 136          * \brief Determine if \c /var/lib/lxc/$name/config exists.
 137          *
 138          * \param c Container.
 139          *
 140          * \return \c true if container is defined, else \c false.
 141          */
 142         bool (*is_defined)(struct lxc_container *c);
 143
 144         /*!
 145          * \brief Determine state of container.
 146          *
 147          * \param c Container.
 148          *
 149          * \return Static upper-case string representing state of container.
 150          *
 151          * \note Returned string must not be freed.
 152          */
 153         const char *(*state)(struct lxc_container *c);
 154
 155         /*!
 156          * \brief Determine if container is running.
 157          *
 158          * \param c Container.
 159          *
 160          * \return \c true on success, else \c false.
 161          */
 162         bool (*is_running)(struct lxc_container *c);
 163
 164         /*!
 165          * \brief Freeze running container.
 166          *
 167          * \param c Container.
 168          *
 169          * \return \c true on success, else \c false.
 170          */
 171         bool (*freeze)(struct lxc_container *c);
 172
 173         /*!
 174          * \brief Thaw a frozen container.
 175          *
 176          * \param c Container.
 177          *
 178          * \return \c true on success, else \c false.
 179          */
 180         bool (*unfreeze)(struct lxc_container *c);
 181
 182         /*!
 183          * \brief Determine process ID of the containers init process.
 184          *
 185          * \param c Container.
 186          *
 187          * \return pid of init process as seen from outside the
 188          *  container.
 189          */
 190         pid_t (*init_pid)(struct lxc_container *c);
 191
 192         /*!
 193          * \brief Load the specified configuration for the container.
 194          *
 195          * \param c Container.
 196          * \param alt_file Full path to alternate configuration file, or
 197          *  \c NULL to use the default configuration file.
 198          *
 199          * \return \c true on success, else \c false.
 200          */
 201         bool (*load_config)(struct lxc_container *c, const char *alt_file);
 202
 203         /*!
 204          * \brief Start the container.
 205          *
 206          * \param c Container.
 207          * \param useinit Use lxcinit rather than \c /sbin/init.
 208          * \param argv Array of arguments to pass to init.
 209          *
 210          * \return \c true on success, else \c false.
 211          */
 212         bool (*start)(struct lxc_container *c, int useinit, char * const argv[]);
 213
 214         /*!
 215          * \brief Start the container (list variant).
 216          *
 217          * \param c Container.
 218          * \param useinit Use lxcinit rather than \c /sbin/init.
 219          * \param ... Command-line to pass to init (must end in \c NULL).
 220          *
 221          * \return \c true on success, else \c false.
 222          *
 223          * \note Identical to \ref start except that that the init
 224          *  arguments are specified via a list rather than an array of
 225          *  pointers.
 226          */
 227         bool (*startl)(struct lxc_container *c, int useinit, ...);
 228
 229         /*!
 230          * \brief Stop the container.
 231          *
 232          * \param c Container.
 233          *
 234          * \return \c true on success, else \c false.
 235          */
 236         bool (*stop)(struct lxc_container *c);
 237
 238         /*!
 239          * \brief Change whether the container wants to run disconnected
 240          * from the terminal.
 241          *
 242          * \param c Container.
 243          * \param state Value for the daemonize bit (0 or 1).
 244          *
 245          * \return \c true on success, else \c false.
 246          */
 247         bool (*want_daemonize)(struct lxc_container *c, bool state);
 248
 249         /*!
 250          * \brief Change whether the container wishes all file descriptors
 251          *  to be closed on startup.
 252          *
 253          * \param c Container.
 254          * \param state Value for the close_all_fds bit (0 or 1).
 255          *
 256          * \return \c true on success, else \c false.
 257          */
 258         bool (*want_close_all_fds)(struct lxc_container *c, bool state);
 259
 260         /*!
 261          * \brief Return current config file name.
 262          *
 263          * \param c Container.
 264          *
 265          * \return config file name, or \c NULL on error.
 266          *
 267          * \note The result is allocated, so the caller must free the result.
 268          */
 269         char *(*config_file_name)(struct lxc_container *c);
 270
 271         /*!
 272          * \brief Wait for container to reach a particular state.
 273          *
 274          * \param c Container.
 275          * \param state State to wait for.
 276          * \param timeout Timeout in seconds.
 277          *
 278          * \return \c true if state reached within \p timeout, else \c false.
 279          *
 280          * \note A \p timeout of \c -1 means wait forever. A \p timeout
 281          *  of \c 0 means do not wait.
 282          */
 283         bool (*wait)(struct lxc_container *c, const char *state, int timeout);
 284
 285         /*!
 286          * \brief Set a key/value configuration option.
 287          *
 288          * \param c Container.
 289          * \param key Name of option to set.
 290          * \param value Value of \p name to set.
 291          *
 292          * \return \c true on success, else \c false.
 293          */
 294         bool (*set_config_item)(struct lxc_container *c, const char *key, const char *value);
 295
 296         /*!
 297          * \brief Delete the container.
 298          *
 299          * \param c Container.
 300          *
 301          * \return \c true on success, else \c false.
 302          *
 303          * \note Container must be stopped and have no dependent snapshots.
 304          */
 305         bool (*destroy)(struct lxc_container *c);
 306
 307         /*!
 308          * \brief Save configuration to a file.
 309          *
 310          * \param c Container.
 311          * \param alt_file Full path to file to save configuration in.
 312          *
 313          * \return \c true on success, else \c false.
 314          */
 315         bool (*save_config)(struct lxc_container *c, const char *alt_file);
 316
 317         /*!
 318          * \brief Create a container.
 319          *
 320          * \param c Container (with lxcpath, name and a starting
 321          *  configuration set).
 322          * \param t Template to execute to instantiate the root
 323          *  filesystem and adjust the configuration.
 324          * \param bdevtype Backing store type to use (if \c NULL, \c dir will be used).
 325          * \param specs Additional parameters for the backing store (for
 326          *  example LVM volume group to use).
 327          * \param flags \c LXC_CREATE_* options (currently only \ref
 328          *  LXC_CREATE_QUIET is supported).
 329          * \param argv Arguments to pass to the template, terminated by \c NULL (if no
 330          *  arguments are required, just pass \c NULL).
 331          *
 332          * \return \c true on success, else \c false.
 333          */
 334         bool (*create)(struct lxc_container *c, const char *t, const char *bdevtype,
 335                         struct bdev_specs *specs, int flags, char *const argv[]);
 336
 337         /*!
 338          * \brief Create a container (list variant).
 339          *
 340          * \param c Container (with lxcpath, name and a starting
 341          *  configuration set).
 342          * \param t Template to execute to instantiate the root
 343          *  filesystem and adjust the configuration.
 344          * \param bdevtype Backing store type to use (if \c NULL, \c dir will be used).
 345          * \param specs Additional parameters for the backing store (for
 346          *  example LVM volume group to use).
 347          * \param flags \c LXC_CREATE_* options (currently only \ref
 348          *  LXC_CREATE_QUIET is supported).
 349          * \param ... Command-line to pass to init (must end in \c NULL).
 350          *
 351          * \return \c true on success, else \c false.
 352          *
 353          * \note Identical to \ref create except that the template
 354          *  arguments are specified as a list rather than an array of
 355          *  pointers.
 356          */
 357         bool (*createl)(struct lxc_container *c, const char *t, const char *bdevtype,
 358                         struct bdev_specs *specs, int flags, ...);
 359
 360         /*!
 361          * \brief Rename a container
 362          *
 363          * \param c Container.
 364          * \param newname New name to be used for the container.
 365          *
 366          * \return \c true on success, else \c false.
 367          */
 368         bool (*rename)(struct lxc_container *c, const char *newname);
 369
 370         /*!
 371          * \brief Request the container reboot by sending it \c SIGINT.
 372          *
 373          * \param c Container.
 374          *
 375          * \return \c true if reboot request successful, else \c false.
 376          */
 377         bool (*reboot)(struct lxc_container *c);
 378
 379         /*!
 380          * \brief Request the container shutdown by sending it \c
 381          * SIGPWR.
 382          *
 383          * \param c Container.
 384          * \param timeout Seconds to wait before returning false.
 385          *  (-1 to wait forever, 0 to avoid waiting).
 386          *
 387          * \return \c true if the container was shutdown successfully, else \c false.
 388          */
 389         bool (*shutdown)(struct lxc_container *c, int timeout);
 390
 391         /*!
 392          * \brief Completely clear the containers in-memory configuration.
 393          *
 394          * \param c Container.
 395          */
 396         void (*clear_config)(struct lxc_container *c);
 397
 398         /*!
 399          * \brief Clear a configuration item.
 400          *
 401          * \param c Container.
 402          * \param key Name of option to clear.
 403          *
 404          * \return \c true on success, else \c false.
 405          *
 406          * \note Analog of \ref set_config_item.
 407          */
 408         bool (*clear_config_item)(struct lxc_container *c, const char *key);
 409
 410         /*!
 411          * \brief Retrieve the value of a config item.
 412          *
 413          * \param c Container.
 414          * \param key Name of option to get.
 415          * \param[out] retv Caller-allocated buffer to write value of \p key
 416          * into (or \c NULL to determine length of value).
 417          * \param inlen Length of \p retv (may be zero).
 418          *
 419          * \return Length of config items value, or < 0 on error.
 420          *
 421          * \note The caller can (and should) determine how large a buffer to allocate for
 422          *  \p retv by initially passing its value as \c NULL and considering the return value.
 423          *  This function can then be called again passing a newly-allocated suitably-sized buffer.
 424          * \note If \p retv is NULL, \p inlen is ignored.
 425          * \note If \p inlen is smaller than required, nothing will be written to \p retv and still return
 426          *  the length of config item value.
 427          */
 428         int (*get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen);
 429
 430
 431         /*!
 432          * \brief Retrieve the value of a config item from running container.
 433          *
 434          * \param c Container.
 435          * \param key Name of option to get.
 436          *
 437          * \return the item or NULL on error.
 438          *
 439          * \note Returned string must be freed by the caller.
 440          */
 441         char* (*get_running_config_item)(struct lxc_container *c, const char *key);
 442
 443         /*!
 444          * \brief Retrieve a list of config item keys given a key
 445          * prefix.
 446          *
 447          * \param c Container.
 448          * \param key Name of option to get.
 449          * \param[out] retv Caller-allocated buffer to write list of keys to
 450          *  (or \c NULL to determine overall length of keys list).
 451          * \param inlen Length of \p retv (may be zero).
 452          *
 453          * \return Length of keys list, or < 0 on error.
 454          *
 455          * \note The list values written to \p retv are separated by
 456          *  a newline character ('\\n').
 457          * \note The caller can (and should) determine how large a buffer to allocate for
 458          *  \p retv by initially passing its value as \c NULL and considering the return value.
 459          *  This function can then be called again passing a newly-allocated suitably-sized buffer.
 460          * \note If \p retv is NULL, \p inlen is ignored.
 461          * \note If \p inlen is smaller than required, the value written
 462          *  to \p retv will be truncated.
 463          */
 464         int (*get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen);
 465
 466         /*!
 467          * \brief Obtain a list of network interfaces.
 468          * \param c Container.
 469          *
 470          * \return Newly-allocated array of network interfaces, or \c
 471          *  NULL on error.
 472          *
 473          * \note The returned array is allocated, so the caller must free it.
 474          * \note The returned array is terminated with a \c NULL entry.
 475          */
 476         char** (*get_interfaces)(struct lxc_container *c);
 477
 478         /*!
 479          * \brief Determine the list of container IP addresses.
 480          *
 481          * \param c Container.
 482          * \param interface Network interface name to consider.
 483          * \param family Network family (for example "inet", "inet6").
 484          * \param scope IPv6 scope id (ignored if \p family is not "inet6").
 485          *
 486          * \return Newly-allocated array of network interfaces, or \c
 487          *  NULL on error.
 488          *
 489          * \note The returned array is allocated, so the caller must free it.
 490          * \note The returned array is terminated with a \c NULL entry.
 491          */
 492         char** (*get_ips)(struct lxc_container *c, const char* interface, const char* family, int scope);
 493
 494         /*!
 495          * \brief Retrieve the specified cgroup subsystem value for the container.
 496          *
 497          * \param c Container.
 498          * \param subsys cgroup subsystem to retrieve.
 499          * \param[out] retv Caller-allocated buffer to write value of \p
 500          *  subsys into (or \c NULL to determine length of value).
 501          * \param inlen length of \p retv (may be zero).
 502          *
 503          * \return Length of \p subsys value, or < 0 on error.
 504          *
 505          * \note If \p retv is \c NULL, \p inlen is ignored.
 506          * \note If \p inlen is smaller than required, the value written
 507          *  to \p retv will be truncated.
 508          */
 509         int (*get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen);
 510
 511         /*!
 512          * \brief Set the specified cgroup subsystem value for the container.
 513          *
 514          * \param c Container.
 515          * \param subsys cgroup subsystem to consider.
 516          * \param value Value to set for \p subsys.
 517          *
 518          * \return \c true on success, else \c false.
 519          */
 520         bool (*set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value);
 521
 522         /*!
 523          * \brief Determine full path to the containers configuration file.
 524          * Each container can have a custom configuration path. However
 525          * by default it will be set to either the \c LXCPATH configure
 526          * variable, or the lxcpath value in the \c LXC_GLOBAL_CONF configuration
 527          * file (i.e. \c /etc/lxc/lxc.conf).
 528          * The value for a specific container can be changed using
 529          * \ref set_config_path. There is no other way to specify this in general at the moment.
 530          *
 531          * \param c Container.
 532          *
 533          * \return Static string representing full path to configuration
 534          * file.
 535          *
 536          * \note Returned string must not be freed.
 537          */
 538         const char *(*get_config_path)(struct lxc_container *c);
 539
 540         /*!
 541          * \brief Set the full path to the containers configuration
 542          * file.
 543          *
 544          * \param c Container.
 545          * \param path Full path to configuration file.
 546          *
 547          * \return \c true on success, else \c false.
 548          */
 549         bool (*set_config_path)(struct lxc_container *c, const char *path);
 550
 551         /*!
 552          * \brief Copy a stopped container.
 553          *
 554          * \param c Original container.
 555          * \param newname New name for the container. If \c NULL, the same
 556          *  name is used and a new lxcpath MUST be specified.
 557          * \param lxcpath lxcpath in which to create the new container. If
 558          *  \c NULL, the original container's lxcpath will be used.
 559          *  (XXX: should we use the default instead?)
 560          * \param flags Additional \c LXC_CLONE* flags to change the cloning behaviour:
 561          *  - \ref LXC_CLONE_KEEPNAME
 562          *  - \ref LXC_CLONE_KEEPMACADDR
 563          *  - \ref LXC_CLONE_SNAPSHOT
 564          * \param bdevtype Optionally force the cloned bdevtype to a specified plugin.
 565          *  By default the original is used (subject to snapshot requirements).
 566          * \param bdevdata Information about how to create the new storage
 567          *  (i.e. fstype and fsdata).
 568          * \param newsize In case of a block device backing store, an
 569          *  optional size. If \c 0, the original backing store's size will
 570          *  be used if possible. Note this only applies to the rootfs. For
 571          *  any other filesystems, the original size will be duplicated.
 572          * \param hookargs Additional arguments to pass to the clone hook script.
 573          *
 574          * \return Newly-allocated copy of container \p c, or \p NULL on
 575          * error.
 576          *
 577          * \note If devtype was not specified, and \p flags contains \ref
 578          * LXC_CLONE_SNAPSHOT then use the native \p bdevtype if possible,
 579          * else use an overlayfs.
 580          */
 581         struct lxc_container *(*clone)(struct lxc_container *c, const char *newname,
 582                         const char *lxcpath, int flags, const char *bdevtype,
 583                         const char *bdevdata, uint64_t newsize, char **hookargs);
 584
 585         /*!
 586          * \brief Allocate a console tty for the container.
 587          *
 588          * \param c Container.
 589          * \param[in,out] ttynum Terminal number to attempt to allocate,
 590          *  or \c -1 to allocate the first available tty.
 591          * \param[out] masterfd File descriptor referring to the master side of the pty.
 592          *
 593          * \return tty file descriptor number on success, or \c -1 on
 594          *  failure.
 595          *
 596          * \note On successful return, \p ttynum will contain the tty number
 597          *  that was allocated.
 598          * \note The returned file descriptor is used to keep the tty
 599          *  allocated. The caller should call close(2) on the returned file
 600          *  descriptor when no longer required so that it may be allocated
 601          *  by another caller.
 602          */
 603         int (*console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd);
 604
 605         /*!
 606          * \brief Allocate and run a console tty.
 607          *
 608          * \param c Container.
 609          * \param ttynum Terminal number to attempt to allocate, \c -1 to
 610          *  allocate the first available tty or \c 0 to allocate the
 611          *  console.
 612          * \param stdinfd File descriptor to read input from.
 613          * \param stdoutfd File descriptor to write output to.
 614          * \param stderrfd File descriptor to write error output to.
 615          * \param escape The escape character (1 == 'a', 2 == 'b', ...).
 616          *
 617          * \return \c 0 on success, \c -1 on failure.
 618          *
 619          * \note This function will not return until the console has been
 620          *  exited by the user.
 621          */
 622         int (*console)(struct lxc_container *c, int ttynum,
 623                         int stdinfd, int stdoutfd, int stderrfd, int escape);
 624
 625         /*!
 626          * \brief Create a sub-process attached to a container and run
 627          *  a function inside it.
 628          *
 629          * \param c Container.
 630          * \param exec_function Function to run.
 631          * \param exec_payload Data to pass to \p exec_function.
 632          * \param options \ref lxc_attach_options_t.
 633          * \param[out] attached_process Process ID of process running inside
 634          *  container \p c that is running \p exec_function.
 635          *
 636          * \return \c 0 on success, \c -1 on error.
 637          */
 638         int (*attach)(struct lxc_container *c, lxc_attach_exec_t exec_function,
 639                         void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process);
 640
 641         /*!
 642          * \brief Run a program inside a container and wait for it to exit.
 643          *
 644          * \param c Container.
 645          * \param options See \ref attach options.
 646          * \param program Full path inside container of program to run.
 647          * \param argv Array of arguments to pass to \p program.
 648          *
 649          * \return \c waitpid(2) status of exited process that ran \p
 650          * program, or \c -1 on error.
 651          */
 652         int (*attach_run_wait)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char * const argv[]);
 653
 654         /*!
 655          * \brief Run a program inside a container and wait for it to exit (list variant).
 656          *
 657          * \param c Container.
 658          * \param options See \ref attach options.
 659          * \param program Full path inside container of program to run.
 660          * \param ... Command-line to pass to \p program (must end in \c NULL).
 661          *
 662          * \return \c waitpid(2) status of exited process that ran \p
 663          * program, or \c -1 on error.
 664          */
 665         int (*attach_run_waitl)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *arg, ...);
 666
 667         /*!
 668          * \brief Create a container snapshot.
 669          *
 670          * Assuming default paths, snapshots will be created as
 671          * \c /var/lib/lxc/\<c\>/snaps/snap\<n\>
 672          * where \c \<c\> represents the container name and \c \<n\>
 673          * represents the zero-based snapshot number.
 674          *
 675          * \param c Container.
 676          * \param commentfile Full path to file containing a description
 677          *  of the snapshot.
 678          *
 679          * \return -1 on error, or zero-based snapshot number.
 680          *
 681          * \note \p commentfile may be \c NULL but this is discouraged.
 682          */
 683         int (*snapshot)(struct lxc_container *c, const char *commentfile);
 684
 685         /*!
 686          * \brief Obtain a list of container snapshots.
 687          *
 688          * \param c Container.
 689          * \param[out] snapshots Dynamically-allocated Array of lxc_snapshot's.
 690          *
 691          * \return Number of snapshots.
 692          *
 693          * \note The array returned in \p snapshots is allocated, so the caller must free it.
 694          * \note To free an individual snapshot as returned in \p
 695          * snapshots, call the snapshots \c free function (see \c src/tests/snapshot.c for an example).
 696          */
 697         int (*snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots);
 698
 699         /*!
 700          * \brief Create a new container based on a snapshot.
 701          *
 702          *  The restored container will be a copy (not snapshot) of the snapshot,
 703          *  and restored in the lxcpath of the original container.
 704          * \param c Container.
 705          * \param snapname Name of snapshot.
 706          * \param newname Name to be used for the restored snapshot.
 707          * \return \c true on success, else \c false.
 708          * \warning If \p newname is the same as the current container
 709          *  name, the container will be destroyed. However, this will
 710          *  fail if the  snapshot is overlay-based, since the snapshots
 711          *  will pin the original container.
 712          * \note As an example, if the container exists as \c /var/lib/lxc/c1, snapname might be \c 'snap0'
 713          *  (representing \c /var/lib/lxc/c1/snaps/snap0). If \p newname is \p c2,
 714          *  then \c snap0 will be copied to \c /var/lib/lxc/c2.
 715          */
 716         bool (*snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname);
 717
 718         /*!
 719          * \brief Destroy the specified snapshot.
 720          *
 721          * \param c Container.
 722          * \param snapname Name of snapshot.
 723          *
 724          * \return \c true on success, else \c false.
 725          */
 726         bool (*snapshot_destroy)(struct lxc_container *c, const char *snapname);
 727
 728         /*!
 729          * \brief Determine if the caller may control the container.
 730          *
 731          * \param c Container.
 732          *
 733          * \return \c false if there is a control socket for the
 734          *  container monitor and the caller may not access it, otherwise
 735          * returns \c true.
 736          */
 737         bool (*may_control)(struct lxc_container *c);
 738
 739         /*!
 740          * \brief Add specified device to the container.
 741          *
 742          * \param c Container.
 743          * \param src_path Full path of the device.
 744          * \param dest_path Alternate path in the container (or \p NULL
 745          *  to use \p src_path).
 746          *
 747          * \return \c true on success, else \c false.
 748          */
 749         bool (*add_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path);
 750
 751         /*!
 752          * \brief Remove specified device from the container.
 753          *
 754          * \param c Container.
 755          * \param src_path Full path of the device.
 756          * \param dest_path Alternate path in the container (or \p NULL
 757          *  to use \p src_path).
 758          *
 759          * \return \c true on success, else \c false.
 760          */
 761         bool (*remove_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path);
 762
 763         /* Post LXC-1.0 additions */
 764
 765         /*!
 766          * \brief Add specified netdev to the container.
 767          *
 768          * \param c Container.
 769          * \param dev name of net device.
 770          *
 771          * \return \c true on success, else \c false.
 772          */
 773         bool (*attach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev);
 774
 775         /*!
 776          * \brief Remove specified netdev from the container.
 777          *
 778          * \param c Container.
 779          * \param dev name of net device.
 780          *
 781          * \return \c true on success, else \c false.
 782          */
 783         bool (*detach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev);
 784         /*!
 785          * \brief Checkpoint a container.
 786          *
 787          * \param c Container.
 788          * \param directory The directory to dump the container to.
 789          * \param stop Whether or not to stop the container after checkpointing.
 790          * \param verbose Enable criu's verbose logs.
 791          *
 792          * \return \c true on success, else \c false.
 793          * present at compile time).
 794          */
 795         bool (*checkpoint)(struct lxc_container *c, char *directory, bool stop, bool verbose);
 796
 797         /*!
 798          * \brief Restore a container from a checkpoint.
 799          *
 800          * \param c Container.
 801          * \param directory The directory to restore the container from.
 802          * \param verbose Enable criu's verbose logs.
 803          *
 804          * \return \c true on success, else \c false.
 805          *
 806          */
 807         bool (*restore)(struct lxc_container *c, char *directory, bool verbose);
 808
 809         /*!
 810          * \brief Delete the container and all its snapshots.
 811          *
 812          * \param c Container.
 813          *
 814          * \return \c true on success, else \c false.
 815          *
 816          * \note Container must be stopped.
 817          */
 818         bool (*destroy_with_snapshots)(struct lxc_container *c);
 819
 820         /*!
 821          * \brief Destroy all the container's snapshot.
 822          *
 823          * \param c Container.
 824          *
 825          * \return \c true on success, else \c false.
 826          */
 827         bool (*snapshot_destroy_all)(struct lxc_container *c);
 828
 829         /* Post LXC-1.1 additions */
 830         /*!
 831          * \brief An API call to perform various migration operations
 832          *
 833          * \param cmd One of the MIGRATE_ constants.
 834          * \param opts A migrate_opts struct filled with relevant options.
 835          * \param size The size of the migrate_opts struct, i.e. sizeof(struct migrate_opts).
 836          *
 837          * \return \c 0 on success, nonzero on failure.
 838          */
 839         int (*migrate)(struct lxc_container *c, unsigned int cmd, struct migrate_opts *opts, unsigned int size);
 840
 841         /*!
 842          * \brief Query the console log of a container.
 843          *
 844          * \param c Container.
 845          * \param opts A lxc_console_log struct filled with relevant options.
 846          *
 847          * \return \c 0 on success, nonzero on failure.
 848          */
 849         int (*console_log)(struct lxc_container *c, struct lxc_console_log *log);
 850
 851         /*!
 852          * \brief Request the container reboot by sending it \c SIGINT.
 853          *
 854          * \param c Container.
 855          * \param timeout Seconds to wait before returning false.
 856          *  (-1 to wait forever, 0 to avoid waiting).
 857          *
 858          * \return \c true if the container was rebooted successfully, else \c false.
 859          */
 860         bool (*reboot2)(struct lxc_container *c, int timeout);
 861
 862         /*!
 863          * \brief Mount the host's path `source` onto the container's path `target`.
 864          */
 865         int (*mount)(struct lxc_container *c, const char *source,
 866                      const char *target, const char *filesystemtype,
 867                      unsigned long mountflags, const void *data,
 868                      struct lxc_mount *mnt);
 869
 870         /*!
 871          * \brief Unmount the container's path `target`.
 872          */
 873         int (*umount)(struct lxc_container *c, const char *target,
 874                       unsigned long mountflags, struct lxc_mount *mnt);
 875
 876         int (*seccomp_notify)(struct lxc_container *c, unsigned int cmd, int fd);
 877 };
 878
 879 /*!
 880  * \brief An LXC container snapshot.
 881  */
 882 struct lxc_snapshot {
 883         char *name; /*!< Name of snapshot */
 884         char *comment_pathname; /*!< Full path to snapshots comment file (may be \c NULL) */
 885         char *timestamp; /*!< Time snapshot was created */
 886         char *lxcpath; /*!< Full path to LXCPATH for snapshot */
 887
 888         /*!
 889          * \brief De-allocate the snapshot.
 890          * \param s snapshot.
 891          */
 892         void (*free)(struct lxc_snapshot *s);
 893 };
 894
 895
 896 /*!
 897  * \brief Specifications for how to create a new backing store
 898  */
 899 struct bdev_specs {
 900         char *fstype; /*!< Filesystem type */
 901         uint64_t fssize;  /*!< Filesystem size in bytes */
 902         struct {
 903                 char *zfsroot; /*!< ZFS root path */
 904         } zfs;
 905         struct {
 906                 char *vg; /*!< LVM Volume Group name */
 907                 char *lv; /*!< LVM Logical Volume name */
 908                 char *thinpool; /*!< LVM thin pool to use, if any */
 909         } lvm;
 910         char *dir; /*!< Directory path */
 911         struct {
 912                 char *rbdname; /*!< RBD image name */
 913                 char *rbdpool; /*!< Ceph pool name */
 914         } rbd;
 915 };
 916
 917 /*!
 918  * \brief Commands for the migrate API call.
 919  */
 920 enum {
 921         MIGRATE_PRE_DUMP,
 922         MIGRATE_DUMP,
 923         MIGRATE_RESTORE,
 924         MIGRATE_FEATURE_CHECK,
 925 };
 926
 927 /*!
 928  * \brief Available feature checks.
 929  */
 930 #define FEATURE_MEM_TRACK    (1ULL << 0)
 931 #define FEATURE_LAZY_PAGES   (1ULL << 1)
 932
 933 /*!
 934  * \brief Options for the migrate API call.
 935  */
 936 struct migrate_opts {
 937         /* new members should be added at the end */
 938         char *directory;
 939         bool verbose;
 940
 941         bool stop; /* stop the container after dump? */
 942         char *predump_dir; /* relative to directory above */
 943         char *pageserver_address; /* where should memory pages be send? */
 944         char *pageserver_port;
 945
 946         /* This flag indicates whether or not the container's rootfs will have
 947          * the same inodes on checkpoint and restore. In the case of e.g. zfs
 948          * send or btrfs send, or an LVM snapshot, this will be true, but it
 949          * won't if e.g. you rsync the filesystems between two machines.
 950          */
 951         bool preserves_inodes;
 952
 953         /* Path to an executable script that will be registered as a criu
 954          * "action script"
 955          */
 956         char *action_script;
 957
 958         /* If CRIU >= 2.4 is detected the option to skip in-flight connections
 959          * will be enabled by default. The flag 'disable_skip_in_flight' will
 960          * unconditionally disable this feature. In-flight connections are
 961          * not fully established TCP connections: SYN, SYN-ACK */
 962         bool disable_skip_in_flight;
 963
 964         /* This is the maximum file size for deleted files (which CRIU calls
 965          * "ghost" files) that will be handled. 0 indicates the CRIU default,
 966          * which at this time is 1MB.
 967          */
 968         uint64_t ghost_limit;
 969
 970         /* Some features cannot be checked by comparing the CRIU version.
 971          * Features like dirty page tracking or userfaultfd depend on
 972          * the architecture/kernel/criu combination. This is a bitmask
 973          * in which the desired feature checks can be encoded.
 974          */
 975         uint64_t features_to_check;
 976 };
 977
 978 struct lxc_console_log {
 979         /* Clear the console log. */
 980         bool clear;
 981
 982         /* Retrieve the console log. */
 983         bool read;
 984
 985         /* This specifies the maximum size to read from the ringbuffer. Setting
 986          * it to 0 means that the a read can be as big as the whole ringbuffer.
 987          * On return callers can check how many bytes were actually read.
 988          * If "read" and "clear" are set to false and a non-zero value is
 989          * specified then up to "read_max" bytes of data will be discarded from
 990          * the ringbuffer.
 991          */
 992         uint64_t *read_max;
 993
 994         /* Data that was read from the ringbuffer. If "read_max" is 0 on return
 995          * "data" is invalid.
 996          */
 997         char *data;
 998 };
 999
1000 /*!
1001  * \brief Create a new container.
1002  *
1003  * \param name Name to use for container.
1004  * \param configpath Full path to configuration file to use.
1005  *
1006  * \return Newly-allocated container, or \c NULL on error.
1007  */
1008 struct lxc_container *lxc_container_new(const char *name, const char *configpath);
1009
1010 /*!
1011  * \brief Add a reference to the specified container.
1012  *
1013  * \param c Container.
1014  *
1015  * \return \c true on success, \c false on error.
1016  */
1017 int lxc_container_get(struct lxc_container *c);
1018
1019 /*!
1020  * \brief Drop a reference to the specified container.
1021  *
1022  * \param c Container.
1023  *
1024  * \return \c 0 on success, \c 1 if reference was successfully dropped
1025  * and container has been freed, and \c -1 on error.
1026  *
1027  * \warning If \c 1 is returned, \p c is no longer valid.
1028  */
1029 int lxc_container_put(struct lxc_container *c);
1030
1031 /*!
1032  * \brief Obtain a list of all container states.
1033  * \param[out] states Caller-allocated array to hold all states (may be \c NULL).
1034  *
1035  * \return Number of container states.
1036  *
1037  * \note Passing \c NULL for \p states allows the caller to first
1038  *  calculate how many states there are before calling the function again, the second time
1039  *  providing a suitably-sized array to store the static string pointers
1040  *  in.
1041  * \note The \p states array should be freed by the caller, but not the strings the elements point to.
1042  */
1043 int lxc_get_wait_states(const char **states);
1044
1045 /*!
1046  * \brief Get the value for a global config key
1047  *
1048  * \param key The name of the config key
1049  *
1050  * \return String representing the current value for the key.
1051  */
1052 const char *lxc_get_global_config_item(const char *key);
1053
1054 /*!
1055  * \brief Determine version of LXC.
1056  * \return Static string representing version of LXC in use.
1057  *
1058  * \note Returned string must not be freed.
1059  */
1060 const char *lxc_get_version(void);
1061
1062 /*!
1063  * \brief Get a list of defined containers in a lxcpath.
1064  *
1065  * \param lxcpath lxcpath under which to look.
1066  * \param names If not \c NULL, then a list of container names will be returned here.
1067  * \param cret If not \c NULL, then a list of lxc_containers will be returned here.
1068  *
1069  * \return Number of containers found, or \c -1 on error.
1070  *
1071  * \note Values returned in \p cret are sorted by container name.
1072  */
1073 int list_defined_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1074
1075 /*!
1076  * \brief Get a list of active containers for a given lxcpath.
1077  *
1078  * \param lxcpath Full \c LXCPATH path to consider.
1079  * \param[out] names Dynamically-allocated array of container names.
1080  * \param[out] cret Dynamically-allocated list of containers.
1081  *
1082  * \return Number of containers found, or -1 on error.
1083  *
1084  * \note Some of the containers may not be "defined".
1085  * \note Values returned in \p cret are sorted by container name.
1086  * \note \p names and \p cret may both (or either) be specified as \c NULL.
1087  * \note \p names and \p cret must be freed by the caller.
1088  */
1089 int list_active_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1090
1091 /*!
1092  * \brief Get a complete list of all containers for a given lxcpath.
1093  *
1094  * \param lxcpath Full \c LXCPATH path to consider.
1095  * \param[out] names Dynamically-allocated array of container name.
1096  * \param[out] cret Dynamically-allocated list of containers.
1097  *
1098  * \return Number of containers, or -1 on error.
1099  *
1100  * \note Some of the containers may not be "defined".
1101  * \note Values returned in \p cret are sorted by container name.
1102  * \note \p names and \p cret may both (or either) be specified as \c NULL.
1103  * \note \p names and \p cret must be freed by the caller.
1104  */
1105 int list_all_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1106
1107 struct lxc_log {
1108         const char *name;
1109         const char *lxcpath;
1110         const char *file;
1111         const char *level;
1112         const char *prefix;
1113         bool quiet;
1114 };
1115
1116 /*!
1117  *\brief Initialize the log
1118  *
1119  *\param log lxc log configuration.
1120  */
1121 int lxc_log_init(struct lxc_log *log);
1122
1123 /*!
1124  * \brief Close log file.
1125  */
1126 void lxc_log_close(void);
1127
1128 /*!
1129  * \brief Check if the configuration item is supported by this LXC instance.
1130  *
1131  * \param key Configuration item to check for.
1132  */
1133 bool lxc_config_item_is_supported(const char *key);
1134
1135 /*!
1136  * \brief Check if an API extension is supported by this LXC instance.
1137  *
1138  * \param extension API extension to check for.
1139  */
1140 bool lxc_has_api_extension(const char *extension);
1141
1142 #ifdef  __cplusplus
1143 }
1144 #endif
1145
1146 #endif