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, can‐
905 not be used with --rm
906 --device="": file path to a device to add to the container; or a path
909 to a directory tree of devices to add to the container
910 --env="": specify additional container environment variables (e.g.
913 FOO=bar)
914 --env-file="": specify additional container environment variables in a
917 file(e.g. FOO=bar, one per line)
918 --fifo-dir="": directory used for storing IO FIFOs
921 --gidmap="": run inside a user namespace with the specified GID mapping
924 range; specified with the format container-gid:host-gid:length
925 --gpus="": add gpus to the container
928 --label="": specify additional labels (e.g. foo=bar)
931 --log-uri="": log uri
934 --memory-limit="": memory limit (in bytes) for the container (default:
937 0)
938 --mount="": specify additional container mount (e.g.
941 type=bind,src=/tmp,dst=/host,options=rbind:ro)
942 --net-host: enable host networking for the container
945 --no-pivot: disable use of pivot-root (linux only)
948 --null-io: send all IO to /dev/null
951 --pid-file="": file path to write the task's pid
954 --platform="": run image for specific platform
957 --privileged: run privileged container
960 --rdt-class="": name of the RDT class to associate the container with.
963 Specifies a Class of Service (CLOS) for cache and memory bandwidth man‐
964 agement.
965 --read-only: set the containers filesystem as readonly
968 --remap-labels: provide the user namespace ID remapping to the snap‐
971 shotter via label options; requires snapshotter support
972 --rm: remove the container after running, cannot be used with --detach
975 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
978 ter
979 --rootfs-propagation="": set the propagation of the container rootfs
982 --runc-binary="": specify runc-compatible binary
985 --runc-root="": specify runc-compatible root
988 --runc-systemd-cgroup: start runc with systemd cgroup manager
991 --runtime="": runtime name (default: io.containerd.runc.v2)
994 --runtime-config-path="": optional runtime config path
997 --seccomp: enable the default seccomp profile
1000 --seccomp-profile="": file path to custom seccomp profile. seccomp must
1003 be set to true, before using seccomp-profile
1004 --snapshotter="": snapshotter name. Empty value stands for the default
1007 value.
1008 --snapshotter-label="": labels added to the new snapshot for this con‐
1011 tainer.
1012 --tty, -t: allocate a TTY for the container
1015 --uidmap="": run inside a user namespace with the specified UID mapping
1018 range; specified with the format container-uid:host-uid:length
1019 --with-ns="": specify existing Linux namespaces to join at container
1022 runtime (format ':')
1023
1026 manage snapshots
1027 --snapshotter="": snapshotter name. Empty value stands for the default
1030 value.
1031 commit
1034 commit an active snapshot into the provided name
1035 diff
1038 get the diff of two snapshots. the default second snapshot is the first
1039 snapshot's parent.
1040 --keep: keep diff content. up to creator to delete it.
1043 --label="": labels to attach to the image
1046 --media-type="": media type to use for creating diff (default: applica‐
1049 tion/vnd.oci.image.layer.v1.tar+gzip)
1050 --ref="": content upload reference to use
1053 info
1056 get info about a snapshot
1057 list, ls
1060 list snapshots
1061 mounts, m, mount
1064 mount gets mount commands for the snapshots
1065 prepare
1068 prepare a snapshot from a committed snapshot
1069 --mounts: Print out snapshot mounts as JSON
1072 --target, -t="": mount target path, will print mount, if provided
1075 delete, del, remove, rm
1078 remove snapshots
1079 label
1082 add labels to content
1083 tree
1086 display tree view of snapshot branches
1087 unpack
1090 unpack applies layers from a manifest to a snapshot
1091 --snapshotter="": snapshotter name. Empty value stands for the default
1094 value.
1095 usage
1098 usage snapshots
1099 -b: display size in bytes
1102 view
1105 create a read-only snapshot from a committed snapshot
1106 --mounts: Print out snapshot mounts as JSON
1109 --target, -t="": mount target path, will print mount, if provided
1112
1115 manage tasks
1116 attach
1119 attach to the IO of a running container
1120 checkpoint
1123 checkpoint a container
1124 --exit: stop the container after the checkpoint
1127 --image-path="": path to criu image files
1130 --work-path="": path to criu work files and logs
1133 delete, del, remove, rm
1136 delete one or more tasks
1137 --exec-id="": process ID to kill
1140 --force, -f: force delete task process
1143 exec
1146 execute additional processes in an existing container
1147 --cwd="": working directory of the new process
1150 --detach, -d: detach from the task after it has started execution
1153 --exec-id="": exec specific id for the process
1156 --fifo-dir="": directory used for storing IO FIFOs
1159 --log-uri="": log uri for custom shim logging
1162 --tty, -t: allocate a TTY for the container
1165 --user="": user id or name
1168 list, ls
1171 list tasks
1172 --quiet, -q: print only the task id
1175 kill
1178 signal a container (default: SIGTERM)
1179 --all, -a: send signal to all processes inside the container
1182 --exec-id="": process ID to kill
1185 --signal, -s="": signal to send to the container
1188 pause
1191 pause an existing container
1192 ps
1195 list processes for container
1196 resume
1199 resume a paused container
1200 start
1203 start a container that has been created
1204 --detach, -d: detach from the task after it has started execution
1207 --fifo-dir="": directory used for storing IO FIFOs
1210 --log-uri="": log uri
1213 --null-io: send all IO to /dev/null
1216 --pid-file="": file path to write the task's pid
1219 metrics, metric
1222 get a single data point of metrics for a task with the built-in Linux
1223 runtime
1224 --format="": "table" or "json" (default: table)
1227
1230 install a new package
1231 --libs, -l: install libs from the image
1234 --path="": set an optional install path other than the managed opt di‐
1237 rectory
1238 --replace, -r: replace any binaries or libs in the opt directory
1241
1244 OCI tools
1245 spec
1248 see the output of the default OCI spec
1249
1252 interact with a shim directly
1253 --id="": container id
1256 delete
1259 delete a container with a task
1260 exec
1263 exec a new process in the task's container
1264 --attach, -a: stay attached to the container and open the fifos
1267 --cwd="": current working directory
1270 --env, -e="": add environment vars
1273 --spec="": runtime spec
1276 --stderr="": specify the path to the stderr fifo
1279 --stdin="": specify the path to the stdin fifo
1282 --stdout="": specify the path to the stdout fifo
1285 --tty, -t: enable tty support
1288 start
1291 start a container with a task
1292 state
1295 get the state of all the processes of the task
1296 ctr(8)()