LXC
lxccontainer.h
1 /* SPDX-License-Identifier: LGPL-2.1+ */
2 
3 #ifndef __LXC_CONTAINER_H
4 #define __LXC_CONTAINER_H
5 
6 #include <malloc.h>
7 #include <semaphore.h>
8 #include <stdbool.h>
9 #include <stdint.h>
10 #include <stdlib.h>
11 
12 #include <lxc/attach_options.h>
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 #define LXC_CLONE_KEEPNAME (1 << 0)
19 #define LXC_CLONE_KEEPMACADDR (1 << 1)
20 #define LXC_CLONE_SNAPSHOT (1 << 2)
21 #define LXC_CLONE_KEEPBDEVTYPE (1 << 3)
22 #define LXC_CLONE_MAYBE_SNAPSHOT (1 << 4)
23 #define LXC_CLONE_MAXFLAGS (1 << 5)
24 #define LXC_CLONE_ALLOW_RUNNING (1 << 6)
25 #define LXC_CREATE_QUIET (1 << 0)
26 #define LXC_CREATE_MAXFLAGS (1 << 1)
27 #define LXC_MOUNT_API_V1 1
28 
29 struct bdev_specs;
30 
31 struct lxc_snapshot;
32 
33 struct lxc_lock;
34 
35 struct migrate_opts;
36 
37 struct lxc_console_log;
38 
39 struct lxc_mount {
40  int version;
41 };
42 
50 struct lxc_container {
51  /* private fields */
56  char *name;
57 
62  char *configfile;
63 
68  char *pidfile;
69 
74  struct lxc_lock *slock;
75 
80  struct lxc_lock *privlock;
81 
87  int numthreads;
88 
95  struct lxc_conf *lxc_conf;
96 
97  /* public fields */
99  char *error_string;
100 
103 
105  bool daemonize;
106 
108  char *config_path;
109 
117  bool (*is_defined)(struct lxc_container *c);
118 
128  const char *(*state)(struct lxc_container *c);
129 
137  bool (*is_running)(struct lxc_container *c);
138 
146  bool (*freeze)(struct lxc_container *c);
147 
155  bool (*unfreeze)(struct lxc_container *c);
156 
165  pid_t (*init_pid)(struct lxc_container *c);
166 
176  bool (*load_config)(struct lxc_container *c, const char *alt_file);
177 
187  bool (*start)(struct lxc_container *c, int useinit, char * const argv[]);
188 
202  bool (*startl)(struct lxc_container *c, int useinit, ...);
203 
211  bool (*stop)(struct lxc_container *c);
212 
222  bool (*want_daemonize)(struct lxc_container *c, bool state);
223 
234  bool (*want_close_all_fds)(struct lxc_container *c, bool state);
235 
245  char *(*config_file_name)(struct lxc_container *c);
246 
259  bool (*wait)(struct lxc_container *c, const char *state, int timeout);
260 
270  bool (*set_config_item)(struct lxc_container *c, const char *key, const char *value);
271 
281  bool (*destroy)(struct lxc_container *c);
282 
291  bool (*save_config)(struct lxc_container *c, const char *alt_file);
292 
310  bool (*create)(struct lxc_container *c, const char *t, const char *bdevtype,
311  struct bdev_specs *specs, int flags, char *const argv[]);
312 
333  bool (*createl)(struct lxc_container *c, const char *t, const char *bdevtype,
334  struct bdev_specs *specs, int flags, ...);
335 
344  bool (*rename)(struct lxc_container *c, const char *newname);
345 
353  bool (*reboot)(struct lxc_container *c);
354 
365  bool (*shutdown)(struct lxc_container *c, int timeout);
366 
372  void (*clear_config)(struct lxc_container *c);
373 
384  bool (*clear_config_item)(struct lxc_container *c, const char *key);
385 
404  int (*get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen);
405 
406 
417  char* (*get_running_config_item)(struct lxc_container *c, const char *key);
418 
440  int (*get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen);
441 
452  char** (*get_interfaces)(struct lxc_container *c);
453 
468  char** (*get_ips)(struct lxc_container *c, const char* interface, const char* family, int scope);
469 
485  int (*get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen);
486 
496  bool (*set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value);
497 
514  const char *(*get_config_path)(struct lxc_container *c);
515 
525  bool (*set_config_path)(struct lxc_container *c, const char *path);
526 
557  struct lxc_container *(*clone)(struct lxc_container *c, const char *newname,
558  const char *lxcpath, int flags, const char *bdevtype,
559  const char *bdevdata, uint64_t newsize, char **hookargs);
560 
579  int (*console_getfd)(struct lxc_container *c, int *ttynum, int *ptxfd);
580 
598  int (*console)(struct lxc_container *c, int ttynum,
599  int stdinfd, int stdoutfd, int stderrfd, int escape);
600 
614  int (*attach)(struct lxc_container *c, lxc_attach_exec_t exec_function,
615  void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process);
616 
628  int (*attach_run_wait)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char * const argv[]);
629 
641  int (*attach_run_waitl)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *arg, ...);
642 
659  int (*snapshot)(struct lxc_container *c, const char *commentfile);
660 
673  int (*snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots);
674 
692  bool (*snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname);
693 
702  bool (*snapshot_destroy)(struct lxc_container *c, const char *snapname);
703 
713  bool (*may_control)(struct lxc_container *c);
714 
725  bool (*add_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path);
726 
737  bool (*remove_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path);
738 
739  /* Post LXC-1.0 additions */
740 
749  bool (*attach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev);
750 
759  bool (*detach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev);
771  bool (*checkpoint)(struct lxc_container *c, char *directory, bool stop, bool verbose);
772 
783  bool (*restore)(struct lxc_container *c, char *directory, bool verbose);
784 
795 
804 
805  /* Post LXC-1.1 additions */
815  int (*migrate)(struct lxc_container *c, unsigned int cmd, struct migrate_opts *opts, unsigned int size);
816 
825  int (*console_log)(struct lxc_container *c, struct lxc_console_log *log);
826 
836  bool (*reboot2)(struct lxc_container *c, int timeout);
837 
841  int (*mount)(struct lxc_container *c, const char *source,
842  const char *target, const char *filesystemtype,
843  unsigned long mountflags, const void *data,
844  struct lxc_mount *mnt);
845 
849  int (*umount)(struct lxc_container *c, const char *target,
850  unsigned long mountflags, struct lxc_mount *mnt);
851 
859  int (*seccomp_notify_fd)(struct lxc_container *c);
860 
869 
877  int (*init_pidfd)(struct lxc_container *c);
878 
886  int (*devpts_fd)(struct lxc_container *c);
887 
892  int rcv_timeout;
893 
903  bool (*set_timeout)(struct lxc_container *c, int timeout);
904 };
905 
909 struct lxc_snapshot {
910  char *name;
912  char *timestamp;
913  char *lxcpath;
919  void (*free)(struct lxc_snapshot *s);
920 };
921 
922 
926 struct bdev_specs {
927  char *fstype;
928  uint64_t fssize;
929  struct {
930  char *zfsroot;
931  } zfs;
932  struct {
933  char *vg;
934  char *lv;
935  char *thinpool;
936  } lvm;
937  char *dir;
938  struct {
939  char *rbdname;
940  char *rbdpool;
941  } rbd;
942 };
943 
947 enum {
948  MIGRATE_PRE_DUMP,
949  MIGRATE_DUMP,
950  MIGRATE_RESTORE,
951  MIGRATE_FEATURE_CHECK,
952 };
953 
957 #define FEATURE_MEM_TRACK (1ULL << 0)
958 #define FEATURE_LAZY_PAGES (1ULL << 1)
959 
963 struct migrate_opts {
964  /* new members should be added at the end */
965  char *directory;
966  bool verbose;
967 
968  bool stop; /* stop the container after dump? */
969  char *predump_dir; /* relative to directory above */
970  char *pageserver_address; /* where should memory pages be send? */
971  char *pageserver_port;
972 
973  /* This flag indicates whether or not the container's rootfs will have
974  * the same inodes on checkpoint and restore. In the case of e.g. zfs
975  * send or btrfs send, or an LVM snapshot, this will be true, but it
976  * won't if e.g. you rsync the filesystems between two machines.
977  */
978  bool preserves_inodes;
979 
980  /* Path to an executable script that will be registered as a criu
981  * "action script"
982  */
983  char *action_script;
984 
985  /* If CRIU >= 2.4 is detected the option to skip in-flight connections
986  * will be enabled by default. The flag 'disable_skip_in_flight' will
987  * unconditionally disable this feature. In-flight connections are
988  * not fully established TCP connections: SYN, SYN-ACK */
989  bool disable_skip_in_flight;
990 
991  /* This is the maximum file size for deleted files (which CRIU calls
992  * "ghost" files) that will be handled. 0 indicates the CRIU default,
993  * which at this time is 1MB.
994  */
995  uint64_t ghost_limit;
996 
997  /* Some features cannot be checked by comparing the CRIU version.
998  * Features like dirty page tracking or userfaultfd depend on
999  * the architecture/kernel/criu combination. This is a bitmask
1000  * in which the desired feature checks can be encoded.
1001  */
1002  uint64_t features_to_check;
1003 };
1004 
1006  /* Clear the console log. */
1007  bool clear;
1008 
1009  /* Retrieve the console log. */
1010  bool read;
1011 
1012  /* This specifies the maximum size to read from the ringbuffer. Setting
1013  * it to 0 means that the a read can be as big as the whole ringbuffer.
1014  * On return callers can check how many bytes were actually read.
1015  * If "read" and "clear" are set to false and a non-zero value is
1016  * specified then up to "read_max" bytes of data will be discarded from
1017  * the ringbuffer.
1018  */
1019  uint64_t *read_max;
1020 
1021  /* Data that was read from the ringbuffer. If "read_max" is 0 on return
1022  * "data" is invalid.
1023  */
1024  char *data;
1025 };
1026 
1035 struct lxc_container *lxc_container_new(const char *name, const char *configpath);
1036 
1044 int lxc_container_get(struct lxc_container *c);
1045 
1056 int lxc_container_put(struct lxc_container *c);
1057 
1070 int lxc_get_wait_states(const char **states);
1071 
1079 const char *lxc_get_global_config_item(const char *key);
1080 
1087 const char *lxc_get_version(void);
1088 
1100 int list_defined_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1101 
1116 int list_active_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1117 
1132 int list_all_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1133 
1134 struct lxc_log {
1135  const char *name;
1136  const char *lxcpath;
1137  const char *file;
1138  const char *level;
1139  const char *prefix;
1140  bool quiet;
1141 };
1142 
1148 int lxc_log_init(struct lxc_log *log);
1149 
1153 void lxc_log_close(void);
1154 
1160 bool lxc_config_item_is_supported(const char *key);
1161 
1167 bool lxc_has_api_extension(const char *extension);
1168 
1169 #ifdef __cplusplus
1170 }
1171 #endif
1172 
1173 #endif
Specifications for how to create a new backing store.
Definition: lxccontainer.h:926
char * zfsroot
Definition: lxccontainer.h:930
char * vg
Definition: lxccontainer.h:933
char * fstype
Definition: lxccontainer.h:927
char * dir
Definition: lxccontainer.h:937
char * lv
Definition: lxccontainer.h:934
char * rbdname
Definition: lxccontainer.h:939
uint64_t fssize
Definition: lxccontainer.h:928
char * rbdpool
Definition: lxccontainer.h:940
char * thinpool
Definition: lxccontainer.h:935
Definition: attach_options.h:90
Definition: lxccontainer.h:1005
Definition: lxccontainer.h:50
int(* seccomp_notify_fd_active)(struct lxc_container *c)
Retrieve a file descriptor for the running container's seccomp filter.
Definition: lxccontainer.h:868
bool(* checkpoint)(struct lxc_container *c, char *directory, bool stop, bool verbose)
Checkpoint a container.
Definition: lxccontainer.h:771
bool(* wait)(struct lxc_container *c, const char *state, int timeout)
Wait for container to reach a particular state.
Definition: lxccontainer.h:259
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:333
bool(* load_config)(struct lxc_container *c, const char *alt_file)
Load the specified configuration for the container.
Definition: lxccontainer.h:176
bool(* snapshot_destroy_all)(struct lxc_container *c)
Destroy all the container's snapshot.
Definition: lxccontainer.h:803
int(* console_log)(struct lxc_container *c, struct lxc_console_log *log)
Query the console log of a container.
Definition: lxccontainer.h:825
int(* attach)(struct lxc_container *c, 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:614
int(* attach_run_waitl)(struct lxc_container *c, 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:641
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:725
bool(* destroy)(struct lxc_container *c)
Delete the container.
Definition: lxccontainer.h:281
bool(* want_close_all_fds)(struct lxc_container *c, bool state)
Change whether the container wishes all file descriptors to be closed on startup. The LISTEN_FDS envi...
Definition: lxccontainer.h:234
void(* clear_config)(struct lxc_container *c)
Completely clear the containers in-memory configuration.
Definition: lxccontainer.h:372
char * error_string
Definition: lxccontainer.h:99
bool(* attach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev)
Add specified netdev to the container.
Definition: lxccontainer.h:749
bool(* set_config_item)(struct lxc_container *c, const char *key, const char *value)
Set a key/value configuration option.
Definition: lxccontainer.h:270
bool(* rename)(struct lxc_container *c, const char *newname)
Rename a container.
Definition: lxccontainer.h:344
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:737
bool(* clear_config_item)(struct lxc_container *c, const char *key)
Clear a configuration item.
Definition: lxccontainer.h:384
bool(* startl)(struct lxc_container *c, int useinit,...)
Start the container (list variant).
Definition: lxccontainer.h:202
bool(* set_timeout)(struct lxc_container *c, int timeout)
Set response receive timeout for LXC commands.
Definition: lxccontainer.h:903
int(* umount)(struct lxc_container *c, const char *target, unsigned long mountflags, struct lxc_mount *mnt)
Unmount the container's path target.
Definition: lxccontainer.h:849
bool(* start)(struct lxc_container *c, int useinit, char *const argv[])
Start the container.
Definition: lxccontainer.h:187
bool(* reboot2)(struct lxc_container *c, int timeout)
Request the container reboot by sending it SIGINT.
Definition: lxccontainer.h:836
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:598
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:485
int(* console_getfd)(struct lxc_container *c, int *ttynum, int *ptxfd)
Allocate a console tty for the container.
Definition: lxccontainer.h:579
bool(* stop)(struct lxc_container *c)
Stop the container.
Definition: lxccontainer.h:211
int(* mount)(struct lxc_container *c, const char *source, const char *target, const char *filesystemtype, unsigned long mountflags, const void *data, struct lxc_mount *mnt)
Mount the host's path source onto the container's path target.
Definition: lxccontainer.h:841
char * config_path
Definition: lxccontainer.h:108
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:404
bool(* may_control)(struct lxc_container *c)
Determine if the caller may control the container.
Definition: lxccontainer.h:713
bool(* snapshot_destroy)(struct lxc_container *c, const char *snapname)
Destroy the specified snapshot.
Definition: lxccontainer.h:702
bool(* is_defined)(struct lxc_container *c)
Determine if /var/lib/lxc/$name/config exists.
Definition: lxccontainer.h:117
int(* devpts_fd)(struct lxc_container *c)
Retrieve a mount fd for the container's devpts instance.
Definition: lxccontainer.h:886
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:440
int(* attach_run_wait)(struct lxc_container *c, 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:628
int(* init_pidfd)(struct lxc_container *c)
Retrieve a pidfd for the container's init process.
Definition: lxccontainer.h:877
pid_t(* init_pid)(struct lxc_container *c)
Determine process ID of the containers init process.
Definition: lxccontainer.h:165
bool(* want_daemonize)(struct lxc_container *c, bool state)
Change whether the container wants to run disconnected from the terminal.
Definition: lxccontainer.h:222
bool(* shutdown)(struct lxc_container *c, int timeout)
Request the container shutdown by sending it SIGPWR.
Definition: lxccontainer.h:365
const char *(* state)(struct lxc_container *c)
Determine state of container.
Definition: lxccontainer.h:128
int(* seccomp_notify_fd)(struct lxc_container *c)
Retrieve a file descriptor for the container's seccomp filter.
Definition: lxccontainer.h:859
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:815
int error_num
Definition: lxccontainer.h:102
bool daemonize
Definition: lxccontainer.h:105
bool(* is_running)(struct lxc_container *c)
Determine if container is running.
Definition: lxccontainer.h:137
int(* snapshot)(struct lxc_container *c, const char *commentfile)
Create a container snapshot.
Definition: lxccontainer.h:659
bool(* freeze)(struct lxc_container *c)
Freeze running container.
Definition: lxccontainer.h:146
int(* snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots)
Obtain a list of container snapshots.
Definition: lxccontainer.h:673
bool(* save_config)(struct lxc_container *c, const char *alt_file)
Save configuration to a file.
Definition: lxccontainer.h:291
bool(* detach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev)
Remove specified netdev from the container.
Definition: lxccontainer.h:759
bool(* unfreeze)(struct lxc_container *c)
Thaw a frozen container.
Definition: lxccontainer.h:155
bool(* restore)(struct lxc_container *c, char *directory, bool verbose)
Restore a container from a checkpoint.
Definition: lxccontainer.h:783
bool(* reboot)(struct lxc_container *c)
Request the container reboot by sending it SIGINT.
Definition: lxccontainer.h:353
bool(* snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname)
Create a new container based on a snapshot.
Definition: lxccontainer.h:692
bool(* set_config_path)(struct lxc_container *c, const char *path)
Set the full path to the containers configuration file.
Definition: lxccontainer.h:525
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:310
bool(* destroy_with_snapshots)(struct lxc_container *c)
Delete the container and all its snapshots.
Definition: lxccontainer.h:794
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:496
Definition: lxclock.h:37
Definition: lxccontainer.h:1134
Definition: lxccontainer.h:39
An LXC container snapshot.
Definition: lxccontainer.h:909
void(* free)(struct lxc_snapshot *s)
De-allocate the snapshot.
Definition: lxccontainer.h:919
char * name
Definition: lxccontainer.h:910
char * lxcpath
Definition: lxccontainer.h:913
char * timestamp
Definition: lxccontainer.h:912
char * comment_pathname
Definition: lxccontainer.h:911
Options for the migrate API call.
Definition: lxccontainer.h:963