LXC
lxccontainer.h
Go to the documentation of this file.
1 
23 #ifndef __LXC_CONTAINER_H
24 #define __LXC_CONTAINER_H
25 
26 #include <malloc.h>
27 #include <semaphore.h>
28 #include <stdbool.h>
29 #include <stdint.h>
30 #include <stdlib.h>
31 
32 #include <lxc/attach_options.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 #define LXC_CLONE_KEEPNAME (1 << 0)
39 #define LXC_CLONE_KEEPMACADDR (1 << 1)
40 #define LXC_CLONE_SNAPSHOT (1 << 2)
41 #define LXC_CLONE_KEEPBDEVTYPE (1 << 3)
42 #define LXC_CLONE_MAYBE_SNAPSHOT (1 << 4)
43 #define LXC_CLONE_MAXFLAGS (1 << 5)
44 #define LXC_CREATE_QUIET (1 << 0)
45 #define LXC_CREATE_MAXFLAGS (1 << 1)
47 struct bdev_specs;
48 
49 struct lxc_snapshot;
50 
51 struct lxc_lock;
52 
53 struct migrate_opts;
54 
55 struct lxc_console_log;
56 
64 struct lxc_container {
65  /* private fields */
70  char *name;
71 
76  char *configfile;
77 
83  char *ocihookfile;
84 
89  char *pidfile;
90 
95  char *exit_fifo;
96 
101  unsigned int start_timeout;
102 
107  struct lxc_lock *slock;
108 
113  struct lxc_lock *privlock;
114 
120  int numthreads;
121 
128  struct lxc_conf *lxc_conf;
129 
130  /* public fields */
133 
136 
138  bool daemonize;
139 
142 
145 
147  bool detach;
148 
150  char *config_path;
151 
159  bool (*is_defined)(struct lxc_container *c);
160 
170  const char *(*state)(struct lxc_container *c);
171 
179  bool (*is_running)(struct lxc_container *c);
180 
188  bool (*freeze)(struct lxc_container *c);
189 
197  bool (*unfreeze)(struct lxc_container *c);
198 
207  pid_t (*init_pid)(struct lxc_container *c);
208 
218  bool (*load_config)(struct lxc_container *c, const char *alt_file);
219 
229  bool (*start)(struct lxc_container *c, int useinit, char * const argv[]);
230 
244  bool (*startl)(struct lxc_container *c, int useinit, ...);
245 
253  bool (*stop)(struct lxc_container *c);
254 
264  bool (*want_disable_pty)(struct lxc_container *c, bool state);
265 
275  bool (*want_open_stdin)(struct lxc_container *c, bool state);
276 
286  bool (*want_daemonize)(struct lxc_container *c, bool state);
287 
297  bool (*want_close_all_fds)(struct lxc_container *c, bool state);
298 
308  char *(*config_file_name)(struct lxc_container *c);
309 
322  bool (*wait)(struct lxc_container *c, const char *state, int timeout);
323 
333  bool (*set_config_item)(struct lxc_container *c, const char *key, const char *value);
334 
344  bool (*destroy)(struct lxc_container *c);
345 
354  bool (*save_config)(struct lxc_container *c, const char *alt_file);
355 
373  bool (*create)(struct lxc_container *c, const char *t, const char *bdevtype,
374  struct bdev_specs *specs, int flags, char *const argv[]);
375 
396  bool (*createl)(struct lxc_container *c, const char *t, const char *bdevtype,
397  struct bdev_specs *specs, int flags, ...);
398 
407  bool (*rename)(struct lxc_container *c, const char *newname);
408 
416  bool (*reboot)(struct lxc_container *c);
417 
428  bool (*shutdown)(struct lxc_container *c, int timeout);
429 
435  void (*clear_config)(struct lxc_container *c);
436 
447  bool (*clear_config_item)(struct lxc_container *c, const char *key);
448 
467  int (*get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen);
468 
469 
480  char* (*get_running_config_item)(struct lxc_container *c, const char *key);
481 
503  int (*get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen);
504 
515  char** (*get_interfaces)(struct lxc_container *c);
516 
531  char** (*get_ips)(struct lxc_container *c, const char* interface, const char* family, int scope);
532 
548  int (*get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen);
549 
559  bool (*set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value);
560 
577  const char *(*get_config_path)(struct lxc_container *c);
578 
588  bool (*set_config_path)(struct lxc_container *c, const char *path);
589 
620  struct lxc_container *(*clone)(struct lxc_container *c, const char *newname,
621  const char *lxcpath, int flags, const char *bdevtype,
622  const char *bdevdata, uint64_t newsize, char **hookargs);
623 
642  int (*console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd);
643 
661  int (*console)(struct lxc_container *c, int ttynum,
662  int stdinfd, int stdoutfd, int stderrfd, int escape);
663 
677  int (*attach)(struct lxc_container *c, const char *suffix, lxc_attach_exec_t exec_function,
678  void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process);
679 
691  int (*attach_run_wait)(struct lxc_container *c, const char *suffix, lxc_attach_options_t *options, const char *program, const char * const argv[]);
692 
704  int (*attach_run_waitl)(struct lxc_container *c, const char *suffix, lxc_attach_options_t *options, const char *program, const char *arg, ...);
705 
722  int (*snapshot)(struct lxc_container *c, const char *commentfile);
723 
736  int (*snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots);
737 
755  bool (*snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname);
756 
765  bool (*snapshot_destroy)(struct lxc_container *c, const char *snapname);
766 
776  bool (*may_control)(struct lxc_container *c);
777 
788  bool (*add_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path);
789 
800  bool (*remove_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path);
801 
802  /* Post LXC-1.0 additions */
803 
812  bool (*attach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev);
813 
822  bool (*detach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev);
834  bool (*checkpoint)(struct lxc_container *c, char *directory, bool stop, bool verbose);
835 
846  bool (*restore)(struct lxc_container *c, char *directory, bool verbose);
847 
858 
867 
868  /* Post LXC-1.1 additions */
878  int (*migrate)(struct lxc_container *c, unsigned int cmd, struct migrate_opts *opts, unsigned int size);
879 
888  int (*console_log)(struct lxc_container *c, struct lxc_console_log *log);
889 
899  bool (*reboot2)(struct lxc_container *c, int timeout);
900 
909  bool (*set_terminal_init_fifos)(struct lxc_container *c, const char *in, const char *out, const char *err);
910 
919  bool (*add_terminal_fifos)(struct lxc_container *c, const char *in, const char *out, const char *err);
920 
929  bool (*set_container_info_file) (struct lxc_container *c, const char *info_file);
930 
939  bool (*set_start_timeout)(struct lxc_container *c, unsigned int start_timeout);
940 
949  bool (*clean_container_resource) (struct lxc_container *c, pid_t pid);
950 
960  bool (*get_container_pids)(struct lxc_container *c,pid_t **pids,size_t *pids_len);
967  bool (*set_terminal_winch)(struct lxc_container *c, unsigned int height, unsigned int width);
968 
969  bool (*set_exec_terminal_winch)(struct lxc_container *c, const char *suffix, unsigned int height, unsigned int width);
970 };
971 
975 struct lxc_snapshot {
976  char *name;
978  char *timestamp;
979  char *lxcpath;
985  void (*free)(struct lxc_snapshot *s);
986 };
987 
988 
992 struct bdev_specs {
993  char *fstype;
994  uint64_t fssize;
995  struct {
996  char *zfsroot;
997  } zfs;
998  struct {
999  char *vg;
1000  char *lv;
1001  char *thinpool;
1002  } lvm;
1003  char *dir;
1004  struct {
1005  char *rbdname;
1006  char *rbdpool;
1007  } rbd;
1008 };
1009 
1013 enum {
1014  MIGRATE_PRE_DUMP,
1015  MIGRATE_DUMP,
1016  MIGRATE_RESTORE,
1017  MIGRATE_FEATURE_CHECK,
1018 };
1019 
1023 #define FEATURE_MEM_TRACK (1ULL << 0)
1024 #define FEATURE_LAZY_PAGES (1ULL << 1)
1025 
1030  /* new members should be added at the end */
1031  char *directory;
1032  bool verbose;
1033 
1034  bool stop; /* stop the container after dump? */
1035  char *predump_dir; /* relative to directory above */
1036  char *pageserver_address; /* where should memory pages be send? */
1037  char *pageserver_port;
1038 
1039  /* This flag indicates whether or not the container's rootfs will have
1040  * the same inodes on checkpoint and restore. In the case of e.g. zfs
1041  * send or btrfs send, or an LVM snapshot, this will be true, but it
1042  * won't if e.g. you rsync the filesystems between two machines.
1043  */
1044  bool preserves_inodes;
1045 
1046  /* Path to an executable script that will be registered as a criu
1047  * "action script"
1048  */
1049  char *action_script;
1050 
1051  /* If CRIU >= 2.4 is detected the option to skip in-flight connections
1052  * will be enabled by default. The flag 'disable_skip_in_flight' will
1053  * unconditionally disable this feature. In-flight connections are
1054  * not fully established TCP connections: SYN, SYN-ACK */
1055  bool disable_skip_in_flight;
1056 
1057  /* This is the maximum file size for deleted files (which CRIU calls
1058  * "ghost" files) that will be handled. 0 indicates the CRIU default,
1059  * which at this time is 1MB.
1060  */
1061  uint64_t ghost_limit;
1062 
1063  /* Some features cannot be checked by comparing the CRIU version.
1064  * Features like dirty page tracking or userfaultfd depend on
1065  * the architecture/kernel/criu combination. This is a bitmask
1066  * in which the desired feature checks can be encoded.
1067  */
1068  uint64_t features_to_check;
1069 };
1070 
1072  /* Clear the console log. */
1073  bool clear;
1074 
1075  /* Retrieve the console log. */
1076  bool read;
1077 
1078  /* This specifies the maximum size to read from the ringbuffer. Setting
1079  * it to 0 means that the a read can be as big as the whole ringbuffer.
1080  * On return callers can check how many bytes were actually read.
1081  * If "read" and "clear" are set to false and a non-zero value is
1082  * specified then up to "read_max" bytes of data will be discarded from
1083  * the ringbuffer.
1084  */
1085  uint64_t *read_max;
1086 
1087  /* Data that was read from the ringbuffer. If "read_max" is 0 on return
1088  * "data" is invalid.
1089  */
1090  char *data;
1091 };
1092 
1101 struct lxc_container *lxc_container_new(const char *name, const char *configpath);
1102 
1113 struct lxc_container *lxc_container_without_config_new(const char *name, const char *configpath);
1114 
1122 int lxc_container_get(struct lxc_container *c);
1123 
1134 int lxc_container_put(struct lxc_container *c);
1135 
1148 int lxc_get_wait_states(const char **states);
1149 
1157 const char *lxc_get_global_config_item(const char *key);
1158 
1165 const char *lxc_get_version(void);
1166 
1178 int list_defined_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1179 
1194 int list_active_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1195 
1210 int list_all_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1211 
1212 struct lxc_log {
1213  const char *name;
1214  const char *lxcpath;
1215  const char *file;
1216  const char *level;
1217  const char *prefix;
1218  bool quiet;
1219 };
1220 
1226 int lxc_log_init(struct lxc_log *log);
1227 
1231 void lxc_log_close(void);
1232 
1238 bool lxc_config_item_is_supported(const char *key);
1239 
1240 #ifdef __cplusplus
1241 }
1242 #endif
1243 
1244 #endif
bool(* start)(struct lxc_container *c, int useinit, char *const argv[])
Start the container.
Definition: lxccontainer.h:229
Definition: lxccontainer.h:64
bool daemonize
Definition: lxccontainer.h:138
int lxc_log_init(struct lxc_log *log)
Initialize the log.
int(* attach_run_waitl)(struct lxc_container *c, const char *suffix, lxc_attach_options_t *options, const char *program, const char *arg,...)
Run a program inside a container and wait for it to exit (list variant).
Definition: lxccontainer.h:704
bool(* unfreeze)(struct lxc_container *c)
Thaw a frozen container.
Definition: lxccontainer.h:197
int(* console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd)
Allocate a console tty for the container.
Definition: lxccontainer.h:642
bool(* attach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev)
Add specified netdev to the container.
Definition: lxccontainer.h:812
int lxc_get_wait_states(const char **states)
Obtain a list of all container states.
bool(* set_container_info_file)(struct lxc_container *c, const char *info_file)
An API call to set the path of info file.
Definition: lxccontainer.h:929
int(* get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen)
Retrieve the specified cgroup subsystem value for the container.
Definition: lxccontainer.h:548
int(* attach)(struct lxc_container *c, const char *suffix, lxc_attach_exec_t exec_function, void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process)
Create a sub-process attached to a container and run a function inside it.
Definition: lxccontainer.h:677
bool(* remove_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path)
Remove specified device from the container.
Definition: lxccontainer.h:800
int(* console)(struct lxc_container *c, int ttynum, int stdinfd, int stdoutfd, int stderrfd, int escape)
Allocate and run a console tty.
Definition: lxccontainer.h:661
bool disable_pty
Definition: lxccontainer.h:141
bool(* snapshot_destroy_all)(struct lxc_container *c)
Destroy all the container&#39;s snapshot.
Definition: lxccontainer.h:866
char * error_string
Definition: lxccontainer.h:132
pid_t(* init_pid)(struct lxc_container *c)
Determine process ID of the containers init process.
Definition: lxccontainer.h:207
const char * lxc_get_global_config_item(const char *key)
Get the value for a global config key.
bool(* destroy_with_snapshots)(struct lxc_container *c)
Delete the container and all its snapshots.
Definition: lxccontainer.h:857
char * vg
Definition: lxccontainer.h:999
bool(* detach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev)
Remove specified netdev from the container.
Definition: lxccontainer.h:822
Specifications for how to create a new backing store.
Definition: lxccontainer.h:992
bool(* shutdown)(struct lxc_container *c, int timeout)
Request the container shutdown by sending it SIGPWR.
Definition: lxccontainer.h:428
int(* get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen)
Retrieve the value of a config item.
Definition: lxccontainer.h:467
bool(* create)(struct lxc_container *c, const char *t, const char *bdevtype, struct bdev_specs *specs, int flags, char *const argv[])
Create a container.
Definition: lxccontainer.h:373
bool(* clear_config_item)(struct lxc_container *c, const char *key)
Clear a configuration item.
Definition: lxccontainer.h:447
uint64_t fssize
Definition: lxccontainer.h:994
bool(* add_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path)
Add specified device to the container.
Definition: lxccontainer.h:788
int(* migrate)(struct lxc_container *c, unsigned int cmd, struct migrate_opts *opts, unsigned int size)
An API call to perform various migration operations.
Definition: lxccontainer.h:878
bool(* get_container_pids)(struct lxc_container *c, pid_t **pids, size_t *pids_len)
An API call to get container pids.
Definition: lxccontainer.h:960
char * zfsroot
Definition: lxccontainer.h:996
bool(* createl)(struct lxc_container *c, const char *t, const char *bdevtype, struct bdev_specs *specs, int flags,...)
Create a container (list variant).
Definition: lxccontainer.h:396
char * timestamp
Definition: lxccontainer.h:978
bool lxc_config_item_is_supported(const char *key)
Check if the configuration item is supported by this LXC instance.
bool(* checkpoint)(struct lxc_container *c, char *directory, bool stop, bool verbose)
Checkpoint a container.
Definition: lxccontainer.h:834
int list_defined_containers(const char *lxcpath, char ***names, struct lxc_container ***cret)
Get a list of defined containers in a lxcpath.
char * name
Definition: lxccontainer.h:976
int lxc_container_put(struct lxc_container *c)
Drop a reference to the specified container.
void lxc_log_close(void)
Close log file.
bool(* want_open_stdin)(struct lxc_container *c, bool state)
Change whether the container wants to keep stdin active for parent process of container.
Definition: lxccontainer.h:275
void(* free)(struct lxc_snapshot *s)
De-allocate the snapshot.
Definition: lxccontainer.h:985
int(* lxc_attach_exec_t)(void *payload, int msg_fd)
Definition: attach_options.h:74
bool(* set_terminal_winch)(struct lxc_container *c, unsigned int height, unsigned int width)
An API call to set terminal winch.
Definition: lxccontainer.h:967
bool(* set_terminal_init_fifos)(struct lxc_container *c, const char *in, const char *out, const char *err)
An API call to change the path of the console default fifos.
Definition: lxccontainer.h:909
int error_num
Definition: lxccontainer.h:135
void(* clear_config)(struct lxc_container *c)
Completely clear the containers in-memory configuration.
Definition: lxccontainer.h:435
bool(* restore)(struct lxc_container *c, char *directory, bool verbose)
Restore a container from a checkpoint.
Definition: lxccontainer.h:846
bool(* set_start_timeout)(struct lxc_container *c, unsigned int start_timeout)
An API call to set start timeout.
Definition: lxccontainer.h:939
bool open_stdin
Definition: lxccontainer.h:144
char * rbdpool
Definition: lxccontainer.h:1006
char * thinpool
Definition: lxccontainer.h:1001
bool(* reboot)(struct lxc_container *c)
Request the container reboot by sending it SIGINT.
Definition: lxccontainer.h:416
struct lxc_container * lxc_container_without_config_new(const char *name, const char *configpath)
Create a new container without loading config.
An LXC container snapshot.
Definition: lxccontainer.h:975
bool(* rename)(struct lxc_container *c, const char *newname)
Rename a container.
Definition: lxccontainer.h:407
bool(* may_control)(struct lxc_container *c)
Determine if the caller may control the container.
Definition: lxccontainer.h:776
char * lxcpath
Definition: lxccontainer.h:979
bool(* is_defined)(struct lxc_container *c)
Determine if /var/lib/lxc/$name/config exists.
Definition: lxccontainer.h:159
char * rbdname
Definition: lxccontainer.h:1005
bool(* wait)(struct lxc_container *c, const char *state, int timeout)
Wait for container to reach a particular state.
Definition: lxccontainer.h:322
bool(* load_config)(struct lxc_container *c, const char *alt_file)
Load the specified configuration for the container.
Definition: lxccontainer.h:218
int lxc_container_get(struct lxc_container *c)
Add a reference to the specified container.
bool(* snapshot_destroy)(struct lxc_container *c, const char *snapname)
Destroy the specified snapshot.
Definition: lxccontainer.h:765
int(* attach_run_wait)(struct lxc_container *c, const char *suffix, lxc_attach_options_t *options, const char *program, const char *const argv[])
Run a program inside a container and wait for it to exit.
Definition: lxccontainer.h:691
int list_all_containers(const char *lxcpath, char ***names, struct lxc_container ***cret)
Get a complete list of all containers for a given lxcpath.
bool(* want_close_all_fds)(struct lxc_container *c, bool state)
Change whether the container wishes all file descriptors to be closed on startup. ...
Definition: lxccontainer.h:297
bool(* reboot2)(struct lxc_container *c, int timeout)
Request the container reboot by sending it SIGINT.
Definition: lxccontainer.h:899
bool(* set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value)
Set the specified cgroup subsystem value for the container.
Definition: lxccontainer.h:559
bool(* set_config_path)(struct lxc_container *c, const char *path)
Set the full path to the containers configuration file.
Definition: lxccontainer.h:588
Definition: lxccontainer.h:1212
bool detach
Definition: lxccontainer.h:147
bool(* stop)(struct lxc_container *c)
Stop the container.
Definition: lxccontainer.h:253
bool(* is_running)(struct lxc_container *c)
Determine if container is running.
Definition: lxccontainer.h:179
bool(* set_config_item)(struct lxc_container *c, const char *key, const char *value)
Set a key/value configuration option.
Definition: lxccontainer.h:333
char * lv
Definition: lxccontainer.h:1000
bool(* snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname)
Create a new container based on a snapshot.
Definition: lxccontainer.h:755
struct lxc_container * lxc_container_new(const char *name, const char *configpath)
Create a new container.
Definition: lxclock.h:53
Definition: attach_options.h:79
bool(* freeze)(struct lxc_container *c)
Freeze running container.
Definition: lxccontainer.h:188
const char *(* state)(struct lxc_container *c)
Determine state of container.
Definition: lxccontainer.h:170
int(* snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots)
Obtain a list of container snapshots.
Definition: lxccontainer.h:736
bool(* clean_container_resource)(struct lxc_container *c, pid_t pid)
An API call to clean resources of container.
Definition: lxccontainer.h:949
int list_active_containers(const char *lxcpath, char ***names, struct lxc_container ***cret)
Get a list of active containers for a given lxcpath.
char * fstype
Definition: lxccontainer.h:993
int(* console_log)(struct lxc_container *c, struct lxc_console_log *log)
Query the console log of a container.
Definition: lxccontainer.h:888
char * comment_pathname
Definition: lxccontainer.h:977
const char * lxc_get_version(void)
Determine version of LXC.
Definition: lxccontainer.h:1071
bool(* startl)(struct lxc_container *c, int useinit,...)
Start the container (list variant).
Definition: lxccontainer.h:244
char * config_path
Definition: lxccontainer.h:150
bool(* save_config)(struct lxc_container *c, const char *alt_file)
Save configuration to a file.
Definition: lxccontainer.h:354
bool(* destroy)(struct lxc_container *c)
Delete the container.
Definition: lxccontainer.h:344
Options for the migrate API call.
Definition: lxccontainer.h:1029
bool(* add_terminal_fifos)(struct lxc_container *c, const char *in, const char *out, const char *err)
An API call to add the path of terminal fifos.
Definition: lxccontainer.h:919
bool(* want_disable_pty)(struct lxc_container *c, bool state)
Change whether the container wants to create pty or pipes from the console log.
Definition: lxccontainer.h:264
int(* get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen)
Retrieve a list of config item keys given a key prefix.
Definition: lxccontainer.h:503
bool(* want_daemonize)(struct lxc_container *c, bool state)
Change whether the container wants to run disconnected from the terminal.
Definition: lxccontainer.h:286
char * dir
Definition: lxccontainer.h:1003
int(* snapshot)(struct lxc_container *c, const char *commentfile)
Create a container snapshot.
Definition: lxccontainer.h:722