src/lxc/lxccontainer.h

   1 /* liblxcapi
   2  *
   3  * Copyright © 2012 Serge Hallyn <serge.hallyn@ubuntu.com>.
   4  * Copyright © 2012 Canonical Ltd.
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public
   8  *  License as published by the Free Software Foundation; either
   9  *  version 2.1 of the License, or (at your option) any later version.
  10
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  19  */
  20
  21 #ifndef __LXC_CONTAINER_H
  22 #define __LXC_CONTAINER_H
  23 #include "lxclock.h"
  24 #include "attach_options.h"
  25 #include <stdlib.h>
  26 #include <malloc.h>
  27
  28 #include <stdbool.h>
  29
  30 #define LXC_CLONE_KEEPNAME        (1 << 0)
  31 #define LXC_CLONE_COPYHOOKS       (1 << 1)
  32 #define LXC_CLONE_KEEPMACADDR     (1 << 2)
  33 #define LXC_CLONE_SNAPSHOT        (1 << 3)
  34 #define LXC_CLONE_MAXFLAGS        (1 << 4)
  35
  36 #define LXC_CREATE_QUIET          (1 << 0)
  37 #define LXC_CREATE_MAXFLAGS       (1 << 1)
  38
  39 struct bdev_specs;
  40
  41 struct lxc_snapshot;
  42
  43 struct lxc_container {
  44         // private fields
  45         char *name;
  46         char *configfile;
  47         struct lxc_lock *slock;
  48         struct lxc_lock *privlock;
  49         int numthreads; /* protected by privlock. */
  50         struct lxc_conf *lxc_conf; // maybe we'll just want the whole lxc_handler?
  51
  52         // public fields
  53         char *error_string;
  54         int error_num;
  55         int daemonize;
  56
  57         char *config_path;
  58
  59         bool (*is_defined)(struct lxc_container *c);  // did /var/lib/lxc/$name/config exist
  60         const char *(*state)(struct lxc_container *c);
  61         bool (*is_running)(struct lxc_container *c);  // true so long as defined and not stopped
  62         bool (*freeze)(struct lxc_container *c);
  63         bool (*unfreeze)(struct lxc_container *c);
  64         pid_t (*init_pid)(struct lxc_container *c);
  65         bool (*load_config)(struct lxc_container *c, const char *alt_file);
  66         /* The '...' is the command line.  If provided, it must be ended with a NULL */
  67         bool (*start)(struct lxc_container *c, int useinit, char * const argv[]);
  68         bool (*startl)(struct lxc_container *c, int useinit, ...);
  69         bool (*stop)(struct lxc_container *c);
  70         void (*want_daemonize)(struct lxc_container *c);
  71         // Return current config file name.  The result is strdup()d, so free the result.
  72         char *(*config_file_name)(struct lxc_container *c);
  73         // for wait, timeout == -1 means wait forever, timeout == 0 means don't wait.
  74         // otherwise timeout is seconds to wait.
  75         bool (*wait)(struct lxc_container *c, const char *state, int timeout);
  76         bool (*set_config_item)(struct lxc_container *c, const char *key, const char *value);
  77         bool (*destroy)(struct lxc_container *c);
  78         bool (*save_config)(struct lxc_container *c, const char *alt_file);
  79         bool (*create)(struct lxc_container *c, const char *t, const char *bdevtype,
  80                         struct bdev_specs *specs, int flags, char *const argv[]);
  81         bool (*createl)(struct lxc_container *c, const char *t, const char *bdevtype,
  82                         struct bdev_specs *specs, int flags, ...);
  83         /* send SIGINT to ask container to reboot */
  84         bool (*reboot)(struct lxc_container *c);
  85         /* send SIGPWR.  if timeout is not 0 or -1, do a hard stop after timeout seconds */
  86         bool (*shutdown)(struct lxc_container *c, int timeout);
  87         /* clear all network or capability items in the in-memory configuration */
  88         bool (*clear_config_item)(struct lxc_container *c, const char *key);
  89         /* print a config item to a in-memory string allocated by the caller.  Return
  90          * the length which was our would be printed. */
  91         int (*get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen);
  92         int (*get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen);
  93         char** (*get_ips)(struct lxc_container *c, char* interface, char* family, int scope);
  94         /*
  95          * get_cgroup_item returns the number of bytes read, or an error (<0).
  96          * If retv NULL or inlen 0 is passed in, then the length of the cgroup
  97          * file will be returned.  *   Otherwise it will return the # of bytes read.
  98          * If inlen is less than the number of bytes available, then the returned
  99          * value will be inlen, not the full available size of the file.
 100          */
 101         int (*get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen);
 102         bool (*set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value);
 103
 104         /*
 105          * Each container can have a custom configuration path.  However
 106          * by default it will be set to either the LXCPATH configure
 107          * variable, or the lxcpath value in the LXC_GLOBAL_CONF configuration
 108          * file (i.e. /etc/lxc/lxc.conf).
 109          * You can change the value for a specific container with
 110          * set_config_path().  Note there is no other way to specify this in
 111          * general at the moment.
 112          */
 113         const char *(*get_config_path)(struct lxc_container *c);
 114         bool (*set_config_path)(struct lxc_container *c, const char *path);
 115
 116         /*
 117          * @c: the original container
 118          * @newname: new name for the container.  If NULL, the same name is used, and
 119          *  a new lxcpath MUST be specified.
 120          * @lxcpath: lxcpath in which to create the new container.  If NULL, then the
 121          *  original container's lxcpath will be used.  (Shoudl we use the default
 122          *  instead?)
 123          * @flags: additional flags to modify cloning behavior.
 124          *  LXC_CLONE_KEEPNAME: don't edit the rootfs to change the hostname.
 125          *  LXC_CLONE_COPYHOOKS: copy all hooks into the container dir
 126          *  LXC_CLONE_KEEPMACADDR: don't change the mac address on network interfaces.
 127          *  LXC_CLONE_SNAPSHOT: snapshot the original filesystem(s).  If @devtype was not
 128          *   specified, then do so with the native bdevtype if possible, else use an
 129          *   overlayfs.
 130          * @bdevtype: optionally force the cloned bdevtype to a specified plugin.  By
 131          *  default the original  is used (subject to snapshot requirements).
 132          * @bdevdata: information about how to create the new storage (i.e. fstype and
 133          *  fsdata)
 134          * @newsize: in case of a block device backing store, an optional size.  If 0,
 135          *  then the original backing store's size will be used if possible.  Note this
 136          *  only applies to the rootfs.  For any other filesystems, the original size
 137          *  will be duplicated.
 138          * @hookargs: additional arguments to pass to the clone hook script
 139          */
 140         struct lxc_container *(*clone)(struct lxc_container *c, const char *newname,
 141                 const char *lxcpath, int flags, const char *bdevtype,
 142                 const char *bdevdata, unsigned long newsize, char **hookargs);
 143
 144         /* lxcapi_console_getfd: allocate a console tty from container @c
 145          *
 146          * @c        : the running container
 147          * @ttynum   : in : tty number to attempt to allocate or -1 to
 148          *                  allocate the first available tty
 149          *             out: the tty number that was allocated
 150          * @masterfd : out: fd refering to the master side of pty
 151          *
 152          * Returns "ttyfd" on success, -1 on failure. The returned "ttyfd" is
 153          * used to keep the tty allocated. The caller should close "ttyfd" to
 154          * indicate that it is done with the allocated console so that it can
 155          * be allocated by another caller.
 156          */
 157         int (*console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd);
 158
 159         /* lxcapi_console: allocate and run a console tty from container @c
 160          *
 161          * @c        : the running container
 162          * @ttynum   : tty number to attempt to allocate, -1 to
 163          *             allocate the first available tty, or 0 to allocate
 164          *             the console
 165          * @stdinfd  : fd to read input from
 166          * @stdoutfd : fd to write output to
 167          * @stderrfd : fd to write error output to
 168          * @escape   : the escape character (1 == 'a', 2 == 'b', ...)
 169          *
 170          * Returns 0 on success, -1 on failure. This function will not return
 171          * until the console has been exited by the user.
 172          */
 173         int (*console)(struct lxc_container *c, int ttynum,
 174                        int stdinfd, int stdoutfd, int stderrfd, int escape);
 175
 176         /* create subprocess and attach it to the container, run exec_function inside */
 177         int (*attach)(struct lxc_container *c, lxc_attach_exec_t exec_function, void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process);
 178
 179         /* run program in container, wait for it to exit */
 180         int (*attach_run_wait)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char * const argv[]);
 181         int (*attach_run_waitl)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *arg, ...);
 182
 183         /*
 184         * snapshot:
 185         * If you have /var/lib/lxc/c1 and call c->snapshot() the firs time, it
 186         * will return 0, and the container will be /var/lib/lxcsnaps/c1/snap0.
 187         * The second call will return 1, and the snapshot will be
 188         * /var/lib/lxcsnaps/c1/snap1.
 189         *
 190         * On error, returns -1.
 191         */
 192         int (*snapshot)(struct lxc_container *c, char *commentfile);
 193
 194         /*
 195          * snapshot_list() will return a description of all snapshots of c in
 196          * a simple array.  See src/tests/snapshot.c for the proper way to
 197          * free the allocated results.
 198          *
 199          * Returns the number of snapshots.
 200          */
 201         int (*snapshot_list)(struct lxc_container *, struct lxc_snapshot **);
 202
 203         /*
 204          * snapshot_restore() will create a new container based on a snapshot.
 205          * c is the container whose snapshot we look for, and snapname is the
 206          * specific snapshot name (i.e. "snap0").  newname is the name to be
 207          * used for the restored container.  If newname is the same as
 208          * c->name, then c will first be destroyed.  That will fail if the
 209          * snapshot is overlayfs-based, since the snapshots will pin the
 210          * original container.
 211          *
 212          * The restored container will be a copy (not snapshot) of the snapshot,
 213          * and restored in the lxcpath of the original container.
 214          *
 215          * As an example, c might be /var/lib/lxc/c1, snapname  might be 'snap0'
 216          * which stands for /var/lib/lxcsnaps/c1/snap0.  If newname is c2,
 217          * then snap0 will be copied to /var/lib/lxc/c2.
 218          *
 219          * Returns true on success, false on failure.
 220          */
 221         bool (*snapshot_restore)(struct lxc_container *c, char *snapname, char *newname);
 222 };
 223
 224 struct lxc_snapshot {
 225         char *name;
 226         char *comment_pathname;
 227         char *timestamp;
 228         char *lxcpath;
 229         void (*free)(struct lxc_snapshot *);
 230 };
 231
 232 struct lxc_container *lxc_container_new(const char *name, const char *configpath);
 233 int lxc_container_get(struct lxc_container *c);
 234 int lxc_container_put(struct lxc_container *c);
 235 int lxc_get_wait_states(const char **states);
 236 const char *lxc_get_default_config_path(void);
 237 const char *lxc_get_default_lvm_vg(void);
 238 const char *lxc_get_default_zfs_root(void);
 239 const char *lxc_get_version(void);
 240
 241 #if 0
 242 char ** lxc_get_valid_keys();
 243 char ** lxc_get_valid_values(char *key);
 244 #endif
 245 #endif