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