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 --cpu-period="": Limit CPU CFS period (default: 0)
93 --cpu-quota="": Limit CPU CFS quota (default: -1)
96 --cwd="": specify the working directory of the process
99 --device="": add a device to a container
102 --env="": specify additional container environment variables (i.e.
105 FOO=bar)
106 --env-file="": specify additional container environment variables in a
109 file(i.e. FOO=bar, one per line)
110 --gpus="": add gpus to the container (default: 0)
113 --label="": specify additional labels (i.e. foo=bar)
116 --memory-limit="": memory limit (in bytes) for the container (default:
119 0)
120 --mount="": specify additional container mount (ex:
123 type=bind,src=/tmp,dst=/host,options=rbind:ro)
124 --net-host: enable host networking for the container
127 --no-pivot: disable use of pivot-root (linux only)
130 --pid-file="": file path to write the task's pid
133 --privileged: run privileged container
136 --read-only: set the containers filesystem as readonly
139 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
142 ter
143 --runtime="": runtime name (default: io.containerd.runc.v2)
146 --seccomp: enable the default seccomp profile
149 --snapshotter="": snapshotter name. Empty value stands for the default
152 value.
153 --tty, -t: allocate a TTY for the container
156 --with-ns="": specify existing Linux namespaces to join at container
159 runtime (format ':')
160 delete, del, rm
163 delete one or more existing containers
164 --keep-snapshot: do not clean up snapshot with container
167 info
170 get info about a container
171 --spec: only display the spec
174 list, ls
177 list containers
178 --quiet, -q: print only the container id
181 label
184 set and clear labels for a container
185 checkpoint
188 checkpoint a container
189 --image: include the image in the checkpoint
192 --rw: include the rw layer in the checkpoint
195 --task: checkpoint container task
198 restore
201 restore a container from checkpoint
202 --live: restore the runtime and memory data from the checkpoint
205 --rw: restore the rw layer from the checkpoint
208
211 manage content
212 active
215 display active transfers
216 --root="": path to content store root (default: /tmp/content)
219 --timeout, -t="": total timeout for fetch (default: 0s)
222 delete, del, remove, rm
225 permanently delete one or more blobs
226 edit
229 edit a blob and return a new digest
230 --editor="": select editor (vim, emacs, etc.)
233 --validate="": validate the result against a format (json, mediatype,
236 etc.)
237 fetch
240 fetch all content for an image into containerd
241 --all-metadata: Pull metadata for all platforms
244 --all-platforms: pull content from all platforms
247 --hosts-dir="": Custom hosts configuration directory
250 --label="": labels to attach to the image
253 --metadata-only: Pull all metadata including manifests and configs
256 --plain-http: allow connections using plain HTTP
259 --platform="": Pull content from a specific platform
262 --refresh="": refresh token for authorization server
265 --skip-verify, -k: skip SSL certificate validation
268 --tlscacert="": path to TLS root CA
271 --tlscert="": path to TLS client certificate
274 --tlskey="": path to TLS client key
277 --user, -u="": user[:password] Registry user and password
280 fetch-object
283 retrieve objects from a remote
284 --hosts-dir="": Custom hosts configuration directory
287 --plain-http: allow connections using plain HTTP
290 --refresh="": refresh token for authorization server
293 --skip-verify, -k: skip SSL certificate validation
296 --tlscacert="": path to TLS root CA
299 --tlscert="": path to TLS client certificate
302 --tlskey="": path to TLS client key
305 --user, -u="": user[:password] Registry user and password
308 get
311 get the data for an object
312 ingest
315 accept content into the store
316 --expected-digest="": verify content against expected digest
319 --expected-size="": validate against provided size (default: 0)
322 list, ls
325 list all blobs in the store
326 --quiet, -q: print only the blob digest
329 push-object
332 push an object to a remote
333 --hosts-dir="": Custom hosts configuration directory
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 label
360 add labels to content
361
364 display containerd events
365
368 manage images
369 check
372 check that an image has all content available locally
373 --snapshotter="": snapshotter name. Empty value stands for the default
376 value.
377 export
380 export images
381 --all-platforms: exports content from all platforms
384 --platform="": Pull content from a specific platform
387 --skip-manifest-json: do not add Docker compatible manifest.json to ar‐
390 chive
391 import
394 import images
395 --all-platforms: imports content for all platforms, false by default
398 --base-name="": base image name for added images, when provided only
401 images with this name prefix are imported
402 --compress-blobs: compress uncompressed blobs when creating manifest
405 (Docker format only)
406 --digests: whether to create digest images (default: false)
409 --index-name="": image name to keep index as, by default index is dis‐
412 carded
413 --no-unpack: skip unpacking the images, false by default
416 --snapshotter="": snapshotter name. Empty value stands for the default
419 value.
420 list, ls
423 list images known to containerd
424 --quiet, -q: print only the image refs
427 mount
430 mount an image to a target path
431 --hosts-dir="": Custom hosts configuration directory
434 --label="": labels to attach to the image
437 --plain-http: allow connections using plain HTTP
440 --platform="": Mount the image for the specified platform (default:
443 linux/amd64)
444 --refresh="": refresh token for authorization server
447 --rw: Enable write support on the mount
450 --skip-verify, -k: skip SSL certificate validation
453 --snapshotter="": snapshotter name. Empty value stands for the default
456 value.
457 --tlscacert="": path to TLS root CA
460 --tlscert="": path to TLS client certificate
463 --tlskey="": path to TLS client key
466 --user, -u="": user[:password] Registry user and password
469 unmount
472 unmount the image from the target
473 --hosts-dir="": Custom hosts configuration directory
476 --label="": labels to attach to the image
479 --plain-http: allow connections using plain HTTP
482 --refresh="": refresh token for authorization server
485 --rm: remove the snapshot after a successful unmount
488 --skip-verify, -k: skip SSL certificate validation
491 --snapshotter="": snapshotter name. Empty value stands for the default
494 value.
495 --tlscacert="": path to TLS root CA
498 --tlscert="": path to TLS client certificate
501 --tlskey="": path to TLS client key
504 --user, -u="": user[:password] Registry user and password
507 pull
510 pull an image from a remote
511 --all-metadata: Pull metadata for all platforms
514 --all-platforms: pull content and metadata from all platforms
517 --hosts-dir="": Custom hosts configuration directory
520 --label="": labels to attach to the image
523 --plain-http: allow connections using plain HTTP
526 --platform="": Pull content from a specific platform
529 --refresh="": refresh token for authorization server
532 --skip-verify, -k: skip SSL certificate validation
535 --snapshotter="": snapshotter name. Empty value stands for the default
538 value.
539 --tlscacert="": path to TLS root CA
542 --tlscert="": path to TLS client certificate
545 --tlskey="": path to TLS client key
548 --user, -u="": user[:password] Registry user and password
551 push
554 push an image to a remote
555 --hosts-dir="": Custom hosts configuration directory
558 --manifest="": digest of manifest
561 --manifest-type="": media type of manifest digest (default: applica‐
564 tion/vnd.oci.image.manifest.v1+json)
565 --plain-http: allow connections using plain HTTP
568 --platform="": push content from a specific platform
571 --refresh="": refresh token for authorization server
574 --skip-verify, -k: skip SSL certificate validation
577 --tlscacert="": path to TLS root CA
580 --tlscert="": path to TLS client certificate
583 --tlskey="": path to TLS client key
586 --user, -u="": user[:password] Registry user and password
589 remove, rm
592 remove one or more images by reference
593 --sync: Synchronously remove image and all associated resources
596 tag
599 tag an image
600 --force: force target_ref to be created, regardless if it already
603 exists
604 label
607 set and clear labels for an image
608 --replace-all, -r: replace all labels
611
614 manage leases
615 list, ls
618 list all active leases
619 --quiet, -q: print only the blob digest
622 create
625 create lease
626 --expires, -x="": expiration of lease (0 value will not expire)
629 (default: 24h0m0s)
630 --id="": set the id for the lease, will be generated by default
633 delete, rm
636 delete a lease
637 --sync: Synchronously remove leases and all unreferenced resources
640
643 manage namespaces
644 create, c
647 create a new namespace
648 list, ls
651 list namespaces
652 --quiet, -q: print only the namespace name
655 remove, rm
658 remove one or more namespaces
659 --cgroup, -c: delete the namespace's cgroup
662 label
665 set and clear labels for a namespace
666
669 provide golang pprof outputs for containerd
670 --debug-socket, -d="": socket path for containerd's debug server
673 (default: /run/containerd/debug.sock)
674 block
677 goroutine blocking profile
678 goroutines
681 dump goroutine stack dump
682 heap
685 dump heap profile
686 profile
689 CPU profile
690 --seconds, -s="": duration for collection (seconds) (default: 30s)
693 threadcreate
696 goroutine thread creating profile
697 trace
700 collect execution trace
701 --seconds, -s="": trace time (seconds) (default: 5s)
704
707 run a container
708 --allow-new-privs: turn off OCI spec's NoNewPrivileges feature flag
711 --cgroup="": cgroup path (To disable use of cgroup, set to "" explic‐
714 itly)
715 --config, -c="": path to the runtime-specific spec config file
718 --cpu-period="": Limit CPU CFS period (default: 0)
721 --cpu-quota="": Limit CPU CFS quota (default: -1)
724 --cpus="": set the CFS cpu qouta (default: 0.000000)
727 --cwd="": specify the working directory of the process
730 --detach, -d: detach from the task after it has started execution
733 --device="": add a device to a container
736 --env="": specify additional container environment variables (i.e.
739 FOO=bar)
740 --env-file="": specify additional container environment variables in a
743 file(i.e. FOO=bar, one per line)
744 --fifo-dir="": directory used for storing IO FIFOs
747 --gidmap="": run inside a user namespace with the specified GID mapping
750 range; specified with the format container-gid:host-gid:length
751 --gpus="": add gpus to the container (default: 0)
754 --label="": specify additional labels (i.e. foo=bar)
757 --log-uri="": log uri
760 --memory-limit="": memory limit (in bytes) for the container (default:
763 0)
764 --mount="": specify additional container mount (ex:
767 type=bind,src=/tmp,dst=/host,options=rbind:ro)
768 --net-host: enable host networking for the container
771 --no-pivot: disable use of pivot-root (linux only)
774 --null-io: send all IO to /dev/null
777 --pid-file="": file path to write the task's pid
780 --platform="": run image for specific platform
783 --privileged: run privileged container
786 --read-only: set the containers filesystem as readonly
789 --remap-labels: provide the user namespace ID remapping to the snap‐
792 shotter via label options; requires snapshotter support
793 --rm: remove the container after running
796 --rootfs: use custom rootfs that is not managed by containerd snapshot‐
799 ter
800 --runc-binary="": specify runc-compatible binary
803 --runc-systemd-cgroup: start runc with systemd cgroup manager
806 --runtime="": runtime name (default: io.containerd.runc.v2)
809 --seccomp: enable the default seccomp profile
812 --snapshotter="": snapshotter name. Empty value stands for the default
815 value.
816 --tty, -t: allocate a TTY for the container
819 --uidmap="": run inside a user namespace with the specified UID mapping
822 range; specified with the format container-uid:host-uid:length
823 --with-ns="": specify existing Linux namespaces to join at container
826 runtime (format ':')
827
830 manage snapshots
831 --snapshotter="": snapshotter name. Empty value stands for the default
834 value.
835 commit
838 commit an active snapshot into the provided name
839 diff
842 get the diff of two snapshots. the default second snapshot is the first
843 snapshot's parent.
844 --keep: keep diff content. up to creator to delete it.
847 --label="": labels to attach to the image
850 --media-type="": media type to use for creating diff (default: applica‐
853 tion/vnd.oci.image.layer.v1.tar+gzip)
854 --ref="": content upload reference to use
857 info
860 get info about a snapshot
861 list, ls
864 list snapshots
865 mounts, m, mount
868 mount gets mount commands for the snapshots
869 prepare
872 prepare a snapshot from a committed snapshot
873 --target, -t="": mount target path, will print mount, if provided
876 remove, rm
879 remove snapshots
880 label
883 add labels to content
884 tree
887 display tree view of snapshot branches
888 unpack
891 unpack applies layers from a manifest to a snapshot
892 --snapshotter="": snapshotter name. Empty value stands for the default
895 value.
896 usage
899 usage snapshots
900 -b: display size in bytes
903 view
906 create a read-only snapshot from a committed snapshot
907 --target, -t="": mount target path, will print mount, if provided
910
913 manage tasks
914 attach
917 attach to the IO of a running container
918 checkpoint
921 checkpoint a container
922 --exit: stop the container after the checkpoint
925 --image-path="": path to criu image files
928 --work-path="": path to criu work files and logs
931 delete, rm
934 delete one or more tasks
935 --exec-id="": process ID to kill
938 --force, -f: force delete task process
941 exec
944 execute additional processes in an existing container
945 --cwd="": working directory of the new process
948 --detach, -d: detach from the task after it has started execution
951 --exec-id="": exec specific id for the process
954 --fifo-dir="": directory used for storing IO FIFOs
957 --log-uri="": log uri for custom shim logging
960 --tty, -t: allocate a TTY for the container
963 list, ls
966 list tasks
967 --quiet, -q: print only the task id
970 kill
973 signal a container (default: SIGTERM)
974 --all, -a: send signal to all processes inside the container
977 --exec-id="": process ID to kill
980 --signal, -s="": signal to send to the container
983 pause
986 pause an existing container
987 ps
990 list processes for container
991 resume
994 resume a paused container
995 start
998 start a container that has been created
999 --detach, -d: detach from the task after it has started execution
1002 --fifo-dir="": directory used for storing IO FIFOs
1005 --log-uri="": log uri
1008 --null-io: send all IO to /dev/null
1011 --pid-file="": file path to write the task's pid
1014 metrics, metric
1017 get a single data point of metrics for a task with the built-in Linux
1018 runtime
1019 --format="": "table" or "json" (default: table)
1022
1025 install a new package
1026 --libs, -l: install libs from the image
1029 --path="": set an optional install path other than the managed opt
1032 directory
1033 --replace, -r: replace any binaries or libs in the opt directory
1036
1039 OCI tools
1040 spec
1043 see the output of the default OCI spec
1044
1047 interact with a shim directly
1048 --id="": container id
1051 delete
1054 delete a container with a task
1055 exec
1058 exec a new process in the task's container
1059 --attach, -a: stay attached to the container and open the fifos
1062 --cwd="": current working directory
1065 --env, -e="": add environment vars
1068 --spec="": runtime spec
1071 --stderr="": specify the path to the stderr fifo
1074 --stdin="": specify the path to the stdin fifo
1077 --stdout="": specify the path to the stdout fifo
1080 --tty, -t: enable tty support
1083 start
1086 start a container with a task
1087 state
1090 get the state of all the processes of the task
1091 ctr(8)()