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 --config, -c="": path to the runtime-specific spec config file
90 --cwd="": specify the working directory of the process
93 --device="": add a device to a container
96 --env="": specify additional container environment variables (i.e.
99 FOO=bar)
100 --env-file="": specify additional container environment variables in a
103 file(i.e. FOO=bar, one per line)
104 --gpus="": add gpus to the container (default: 0)
107 --label="": specify additional labels (i.e. foo=bar)
110 --memory-limit="": memory limit (in bytes) for the container (default:
113 0)
114 --mount="": specify additional container mount (ex:
117 type=bind,src=/tmp,dst=/host,options=rbind:ro)
118 --net-host: enable host networking for the container
121 --no-pivot: disable use of pivot-root (linux only)
124 --pid-file="": file path to write the task's pid
127 --privileged: run privileged container
130 --read-only: set the containers filesystem as readonly
133 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
136 ter
137 --runtime="": runtime name (default: io.containerd.runc.v2)
140 --seccomp: enable the default seccomp profile
143 --snapshotter="": snapshotter name. Empty value stands for the default
146 value.
147 --tty, -t: allocate a TTY for the container
150 --with-ns="": specify existing Linux namespaces to join at container
153 runtime (format ':')
154 delete, del, rm
157 delete one or more existing containers
158 --keep-snapshot: do not clean up snapshot with container
161 info
164 get info about a container
165 list, ls
168 list containers
169 --quiet, -q: print only the container id
172 label
175 set and clear labels for a container
176 checkpoint
179 checkpoint a container
180 --image: include the image in the checkpoint
183 --rw: include the rw layer in the checkpoint
186 --task: checkpoint container task
189 restore
192 restore a container from checkpoint
193 --live: restore the runtime and memory data from the checkpoint
196 --rw: restore the rw layer from the checkpoint
199
202 manage content
203 active
206 display active transfers
207 --root="": path to content store root (default: /tmp/content)
210 --timeout, -t="": total timeout for fetch (default: 0s)
213 delete, del, remove, rm
216 permanently delete one or more blobs
217 edit
220 edit a blob and return a new digest
221 --editor="": select editor (vim, emacs, etc.)
224 --validate="": validate the result against a format (json, mediatype,
227 etc.)
228 fetch
231 fetch all content for an image into containerd
232 --all-metadata: Pull metadata for all platforms
235 --all-platforms: pull content from all platforms
238 --label="": labels to attach to the image
241 --metadata-only: Pull all metadata including manifests and configs
244 --plain-http: allow connections using plain HTTP
247 --platform="": Pull content from a specific platform
250 --refresh="": refresh token for authorization server
253 --skip-verify, -k: skip SSL certificate validation
256 --user, -u="": user[:password] Registry user and password
259 fetch-object
262 retrieve objects from a remote
263 --plain-http: allow connections using plain HTTP
266 --refresh="": refresh token for authorization server
269 --skip-verify, -k: skip SSL certificate validation
272 --user, -u="": user[:password] Registry user and password
275 get
278 get the data for an object
279 ingest
282 accept content into the store
283 --expected-digest="": verify content against expected digest
286 --expected-size="": validate against provided size (default: 0)
289 list, ls
292 list all blobs in the store
293 --quiet, -q: print only the blob digest
296 push-object
299 push an object to a remote
300 --plain-http: allow connections using plain HTTP
303 --refresh="": refresh token for authorization server
306 --skip-verify, -k: skip SSL certificate validation
309 --user, -u="": user[:password] Registry user and password
312 label
315 add labels to content
316
319 display containerd events
320
323 manage images
324 check
327 check that an image has all content available locally
328 --snapshotter="": snapshotter name. Empty value stands for the default
331 value.
332 export
335 export images
336 --all-platforms: exports content from all platforms
339 --platform="": Pull content from a specific platform
342 --skip-manifest-json: do not add Docker compatible manifest.json to ar‐
345 chive
346 import
349 import images
350 --all-platforms: imports content for all platforms, false by default
353 --base-name="": base image name for added images, when provided only
356 images with this name prefix are imported
357 --compress-blobs: compress uncompressed blobs when creating manifest
360 (Docker format only)
361 --digests: whether to create digest images (default: false)
364 --index-name="": image name to keep index as, by default index is dis‐
367 carded
368 --no-unpack: skip unpacking the images, false by default
371 --snapshotter="": snapshotter name. Empty value stands for the default
374 value.
375 list, ls
378 list images known to containerd
379 --quiet, -q: print only the image refs
382 pull
385 pull an image from a remote
386 --all-metadata: Pull metadata for all platforms
389 --all-platforms: pull content and metadata from all platforms
392 --label="": labels to attach to the image
395 --plain-http: allow connections using plain HTTP
398 --platform="": Pull content from a specific platform
401 --refresh="": refresh token for authorization server
404 --skip-verify, -k: skip SSL certificate validation
407 --snapshotter="": snapshotter name. Empty value stands for the default
410 value.
411 --user, -u="": user[:password] Registry user and password
414 push
417 push an image to a remote
418 --manifest="": digest of manifest
421 --manifest-type="": media type of manifest digest (default: applica‐
424 tion/vnd.oci.image.manifest.v1+json)
425 --plain-http: allow connections using plain HTTP
428 --refresh="": refresh token for authorization server
431 --skip-verify, -k: skip SSL certificate validation
434 --user, -u="": user[:password] Registry user and password
437 remove, rm
440 remove one or more images by reference
441 --sync: Synchronously remove image and all associated resources
444 tag
447 tag an image
448 --force: force target_ref to be created, regardless if it already
451 exists
452 label
455 set and clear labels for an image
456 --replace-all, -r: replace all labels
459
462 manage leases
463 list, ls
466 list all active leases
467 --quiet, -q: print only the blob digest
470 create
473 create lease
474 --expires, -x="": expiration of lease (0 value will not expire)
477 (default: 24h0m0s)
478 --id="": set the id for the lease, will be generated by default
481 delete, rm
484 delete a lease
485 --sync: Synchronously remove leases and all unreferenced resources
488
491 manage namespaces
492 create, c
495 create a new namespace
496 list, ls
499 list namespaces
500 --quiet, -q: print only the namespace name
503 remove, rm
506 remove one or more namespaces
507 --cgroup, -c: delete the namespace's cgroup
510 label
513 set and clear labels for a namespace
514
517 provide golang pprof outputs for containerd
518 --debug-socket, -d="": socket path for containerd's debug server
521 (default: /run/containerd/debug.sock)
522 block
525 goroutine blocking profile
526 goroutines
529 dump goroutine stack dump
530 heap
533 dump heap profile
534 profile
537 CPU profile
538 --seconds, -s="": duration for collection (seconds) (default: 30s)
541 threadcreate
544 goroutine thread creating profile
545 trace
548 collect execution trace
549 --seconds, -s="": trace time (seconds) (default: 5s)
552
555 run a container
556 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
559 --cgroup="": cgroup path (To disable use of cgroup, set to "" explic‐
562 itly)
563 --config, -c="": path to the runtime-specific spec config file
566 --cwd="": specify the working directory of the process
569 --detach, -d: detach from the task after it has started execution
572 --device="": add a device to a container
575 --env="": specify additional container environment variables (i.e.
578 FOO=bar)
579 --env-file="": specify additional container environment variables in a
582 file(i.e. FOO=bar, one per line)
583 --fifo-dir="": directory used for storing IO FIFOs
586 --gpus="": add gpus to the container (default: 0)
589 --label="": specify additional labels (i.e. foo=bar)
592 --log-uri="": log uri
595 --memory-limit="": memory limit (in bytes) for the container (default:
598 0)
599 --mount="": specify additional container mount (ex:
602 type=bind,src=/tmp,dst=/host,options=rbind:ro)
603 --net-host: enable host networking for the container
606 --no-pivot: disable use of pivot-root (linux only)
609 --null-io: send all IO to /dev/null
612 --pid-file="": file path to write the task's pid
615 --platform="": run image for specific platform
618 --privileged: run privileged container
621 --read-only: set the containers filesystem as readonly
624 --rm: remove the container after running
627 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
630 ter
631 --runtime="": runtime name (default: io.containerd.runc.v2)
634 --seccomp: enable the default seccomp profile
637 --snapshotter="": snapshotter name. Empty value stands for the default
640 value.
641 --tty, -t: allocate a TTY for the container
644 --with-ns="": specify existing Linux namespaces to join at container
647 runtime (format ':')
648
651 manage snapshots
652 --snapshotter="": snapshotter name. Empty value stands for the default
655 value.
656 commit
659 commit an active snapshot into the provided name
660 diff
663 get the diff of two snapshots. the default second snapshot is the first
664 snapshot's parent.
665 --keep: keep diff content. up to creator to delete it.
668 --label="": labels to attach to the image
671 --media-type="": media type to use for creating diff (default: applica‐
674 tion/vnd.oci.image.layer.v1.tar+gzip)
675 --ref="": content upload reference to use
678 info
681 get info about a snapshot
682 list, ls
685 list snapshots
686 mounts, m, mount
689 mount gets mount commands for the snapshots
690 prepare
693 prepare a snapshot from a committed snapshot
694 --target, -t="": mount target path, will print mount, if provided
697 remove, rm
700 remove snapshots
701 label
704 add labels to content
705 tree
708 display tree view of snapshot branches
709 unpack
712 unpack applies layers from a manifest to a snapshot
713 --snapshotter="": snapshotter name. Empty value stands for the default
716 value.
717 usage
720 usage snapshots
721 -b: display size in bytes
724 view
727 create a read-only snapshot from a committed snapshot
728 --target, -t="": mount target path, will print mount, if provided
731
734 manage tasks
735 attach
738 attach to the IO of a running container
739 checkpoint
742 checkpoint a container
743 --exit: stop the container after the checkpoint
746 --image-path="": path to criu image files
749 --work-path="": path to criu work files and logs
752 delete, rm
755 delete one or more tasks
756 --exec-id="": process ID to kill
759 --force, -f: force delete task process
762 exec
765 execute additional processes in an existing container
766 --cwd="": working directory of the new process
769 --detach, -d: detach from the task after it has started execution
772 --exec-id="": exec specific id for the process
775 --fifo-dir="": directory used for storing IO FIFOs
778 --log-uri="": log uri for custom shim logging
781 --tty, -t: allocate a TTY for the container
784 list, ls
787 list tasks
788 --quiet, -q: print only the task id
791 kill
794 signal a container (default: SIGTERM)
795 --all, -a: send signal to all processes inside the container
798 --exec-id="": process ID to kill
801 --signal, -s="": signal to send to the container
804 pause
807 pause an existing container
808 ps
811 list processes for container
812 resume
815 resume a paused container
816 start
819 start a container that have been created
820 --detach, -d: detach from the task after it has started execution
823 --fifo-dir="": directory used for storing IO FIFOs
826 --log-uri="": log uri
829 --null-io: send all IO to /dev/null
832 --pid-file="": file path to write the task's pid
835 metrics, metric
838 get a single data point of metrics for a task with the built-in Linux
839 runtime
840 --format="": "table" or "json" (default: table)
843
846 install a new package
847 --libs, -l: install libs from the image
850 --path="": set an optional install path other than the managed opt
853 directory
854 --replace, -r: replace any binaries or libs in the opt directory
857
860 interact with a shim directly
861 --id="": container id
864 delete
867 delete a container with a task
868 exec
871 exec a new process in the task's container
872 --attach, -a: stay attached to the container and open the fifos
875 --cwd="": current working directory
878 --env, -e="": add environment vars
881 --spec="": runtime spec
884 --stderr="": specify the path to the stderr fifo
887 --stdin="": specify the path to the stdin fifo
890 --stdout="": specify the path to the stdout fifo
893 --tty, -t: enable tty support
896 start
899 start a container with a task
900 state
903 get the state of all the processes of the task
904 ctr(8)()