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 --cap-add="": add Linux capabilities (Set capabilities with 'CAP_' pre‐
97 fix)
98 --cap-drop="": drop Linux capabilities (Set capabilities with 'CAP_'
101 prefix)
102 --config, -c="": path to the runtime-specific spec config file
105 --cpu-period="": Limit CPU CFS period (default: 0)
108 --cpu-quota="": Limit CPU CFS quota (default: -1)
111 --cwd="": specify the working directory of the process
114 --device="": file path to a device to add to the container; or a path
117 to a directory tree of devices to add to the container
118 --env="": specify additional container environment variables (e.g.
121 FOO=bar)
122 --env-file="": specify additional container environment variables in a
125 file(e.g. FOO=bar, one per line)
126 --gpus="": add gpus to the container
129 --label="": specify additional labels (e.g. foo=bar)
132 --memory-limit="": memory limit (in bytes) for the container (default:
135 0)
136 --mount="": specify additional container mount (e.g.
139 type=bind,src=/tmp,dst=/host,options=rbind:ro)
140 --net-host: enable host networking for the container
143 --no-pivot: disable use of pivot-root (linux only)
146 --pid-file="": file path to write the task's pid
149 --privileged: run privileged container
152 --rdt-class="": name of the RDT class to associate the container with.
155 Specifies a Class of Service (CLOS) for cache and memory bandwidth man‐
156 agement.
157 --read-only: set the containers filesystem as readonly
160 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
163 ter
164 --rootfs-propagation="": set the propagation of the container rootfs
167 --runtime="": runtime name (default: io.containerd.runc.v2)
170 --runtime-config-path="": optional runtime config path
173 --seccomp: enable the default seccomp profile
176 --seccomp-profile="": file path to custom seccomp profile. seccomp must
179 be set to true, before using seccomp-profile
180 --snapshotter="": snapshotter name. Empty value stands for the default
183 value.
184 --snapshotter-label="": labels added to the new snapshot for this con‐
187 tainer.
188 --tty, -t: allocate a TTY for the container
191 --with-ns="": specify existing Linux namespaces to join at container
194 runtime (format ':')
195 delete, del, remove, rm
198 delete one or more existing containers
199 --keep-snapshot: do not clean up snapshot with container
202 info
205 get info about a container
206 --spec: only display the spec
209 list, ls
212 list containers
213 --quiet, -q: print only the container id
216 label
219 set and clear labels for a container
220 checkpoint
223 checkpoint a container
224 --image: include the image in the checkpoint
227 --rw: include the rw layer in the checkpoint
230 --task: checkpoint container task
233 restore
236 restore a container from checkpoint
237 --live: restore the runtime and memory data from the checkpoint
240 --rw: restore the rw layer from the checkpoint
243
246 manage content
247 active
250 display active transfers
251 --root="": path to content store root (default: /tmp/content)
254 --timeout, -t="": total timeout for fetch (default: 0s)
257 delete, del, remove, rm
260 permanently delete one or more blobs
261 edit
264 edit a blob and return a new digest
265 --editor="": select editor (vim, emacs, etc.)
268 --validate="": validate the result against a format (json, mediatype,
271 etc.)
272 fetch
275 fetch all content for an image into containerd
276 --all-metadata: Pull metadata for all platforms
279 --all-platforms: pull content from all platforms
282 --hosts-dir="": Custom hosts configuration directory
285 --http-dump: dump all HTTP request/responses when interacting with con‐
288 tainer registry
289 --http-trace: enable HTTP tracing for registry interactions
292 --label="": labels to attach to the image
295 --metadata-only: Pull all metadata including manifests and configs
298 --plain-http: allow connections using plain HTTP
301 --platform="": Pull content from a specific platform
304 --refresh="": refresh token for authorization server
307 --skip-verify, -k: skip SSL certificate validation
310 --tlscacert="": path to TLS root CA
313 --tlscert="": path to TLS client certificate
316 --tlskey="": path to TLS client key
319 --user, -u="": user[:password] Registry user and password
322 fetch-object
325 retrieve objects from a remote
326 --hosts-dir="": Custom hosts configuration directory
329 --http-dump: dump all HTTP request/responses when interacting with con‐
332 tainer registry
333 --http-trace: enable HTTP tracing for registry interactions
336 --plain-http: allow connections using plain HTTP
339 --refresh="": refresh token for authorization server
342 --skip-verify, -k: skip SSL certificate validation
345 --tlscacert="": path to TLS root CA
348 --tlscert="": path to TLS client certificate
351 --tlskey="": path to TLS client key
354 --user, -u="": user[:password] Registry user and password
357 get
360 get the data for an object
361 ingest
364 accept content into the store
365 --expected-digest="": verify content against expected digest
368 --expected-size="": validate against provided size (default: 0)
371 list, ls
374 list all blobs in the store
375 --quiet, -q: print only the blob digest
378 push-object
381 push an object to a remote
382 --hosts-dir="": Custom hosts configuration directory
385 --http-dump: dump all HTTP request/responses when interacting with con‐
388 tainer registry
389 --http-trace: enable HTTP tracing for registry interactions
392 --plain-http: allow connections using plain HTTP
395 --refresh="": refresh token for authorization server
398 --skip-verify, -k: skip SSL certificate validation
401 --tlscacert="": path to TLS root CA
404 --tlscert="": path to TLS client certificate
407 --tlskey="": path to TLS client key
410 --user, -u="": user[:password] Registry user and password
413 label
416 add labels to content
417 prune
420 prunes content from the content store
421 references
424 prunes preference labels from the content store (layers only by de‐
425 fault)
426 --async: allow garbage collection to cleanup asynchronously
429 --dry: just show updates without applying (enables debug logging)
432
435 display containerd events
436
439 manage images
440 check
443 check existing images to ensure all content is available locally
444 --quiet, -q: print only the ready image refs (fully downloaded and un‐
447 packed)
448 --snapshotter="": snapshotter name. Empty value stands for the default
451 value.
452 export
455 export images
456 --all-platforms: exports content from all platforms
459 --platform="": Pull content from a specific platform
462 --skip-manifest-json: do not add Docker compatible manifest.json to ar‐
465 chive
466 --skip-non-distributable: do not add non-distributable blobs such as
469 Windows layers to archive
470 import
473 import images
474 --all-platforms: imports content for all platforms, false by default
477 --base-name="": base image name for added images, when provided only
480 images with this name prefix are imported
481 --compress-blobs: compress uncompressed blobs when creating manifest
484 (Docker format only)
485 --digests: whether to create digest images (default: false)
488 --index-name="": image name to keep index as, by default index is dis‐
491 carded
492 --no-unpack: skip unpacking the images, false by default
495 --platform="": imports content for specific platform
498 --skip-digest-for-named: skip applying --digests option to images named
501 in the importing tar (use it in conjunction with --digests)
502 --snapshotter="": snapshotter name. Empty value stands for the default
505 value.
506 list, ls
509 list images known to containerd
510 --quiet, -q: print only the image refs
513 mount
516 mount an image to a target path
517 --hosts-dir="": Custom hosts configuration directory
520 --http-dump: dump all HTTP request/responses when interacting with con‐
523 tainer registry
524 --http-trace: enable HTTP tracing for registry interactions
527 --label="": labels to attach to the image
530 --plain-http: allow connections using plain HTTP
533 --platform="": Mount the image for the specified platform (default:
536 linux/amd64)
537 --refresh="": refresh token for authorization server
540 --rw: Enable write support on the mount
543 --skip-verify, -k: skip SSL certificate validation
546 --snapshotter="": snapshotter name. Empty value stands for the default
549 value.
550 --tlscacert="": path to TLS root CA
553 --tlscert="": path to TLS client certificate
556 --tlskey="": path to TLS client key
559 --user, -u="": user[:password] Registry user and password
562 unmount
565 unmount the image from the target
566 --hosts-dir="": Custom hosts configuration directory
569 --http-dump: dump all HTTP request/responses when interacting with con‐
572 tainer registry
573 --http-trace: enable HTTP tracing for registry interactions
576 --label="": labels to attach to the image
579 --plain-http: allow connections using plain HTTP
582 --refresh="": refresh token for authorization server
585 --rm: remove the snapshot after a successful unmount
588 --skip-verify, -k: skip SSL certificate validation
591 --snapshotter="": snapshotter name. Empty value stands for the default
594 value.
595 --tlscacert="": path to TLS root CA
598 --tlscert="": path to TLS client certificate
601 --tlskey="": path to TLS client key
604 --user, -u="": user[:password] Registry user and password
607 pull
610 pull an image from a remote
611 --all-metadata: Pull metadata for all platforms
614 --all-platforms: pull content and metadata from all platforms
617 --hosts-dir="": Custom hosts configuration directory
620 --http-dump: dump all HTTP request/responses when interacting with con‐
623 tainer registry
624 --http-trace: enable HTTP tracing for registry interactions
627 --label="": labels to attach to the image
630 --max-concurrent-downloads="": Set the max concurrent downloads for
633 each pull (default: 0)
634 --plain-http: allow connections using plain HTTP
637 --platform="": Pull content from a specific platform
640 --print-chainid: Print the resulting image's chain ID
643 --refresh="": refresh token for authorization server
646 --skip-verify, -k: skip SSL certificate validation
649 --snapshotter="": snapshotter name. Empty value stands for the default
652 value.
653 --tlscacert="": path to TLS root CA
656 --tlscert="": path to TLS client certificate
659 --tlskey="": path to TLS client key
662 --user, -u="": user[:password] Registry user and password
665 push
668 push an image to a remote
669 --allow-non-distributable-blobs: Allow pushing blobs that are marked as
672 non-distributable
673 --hosts-dir="": Custom hosts configuration directory
676 --http-dump: dump all HTTP request/responses when interacting with con‐
679 tainer registry
680 --http-trace: enable HTTP tracing for registry interactions
683 --manifest="": digest of manifest
686 --manifest-type="": media type of manifest digest (default: applica‐
689 tion/vnd.oci.image.manifest.v1+json)
690 --max-concurrent-uploaded-layers="": Set the max concurrent uploaded
693 layers for each push (default: 0)
694 --plain-http: allow connections using plain HTTP
697 --platform="": push content from a specific platform
700 --refresh="": refresh token for authorization server
703 --skip-verify, -k: skip SSL certificate validation
706 --tlscacert="": path to TLS root CA
709 --tlscert="": path to TLS client certificate
712 --tlskey="": path to TLS client key
715 --user, -u="": user[:password] Registry user and password
718 delete, del, remove, rm
721 remove one or more images by reference
722 --sync: Synchronously remove image and all associated resources
725 tag
728 tag an image
729 --force: force target_ref to be created, regardless if it already ex‐
732 ists
733 label
736 set and clear labels for an image
737 --replace-all, -r: replace all labels
740 convert
743 convert an image
744 --all-platforms: exports content from all platforms
747 --oci: convert Docker media types to OCI media types
750 --platform="": Pull content from a specific platform
753 --uncompress: convert tar.gz layers to uncompressed tar layers
756
759 manage leases
760 list, ls
763 list all active leases
764 --quiet, -q: print only the blob digest
767 create
770 create lease
771 --expires, -x="": expiration of lease (0 value will not expire) (de‐
774 fault: 24h0m0s)
775 --id="": set the id for the lease, will be generated by default
778 delete, del, remove, rm
781 delete a lease
782 --sync: Synchronously remove leases and all unreferenced resources
785
788 manage namespaces
789 create, c
792 create a new namespace
793 list, ls
796 list namespaces
797 --quiet, -q: print only the namespace name
800 remove, rm
803 remove one or more namespaces
804 --cgroup, -c: delete the namespace's cgroup
807 label
810 set and clear labels for a namespace
811
814 provide golang pprof outputs for containerd
815 --debug-socket, -d="": socket path for containerd's debug server (de‐
818 fault: /run/containerd/debug.sock)
819 block
822 goroutine blocking profile
823 goroutines
826 dump goroutine stack dump
827 heap
830 dump heap profile
831 profile
834 CPU profile
835 --seconds, -s="": duration for collection (seconds) (default: 30s)
838 threadcreate
841 goroutine thread creating profile
842 trace
845 collect execution trace
846 --seconds, -s="": trace time (seconds) (default: 5s)
849
852 run a container
853 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
856 --apparmor-default-profile="": enable AppArmor with the default profile
859 with the specified name, e.g. "cri-containerd.apparmor.d"
860 --apparmor-profile="": enable AppArmor with an existing custom profile
863 --cap-add="": add Linux capabilities (Set capabilities with 'CAP_' pre‐
866 fix)
867 --cap-drop="": drop Linux capabilities (Set capabilities with 'CAP_'
870 prefix)
871 --cgroup="": cgroup path (To disable use of cgroup, set to "" explic‐
874 itly)
875 --cni: enable cni networking for the container
878 --config, -c="": path to the runtime-specific spec config file
881 --cpu-period="": Limit CPU CFS period (default: 0)
884 --cpu-quota="": Limit CPU CFS quota (default: -1)
887 --cpu-shares="": set the cpu shares (default: 1024)
890 --cpus="": set the CFS cpu quota (default: 0.000000)
893 --cwd="": specify the working directory of the process
896 --detach, -d: detach from the task after it has started execution
899 --device="": file path to a device to add to the container; or a path
902 to a directory tree of devices to add to the container
903 --env="": specify additional container environment variables (e.g.
906 FOO=bar)
907 --env-file="": specify additional container environment variables in a
910 file(e.g. FOO=bar, one per line)
911 --fifo-dir="": directory used for storing IO FIFOs
914 --gidmap="": run inside a user namespace with the specified GID mapping
917 range; specified with the format container-gid:host-gid:length
918 --gpus="": add gpus to the container
921 --label="": specify additional labels (e.g. foo=bar)
924 --log-uri="": log uri
927 --memory-limit="": memory limit (in bytes) for the container (default:
930 0)
931 --mount="": specify additional container mount (e.g.
934 type=bind,src=/tmp,dst=/host,options=rbind:ro)
935 --net-host: enable host networking for the container
938 --no-pivot: disable use of pivot-root (linux only)
941 --null-io: send all IO to /dev/null
944 --pid-file="": file path to write the task's pid
947 --platform="": run image for specific platform
950 --privileged: run privileged container
953 --rdt-class="": name of the RDT class to associate the container with.
956 Specifies a Class of Service (CLOS) for cache and memory bandwidth man‐
957 agement.
958 --read-only: set the containers filesystem as readonly
961 --remap-labels: provide the user namespace ID remapping to the snap‐
964 shotter via label options; requires snapshotter support
965 --rm: remove the container after running
968 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
971 ter
972 --rootfs-propagation="": set the propagation of the container rootfs
975 --runc-binary="": specify runc-compatible binary
978 --runc-root="": specify runc-compatible root
981 --runc-systemd-cgroup: start runc with systemd cgroup manager
984 --runtime="": runtime name (default: io.containerd.runc.v2)
987 --runtime-config-path="": optional runtime config path
990 --seccomp: enable the default seccomp profile
993 --seccomp-profile="": file path to custom seccomp profile. seccomp must
996 be set to true, before using seccomp-profile
997 --snapshotter="": snapshotter name. Empty value stands for the default
1000 value.
1001 --snapshotter-label="": labels added to the new snapshot for this con‐
1004 tainer.
1005 --tty, -t: allocate a TTY for the container
1008 --uidmap="": run inside a user namespace with the specified UID mapping
1011 range; specified with the format container-uid:host-uid:length
1012 --with-ns="": specify existing Linux namespaces to join at container
1015 runtime (format ':')
1016
1019 manage snapshots
1020 --snapshotter="": snapshotter name. Empty value stands for the default
1023 value.
1024 commit
1027 commit an active snapshot into the provided name
1028 diff
1031 get the diff of two snapshots. the default second snapshot is the first
1032 snapshot's parent.
1033 --keep: keep diff content. up to creator to delete it.
1036 --label="": labels to attach to the image
1039 --media-type="": media type to use for creating diff (default: applica‐
1042 tion/vnd.oci.image.layer.v1.tar+gzip)
1043 --ref="": content upload reference to use
1046 info
1049 get info about a snapshot
1050 list, ls
1053 list snapshots
1054 mounts, m, mount
1057 mount gets mount commands for the snapshots
1058 prepare
1061 prepare a snapshot from a committed snapshot
1062 --mounts: Print out snapshot mounts as JSON
1065 --target, -t="": mount target path, will print mount, if provided
1068 delete, del, remove, rm
1071 remove snapshots
1072 label
1075 add labels to content
1076 tree
1079 display tree view of snapshot branches
1080 unpack
1083 unpack applies layers from a manifest to a snapshot
1084 --snapshotter="": snapshotter name. Empty value stands for the default
1087 value.
1088 usage
1091 usage snapshots
1092 -b: display size in bytes
1095 view
1098 create a read-only snapshot from a committed snapshot
1099 --mounts: Print out snapshot mounts as JSON
1102 --target, -t="": mount target path, will print mount, if provided
1105
1108 manage tasks
1109 attach
1112 attach to the IO of a running container
1113 checkpoint
1116 checkpoint a container
1117 --exit: stop the container after the checkpoint
1120 --image-path="": path to criu image files
1123 --work-path="": path to criu work files and logs
1126 delete, del, remove, rm
1129 delete one or more tasks
1130 --exec-id="": process ID to kill
1133 --force, -f: force delete task process
1136 exec
1139 execute additional processes in an existing container
1140 --cwd="": working directory of the new process
1143 --detach, -d: detach from the task after it has started execution
1146 --exec-id="": exec specific id for the process
1149 --fifo-dir="": directory used for storing IO FIFOs
1152 --log-uri="": log uri for custom shim logging
1155 --tty, -t: allocate a TTY for the container
1158 --user="": user id or name
1161 list, ls
1164 list tasks
1165 --quiet, -q: print only the task id
1168 kill
1171 signal a container (default: SIGTERM)
1172 --all, -a: send signal to all processes inside the container
1175 --exec-id="": process ID to kill
1178 --signal, -s="": signal to send to the container
1181 pause
1184 pause an existing container
1185 ps
1188 list processes for container
1189 resume
1192 resume a paused container
1193 start
1196 start a container that has been created
1197 --detach, -d: detach from the task after it has started execution
1200 --fifo-dir="": directory used for storing IO FIFOs
1203 --log-uri="": log uri
1206 --null-io: send all IO to /dev/null
1209 --pid-file="": file path to write the task's pid
1212 metrics, metric
1215 get a single data point of metrics for a task with the built-in Linux
1216 runtime
1217 --format="": "table" or "json" (default: table)
1220
1223 install a new package
1224 --libs, -l: install libs from the image
1227 --path="": set an optional install path other than the managed opt di‐
1230 rectory
1231 --replace, -r: replace any binaries or libs in the opt directory
1234
1237 OCI tools
1238 spec
1241 see the output of the default OCI spec
1242
1245 interact with a shim directly
1246 --id="": container id
1249 delete
1252 delete a container with a task
1253 exec
1256 exec a new process in the task's container
1257 --attach, -a: stay attached to the container and open the fifos
1260 --cwd="": current working directory
1263 --env, -e="": add environment vars
1266 --spec="": runtime spec
1269 --stderr="": specify the path to the stderr fifo
1272 --stdin="": specify the path to the stdin fifo
1275 --stdout="": specify the path to the stdout fifo
1278 --tty, -t: enable tty support
1281 start
1284 start a container with a task
1285 state
1288 get the state of all the processes of the task
1289 ctr(8)()