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
15extern "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#define LXC_IMAGE_OCI_KEY "lxc.imagetype.oci"
30
31struct bdev_specs;
32
33struct lxc_snapshot;
34
35struct lxc_lock;
36
37struct migrate_opts;
38
39struct lxc_console_log;
40
41struct lxc_mount {
42 int version;
43};
44
46 uint64_t read;
47 uint64_t write;
48 uint64_t total;
49};
50
52 /* State of container */
53 const char *state;
54 /* The process ID of the init container */
55 pid_t init;
56 /* Current pids */
57 uint64_t pids_current;
58 /* CPU usage */
59 uint64_t cpu_use_nanos;
60 uint64_t cpu_use_user;
61 uint64_t cpu_use_sys;
62 /* BlkIO usage */
63 struct lxc_blkio_metrics io_service_bytes;
64 struct lxc_blkio_metrics io_serviced;
65 /* Memory usage */
66 uint64_t mem_used;
67 uint64_t mem_limit;
68 /* Kernel Memory usage */
69 uint64_t kmem_used;
70 uint64_t kmem_limit;
71 /* Cache usage */
72 uint64_t cache;
73 uint64_t cache_total;
74 /* total inactive file */
75 uint64_t inactive_file_total;
76};
77
86 /* private fields */
91 char *name;
92
97 char *configfile;
98
103 char *pidfile;
104
109 struct lxc_lock *slock;
110
115 struct lxc_lock *privlock;
116
122 int numthreads;
123
130 struct lxc_conf *lxc_conf;
131
132 /* public fields */
135
138
141
144
149 char *exit_fifo;
152
155
161 char *ocihookfile;
162
167 unsigned int start_timeout;
168
173 bool image_type_oci;
174
182 bool (*is_defined)(struct lxc_container *c);
183
193 const char *(*state)(struct lxc_container *c);
194
202 bool (*is_running)(struct lxc_container *c);
203
211 bool (*freeze)(struct lxc_container *c);
212
220 bool (*unfreeze)(struct lxc_container *c);
221
230 pid_t (*init_pid)(struct lxc_container *c);
231
241 bool (*load_config)(struct lxc_container *c, const char *alt_file);
242
252 bool (*start)(struct lxc_container *c, int useinit, char * const argv[]);
253
267 bool (*startl)(struct lxc_container *c, int useinit, ...);
268
276 bool (*stop)(struct lxc_container *c);
277
287 bool (*want_daemonize)(struct lxc_container *c, bool state);
288
298 bool (*want_close_all_fds)(struct lxc_container *c, bool state);
299
309 char *(*config_file_name)(struct lxc_container *c);
310
323 bool (*wait)(struct lxc_container *c, const char *state, int timeout);
324
334 bool (*set_config_item)(struct lxc_container *c, const char *key, const char *value);
335
345 bool (*destroy)(struct lxc_container *c);
346
355 bool (*save_config)(struct lxc_container *c, const char *alt_file);
356
374 bool (*create)(struct lxc_container *c, const char *t, const char *bdevtype,
375 struct bdev_specs *specs, int flags, char *const argv[]);
376
397 bool (*createl)(struct lxc_container *c, const char *t, const char *bdevtype,
398 struct bdev_specs *specs, int flags, ...);
399
408 bool (*rename)(struct lxc_container *c, const char *newname);
409
417 bool (*reboot)(struct lxc_container *c);
418
429 bool (*shutdown)(struct lxc_container *c, int timeout);
430
436 void (*clear_config)(struct lxc_container *c);
437
448 bool (*clear_config_item)(struct lxc_container *c, const char *key);
449
468 int (*get_config_item)(struct lxc_container *c, const char *key, char *retv, int inlen);
469
470
481 char* (*get_running_config_item)(struct lxc_container *c, const char *key);
482
504 int (*get_keys)(struct lxc_container *c, const char *key, char *retv, int inlen);
505
516 char** (*get_interfaces)(struct lxc_container *c);
517
532 char** (*get_ips)(struct lxc_container *c, const char* interface, const char* family, int scope);
533
549 int (*get_cgroup_item)(struct lxc_container *c, const char *subsys, char *retv, int inlen);
550
560 bool (*set_cgroup_item)(struct lxc_container *c, const char *subsys, const char *value);
561
578 const char *(*get_config_path)(struct lxc_container *c);
579
589 bool (*set_config_path)(struct lxc_container *c, const char *path);
590
621 struct lxc_container *(*clone)(struct lxc_container *c, const char *newname,
622 const char *lxcpath, int flags, const char *bdevtype,
623 const char *bdevdata, uint64_t newsize, char **hookargs);
624
643 int (*console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd);
644
662 int (*console)(struct lxc_container *c, int ttynum,
663 int stdinfd, int stdoutfd, int stderrfd, int escape);
664
678 int (*attach)(struct lxc_container *c, lxc_attach_exec_t exec_function,
679 void *exec_payload, lxc_attach_options_t *options, pid_t *attached_process);
680
692 int (*attach_run_wait)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char * const argv[]);
693
705 int (*attach_run_waitl)(struct lxc_container *c, lxc_attach_options_t *options, const char *program, const char *arg, ...);
706
723 int (*snapshot)(struct lxc_container *c, const char *commentfile);
724
737 int (*snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots);
738
756 bool (*snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname);
757
766 bool (*snapshot_destroy)(struct lxc_container *c, const char *snapname);
767
777 bool (*may_control)(struct lxc_container *c);
778
789 bool (*add_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path);
790
801 bool (*remove_device_node)(struct lxc_container *c, const char *src_path, const char *dest_path);
802
803 /* Post LXC-1.0 additions */
804
813 bool (*attach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev);
814
823 bool (*detach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev);
835 bool (*checkpoint)(struct lxc_container *c, char *directory, bool stop, bool verbose);
836
847 bool (*restore)(struct lxc_container *c, char *directory, bool verbose);
848
859
868
869 /* Post LXC-1.1 additions */
879 int (*migrate)(struct lxc_container *c, unsigned int cmd, struct migrate_opts *opts, unsigned int size);
880
889 int (*console_log)(struct lxc_container *c, struct lxc_console_log *log);
890
900 bool (*reboot2)(struct lxc_container *c, int timeout);
901
905 int (*mount)(struct lxc_container *c, const char *source,
906 const char *target, const char *filesystemtype,
907 unsigned long mountflags, const void *data,
908 struct lxc_mount *mnt);
909
913 int (*umount)(struct lxc_container *c, const char *target,
914 unsigned long mountflags, struct lxc_mount *mnt);
915
924
932 int (*init_pidfd)(struct lxc_container *c);
933
942 bool (*set_container_info_file) (struct lxc_container *c, const char *info_file);
943
952 bool (*set_terminal_init_fifos)(struct lxc_container *c, const char *in, const char *out, const char *err);
953
962 bool (*add_terminal_fifos)(struct lxc_container *c, const char *in, const char *out, const char *err);
963
964 bool (*set_terminal_winch)(struct lxc_container *c, unsigned int height, unsigned int width);
965
966 bool (*set_exec_terminal_winch)(struct lxc_container *c, const char *suffix, unsigned int height, unsigned int width);
967
977 bool (*want_disable_pty)(struct lxc_container *c, bool state);
978
988 bool (*want_open_stdin)(struct lxc_container *c, bool state);
989
998 bool (*clean_container_resource) (struct lxc_container *c, pid_t pid);
999
1009 bool (*get_container_pids)(struct lxc_container *c,pid_t **pids,size_t *pids_len);
1010
1019 bool (*set_start_timeout)(struct lxc_container *c, unsigned int start_timeout);
1020
1029 bool (*set_oci_type)(struct lxc_container *c, bool image_type_oci);
1030
1039 bool (*get_container_metrics)(struct lxc_container *c, struct lxc_container_metrics *metrics);
1040
1041};
1042
1047 char *name;
1050 char *lxcpath;
1056 void (*free)(struct lxc_snapshot *s);
1057};
1058
1059
1064 char *fstype;
1065 uint64_t fssize;
1066 struct {
1067 char *zfsroot;
1068 } zfs;
1069 struct {
1070 char *vg;
1071 char *lv;
1072 char *thinpool;
1073 } lvm;
1074 char *dir;
1075 struct {
1076 char *rbdname;
1077 char *rbdpool;
1078 } rbd;
1079};
1080
1084enum {
1085 MIGRATE_PRE_DUMP,
1086 MIGRATE_DUMP,
1087 MIGRATE_RESTORE,
1088 MIGRATE_FEATURE_CHECK,
1089};
1090
1094#define FEATURE_MEM_TRACK (1ULL << 0)
1095#define FEATURE_LAZY_PAGES (1ULL << 1)
1096
1101 /* new members should be added at the end */
1102 char *directory;
1103 bool verbose;
1104
1105 bool stop; /* stop the container after dump? */
1106 char *predump_dir; /* relative to directory above */
1107 char *pageserver_address; /* where should memory pages be send? */
1108 char *pageserver_port;
1109
1110 /* This flag indicates whether or not the container's rootfs will have
1111 * the same inodes on checkpoint and restore. In the case of e.g. zfs
1112 * send or btrfs send, or an LVM snapshot, this will be true, but it
1113 * won't if e.g. you rsync the filesystems between two machines.
1114 */
1115 bool preserves_inodes;
1116
1117 /* Path to an executable script that will be registered as a criu
1118 * "action script"
1119 */
1120 char *action_script;
1121
1122 /* If CRIU >= 2.4 is detected the option to skip in-flight connections
1123 * will be enabled by default. The flag 'disable_skip_in_flight' will
1124 * unconditionally disable this feature. In-flight connections are
1125 * not fully established TCP connections: SYN, SYN-ACK */
1126 bool disable_skip_in_flight;
1127
1128 /* This is the maximum file size for deleted files (which CRIU calls
1129 * "ghost" files) that will be handled. 0 indicates the CRIU default,
1130 * which at this time is 1MB.
1131 */
1132 uint64_t ghost_limit;
1133
1134 /* Some features cannot be checked by comparing the CRIU version.
1135 * Features like dirty page tracking or userfaultfd depend on
1136 * the architecture/kernel/criu combination. This is a bitmask
1137 * in which the desired feature checks can be encoded.
1138 */
1139 uint64_t features_to_check;
1140};
1141
1143 /* Clear the console log. */
1144 bool clear;
1145
1146 /* Retrieve the console log. */
1147 bool read;
1148
1149 /* This specifies the maximum size to read from the ringbuffer. Setting
1150 * it to 0 means that the a read can be as big as the whole ringbuffer.
1151 * On return callers can check how many bytes were actually read.
1152 * If "read" and "clear" are set to false and a non-zero value is
1153 * specified then up to "read_max" bytes of data will be discarded from
1154 * the ringbuffer.
1155 */
1156 uint64_t *read_max;
1157
1158 /* Data that was read from the ringbuffer. If "read_max" is 0 on return
1159 * "data" is invalid.
1160 */
1161 char *data;
1162};
1163
1172struct lxc_container *lxc_container_new(const char *name, const char *configpath);
1173
1184struct lxc_container *lxc_container_without_config_new(const char *name, const char *configpath);
1185
1193int lxc_container_get(struct lxc_container *c);
1194
1205int lxc_container_put(struct lxc_container *c);
1206
1219int lxc_get_wait_states(const char **states);
1220
1228const char *lxc_get_global_config_item(const char *key);
1229
1236const char *lxc_get_version(void);
1237
1249int list_defined_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1250
1265int list_active_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1266
1281int list_all_containers(const char *lxcpath, char ***names, struct lxc_container ***cret);
1282
1283struct lxc_log {
1284 const char *name;
1285 const char *lxcpath;
1286 const char *file;
1287 const char *level;
1288 const char *prefix;
1289 bool quiet;
1290};
1291
1297int lxc_log_init(struct lxc_log *log);
1298
1302void lxc_log_close(void);
1303
1309bool lxc_config_item_is_supported(const char *key);
1310
1316bool lxc_has_api_extension(const char *extension);
1317
1318#ifdef __cplusplus
1319}
1320#endif
1321
1322#endif
Specifications for how to create a new backing store.
Definition: lxccontainer.h:1063
char * zfsroot
Definition: lxccontainer.h:1067
char * vg
Definition: lxccontainer.h:1070
char * fstype
Definition: lxccontainer.h:1064
char * dir
Definition: lxccontainer.h:1074
char * lv
Definition: lxccontainer.h:1071
char * rbdname
Definition: lxccontainer.h:1076
uint64_t fssize
Definition: lxccontainer.h:1065
char * rbdpool
Definition: lxccontainer.h:1077
char * thinpool
Definition: lxccontainer.h:1072
Definition: attach_options.h:61
Definition: lxccontainer.h:45
Definition: lxccontainer.h:1142
Definition: lxccontainer.h:51
Definition: lxccontainer.h:85
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:977
bool(* checkpoint)(struct lxc_container *c, char *directory, bool stop, bool verbose)
Checkpoint a container.
Definition: lxccontainer.h:835
bool(* clean_container_resource)(struct lxc_container *c, pid_t pid)
An API call to clean resources of container.
Definition: lxccontainer.h:998
bool(* wait)(struct lxc_container *c, const char *state, int timeout)
Wait for container to reach a particular state.
Definition: lxccontainer.h:323
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:397
bool(* load_config)(struct lxc_container *c, const char *alt_file)
Load the specified configuration for the container.
Definition: lxccontainer.h:241
bool(* snapshot_destroy_all)(struct lxc_container *c)
Destroy all the container's snapshot.
Definition: lxccontainer.h:867
bool open_stdin
Definition: lxccontainer.h:154
int(* console_log)(struct lxc_container *c, struct lxc_console_log *log)
Query the console log of a container.
Definition: lxccontainer.h:889
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:678
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:705
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:789
bool(* destroy)(struct lxc_container *c)
Delete the container.
Definition: lxccontainer.h:345
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:298
void(* clear_config)(struct lxc_container *c)
Completely clear the containers in-memory configuration.
Definition: lxccontainer.h:436
char * error_string
Definition: lxccontainer.h:134
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:952
bool(* attach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev)
Add specified netdev to the container.
Definition: lxccontainer.h:813
bool(* set_config_item)(struct lxc_container *c, const char *key, const char *value)
Set a key/value configuration option.
Definition: lxccontainer.h:334
bool(* rename)(struct lxc_container *c, const char *newname)
Rename a container.
Definition: lxccontainer.h:408
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:801
const char *(* state)(struct lxc_container *c)
Determine state of container.
Definition: lxccontainer.h:193
bool(* clear_config_item)(struct lxc_container *c, const char *key)
Clear a configuration item.
Definition: lxccontainer.h:448
bool(* startl)(struct lxc_container *c, int useinit,...)
Start the container (list variant).
Definition: lxccontainer.h:267
int(* console_getfd)(struct lxc_container *c, int *ttynum, int *masterfd)
Allocate a console tty for the container.
Definition: lxccontainer.h:643
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:913
bool(* start)(struct lxc_container *c, int useinit, char *const argv[])
Start the container.
Definition: lxccontainer.h:252
bool(* reboot2)(struct lxc_container *c, int timeout)
Request the container reboot by sending it SIGINT.
Definition: lxccontainer.h:900
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:662
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:549
bool(* stop)(struct lxc_container *c)
Stop the container.
Definition: lxccontainer.h:276
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:905
char * config_path
Definition: lxccontainer.h:143
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:468
bool(* may_control)(struct lxc_container *c)
Determine if the caller may control the container.
Definition: lxccontainer.h:777
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:1009
bool(* snapshot_destroy)(struct lxc_container *c, const char *snapname)
Destroy the specified snapshot.
Definition: lxccontainer.h:766
bool(* is_defined)(struct lxc_container *c)
Determine if /var/lib/lxc/$name/config exists.
Definition: lxccontainer.h:182
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:504
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:692
int(* init_pidfd)(struct lxc_container *c)
Retrieve a pidfd for the container's init process.
Definition: lxccontainer.h:932
pid_t(* init_pid)(struct lxc_container *c)
Determine process ID of the containers init process.
Definition: lxccontainer.h:230
bool(* want_daemonize)(struct lxc_container *c, bool state)
Change whether the container wants to run disconnected from the terminal.
Definition: lxccontainer.h:287
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:988
bool(* shutdown)(struct lxc_container *c, int timeout)
Request the container shutdown by sending it SIGPWR.
Definition: lxccontainer.h:429
bool(* set_oci_type)(struct lxc_container *c, bool image_type_oci)
An API call to set oci type.
Definition: lxccontainer.h:1029
int(* seccomp_notify_fd)(struct lxc_container *c)
Retrieve a file descriptor for the container's seccomp filter.
Definition: lxccontainer.h:923
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:879
int error_num
Definition: lxccontainer.h:137
bool daemonize
Definition: lxccontainer.h:140
bool(* is_running)(struct lxc_container *c)
Determine if container is running.
Definition: lxccontainer.h:202
int(* snapshot)(struct lxc_container *c, const char *commentfile)
Create a container snapshot.
Definition: lxccontainer.h:723
bool(* freeze)(struct lxc_container *c)
Freeze running container.
Definition: lxccontainer.h:211
int(* snapshot_list)(struct lxc_container *c, struct lxc_snapshot **snapshots)
Obtain a list of container snapshots.
Definition: lxccontainer.h:737
bool(* save_config)(struct lxc_container *c, const char *alt_file)
Save configuration to a file.
Definition: lxccontainer.h:355
bool(* detach_interface)(struct lxc_container *c, const char *dev, const char *dst_dev)
Remove specified netdev from the container.
Definition: lxccontainer.h:823
bool(* unfreeze)(struct lxc_container *c)
Thaw a frozen container.
Definition: lxccontainer.h:220
bool(* restore)(struct lxc_container *c, char *directory, bool verbose)
Restore a container from a checkpoint.
Definition: lxccontainer.h:847
bool(* reboot)(struct lxc_container *c)
Request the container reboot by sending it SIGINT.
Definition: lxccontainer.h:417
bool(* snapshot_restore)(struct lxc_container *c, const char *snapname, const char *newname)
Create a new container based on a snapshot.
Definition: lxccontainer.h:756
bool(* set_config_path)(struct lxc_container *c, const char *path)
Set the full path to the containers configuration file.
Definition: lxccontainer.h:589
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:374
bool(* set_start_timeout)(struct lxc_container *c, unsigned int start_timeout)
An API call to set start timeout.
Definition: lxccontainer.h:1019
bool disable_pty
Definition: lxccontainer.h:151
bool(* get_container_metrics)(struct lxc_container *c, struct lxc_container_metrics *metrics)
An API call to set start timeout.
Definition: lxccontainer.h:1039
bool(* destroy_with_snapshots)(struct lxc_container *c)
Delete the container and all its snapshots.
Definition: lxccontainer.h:858
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:942
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:962
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:560
Definition: lxclock.h:33
Definition: lxccontainer.h:1283
Definition: lxccontainer.h:41
An LXC container snapshot.
Definition: lxccontainer.h:1046
void(* free)(struct lxc_snapshot *s)
De-allocate the snapshot.
Definition: lxccontainer.h:1056
char * name
Definition: lxccontainer.h:1047
char * lxcpath
Definition: lxccontainer.h:1050
char * timestamp
Definition: lxccontainer.h:1049
char * comment_pathname
Definition: lxccontainer.h:1048
Options for the migrate API call.
Definition: lxccontainer.h:1100