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