1ctr(8)() ctr(8)()
2 ctr is an unsupported debug and administrative client for interacting
6 with the containerd daemon. Because it is unsupported, the commands,
7 options, and operations are not guaranteed to be backward compatible or
8 stable from release to release of the containerd project.
9
16 ctr
17
21 ctr
22 [--address|-a]=[value]
25 [--connect-timeout]=[value]
26 [--debug]
27 [--namespace|-n]=[value]
28 [--timeout]=[value]
29 Usage:
33 ctr [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
36
41 --address, -a="": address for containerd's GRPC server (default:
42 /run/containerd/containerd.sock)
43 --connect-timeout="": timeout for connecting to containerd (default:
46 0s)
47 --debug: enable debug output in logs
50 --namespace, -n="": namespace to use with commands (default: default)
53 --timeout="": total timeout for ctr commands (default: 0s)
56
61 provides information about containerd plugins
62 list, ls
65 lists containerd plugins
66 --detailed, -d: print detailed information about each plugin
69 --quiet, -q: print only the plugin ids
72
75 print the client and server versions
76
79 manage containers
80 create
83 create container
84 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
87 --annotation="": specify additional OCI annotations (e.g. foo=bar)
90 --apparmor-default-profile="": enable AppArmor with the default profile
93 with the specified name, e.g. "cri-containerd.apparmor.d"
94 --apparmor-profile="": enable AppArmor with an existing custom profile
97 --cap-add="": add Linux capabilities (Set capabilities with 'CAP_' pre‐
100 fix)
101 --cap-drop="": drop Linux capabilities (Set capabilities with 'CAP_'
104 prefix)
105 --config, -c="": path to the runtime-specific spec config file
108 --cpu-period="": Limit CPU CFS period (default: 0)
111 --cpu-quota="": Limit CPU CFS quota (default: -1)
114 --cwd="": specify the working directory of the process
117 --device="": file path to a device to add to the container; or a path
120 to a directory tree of devices to add to the container
121 --env="": specify additional container environment variables (e.g.
124 FOO=bar)
125 --env-file="": specify additional container environment variables in a
128 file(e.g. FOO=bar, one per line)
129 --gpus="": add gpus to the container
132 --label="": specify additional labels (e.g. foo=bar)
135 --memory-limit="": memory limit (in bytes) for the container (default:
138 0)
139 --mount="": specify additional container mount (e.g.
142 type=bind,src=/tmp,dst=/host,options=rbind:ro)
143 --net-host: enable host networking for the container
146 --no-pivot: disable use of pivot-root (linux only)
149 --pid-file="": file path to write the task's pid
152 --privileged: run privileged container
155 --rdt-class="": name of the RDT class to associate the container with.
158 Specifies a Class of Service (CLOS) for cache and memory bandwidth man‐
159 agement.
160 --read-only: set the containers filesystem as readonly
163 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
166 ter
167 --rootfs-propagation="": set the propagation of the container rootfs
170 --runtime="": runtime name (default: io.containerd.runc.v2)
173 --runtime-config-path="": optional runtime config path
176 --seccomp: enable the default seccomp profile
179 --seccomp-profile="": file path to custom seccomp profile. seccomp must
182 be set to true, before using seccomp-profile
183 --snapshotter="": snapshotter name. Empty value stands for the default
186 value.
187 --snapshotter-label="": labels added to the new snapshot for this con‐
190 tainer.
191 --tty, -t: allocate a TTY for the container
194 --with-ns="": specify existing Linux namespaces to join at container
197 runtime (format ':')
198 delete, del, remove, rm
201 delete one or more existing containers
202 --keep-snapshot: do not clean up snapshot with container
205 info
208 get info about a container
209 --spec: only display the spec
212 list, ls
215 list containers
216 --quiet, -q: print only the container id
219 label
222 set and clear labels for a container
223 checkpoint
226 checkpoint a container
227 --image: include the image in the checkpoint
230 --rw: include the rw layer in the checkpoint
233 --task: checkpoint container task
236 restore
239 restore a container from checkpoint
240 --live: restore the runtime and memory data from the checkpoint
243 --rw: restore the rw layer from the checkpoint
246
249 manage content
250 active
253 display active transfers
254 --root="": path to content store root (default: /tmp/content)
257 --timeout, -t="": total timeout for fetch (default: 0s)
260 delete, del, remove, rm
263 permanently delete one or more blobs
264 edit
267 edit a blob and return a new digest
268 --editor="": select editor (vim, emacs, etc.)
271 --validate="": validate the result against a format (json, mediatype,
274 etc.)
275 fetch
278 fetch all content for an image into containerd
279 --all-metadata: Pull metadata for all platforms
282 --all-platforms: pull content from all platforms
285 --hosts-dir="": Custom hosts configuration directory
288 --http-dump: dump all HTTP request/responses when interacting with con‐
291 tainer registry
292 --http-trace: enable HTTP tracing for registry interactions
295 --label="": labels to attach to the image
298 --metadata-only: Pull all metadata including manifests and configs
301 --plain-http: allow connections using plain HTTP
304 --platform="": Pull content from a specific platform
307 --refresh="": refresh token for authorization server
310 --skip-verify, -k: skip SSL certificate validation
313 --tlscacert="": path to TLS root CA
316 --tlscert="": path to TLS client certificate
319 --tlskey="": path to TLS client key
322 --user, -u="": user[:password] Registry user and password
325 fetch-object
328 retrieve objects from a remote
329 --hosts-dir="": Custom hosts configuration directory
332 --http-dump: dump all HTTP request/responses when interacting with con‐
335 tainer registry
336 --http-trace: enable HTTP tracing for registry interactions
339 --plain-http: allow connections using plain HTTP
342 --refresh="": refresh token for authorization server
345 --skip-verify, -k: skip SSL certificate validation
348 --tlscacert="": path to TLS root CA
351 --tlscert="": path to TLS client certificate
354 --tlskey="": path to TLS client key
357 --user, -u="": user[:password] Registry user and password
360 get
363 get the data for an object
364 ingest
367 accept content into the store
368 --expected-digest="": verify content against expected digest
371 --expected-size="": validate against provided size (default: 0)
374 list, ls
377 list all blobs in the store
378 --quiet, -q: print only the blob digest
381 push-object
384 push an object to a remote
385 --hosts-dir="": Custom hosts configuration directory
388 --http-dump: dump all HTTP request/responses when interacting with con‐
391 tainer registry
392 --http-trace: enable HTTP tracing for registry interactions
395 --plain-http: allow connections using plain HTTP
398 --refresh="": refresh token for authorization server
401 --skip-verify, -k: skip SSL certificate validation
404 --tlscacert="": path to TLS root CA
407 --tlscert="": path to TLS client certificate
410 --tlskey="": path to TLS client key
413 --user, -u="": user[:password] Registry user and password
416 label
419 add labels to content
420 prune
423 prunes content from the content store
424 references
427 prunes preference labels from the content store (layers only by de‐
428 fault)
429 --async: allow garbage collection to cleanup asynchronously
432 --dry: just show updates without applying (enables debug logging)
435
438 display containerd events
439
442 manage images
443 check
446 check existing images to ensure all content is available locally
447 --quiet, -q: print only the ready image refs (fully downloaded and un‐
450 packed)
451 --snapshotter="": snapshotter name. Empty value stands for the default
454 value.
455 export
458 export images
459 --all-platforms: exports content from all platforms
462 --platform="": Pull content from a specific platform
465 --skip-manifest-json: do not add Docker compatible manifest.json to ar‐
468 chive
469 --skip-non-distributable: do not add non-distributable blobs such as
472 Windows layers to archive
473 import
476 import images
477 --all-platforms: imports content for all platforms, false by default
480 --base-name="": base image name for added images, when provided only
483 images with this name prefix are imported
484 --compress-blobs: compress uncompressed blobs when creating manifest
487 (Docker format only)
488 --digests: whether to create digest images (default: false)
491 --index-name="": image name to keep index as, by default index is dis‐
494 carded
495 --no-unpack: skip unpacking the images, false by default
498 --platform="": imports content for specific platform
501 --skip-digest-for-named: skip applying --digests option to images named
504 in the importing tar (use it in conjunction with --digests)
505 --snapshotter="": snapshotter name. Empty value stands for the default
508 value.
509 list, ls
512 list images known to containerd
513 --quiet, -q: print only the image refs
516 mount
519 mount an image to a target path
520 --hosts-dir="": Custom hosts configuration directory
523 --http-dump: dump all HTTP request/responses when interacting with con‐
526 tainer registry
527 --http-trace: enable HTTP tracing for registry interactions
530 --label="": labels to attach to the image
533 --plain-http: allow connections using plain HTTP
536 --platform="": Mount the image for the specified platform (default:
539 linux/amd64)
540 --refresh="": refresh token for authorization server
543 --rw: Enable write support on the mount
546 --skip-verify, -k: skip SSL certificate validation
549 --snapshotter="": snapshotter name. Empty value stands for the default
552 value.
553 --tlscacert="": path to TLS root CA
556 --tlscert="": path to TLS client certificate
559 --tlskey="": path to TLS client key
562 --user, -u="": user[:password] Registry user and password
565 unmount
568 unmount the image from the target
569 --hosts-dir="": Custom hosts configuration directory
572 --http-dump: dump all HTTP request/responses when interacting with con‐
575 tainer registry
576 --http-trace: enable HTTP tracing for registry interactions
579 --label="": labels to attach to the image
582 --plain-http: allow connections using plain HTTP
585 --refresh="": refresh token for authorization server
588 --rm: remove the snapshot after a successful unmount
591 --skip-verify, -k: skip SSL certificate validation
594 --snapshotter="": snapshotter name. Empty value stands for the default
597 value.
598 --tlscacert="": path to TLS root CA
601 --tlscert="": path to TLS client certificate
604 --tlskey="": path to TLS client key
607 --user, -u="": user[:password] Registry user and password
610 pull
613 pull an image from a remote
614 --all-metadata: Pull metadata for all platforms
617 --all-platforms: pull content and metadata from all platforms
620 --hosts-dir="": Custom hosts configuration directory
623 --http-dump: dump all HTTP request/responses when interacting with con‐
626 tainer registry
627 --http-trace: enable HTTP tracing for registry interactions
630 --label="": labels to attach to the image
633 --max-concurrent-downloads="": Set the max concurrent downloads for
636 each pull (default: 0)
637 --plain-http: allow connections using plain HTTP
640 --platform="": Pull content from a specific platform
643 --print-chainid: Print the resulting image's chain ID
646 --refresh="": refresh token for authorization server
649 --skip-verify, -k: skip SSL certificate validation
652 --snapshotter="": snapshotter name. Empty value stands for the default
655 value.
656 --tlscacert="": path to TLS root CA
659 --tlscert="": path to TLS client certificate
662 --tlskey="": path to TLS client key
665 --user, -u="": user[:password] Registry user and password
668 push
671 push an image to a remote
672 --allow-non-distributable-blobs: Allow pushing blobs that are marked as
675 non-distributable
676 --hosts-dir="": Custom hosts configuration directory
679 --http-dump: dump all HTTP request/responses when interacting with con‐
682 tainer registry
683 --http-trace: enable HTTP tracing for registry interactions
686 --manifest="": digest of manifest
689 --manifest-type="": media type of manifest digest (default: applica‐
692 tion/vnd.oci.image.manifest.v1+json)
693 --max-concurrent-uploaded-layers="": Set the max concurrent uploaded
696 layers for each push (default: 0)
697 --plain-http: allow connections using plain HTTP
700 --platform="": push content from a specific platform
703 --refresh="": refresh token for authorization server
706 --skip-verify, -k: skip SSL certificate validation
709 --tlscacert="": path to TLS root CA
712 --tlscert="": path to TLS client certificate
715 --tlskey="": path to TLS client key
718 --user, -u="": user[:password] Registry user and password
721 delete, del, remove, rm
724 remove one or more images by reference
725 --sync: Synchronously remove image and all associated resources
728 tag
731 tag an image
732 --force: force target_ref to be created, regardless if it already ex‐
735 ists
736 label
739 set and clear labels for an image
740 --replace-all, -r: replace all labels
743 convert
746 convert an image
747 --all-platforms: exports content from all platforms
750 --oci: convert Docker media types to OCI media types
753 --platform="": Pull content from a specific platform
756 --uncompress: convert tar.gz layers to uncompressed tar layers
759
762 manage leases
763 list, ls
766 list all active leases
767 --quiet, -q: print only the blob digest
770 create
773 create lease
774 --expires, -x="": expiration of lease (0 value will not expire) (de‐
777 fault: 24h0m0s)
778 --id="": set the id for the lease, will be generated by default
781 delete, del, remove, rm
784 delete a lease
785 --sync: Synchronously remove leases and all unreferenced resources
788
791 manage namespaces
792 create, c
795 create a new namespace
796 list, ls
799 list namespaces
800 --quiet, -q: print only the namespace name
803 remove, rm
806 remove one or more namespaces
807 --cgroup, -c: delete the namespace's cgroup
810 label
813 set and clear labels for a namespace
814
817 provide golang pprof outputs for containerd
818 --debug-socket, -d="": socket path for containerd's debug server (de‐
821 fault: /run/containerd/debug.sock)
822 block
825 goroutine blocking profile
826 goroutines
829 dump goroutine stack dump
830 heap
833 dump heap profile
834 profile
837 CPU profile
838 --seconds, -s="": duration for collection (seconds) (default: 30s)
841 threadcreate
844 goroutine thread creating profile
845 trace
848 collect execution trace
849 --seconds, -s="": trace time (seconds) (default: 5s)
852
855 run a container
856 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
859 --annotation="": specify additional OCI annotations (e.g. foo=bar)
862 --apparmor-default-profile="": enable AppArmor with the default profile
865 with the specified name, e.g. "cri-containerd.apparmor.d"
866 --apparmor-profile="": enable AppArmor with an existing custom profile
869 --cap-add="": add Linux capabilities (Set capabilities with 'CAP_' pre‐
872 fix)
873 --cap-drop="": drop Linux capabilities (Set capabilities with 'CAP_'
876 prefix)
877 --cgroup="": cgroup path (To disable use of cgroup, set to "" explic‐
880 itly)
881 --cni: enable cni networking for the container
884 --config, -c="": path to the runtime-specific spec config file
887 --cpu-period="": Limit CPU CFS period (default: 0)
890 --cpu-quota="": Limit CPU CFS quota (default: -1)
893 --cpu-shares="": set the cpu shares (default: 1024)
896 --cpus="": set the CFS cpu quota (default: 0.000000)
899 --cwd="": specify the working directory of the process
902 --detach, -d: detach from the task after it has started execution
905 --device="": file path to a device to add to the container; or a path
908 to a directory tree of devices to add to the container
909 --env="": specify additional container environment variables (e.g.
912 FOO=bar)
913 --env-file="": specify additional container environment variables in a
916 file(e.g. FOO=bar, one per line)
917 --fifo-dir="": directory used for storing IO FIFOs
920 --gidmap="": run inside a user namespace with the specified GID mapping
923 range; specified with the format container-gid:host-gid:length
924 --gpus="": add gpus to the container
927 --label="": specify additional labels (e.g. foo=bar)
930 --log-uri="": log uri
933 --memory-limit="": memory limit (in bytes) for the container (default:
936 0)
937 --mount="": specify additional container mount (e.g.
940 type=bind,src=/tmp,dst=/host,options=rbind:ro)
941 --net-host: enable host networking for the container
944 --no-pivot: disable use of pivot-root (linux only)
947 --null-io: send all IO to /dev/null
950 --pid-file="": file path to write the task's pid
953 --platform="": run image for specific platform
956 --privileged: run privileged container
959 --rdt-class="": name of the RDT class to associate the container with.
962 Specifies a Class of Service (CLOS) for cache and memory bandwidth man‐
963 agement.
964 --read-only: set the containers filesystem as readonly
967 --remap-labels: provide the user namespace ID remapping to the snap‐
970 shotter via label options; requires snapshotter support
971 --rm: remove the container after running
974 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
977 ter
978 --rootfs-propagation="": set the propagation of the container rootfs
981 --runc-binary="": specify runc-compatible binary
984 --runc-root="": specify runc-compatible root
987 --runc-systemd-cgroup: start runc with systemd cgroup manager
990 --runtime="": runtime name (default: io.containerd.runc.v2)
993 --runtime-config-path="": optional runtime config path
996 --seccomp: enable the default seccomp profile
999 --seccomp-profile="": file path to custom seccomp profile. seccomp must
1002 be set to true, before using seccomp-profile
1003 --snapshotter="": snapshotter name. Empty value stands for the default
1006 value.
1007 --snapshotter-label="": labels added to the new snapshot for this con‐
1010 tainer.
1011 --tty, -t: allocate a TTY for the container
1014 --uidmap="": run inside a user namespace with the specified UID mapping
1017 range; specified with the format container-uid:host-uid:length
1018 --with-ns="": specify existing Linux namespaces to join at container
1021 runtime (format ':')
1022
1025 manage snapshots
1026 --snapshotter="": snapshotter name. Empty value stands for the default
1029 value.
1030 commit
1033 commit an active snapshot into the provided name
1034 diff
1037 get the diff of two snapshots. the default second snapshot is the first
1038 snapshot's parent.
1039 --keep: keep diff content. up to creator to delete it.
1042 --label="": labels to attach to the image
1045 --media-type="": media type to use for creating diff (default: applica‐
1048 tion/vnd.oci.image.layer.v1.tar+gzip)
1049 --ref="": content upload reference to use
1052 info
1055 get info about a snapshot
1056 list, ls
1059 list snapshots
1060 mounts, m, mount
1063 mount gets mount commands for the snapshots
1064 prepare
1067 prepare a snapshot from a committed snapshot
1068 --mounts: Print out snapshot mounts as JSON
1071 --target, -t="": mount target path, will print mount, if provided
1074 delete, del, remove, rm
1077 remove snapshots
1078 label
1081 add labels to content
1082 tree
1085 display tree view of snapshot branches
1086 unpack
1089 unpack applies layers from a manifest to a snapshot
1090 --snapshotter="": snapshotter name. Empty value stands for the default
1093 value.
1094 usage
1097 usage snapshots
1098 -b: display size in bytes
1101 view
1104 create a read-only snapshot from a committed snapshot
1105 --mounts: Print out snapshot mounts as JSON
1108 --target, -t="": mount target path, will print mount, if provided
1111
1114 manage tasks
1115 attach
1118 attach to the IO of a running container
1119 checkpoint
1122 checkpoint a container
1123 --exit: stop the container after the checkpoint
1126 --image-path="": path to criu image files
1129 --work-path="": path to criu work files and logs
1132 delete, del, remove, rm
1135 delete one or more tasks
1136 --exec-id="": process ID to kill
1139 --force, -f: force delete task process
1142 exec
1145 execute additional processes in an existing container
1146 --cwd="": working directory of the new process
1149 --detach, -d: detach from the task after it has started execution
1152 --exec-id="": exec specific id for the process
1155 --fifo-dir="": directory used for storing IO FIFOs
1158 --log-uri="": log uri for custom shim logging
1161 --tty, -t: allocate a TTY for the container
1164 --user="": user id or name
1167 list, ls
1170 list tasks
1171 --quiet, -q: print only the task id
1174 kill
1177 signal a container (default: SIGTERM)
1178 --all, -a: send signal to all processes inside the container
1181 --exec-id="": process ID to kill
1184 --signal, -s="": signal to send to the container
1187 pause
1190 pause an existing container
1191 ps
1194 list processes for container
1195 resume
1198 resume a paused container
1199 start
1202 start a container that has been created
1203 --detach, -d: detach from the task after it has started execution
1206 --fifo-dir="": directory used for storing IO FIFOs
1209 --log-uri="": log uri
1212 --null-io: send all IO to /dev/null
1215 --pid-file="": file path to write the task's pid
1218 metrics, metric
1221 get a single data point of metrics for a task with the built-in Linux
1222 runtime
1223 --format="": "table" or "json" (default: table)
1226
1229 install a new package
1230 --libs, -l: install libs from the image
1233 --path="": set an optional install path other than the managed opt di‐
1236 rectory
1237 --replace, -r: replace any binaries or libs in the opt directory
1240
1243 OCI tools
1244 spec
1247 see the output of the default OCI spec
1248
1251 interact with a shim directly
1252 --id="": container id
1255 delete
1258 delete a container with a task
1259 exec
1262 exec a new process in the task's container
1263 --attach, -a: stay attached to the container and open the fifos
1266 --cwd="": current working directory
1269 --env, -e="": add environment vars
1272 --spec="": runtime spec
1275 --stderr="": specify the path to the stderr fifo
1278 --stdin="": specify the path to the stdin fifo
1281 --stdout="": specify the path to the stdout fifo
1284 --tty, -t: enable tty support
1287 start
1290 start a container with a task
1291 state
1294 get the state of all the processes of the task
1295 ctr(8)()