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 --apparmor-default-profile="": enable AppArmor with the default profile
90 with the specified name, e.g. "cri-containerd.apparmor.d"
91 --apparmor-profile="": enable AppArmor with an existing custom profile
94 --config, -c="": path to the runtime-specific spec config file
97 --cpu-period="": Limit CPU CFS period (default: 0)
100 --cpu-quota="": Limit CPU CFS quota (default: -1)
103 --cwd="": specify the working directory of the process
106 --device="": file path to a device to add to the container; or a path
109 to a directory tree of devices to add to the container
110 --env="": specify additional container environment variables (e.g.
113 FOO=bar)
114 --env-file="": specify additional container environment variables in a
117 file(e.g. FOO=bar, one per line)
118 --gpus="": add gpus to the container (default: 0)
121 --label="": specify additional labels (e.g. foo=bar)
124 --memory-limit="": memory limit (in bytes) for the container (default:
127 0)
128 --mount="": specify additional container mount (e.g.
131 type=bind,src=/tmp,dst=/host,options=rbind:ro)
132 --net-host: enable host networking for the container
135 --no-pivot: disable use of pivot-root (linux only)
138 --pid-file="": file path to write the task's pid
141 --privileged: run privileged container
144 --read-only: set the containers filesystem as readonly
147 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
150 ter
151 --runtime="": runtime name (default: io.containerd.runc.v2)
154 --runtime-config-path="": optional runtime config path
157 --seccomp: enable the default seccomp profile
160 --seccomp-profile="": file path to custom seccomp profile. seccomp must
163 be set to true, before using seccomp-profile
164 --snapshotter="": snapshotter name. Empty value stands for the default
167 value.
168 --tty, -t: allocate a TTY for the container
171 --with-ns="": specify existing Linux namespaces to join at container
174 runtime (format ':')
175 delete, del, rm
178 delete one or more existing containers
179 --keep-snapshot: do not clean up snapshot with container
182 info
185 get info about a container
186 --spec: only display the spec
189 list, ls
192 list containers
193 --quiet, -q: print only the container id
196 label
199 set and clear labels for a container
200 checkpoint
203 checkpoint a container
204 --image: include the image in the checkpoint
207 --rw: include the rw layer in the checkpoint
210 --task: checkpoint container task
213 restore
216 restore a container from checkpoint
217 --live: restore the runtime and memory data from the checkpoint
220 --rw: restore the rw layer from the checkpoint
223
226 manage content
227 active
230 display active transfers
231 --root="": path to content store root (default: /tmp/content)
234 --timeout, -t="": total timeout for fetch (default: 0s)
237 delete, del, remove, rm
240 permanently delete one or more blobs
241 edit
244 edit a blob and return a new digest
245 --editor="": select editor (vim, emacs, etc.)
248 --validate="": validate the result against a format (json, mediatype,
251 etc.)
252 fetch
255 fetch all content for an image into containerd
256 --all-metadata: Pull metadata for all platforms
259 --all-platforms: pull content from all platforms
262 --hosts-dir="": Custom hosts configuration directory
265 --http-dump: dump all HTTP request/responses when interacting with con‐
268 tainer registry
269 --http-trace: enable HTTP tracing for registry interactions
272 --label="": labels to attach to the image
275 --metadata-only: Pull all metadata including manifests and configs
278 --plain-http: allow connections using plain HTTP
281 --platform="": Pull content from a specific platform
284 --refresh="": refresh token for authorization server
287 --skip-verify, -k: skip SSL certificate validation
290 --tlscacert="": path to TLS root CA
293 --tlscert="": path to TLS client certificate
296 --tlskey="": path to TLS client key
299 --user, -u="": user[:password] Registry user and password
302 fetch-object
305 retrieve objects from a remote
306 --hosts-dir="": Custom hosts configuration directory
309 --http-dump: dump all HTTP request/responses when interacting with con‐
312 tainer registry
313 --http-trace: enable HTTP tracing for registry interactions
316 --plain-http: allow connections using plain HTTP
319 --refresh="": refresh token for authorization server
322 --skip-verify, -k: skip SSL certificate validation
325 --tlscacert="": path to TLS root CA
328 --tlscert="": path to TLS client certificate
331 --tlskey="": path to TLS client key
334 --user, -u="": user[:password] Registry user and password
337 get
340 get the data for an object
341 ingest
344 accept content into the store
345 --expected-digest="": verify content against expected digest
348 --expected-size="": validate against provided size (default: 0)
351 list, ls
354 list all blobs in the store
355 --quiet, -q: print only the blob digest
358 push-object
361 push an object to a remote
362 --hosts-dir="": Custom hosts configuration directory
365 --http-dump: dump all HTTP request/responses when interacting with con‐
368 tainer registry
369 --http-trace: enable HTTP tracing for registry interactions
372 --plain-http: allow connections using plain HTTP
375 --refresh="": refresh token for authorization server
378 --skip-verify, -k: skip SSL certificate validation
381 --tlscacert="": path to TLS root CA
384 --tlscert="": path to TLS client certificate
387 --tlskey="": path to TLS client key
390 --user, -u="": user[:password] Registry user and password
393 label
396 add labels to content
397 prune
400 prunes content from the content store
401 references
404 prunes preference labels from the content store (layers only by de‐
405 fault)
406 --async: allow garbage collection to cleanup asynchronously
409 --dry: just show updates without applying (enables debug logging)
412
415 display containerd events
416
419 manage images
420 check
423 check existing images to ensure all content is available locally
424 --quiet, -q: print only the ready image refs (fully downloaded and un‐
427 packed)
428 --snapshotter="": snapshotter name. Empty value stands for the default
431 value.
432 export
435 export images
436 --all-platforms: exports content from all platforms
439 --platform="": Pull content from a specific platform
442 --skip-manifest-json: do not add Docker compatible manifest.json to ar‐
445 chive
446 --skip-non-distributable: do not add non-distributable blobs such as
449 Windows layers to archive
450 import
453 import images
454 --all-platforms: imports content for all platforms, false by default
457 --base-name="": base image name for added images, when provided only
460 images with this name prefix are imported
461 --compress-blobs: compress uncompressed blobs when creating manifest
464 (Docker format only)
465 --digests: whether to create digest images (default: false)
468 --index-name="": image name to keep index as, by default index is dis‐
471 carded
472 --no-unpack: skip unpacking the images, false by default
475 --snapshotter="": snapshotter name. Empty value stands for the default
478 value.
479 list, ls
482 list images known to containerd
483 --quiet, -q: print only the image refs
486 mount
489 mount an image to a target path
490 --hosts-dir="": Custom hosts configuration directory
493 --http-dump: dump all HTTP request/responses when interacting with con‐
496 tainer registry
497 --http-trace: enable HTTP tracing for registry interactions
500 --label="": labels to attach to the image
503 --plain-http: allow connections using plain HTTP
506 --platform="": Mount the image for the specified platform (default:
509 linux/amd64)
510 --refresh="": refresh token for authorization server
513 --rw: Enable write support on the mount
516 --skip-verify, -k: skip SSL certificate validation
519 --snapshotter="": snapshotter name. Empty value stands for the default
522 value.
523 --tlscacert="": path to TLS root CA
526 --tlscert="": path to TLS client certificate
529 --tlskey="": path to TLS client key
532 --user, -u="": user[:password] Registry user and password
535 unmount
538 unmount the image from the target
539 --hosts-dir="": Custom hosts configuration directory
542 --http-dump: dump all HTTP request/responses when interacting with con‐
545 tainer registry
546 --http-trace: enable HTTP tracing for registry interactions
549 --label="": labels to attach to the image
552 --plain-http: allow connections using plain HTTP
555 --refresh="": refresh token for authorization server
558 --rm: remove the snapshot after a successful unmount
561 --skip-verify, -k: skip SSL certificate validation
564 --snapshotter="": snapshotter name. Empty value stands for the default
567 value.
568 --tlscacert="": path to TLS root CA
571 --tlscert="": path to TLS client certificate
574 --tlskey="": path to TLS client key
577 --user, -u="": user[:password] Registry user and password
580 pull
583 pull an image from a remote
584 --all-metadata: Pull metadata for all platforms
587 --all-platforms: pull content and metadata from all platforms
590 --hosts-dir="": Custom hosts configuration directory
593 --http-dump: dump all HTTP request/responses when interacting with con‐
596 tainer registry
597 --http-trace: enable HTTP tracing for registry interactions
600 --label="": labels to attach to the image
603 --max-concurrent-downloads="": Set the max concurrent downloads for
606 each pull (default: 0)
607 --plain-http: allow connections using plain HTTP
610 --platform="": Pull content from a specific platform
613 --print-chainid: Print the resulting image's chain ID
616 --refresh="": refresh token for authorization server
619 --skip-verify, -k: skip SSL certificate validation
622 --snapshotter="": snapshotter name. Empty value stands for the default
625 value.
626 --tlscacert="": path to TLS root CA
629 --tlscert="": path to TLS client certificate
632 --tlskey="": path to TLS client key
635 --user, -u="": user[:password] Registry user and password
638 push
641 push an image to a remote
642 --hosts-dir="": Custom hosts configuration directory
645 --http-dump: dump all HTTP request/responses when interacting with con‐
648 tainer registry
649 --http-trace: enable HTTP tracing for registry interactions
652 --manifest="": digest of manifest
655 --manifest-type="": media type of manifest digest (default: applica‐
658 tion/vnd.oci.image.manifest.v1+json)
659 --max-concurrent-uploaded-layers="": Set the max concurrent uploaded
662 layers for each push (default: 0)
663 --plain-http: allow connections using plain HTTP
666 --platform="": push content from a specific platform
669 --refresh="": refresh token for authorization server
672 --skip-verify, -k: skip SSL certificate validation
675 --tlscacert="": path to TLS root CA
678 --tlscert="": path to TLS client certificate
681 --tlskey="": path to TLS client key
684 --user, -u="": user[:password] Registry user and password
687 remove, rm
690 remove one or more images by reference
691 --sync: Synchronously remove image and all associated resources
694 tag
697 tag an image
698 --force: force target_ref to be created, regardless if it already ex‐
701 ists
702 label
705 set and clear labels for an image
706 --replace-all, -r: replace all labels
709 convert
712 convert an image
713 --all-platforms: exports content from all platforms
716 --oci: convert Docker media types to OCI media types
719 --platform="": Pull content from a specific platform
722 --uncompress: convert tar.gz layers to uncompressed tar layers
725
728 manage leases
729 list, ls
732 list all active leases
733 --quiet, -q: print only the blob digest
736 create
739 create lease
740 --expires, -x="": expiration of lease (0 value will not expire) (de‐
743 fault: 24h0m0s)
744 --id="": set the id for the lease, will be generated by default
747 delete, rm
750 delete a lease
751 --sync: Synchronously remove leases and all unreferenced resources
754
757 manage namespaces
758 create, c
761 create a new namespace
762 list, ls
765 list namespaces
766 --quiet, -q: print only the namespace name
769 remove, rm
772 remove one or more namespaces
773 --cgroup, -c: delete the namespace's cgroup
776 label
779 set and clear labels for a namespace
780
783 provide golang pprof outputs for containerd
784 --debug-socket, -d="": socket path for containerd's debug server (de‐
787 fault: /run/containerd/debug.sock)
788 block
791 goroutine blocking profile
792 goroutines
795 dump goroutine stack dump
796 heap
799 dump heap profile
800 profile
803 CPU profile
804 --seconds, -s="": duration for collection (seconds) (default: 30s)
807 threadcreate
810 goroutine thread creating profile
811 trace
814 collect execution trace
815 --seconds, -s="": trace time (seconds) (default: 5s)
818
821 run a container
822 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
825 --apparmor-default-profile="": enable AppArmor with the default profile
828 with the specified name, e.g. "cri-containerd.apparmor.d"
829 --apparmor-profile="": enable AppArmor with an existing custom profile
832 --cgroup="": cgroup path (To disable use of cgroup, set to "" explic‐
835 itly)
836 --cni: enable cni networking for the container
839 --config, -c="": path to the runtime-specific spec config file
842 --cpu-period="": Limit CPU CFS period (default: 0)
845 --cpu-quota="": Limit CPU CFS quota (default: -1)
848 --cpus="": set the CFS cpu quota (default: 0.000000)
851 --cwd="": specify the working directory of the process
854 --detach, -d: detach from the task after it has started execution
857 --device="": file path to a device to add to the container; or a path
860 to a directory tree of devices to add to the container
861 --env="": specify additional container environment variables (e.g.
864 FOO=bar)
865 --env-file="": specify additional container environment variables in a
868 file(e.g. FOO=bar, one per line)
869 --fifo-dir="": directory used for storing IO FIFOs
872 --gidmap="": run inside a user namespace with the specified GID mapping
875 range; specified with the format container-gid:host-gid:length
876 --gpus="": add gpus to the container (default: 0)
879 --label="": specify additional labels (e.g. foo=bar)
882 --log-uri="": log uri
885 --memory-limit="": memory limit (in bytes) for the container (default:
888 0)
889 --mount="": specify additional container mount (e.g.
892 type=bind,src=/tmp,dst=/host,options=rbind:ro)
893 --net-host: enable host networking for the container
896 --no-pivot: disable use of pivot-root (linux only)
899 --null-io: send all IO to /dev/null
902 --pid-file="": file path to write the task's pid
905 --platform="": run image for specific platform
908 --privileged: run privileged container
911 --read-only: set the containers filesystem as readonly
914 --remap-labels: provide the user namespace ID remapping to the snap‐
917 shotter via label options; requires snapshotter support
918 --rm: remove the container after running
921 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
924 ter
925 --runc-binary="": specify runc-compatible binary
928 --runc-root="": specify runc-compatible root
931 --runc-systemd-cgroup: start runc with systemd cgroup manager
934 --runtime="": runtime name (default: io.containerd.runc.v2)
937 --runtime-config-path="": optional runtime config path
940 --seccomp: enable the default seccomp profile
943 --seccomp-profile="": file path to custom seccomp profile. seccomp must
946 be set to true, before using seccomp-profile
947 --snapshotter="": snapshotter name. Empty value stands for the default
950 value.
951 --tty, -t: allocate a TTY for the container
954 --uidmap="": run inside a user namespace with the specified UID mapping
957 range; specified with the format container-uid:host-uid:length
958 --with-ns="": specify existing Linux namespaces to join at container
961 runtime (format ':')
962
965 manage snapshots
966 --snapshotter="": snapshotter name. Empty value stands for the default
969 value.
970 commit
973 commit an active snapshot into the provided name
974 diff
977 get the diff of two snapshots. the default second snapshot is the first
978 snapshot's parent.
979 --keep: keep diff content. up to creator to delete it.
982 --label="": labels to attach to the image
985 --media-type="": media type to use for creating diff (default: applica‐
988 tion/vnd.oci.image.layer.v1.tar+gzip)
989 --ref="": content upload reference to use
992 info
995 get info about a snapshot
996 list, ls
999 list snapshots
1000 mounts, m, mount
1003 mount gets mount commands for the snapshots
1004 prepare
1007 prepare a snapshot from a committed snapshot
1008 --mounts: Print out snapshot mounts as JSON
1011 --target, -t="": mount target path, will print mount, if provided
1014 remove, rm
1017 remove snapshots
1018 label
1021 add labels to content
1022 tree
1025 display tree view of snapshot branches
1026 unpack
1029 unpack applies layers from a manifest to a snapshot
1030 --snapshotter="": snapshotter name. Empty value stands for the default
1033 value.
1034 usage
1037 usage snapshots
1038 -b: display size in bytes
1041 view
1044 create a read-only snapshot from a committed snapshot
1045 --mounts: Print out snapshot mounts as JSON
1048 --target, -t="": mount target path, will print mount, if provided
1051
1054 manage tasks
1055 attach
1058 attach to the IO of a running container
1059 checkpoint
1062 checkpoint a container
1063 --exit: stop the container after the checkpoint
1066 --image-path="": path to criu image files
1069 --work-path="": path to criu work files and logs
1072 delete, rm
1075 delete one or more tasks
1076 --exec-id="": process ID to kill
1079 --force, -f: force delete task process
1082 exec
1085 execute additional processes in an existing container
1086 --cwd="": working directory of the new process
1089 --detach, -d: detach from the task after it has started execution
1092 --exec-id="": exec specific id for the process
1095 --fifo-dir="": directory used for storing IO FIFOs
1098 --log-uri="": log uri for custom shim logging
1101 --tty, -t: allocate a TTY for the container
1104 --user="": user id or name
1107 list, ls
1110 list tasks
1111 --quiet, -q: print only the task id
1114 kill
1117 signal a container (default: SIGTERM)
1118 --all, -a: send signal to all processes inside the container
1121 --exec-id="": process ID to kill
1124 --signal, -s="": signal to send to the container
1127 pause
1130 pause an existing container
1131 ps
1134 list processes for container
1135 resume
1138 resume a paused container
1139 start
1142 start a container that has been created
1143 --detach, -d: detach from the task after it has started execution
1146 --fifo-dir="": directory used for storing IO FIFOs
1149 --log-uri="": log uri
1152 --null-io: send all IO to /dev/null
1155 --pid-file="": file path to write the task's pid
1158 metrics, metric
1161 get a single data point of metrics for a task with the built-in Linux
1162 runtime
1163 --format="": "table" or "json" (default: table)
1166
1169 install a new package
1170 --libs, -l: install libs from the image
1173 --path="": set an optional install path other than the managed opt di‐
1176 rectory
1177 --replace, -r: replace any binaries or libs in the opt directory
1180
1183 OCI tools
1184 spec
1187 see the output of the default OCI spec
1188
1191 interact with a shim directly
1192 --id="": container id
1195 delete
1198 delete a container with a task
1199 exec
1202 exec a new process in the task's container
1203 --attach, -a: stay attached to the container and open the fifos
1206 --cwd="": current working directory
1209 --env, -e="": add environment vars
1212 --spec="": runtime spec
1215 --stderr="": specify the path to the stderr fifo
1218 --stdin="": specify the path to the stdin fifo
1221 --stdout="": specify the path to the stdout fifo
1224 --tty, -t: enable tty support
1227 start
1230 start a container with a task
1231 state
1234 get the state of all the processes of the task
1235 ctr(8)()