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]
24 [--connect-timeout]=[value]
25 [--debug]
26 [--namespace|-n]=[value]
27 [--timeout]=[value]
28 Usage:
32 ctr [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
34
39 --address, -a="": address for containerd's GRPC server (default:
40 /run/containerd/containerd.sock)
41 --connect-timeout="": timeout for connecting to containerd (default:
44 0s)
45 --debug: enable debug output in logs
48 --namespace, -n="": namespace to use with commands (default: default)
51 --timeout="": total timeout for ctr commands (default: 0s)
54
59 provides information about containerd plugins
60 list, ls
63 lists containerd plugins
64 --detailed, -d: print detailed information about each plugin
67 --quiet, -q: print only the plugin ids
70
73 print the client and server versions
74
77 manage containers
78 create
81 create container
82 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
85 --annotation="": specify additional OCI annotations (e.g. foo=bar)
88 --apparmor-default-profile="": enable AppArmor with the default profile
91 with the specified name, e.g. "cri-containerd.apparmor.d"
92 --apparmor-profile="": enable AppArmor with an existing custom profile
95 --cap-add="": add Linux capabilities (Set capabilities with 'CAP_' pre‐
98 fix)
99 --cap-drop="": drop Linux capabilities (Set capabilities with 'CAP_'
102 prefix)
103 --config, -c="": path to the runtime-specific spec config file
106 --cpu-period="": Limit CPU CFS period (default: 0)
109 --cpu-quota="": Limit CPU CFS quota (default: -1)
112 --cwd="": specify the working directory of the process
115 --device="": file path to a device to add to the container; or a path
118 to a directory tree of devices to add to the container
119 --env="": specify additional container environment variables (e.g.
122 FOO=bar)
123 --env-file="": specify additional container environment variables in a
126 file(e.g. FOO=bar, one per line)
127 --gpus="": add gpus to the container
130 --label="": specify additional labels (e.g. foo=bar)
133 --memory-limit="": memory limit (in bytes) for the container (default:
136 0)
137 --mount="": specify additional container mount (e.g.
140 type=bind,src=/tmp,dst=/host,options=rbind:ro)
141 --net-host: enable host networking for the container
144 --no-pivot: disable use of pivot-root (linux only)
147 --pid-file="": file path to write the task's pid
150 --privileged: run privileged container
153 --rdt-class="": name of the RDT class to associate the container with.
156 Specifies a Class of Service (CLOS) for cache and memory bandwidth man‐
157 agement.
158 --read-only: set the containers filesystem as readonly
161 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
164 ter
165 --rootfs-propagation="": set the propagation of the container rootfs
168 --runtime="": runtime name (default: io.containerd.runc.v2)
171 --runtime-config-path="": optional runtime config path
174 --seccomp: enable the default seccomp profile
177 --seccomp-profile="": file path to custom seccomp profile. seccomp must
180 be set to true, before using seccomp-profile
181 --snapshotter="": snapshotter name. Empty value stands for the default
184 value.
185 --snapshotter-label="": labels added to the new snapshot for this con‐
188 tainer.
189 --tty, -t: allocate a TTY for the container
192 --with-ns="": specify existing Linux namespaces to join at container
195 runtime (format ':')
196 delete, del, remove, rm
199 delete one or more existing containers
200 --keep-snapshot: do not clean up snapshot with container
203 info
206 get info about a container
207 --spec: only display the spec
210 list, ls
213 list containers
214 --quiet, -q: print only the container id
217 label
220 set and clear labels for a container
221 checkpoint
224 checkpoint a container
225 --image: include the image in the checkpoint
228 --rw: include the rw layer in the checkpoint
231 --task: checkpoint container task
234 restore
237 restore a container from checkpoint
238 --live: restore the runtime and memory data from the checkpoint
241 --rw: restore the rw layer from the checkpoint
244
247 manage content
248 active
251 display active transfers
252 --root="": path to content store root (default: /tmp/content)
255 --timeout, -t="": total timeout for fetch (default: 0s)
258 delete, del, remove, rm
261 permanently delete one or more blobs
262 edit
265 edit a blob and return a new digest
266 --editor="": select editor (vim, emacs, etc.)
269 --validate="": validate the result against a format (json, mediatype,
272 etc.)
273 fetch
276 fetch all content for an image into containerd
277 --all-metadata: Pull metadata for all platforms
280 --all-platforms: pull content from all platforms
283 --hosts-dir="": Custom hosts configuration directory
286 --http-dump: dump all HTTP request/responses when interacting with con‐
289 tainer registry
290 --http-trace: enable HTTP tracing for registry interactions
293 --label="": labels to attach to the image
296 --metadata-only: Pull all metadata including manifests and configs
299 --plain-http: allow connections using plain HTTP
302 --platform="": Pull content from a specific platform
305 --refresh="": refresh token for authorization server
308 --skip-verify, -k: skip SSL certificate validation
311 --tlscacert="": path to TLS root CA
314 --tlscert="": path to TLS client certificate
317 --tlskey="": path to TLS client key
320 --user, -u="": user[:password] Registry user and password
323 fetch-object
326 retrieve objects from a remote
327 --hosts-dir="": Custom hosts configuration directory
330 --http-dump: dump all HTTP request/responses when interacting with con‐
333 tainer registry
334 --http-trace: enable HTTP tracing for registry interactions
337 --plain-http: allow connections using plain HTTP
340 --refresh="": refresh token for authorization server
343 --skip-verify, -k: skip SSL certificate validation
346 --tlscacert="": path to TLS root CA
349 --tlscert="": path to TLS client certificate
352 --tlskey="": path to TLS client key
355 --user, -u="": user[:password] Registry user and password
358 get
361 get the data for an object
362 ingest
365 accept content into the store
366 --expected-digest="": verify content against expected digest
369 --expected-size="": validate against provided size (default: 0)
372 list, ls
375 list all blobs in the store
376 --quiet, -q: print only the blob digest
379 push-object
382 push an object to a remote
383 --hosts-dir="": Custom hosts configuration directory
386 --http-dump: dump all HTTP request/responses when interacting with con‐
389 tainer registry
390 --http-trace: enable HTTP tracing for registry interactions
393 --plain-http: allow connections using plain HTTP
396 --refresh="": refresh token for authorization server
399 --skip-verify, -k: skip SSL certificate validation
402 --tlscacert="": path to TLS root CA
405 --tlscert="": path to TLS client certificate
408 --tlskey="": path to TLS client key
411 --user, -u="": user[:password] Registry user and password
414 label
417 add labels to content
418 prune
421 prunes content from the content store
422 references
425 prunes preference labels from the content store (layers only by de‐
426 fault)
427 --async: allow garbage collection to cleanup asynchronously
430 --dry: just show updates without applying (enables debug logging)
433
436 display containerd events
437
440 manage images
441 check
444 check existing images to ensure all content is available locally
445 --quiet, -q: print only the ready image refs (fully downloaded and un‐
448 packed)
449 --snapshotter="": snapshotter name. Empty value stands for the default
452 value.
453 export
456 export images
457 --all-platforms: exports content from all platforms
460 --platform="": Pull content from a specific platform
463 --skip-manifest-json: do not add Docker compatible manifest.json to ar‐
466 chive
467 --skip-non-distributable: do not add non-distributable blobs such as
470 Windows layers to archive
471 import
474 import images
475 --all-platforms: imports content for all platforms, false by default
478 --base-name="": base image name for added images, when provided only
481 images with this name prefix are imported
482 --compress-blobs: compress uncompressed blobs when creating manifest
485 (Docker format only)
486 --digests: whether to create digest images (default: false)
489 --index-name="": image name to keep index as, by default index is dis‐
492 carded
493 --no-unpack: skip unpacking the images, false by default
496 --platform="": imports content for specific platform
499 --skip-digest-for-named: skip applying --digests option to images named
502 in the importing tar (use it in conjunction with --digests)
503 --snapshotter="": snapshotter name. Empty value stands for the default
506 value.
507 list, ls
510 list images known to containerd
511 --quiet, -q: print only the image refs
514 mount
517 mount an image to a target path
518 --hosts-dir="": Custom hosts configuration directory
521 --http-dump: dump all HTTP request/responses when interacting with con‐
524 tainer registry
525 --http-trace: enable HTTP tracing for registry interactions
528 --label="": labels to attach to the image
531 --plain-http: allow connections using plain HTTP
534 --platform="": Mount the image for the specified platform (default:
537 linux/amd64)
538 --refresh="": refresh token for authorization server
541 --rw: Enable write support on the mount
544 --skip-verify, -k: skip SSL certificate validation
547 --snapshotter="": snapshotter name. Empty value stands for the default
550 value.
551 --tlscacert="": path to TLS root CA
554 --tlscert="": path to TLS client certificate
557 --tlskey="": path to TLS client key
560 --user, -u="": user[:password] Registry user and password
563 unmount
566 unmount the image from the target
567 --hosts-dir="": Custom hosts configuration directory
570 --http-dump: dump all HTTP request/responses when interacting with con‐
573 tainer registry
574 --http-trace: enable HTTP tracing for registry interactions
577 --label="": labels to attach to the image
580 --plain-http: allow connections using plain HTTP
583 --refresh="": refresh token for authorization server
586 --rm: remove the snapshot after a successful unmount
589 --skip-verify, -k: skip SSL certificate validation
592 --snapshotter="": snapshotter name. Empty value stands for the default
595 value.
596 --tlscacert="": path to TLS root CA
599 --tlscert="": path to TLS client certificate
602 --tlskey="": path to TLS client key
605 --user, -u="": user[:password] Registry user and password
608 pull
611 pull an image from a remote
612 --all-metadata: Pull metadata for all platforms
615 --all-platforms: pull content and metadata from all platforms
618 --hosts-dir="": Custom hosts configuration directory
621 --http-dump: dump all HTTP request/responses when interacting with con‐
624 tainer registry
625 --http-trace: enable HTTP tracing for registry interactions
628 --label="": labels to attach to the image
631 --max-concurrent-downloads="": Set the max concurrent downloads for
634 each pull (default: 0)
635 --plain-http: allow connections using plain HTTP
638 --platform="": Pull content from a specific platform
641 --print-chainid: Print the resulting image's chain ID
644 --refresh="": refresh token for authorization server
647 --skip-verify, -k: skip SSL certificate validation
650 --snapshotter="": snapshotter name. Empty value stands for the default
653 value.
654 --tlscacert="": path to TLS root CA
657 --tlscert="": path to TLS client certificate
660 --tlskey="": path to TLS client key
663 --user, -u="": user[:password] Registry user and password
666 push
669 push an image to a remote
670 --allow-non-distributable-blobs: Allow pushing blobs that are marked as
673 non-distributable
674 --hosts-dir="": Custom hosts configuration directory
677 --http-dump: dump all HTTP request/responses when interacting with con‐
680 tainer registry
681 --http-trace: enable HTTP tracing for registry interactions
684 --manifest="": digest of manifest
687 --manifest-type="": media type of manifest digest (default: applica‐
690 tion/vnd.oci.image.manifest.v1+json)
691 --max-concurrent-uploaded-layers="": Set the max concurrent uploaded
694 layers for each push (default: 0)
695 --plain-http: allow connections using plain HTTP
698 --platform="": push content from a specific platform
701 --refresh="": refresh token for authorization server
704 --skip-verify, -k: skip SSL certificate validation
707 --tlscacert="": path to TLS root CA
710 --tlscert="": path to TLS client certificate
713 --tlskey="": path to TLS client key
716 --user, -u="": user[:password] Registry user and password
719 delete, del, remove, rm
722 remove one or more images by reference
723 --sync: Synchronously remove image and all associated resources
726 tag
729 tag an image
730 --force: force target_ref to be created, regardless if it already ex‐
733 ists
734 label
737 set and clear labels for an image
738 --replace-all, -r: replace all labels
741 convert
744 convert an image
745 --all-platforms: exports content from all platforms
748 --oci: convert Docker media types to OCI media types
751 --platform="": Pull content from a specific platform
754 --uncompress: convert tar.gz layers to uncompressed tar layers
757
760 manage leases
761 list, ls
764 list all active leases
765 --quiet, -q: print only the blob digest
768 create
771 create lease
772 --expires, -x="": expiration of lease (0 value will not expire) (de‐
775 fault: 24h0m0s)
776 --id="": set the id for the lease, will be generated by default
779 delete, del, remove, rm
782 delete a lease
783 --sync: Synchronously remove leases and all unreferenced resources
786
789 manage namespaces
790 create, c
793 create a new namespace
794 list, ls
797 list namespaces
798 --quiet, -q: print only the namespace name
801 remove, rm
804 remove one or more namespaces
805 --cgroup, -c: delete the namespace's cgroup
808 label
811 set and clear labels for a namespace
812
815 provide golang pprof outputs for containerd
816 --debug-socket, -d="": socket path for containerd's debug server (de‐
819 fault: /run/containerd/debug.sock)
820 block
823 goroutine blocking profile
824 goroutines
827 dump goroutine stack dump
828 heap
831 dump heap profile
832 profile
835 CPU profile
836 --seconds, -s="": duration for collection (seconds) (default: 30s)
839 threadcreate
842 goroutine thread creating profile
843 trace
846 collect execution trace
847 --seconds, -s="": trace time (seconds) (default: 5s)
850
853 run a container
854 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
857 --annotation="": specify additional OCI annotations (e.g. foo=bar)
860 --apparmor-default-profile="": enable AppArmor with the default profile
863 with the specified name, e.g. "cri-containerd.apparmor.d"
864 --apparmor-profile="": enable AppArmor with an existing custom profile
867 --cap-add="": add Linux capabilities (Set capabilities with 'CAP_' pre‐
870 fix)
871 --cap-drop="": drop Linux capabilities (Set capabilities with 'CAP_'
874 prefix)
875 --cgroup="": cgroup path (To disable use of cgroup, set to "" explic‐
878 itly)
879 --cni: enable cni networking for the container
882 --config, -c="": path to the runtime-specific spec config file
885 --cpu-period="": Limit CPU CFS period (default: 0)
888 --cpu-quota="": Limit CPU CFS quota (default: -1)
891 --cpu-shares="": set the cpu shares (default: 1024)
894 --cpus="": set the CFS cpu quota (default: 0.000000)
897 --cwd="": specify the working directory of the process
900 --detach, -d: detach from the task after it has started execution, can‐
903 not be used with --rm
904 --device="": file path to a device to add to the container; or a path
907 to a directory tree of devices to add to the container
908 --env="": specify additional container environment variables (e.g.
911 FOO=bar)
912 --env-file="": specify additional container environment variables in a
915 file(e.g. FOO=bar, one per line)
916 --fifo-dir="": directory used for storing IO FIFOs
919 --gidmap="": run inside a user namespace with the specified GID mapping
922 range; specified with the format container-gid:host-gid:length
923 --gpus="": add gpus to the container
926 --label="": specify additional labels (e.g. foo=bar)
929 --log-uri="": log uri
932 --memory-limit="": memory limit (in bytes) for the container (default:
935 0)
936 --mount="": specify additional container mount (e.g.
939 type=bind,src=/tmp,dst=/host,options=rbind:ro)
940 --net-host: enable host networking for the container
943 --no-pivot: disable use of pivot-root (linux only)
946 --null-io: send all IO to /dev/null
949 --pid-file="": file path to write the task's pid
952 --platform="": run image for specific platform
955 --privileged: run privileged container
958 --rdt-class="": name of the RDT class to associate the container with.
961 Specifies a Class of Service (CLOS) for cache and memory bandwidth man‐
962 agement.
963 --read-only: set the containers filesystem as readonly
966 --remap-labels: provide the user namespace ID remapping to the snap‐
969 shotter via label options; requires snapshotter support
970 --rm: remove the container after running, cannot be used with --detach
973 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
976 ter
977 --rootfs-propagation="": set the propagation of the container rootfs
980 --runc-binary="": specify runc-compatible binary
983 --runc-root="": specify runc-compatible root
986 --runc-systemd-cgroup: start runc with systemd cgroup manager
989 --runtime="": runtime name (default: io.containerd.runc.v2)
992 --runtime-config-path="": optional runtime config path
995 --seccomp: enable the default seccomp profile
998 --seccomp-profile="": file path to custom seccomp profile. seccomp must
1001 be set to true, before using seccomp-profile
1002 --snapshotter="": snapshotter name. Empty value stands for the default
1005 value.
1006 --snapshotter-label="": labels added to the new snapshot for this con‐
1009 tainer.
1010 --tty, -t: allocate a TTY for the container
1013 --uidmap="": run inside a user namespace with the specified UID mapping
1016 range; specified with the format container-uid:host-uid:length
1017 --with-ns="": specify existing Linux namespaces to join at container
1020 runtime (format ':')
1021
1024 manage snapshots
1025 --snapshotter="": snapshotter name. Empty value stands for the default
1028 value.
1029 commit
1032 commit an active snapshot into the provided name
1033 diff
1036 get the diff of two snapshots. the default second snapshot is the first
1037 snapshot's parent.
1038 --keep: keep diff content. up to creator to delete it.
1041 --label="": labels to attach to the image
1044 --media-type="": media type to use for creating diff (default: applica‐
1047 tion/vnd.oci.image.layer.v1.tar+gzip)
1048 --ref="": content upload reference to use
1051 info
1054 get info about a snapshot
1055 list, ls
1058 list snapshots
1059 mounts, m, mount
1062 mount gets mount commands for the snapshots
1063 prepare
1066 prepare a snapshot from a committed snapshot
1067 --mounts: Print out snapshot mounts as JSON
1070 --target, -t="": mount target path, will print mount, if provided
1073 delete, del, remove, rm
1076 remove snapshots
1077 label
1080 add labels to content
1081 tree
1084 display tree view of snapshot branches
1085 unpack
1088 unpack applies layers from a manifest to a snapshot
1089 --snapshotter="": snapshotter name. Empty value stands for the default
1092 value.
1093 usage
1096 usage snapshots
1097 -b: display size in bytes
1100 view
1103 create a read-only snapshot from a committed snapshot
1104 --mounts: Print out snapshot mounts as JSON
1107 --target, -t="": mount target path, will print mount, if provided
1110
1113 manage tasks
1114 attach
1117 attach to the IO of a running container
1118 checkpoint
1121 checkpoint a container
1122 --exit: stop the container after the checkpoint
1125 --image-path="": path to criu image files
1128 --work-path="": path to criu work files and logs
1131 delete, del, remove, rm
1134 delete one or more tasks
1135 --exec-id="": process ID to kill
1138 --force, -f: force delete task process
1141 exec
1144 execute additional processes in an existing container
1145 --cwd="": working directory of the new process
1148 --detach, -d: detach from the task after it has started execution
1151 --exec-id="": exec specific id for the process
1154 --fifo-dir="": directory used for storing IO FIFOs
1157 --log-uri="": log uri for custom shim logging
1160 --tty, -t: allocate a TTY for the container
1163 --user="": user id or name
1166 list, ls
1169 list tasks
1170 --quiet, -q: print only the task id
1173 kill
1176 signal a container (default: SIGTERM)
1177 --all, -a: send signal to all processes inside the container
1180 --exec-id="": process ID to kill
1183 --signal, -s="": signal to send to the container
1186 pause
1189 pause an existing container
1190 ps
1193 list processes for container
1194 resume
1197 resume a paused container
1198 start
1201 start a container that has been created
1202 --detach, -d: detach from the task after it has started execution
1205 --fifo-dir="": directory used for storing IO FIFOs
1208 --log-uri="": log uri
1211 --null-io: send all IO to /dev/null
1214 --pid-file="": file path to write the task's pid
1217 metrics, metric
1220 get a single data point of metrics for a task with the built-in Linux
1221 runtime
1222 --format="": "table" or "json" (default: table)
1225
1228 install a new package
1229 --libs, -l: install libs from the image
1232 --path="": set an optional install path other than the managed opt di‐
1235 rectory
1236 --replace, -r: replace any binaries or libs in the opt directory
1239
1242 OCI tools
1243 spec
1246 see the output of the default OCI spec
1247
1250 interact with a shim directly
1251 --id="": container id
1254 delete
1257 delete a container with a task
1258 exec
1261 exec a new process in the task's container
1262 --attach, -a: stay attached to the container and open the fifos
1265 --cwd="": current working directory
1268 --env, -e="": add environment vars
1271 --spec="": runtime spec
1274 --stderr="": specify the path to the stderr fifo
1277 --stdin="": specify the path to the stdin fifo
1280 --stdout="": specify the path to the stdout fifo
1283 --tty, -t: enable tty support
1286 start
1289 start a container with a task
1290 state
1293 get the state of all the processes of the task
1294 ctr(8)()