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 that an image has all content available locally
424 --snapshotter="": snapshotter name. Empty value stands for the default
427 value.
428 export
431 export images
432 --all-platforms: exports content from all platforms
435 --platform="": Pull content from a specific platform
438 --skip-manifest-json: do not add Docker compatible manifest.json to ar‐
441 chive
442 --skip-non-distributable: do not add non-distributable blobs such as
445 Windows layers to archive
446 import
449 import images
450 --all-platforms: imports content for all platforms, false by default
453 --base-name="": base image name for added images, when provided only
456 images with this name prefix are imported
457 --compress-blobs: compress uncompressed blobs when creating manifest
460 (Docker format only)
461 --digests: whether to create digest images (default: false)
464 --index-name="": image name to keep index as, by default index is dis‐
467 carded
468 --no-unpack: skip unpacking the images, false by default
471 --snapshotter="": snapshotter name. Empty value stands for the default
474 value.
475 list, ls
478 list images known to containerd
479 --quiet, -q: print only the image refs
482 mount
485 mount an image to a target path
486 --hosts-dir="": Custom hosts configuration directory
489 --http-dump: dump all HTTP request/responses when interacting with con‐
492 tainer registry
493 --http-trace: enable HTTP tracing for registry interactions
496 --label="": labels to attach to the image
499 --plain-http: allow connections using plain HTTP
502 --platform="": Mount the image for the specified platform (default:
505 linux/amd64)
506 --refresh="": refresh token for authorization server
509 --rw: Enable write support on the mount
512 --skip-verify, -k: skip SSL certificate validation
515 --snapshotter="": snapshotter name. Empty value stands for the default
518 value.
519 --tlscacert="": path to TLS root CA
522 --tlscert="": path to TLS client certificate
525 --tlskey="": path to TLS client key
528 --user, -u="": user[:password] Registry user and password
531 unmount
534 unmount the image from the target
535 --hosts-dir="": Custom hosts configuration directory
538 --http-dump: dump all HTTP request/responses when interacting with con‐
541 tainer registry
542 --http-trace: enable HTTP tracing for registry interactions
545 --label="": labels to attach to the image
548 --plain-http: allow connections using plain HTTP
551 --refresh="": refresh token for authorization server
554 --rm: remove the snapshot after a successful unmount
557 --skip-verify, -k: skip SSL certificate validation
560 --snapshotter="": snapshotter name. Empty value stands for the default
563 value.
564 --tlscacert="": path to TLS root CA
567 --tlscert="": path to TLS client certificate
570 --tlskey="": path to TLS client key
573 --user, -u="": user[:password] Registry user and password
576 pull
579 pull an image from a remote
580 --all-metadata: Pull metadata for all platforms
583 --all-platforms: pull content and metadata from all platforms
586 --hosts-dir="": Custom hosts configuration directory
589 --http-dump: dump all HTTP request/responses when interacting with con‐
592 tainer registry
593 --http-trace: enable HTTP tracing for registry interactions
596 --label="": labels to attach to the image
599 --max-concurrent-downloads="": Set the max concurrent downloads for
602 each pull (default: 0)
603 --plain-http: allow connections using plain HTTP
606 --platform="": Pull content from a specific platform
609 --print-chainid: Print the resulting image's chain ID
612 --refresh="": refresh token for authorization server
615 --skip-verify, -k: skip SSL certificate validation
618 --snapshotter="": snapshotter name. Empty value stands for the default
621 value.
622 --tlscacert="": path to TLS root CA
625 --tlscert="": path to TLS client certificate
628 --tlskey="": path to TLS client key
631 --user, -u="": user[:password] Registry user and password
634 push
637 push an image to a remote
638 --hosts-dir="": Custom hosts configuration directory
641 --http-dump: dump all HTTP request/responses when interacting with con‐
644 tainer registry
645 --http-trace: enable HTTP tracing for registry interactions
648 --manifest="": digest of manifest
651 --manifest-type="": media type of manifest digest (default: applica‐
654 tion/vnd.oci.image.manifest.v1+json)
655 --max-concurrent-uploaded-layers="": Set the max concurrent uploaded
658 layers for each push (default: 0)
659 --plain-http: allow connections using plain HTTP
662 --platform="": push content from a specific platform
665 --refresh="": refresh token for authorization server
668 --skip-verify, -k: skip SSL certificate validation
671 --tlscacert="": path to TLS root CA
674 --tlscert="": path to TLS client certificate
677 --tlskey="": path to TLS client key
680 --user, -u="": user[:password] Registry user and password
683 remove, rm
686 remove one or more images by reference
687 --sync: Synchronously remove image and all associated resources
690 tag
693 tag an image
694 --force: force target_ref to be created, regardless if it already ex‐
697 ists
698 label
701 set and clear labels for an image
702 --replace-all, -r: replace all labels
705 convert
708 convert an image
709 --all-platforms: exports content from all platforms
712 --oci: convert Docker media types to OCI media types
715 --platform="": Pull content from a specific platform
718 --uncompress: convert tar.gz layers to uncompressed tar layers
721
724 manage leases
725 list, ls
728 list all active leases
729 --quiet, -q: print only the blob digest
732 create
735 create lease
736 --expires, -x="": expiration of lease (0 value will not expire) (de‐
739 fault: 24h0m0s)
740 --id="": set the id for the lease, will be generated by default
743 delete, rm
746 delete a lease
747 --sync: Synchronously remove leases and all unreferenced resources
750
753 manage namespaces
754 create, c
757 create a new namespace
758 list, ls
761 list namespaces
762 --quiet, -q: print only the namespace name
765 remove, rm
768 remove one or more namespaces
769 --cgroup, -c: delete the namespace's cgroup
772 label
775 set and clear labels for a namespace
776
779 provide golang pprof outputs for containerd
780 --debug-socket, -d="": socket path for containerd's debug server (de‐
783 fault: /run/containerd/debug.sock)
784 block
787 goroutine blocking profile
788 goroutines
791 dump goroutine stack dump
792 heap
795 dump heap profile
796 profile
799 CPU profile
800 --seconds, -s="": duration for collection (seconds) (default: 30s)
803 threadcreate
806 goroutine thread creating profile
807 trace
810 collect execution trace
811 --seconds, -s="": trace time (seconds) (default: 5s)
814
817 run a container
818 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
821 --apparmor-default-profile="": enable AppArmor with the default profile
824 with the specified name, e.g. "cri-containerd.apparmor.d"
825 --apparmor-profile="": enable AppArmor with an existing custom profile
828 --cgroup="": cgroup path (To disable use of cgroup, set to "" explic‐
831 itly)
832 --cni: enable cni networking for the container
835 --config, -c="": path to the runtime-specific spec config file
838 --cpu-period="": Limit CPU CFS period (default: 0)
841 --cpu-quota="": Limit CPU CFS quota (default: -1)
844 --cpus="": set the CFS cpu quota (default: 0.000000)
847 --cwd="": specify the working directory of the process
850 --detach, -d: detach from the task after it has started execution
853 --device="": file path to a device to add to the container; or a path
856 to a directory tree of devices to add to the container
857 --env="": specify additional container environment variables (e.g.
860 FOO=bar)
861 --env-file="": specify additional container environment variables in a
864 file(e.g. FOO=bar, one per line)
865 --fifo-dir="": directory used for storing IO FIFOs
868 --gidmap="": run inside a user namespace with the specified GID mapping
871 range; specified with the format container-gid:host-gid:length
872 --gpus="": add gpus to the container (default: 0)
875 --label="": specify additional labels (e.g. foo=bar)
878 --log-uri="": log uri
881 --memory-limit="": memory limit (in bytes) for the container (default:
884 0)
885 --mount="": specify additional container mount (e.g.
888 type=bind,src=/tmp,dst=/host,options=rbind:ro)
889 --net-host: enable host networking for the container
892 --no-pivot: disable use of pivot-root (linux only)
895 --null-io: send all IO to /dev/null
898 --pid-file="": file path to write the task's pid
901 --platform="": run image for specific platform
904 --privileged: run privileged container
907 --read-only: set the containers filesystem as readonly
910 --remap-labels: provide the user namespace ID remapping to the snap‐
913 shotter via label options; requires snapshotter support
914 --rm: remove the container after running
917 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
920 ter
921 --runc-binary="": specify runc-compatible binary
924 --runc-root="": specify runc-compatible root
927 --runc-systemd-cgroup: start runc with systemd cgroup manager
930 --runtime="": runtime name (default: io.containerd.runc.v2)
933 --runtime-config-path="": optional runtime config path
936 --seccomp: enable the default seccomp profile
939 --seccomp-profile="": file path to custom seccomp profile. seccomp must
942 be set to true, before using seccomp-profile
943 --snapshotter="": snapshotter name. Empty value stands for the default
946 value.
947 --tty, -t: allocate a TTY for the container
950 --uidmap="": run inside a user namespace with the specified UID mapping
953 range; specified with the format container-uid:host-uid:length
954 --with-ns="": specify existing Linux namespaces to join at container
957 runtime (format ':')
958
961 manage snapshots
962 --snapshotter="": snapshotter name. Empty value stands for the default
965 value.
966 commit
969 commit an active snapshot into the provided name
970 diff
973 get the diff of two snapshots. the default second snapshot is the first
974 snapshot's parent.
975 --keep: keep diff content. up to creator to delete it.
978 --label="": labels to attach to the image
981 --media-type="": media type to use for creating diff (default: applica‐
984 tion/vnd.oci.image.layer.v1.tar+gzip)
985 --ref="": content upload reference to use
988 info
991 get info about a snapshot
992 list, ls
995 list snapshots
996 mounts, m, mount
999 mount gets mount commands for the snapshots
1000 prepare
1003 prepare a snapshot from a committed snapshot
1004 --mounts: Print out snapshot mounts as JSON
1007 --target, -t="": mount target path, will print mount, if provided
1010 remove, rm
1013 remove snapshots
1014 label
1017 add labels to content
1018 tree
1021 display tree view of snapshot branches
1022 unpack
1025 unpack applies layers from a manifest to a snapshot
1026 --snapshotter="": snapshotter name. Empty value stands for the default
1029 value.
1030 usage
1033 usage snapshots
1034 -b: display size in bytes
1037 view
1040 create a read-only snapshot from a committed snapshot
1041 --mounts: Print out snapshot mounts as JSON
1044 --target, -t="": mount target path, will print mount, if provided
1047
1050 manage tasks
1051 attach
1054 attach to the IO of a running container
1055 checkpoint
1058 checkpoint a container
1059 --exit: stop the container after the checkpoint
1062 --image-path="": path to criu image files
1065 --work-path="": path to criu work files and logs
1068 delete, rm
1071 delete one or more tasks
1072 --exec-id="": process ID to kill
1075 --force, -f: force delete task process
1078 exec
1081 execute additional processes in an existing container
1082 --cwd="": working directory of the new process
1085 --detach, -d: detach from the task after it has started execution
1088 --exec-id="": exec specific id for the process
1091 --fifo-dir="": directory used for storing IO FIFOs
1094 --log-uri="": log uri for custom shim logging
1097 --tty, -t: allocate a TTY for the container
1100 --user="": user id or name
1103 list, ls
1106 list tasks
1107 --quiet, -q: print only the task id
1110 kill
1113 signal a container (default: SIGTERM)
1114 --all, -a: send signal to all processes inside the container
1117 --exec-id="": process ID to kill
1120 --signal, -s="": signal to send to the container
1123 pause
1126 pause an existing container
1127 ps
1130 list processes for container
1131 resume
1134 resume a paused container
1135 start
1138 start a container that has been created
1139 --detach, -d: detach from the task after it has started execution
1142 --fifo-dir="": directory used for storing IO FIFOs
1145 --log-uri="": log uri
1148 --null-io: send all IO to /dev/null
1151 --pid-file="": file path to write the task's pid
1154 metrics, metric
1157 get a single data point of metrics for a task with the built-in Linux
1158 runtime
1159 --format="": "table" or "json" (default: table)
1162
1165 install a new package
1166 --libs, -l: install libs from the image
1169 --path="": set an optional install path other than the managed opt di‐
1172 rectory
1173 --replace, -r: replace any binaries or libs in the opt directory
1176
1179 OCI tools
1180 spec
1183 see the output of the default OCI spec
1184
1187 interact with a shim directly
1188 --id="": container id
1191 delete
1194 delete a container with a task
1195 exec
1198 exec a new process in the task's container
1199 --attach, -a: stay attached to the container and open the fifos
1202 --cwd="": current working directory
1205 --env, -e="": add environment vars
1208 --spec="": runtime spec
1211 --stderr="": specify the path to the stderr fifo
1214 --stdin="": specify the path to the stdin fifo
1217 --stdout="": specify the path to the stdout fifo
1220 --tty, -t: enable tty support
1223 start
1226 start a container with a task
1227 state
1230 get the state of all the processes of the task
1231 ctr(8)()