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