# Podman Service Interface and API description. The master version of this document can be found # in the [API.md](https://github.com/projectatomic/libpod/blob/master/API.md) file in the upstream libpod repository. interface io.projectatomic.podman # Version is the structure returned by GetVersion type Version ( version: string, go_version: string, git_commit: string, built: int, os_arch: string ) type NotImplemented ( comment: string ) type StringResponse ( message: string ) # ContainerChanges describes the return struct for ListContainerChanges type ContainerChanges ( changed: []string, added: []string, deleted: []string ) # ImageInList describes the structure that is returned in # ListImages. type ImageInList ( id: string, parentId: string, repoTags: []string, repoDigests: []string, created: string, size: int, virtualSize: int, containers: int, labels: [string]string ) # ImageHistory describes the returned structure from ImageHistory. type ImageHistory ( id: string, created: string, createdBy: string, tags: []string, size: int, comment: string ) # ImageSearch is the returned structure for SearchImage. It is returned # in array form. type ImageSearch ( description: string, is_official: bool, is_automated: bool, name: string, star_count: int ) # ListContainer is the returned struct for an individual container type ListContainerData ( id: string, image: string, imageid: string, command: []string, createdat: string, runningfor: string, status: string, ports: []ContainerPortMappings, rootfssize: int, rwsize: int, names: string, labels: [string]string, mounts: []ContainerMount, containerrunning: bool, namespaces: ContainerNameSpace ) # ContainerStats is the return struct for the stats of a container type ContainerStats ( id: string, name: string, cpu: float, cpu_nano: int, system_nano: int, mem_usage: int, mem_limit: int, mem_perc: float, net_input: int, net_output: int, block_output: int, block_input: int, pids: int ) # ContainerMount describes the struct for mounts in a container type ContainerMount ( destination: string, type: string, source: string, options: []string ) # ContainerPortMappings describes the struct for portmappings in an existing container type ContainerPortMappings ( host_port: string, host_ip: string, protocol: string, container_port: string ) # ContainerNamespace describes the namespace structure for an existing container type ContainerNameSpace ( user: string, uts: string, pidns: string, pid: string, cgroup: string, net: string, mnt: string, ipc: string ) # InfoHost describes the host stats portion of PodmanInfo type InfoHost ( mem_free: int, mem_total: int, swap_free: int, swap_total: int, arch: string, cpus: int, hostname: string, kernel: string, os: string, uptime: string ) # InfoGraphStatus describes the detailed status of the storage driver type InfoGraphStatus ( backing_filesystem: string, native_overlay_diff: string, supports_d_type: string ) # InfoStore describes the host's storage informatoin type InfoStore ( containers: int, images: int, graph_driver_name: string, graph_driver_options: string, graph_root: string, graph_status: InfoGraphStatus, run_root: string ) # InfoPodman provides details on the podman binary type InfoPodmanBinary ( compiler: string, go_version: string, podman_version: string, git_commit: string ) # PodmanInfo describes the Podman host and build type PodmanInfo ( host: InfoHost, registries: []string, insecure_registries: []string, store: InfoStore, podman: InfoPodmanBinary ) # Sockets describes sockets location for a container type Sockets( container_id: string, io_socket: string, control_socket: string ) # Create is an input structure for creating containers. It closely resembles the # CreateConfig structure in libpod/pkg/spec. type Create ( args: []string, cap_add: []string, cap_drop: []string, conmon_pidfile: string, cgroup_parent: string, command: []string, detach: bool, devices: []string, dns_opt: []string, dns_search: []string, dns_servers: []string, entrypoint: []string, env: [string]string, exposed_ports: []string, gidmap: []string, group_add: []string, host_add: []string, hostname: string, image: string, image_id: string, builtin_imgvolumes: []string, id_mappings: IDMappingOptions, image_volume_type: string, interactive: bool, ipc_mode: string, labels: [string]string, log_driver: string, log_driver_opt: []string, name: string, net_mode: string, network: string, pid_mode: string, pod: string, privileged: bool, publish: []string, publish_all: bool, quiet: bool, readonly_rootfs: bool, resources: CreateResourceConfig, rm: bool, shm_dir: string, stop_signal: int, stop_timeout: int, subuidmap: string, subgidmap: string, subuidname: string, subgidname: string, sys_ctl: [string]string, tmpfs: []string, tty: bool, uidmap: []string, userns_mode: string, user: string, uts_mode: string, volumes: []string, work_dir: string, mount_label: string, process_label: string, no_new_privs: bool, apparmor_profile: string, seccomp_profile_path: string, security_opts: []string ) # CreateResourceConfig is an input structure used to describe host attributes during # container creation. It is only valid inside a [Create](#Create) type. type CreateResourceConfig ( blkio_weight: int, blkio_weight_device: []string, cpu_period: int, cpu_quota: int, cpu_rt_period: int, cpu_rt_runtime: int, cpu_shares: int, cpus: float, cpuset_cpus: string, cpuset_mems: string, device_read_bps: []string, device_read_iops: []string, device_write_bps: []string, device_write_iops: []string, disable_oomkiller: bool, kernel_memory: int, memory: int, memory_reservation: int, memory_swap: int, memory_swappiness: int, oom_score_adj: int, pids_limit: int, shm_size: int, ulimit: []string ) # IDMappingOptions is an input structure used to described ids during container creation. type IDMappingOptions ( host_uid_mapping: bool, host_gid_mapping: bool, uid_map: IDMap, gid_map: IDMap ) # IDMap is used to describe user name spaces during container creation type IDMap ( container_id: int, host_id: int, size: int ) # BuildInfo is used to describe user input for building images type BuildInfo ( # paths to one or more dockerfiles dockerfile: []string, tags: []string, add_hosts: []string, cgroup_parent: string, cpu_period: int, cpu_quota: int, cpu_shares: int, cpuset_cpus: string, cpuset_mems: string, memory: string, memory_swap: string, security_opts: []string, shm_size: string, ulimit: []string, volume: []string, squash: bool, pull: bool, pull_always: bool, force_rm: bool, rm: bool, label: []string, annotations: []string, build_args: [string]string, image_format: string ) # Ping provides a response for developers to ensure their varlink setup is working. # #### Example # ~~~ # $ varlink call -m unix:/run/podman/io.projectatomic.podman/io.projectatomic.podman.Ping # { # "ping": { # "message": "OK" # } # } # ~~~ method Ping() -> (ping: StringResponse) # GetVersion returns a Version structure describing the libpod setup on their # system. method GetVersion() -> (version: Version) # GetInfo returns a [PodmanInfo](#PodmanInfo) struct that describes podman and its host such as storage stats, # build information of Podman, and system-wide registries. method GetInfo() -> (info: PodmanInfo) # ListContainers returns a list of containers in no particular order. There are # returned as an array of ListContainerData structs. See also [GetContainer](#GetContainer). method ListContainers() -> (containers: []ListContainerData) # GetContainer takes a name or ID of a container and returns single ListContainerData # structure. A [ContainerNotFound](#ContainerNotFound) error will be returned if the container cannot be found. # See also [ListContainers](ListContainers) and [InspectContainer](#InspectContainer). method GetContainer(name: string) -> (container: ListContainerData) # CreateContainer creates a new container from an image. It uses a [Create](#Create) type for input. The minimum # input required for CreateContainer is an image name. If the image name is not found, an [ImageNotFound](#ImageNotFound) # error will be returned. Otherwise, the ID of the newly created container will be returned. # #### Example # ~~~ # $ varlink call unix:/run/podman/io.projectatomic.podman/io.projectatomic.podman.CreateContainer '{"create": {"image": "alpine"}}' # { # "container": "8759dafbc0a4dc3bcfb57eeb72e4331eb73c5cc09ab968e65ce45b9ad5c4b6bb" # } # ~~~ method CreateContainer(create: Create) -> (container: string) # InspectContainer data takes a name or ID of a container returns the inspection # data in string format. You can then serialize the string into JSON. A [ContainerNotFound](#ContainerNotFound) # error will be returned if the container cannot be found. See also [InspectImage](#InspectImage). method InspectContainer(name: string) -> (container: string) # ListContainerProcesses takes a name or ID of a container and returns the processes # running inside the container as array of strings. It will accept an array of string # arguments that represent ps options. If the container cannot be found, a [ContainerNotFound](#ContainerNotFound) # error will be returned. # #### Example # ~~~ # $ varlink call -m unix:/run/podman/io.projectatomic.podman/io.projectatomic.podman.ListContainerProcesses '{"name": "135d71b9495f", "opts": []}' # { # "container": [ # " UID PID PPID C STIME TTY TIME CMD", # " 0 21220 21210 0 09:05 pts/0 00:00:00 /bin/sh", # " 0 21232 21220 0 09:05 pts/0 00:00:00 top", # " 0 21284 21220 0 09:05 pts/0 00:00:00 vi /etc/hosts" # ] # } # ~~~ method ListContainerProcesses(name: string, opts: []string) -> (container: []string) # GetContainerLogs takes a name or ID of a container and returns the logs of that container. # If the container cannot be found, a [ContainerNotFound](#ContainerNotFound) error will be returned. # The container logs are returned as an array of strings. GetContainerLogs will honor the streaming # capability of varlink if the client invokes it. method GetContainerLogs(name: string) -> (container: []string) # ListContainerChanges takes a name or ID of a container and returns changes between the container and # its base image. It returns a struct of changed, deleted, and added path names. If the # container cannot be found, a [ContainerNotFound](#ContainerNotFound) error will be returned. method ListContainerChanges(name: string) -> (container: ContainerChanges) # ExportContainer creates an image from a container. It takes the name or ID of a container and a # path representing the target tarfile. If the container cannot be found, a [ContainerNotFound](#ContainerNotFound) # error will be returned. # The return value is the written tarfile. method ExportContainer(name: string, path: string) -> (tarfile: string) # GetContainerStats takes the name or ID of a container and returns a single ContainerStats structure which # contains attributes like memory and cpu usage. If the container cannot be found, a # [ContainerNotFound](#ContainerNotFound) error will be returned. # #### Example # ~~~ # $ varlink call -m unix:/run/podman/io.projectatomic.podman/io.projectatomic.podman.GetContainerStats '{"name": "c33e4164f384"}' # { # "container": { # "block_input": 0, # "block_output": 0, # "cpu": 2.571123918839990154678e-08, # "cpu_nano": 49037378, # "id": "c33e4164f384aa9d979072a63319d66b74fd7a128be71fa68ede24f33ec6cfee", # "mem_limit": 33080606720, # "mem_perc": 2.166828456524753747370e-03, # "mem_usage": 716800, # "name": "competent_wozniak", # "net_input": 768, # "net_output": 5910, # "pids": 1, # "system_nano": 10000000 # } # } # ~~~ method GetContainerStats(name: string) -> (container: ContainerStats) # This method has not be implemented yet. method ResizeContainerTty() -> (notimplemented: NotImplemented) # StartContainer starts a created or stopped container. It takes the name or ID of container. It returns # the container ID once started. If the container cannot be found, a [ContainerNotFound](#ContainerNotFound) # error will be returned. See also [CreateContainer](#CreateContainer). method StartContainer(name: string) -> (container: string) # StopContainer stops a container given a timeout. It takes the name or ID of a container as well as a # timeout value. The timeout value the time before a forcible stop to the container is applied. It # returns the container ID once stopped. If the container cannot be found, a [ContainerNotFound](#ContainerNotFound) # error will be returned instead. See also [KillContainer](KillContainer). # #### Error # ~~~ # $ varlink call -m unix:/run/podman/io.projectatomic.podman/io.projectatomic.podman.StopContainer '{"name": "135d71b9495f", "timeout": 5}' # { # "container": "135d71b9495f7c3967f536edad57750bfdb569336cd107d8aabab45565ffcfb6" # } # ~~~ method StopContainer(name: string, timeout: int) -> (container: string) # RestartContainer will restart a running container given a container name or ID and timeout value. The timeout # value is the time before a forcible stop is used to stop the container. If the container cannot be found by # name or ID, a [ContainerNotFound](#ContainerNotFound) error will be returned; otherwise, the ID of the # container will be returned. method RestartContainer(name: string, timeout: int) -> (container: string) # KillContainer takes the name or ID of a container as well as a signal to be applied to the container. Once the # container has been killed, the container's ID is returned. If the container cannot be found, a # [ContainerNotFound](#ContainerNotFound) error is returned. See also [StopContainer](StopContainer). method KillContainer(name: string, signal: int) -> (container: string) # This method has not be implemented yet. method UpdateContainer() -> (notimplemented: NotImplemented) # This method has not be implemented yet. method RenameContainer() -> (notimplemented: NotImplemented) # PauseContainer takes the name or ID of container and pauses it. If the container cannot be found, # a [ContainerNotFound](#ContainerNotFound) error will be returned; otherwise the ID of the container is returned. # See also [UnpauseContainer](#UnpauseContainer). method PauseContainer(name: string) -> (container: string) # UnpauseContainer takes the name or ID of container and unpauses a paused container. If the container cannot be # found, a [ContainerNotFound](#ContainerNotFound) error will be returned; otherwise the ID of the container is returned. # See also [PauseContainer](#PauseContainer). method UnpauseContainer(name: string) -> (container: string) # This method has not be implemented yet. method AttachToContainer() -> (notimplemented: NotImplemented) # GetAttachSockets takes the name or ID of an existing container. It returns file paths for two sockets needed # to properly communicate with a container. The first is the actual I/O socket that the container uses. The # second is a "control" socket where things like resizing the TTY events are sent. If the container cannot be # found, a [ContainerNotFound](#ContainerNotFound) error will be returned. # #### Example # ~~~ # $ varlink call -m unix:/run/io.projectatomic.podman/io.projectatomic.podman.GetAttachSockets '{"name": "b7624e775431219161"}' # { # "sockets": { # "container_id": "b7624e7754312191613245ce1a46844abee60025818fe3c3f3203435623a1eca", # "control_socket": "/var/lib/containers/storage/overlay-containers/b7624e7754312191613245ce1a46844abee60025818fe3c3f3203435623a1eca/userdata/ctl", # "io_socket": "/var/run/libpod/socket/b7624e7754312191613245ce1a46844abee60025818fe3c3f3203435623a1eca/attach" # } # } # ~~~ method GetAttachSockets(name: string) -> (sockets: Sockets) # WaitContainer takes the name or ID of a container and waits until the container stops. Upon stopping, the return # code of the container is returned. If the container container cannot be found by ID or name, # a [ContainerNotFound](#ContainerNotFound) error is returned. method WaitContainer(name: string) -> (exitcode: int) # RemoveContainer takes requires the name or ID of container as well a boolean representing whether a running # container can be stopped and removed. Upon successful removal of the container, its ID is returned. If the # container cannot be found by name or ID, a [ContainerNotFound](#ContainerNotFound) error will be returned. # #### Example # ~~~ # $ varlink call -m unix:/run/podman/io.projectatomic.podman/io.projectatomic.podman.RemoveContainer '{"name": "62f4fd98cb57"}' # { # "container": "62f4fd98cb57f529831e8f90610e54bba74bd6f02920ffb485e15376ed365c20" # } # ~~~ method RemoveContainer(name: string, force: bool) -> (container: string) # DeleteStoppedContainers will delete all containers that are not running. It will return a list the deleted # container IDs. See also [RemoveContainer](RemoveContainer). method DeleteStoppedContainers() -> (containers: []string) # ListImages returns an array of ImageInList structures which provide basic information about # an image currently in storage. See also [InspectImage](InspectImage). method ListImages() -> (images: []ImageInList) # GetImage returns a single image in an [ImageInList](#ImageInList) struct. You must supply an image name as a string. # If the image cannot be found, an [ImageNotFound](#ImageNotFound) error will be returned. method GetImage(name: string) -> (image: ImageInList) # BuildImage takes a [BuildInfo](#BuildInfo) structure and builds an image. At a minimum, you must provide the # 'dockerfile' and 'tags' options in the BuildInfo structure. Upon a successful build, it will # return the ID of the container. method BuildImage(build: BuildInfo) -> (image: []string) # This function is not implemented yet. method CreateImage() -> (notimplemented: NotImplemented) # InspectImage takes the name or ID of an image and returns a string respresentation of data associated with the #image. You must serialize the string into JSON to use it further. An [ImageNotFound](#ImageNotFound) error will # be returned if the image cannot be found. method InspectImage(name: string) -> (image: string) # HistoryImage takes the name or ID of an image and returns information about its history and layers. The returned # history is in the form of an array of ImageHistory structures. If the image cannot be found, an # [ImageNotFound](#ImageNotFound) error is returned. method HistoryImage(name: string) -> (history: []ImageHistory) # PushImage takes three input arguments: the name or ID of an image, the fully-qualified destination name of the image, # and a boolean as to whether tls-verify should be used. It will return an [ImageNotFound](#ImageNotFound) error if # the image cannot be found in local storage; otherwise the ID of the image will be returned on success. method PushImage(name: string, tag: string, tlsverify: bool) -> (image: string) # TagImage takes the name or ID of an image in local storage as well as the desired tag name. If the image cannot # be found, an [ImageNotFound](#ImageNotFound) error will be returned; otherwise, the ID of the image is returned on success. method TagImage(name: string, tagged: string) -> (image: string) # RemoveImage takes the name or ID of an image as well as a boolean that determines if containers using that image # should be deleted. If the image cannot be found, an [ImageNotFound](#ImageNotFound) error will be returned. The # ID of the removed image is returned when complete. See also [DeleteUnusedImages](DeleteUnusedImages). # #### Example # ~~~ # varlink call -m unix:/run/podman/io.projectatomic.podman/io.projectatomic.podman.RemoveImage '{"name": "registry.fedoraproject.org/fedora", "force": true}' # { # "image": "426866d6fa419873f97e5cbd320eeb22778244c1dfffa01c944db3114f55772e" # } # ~~~ method RemoveImage(name: string, force: bool) -> (image: string) # SearchImage takes the string of an image name and a limit of searches from each registries to be returned. SearchImage # will then use a glob-like match to find the image you are searching for. The images are returned in an array of # ImageSearch structures which contain information about the image as well as its fully-qualified name. method SearchImage(name: string, limit: int) -> (images: []ImageSearch) # DeleteUnusedImages deletes any images not associated with a container. The IDs of the deleted images are returned # in a string array. method DeleteUnusedImages() -> (images: []string) # Commit, creates an image from an existing container. It requires the name or # ID of the container as well as the resulting image name. Optionally, you can define an author and message # to be added to the resulting image. You can also define changes to the resulting image for the following # attributes: _CMD, ENTRYPOINT, ENV, EXPOSE, LABEL, ONBUILD, STOPSIGNAL, USER, VOLUME, and WORKDIR_. To pause the # container while it is being committed, pass a _true_ bool for the pause argument. If the container cannot # be found by the ID or name provided, a (ContainerNotFound)[#ContainerNotFound] error will be returned; otherwise, # the resulting image's ID will be returned as a string. method Commit(name: string, image_name: string, changes: []string, author: string, message: string, pause: bool) -> (image: string) # ImportImage imports an image from a source (like tarball) into local storage. The image can have additional # descriptions added to it using the message and changes options. See also [ExportImage](ExportImage). method ImportImage(source: string, reference: string, message: string, changes: []string) -> (image: string) # ExportImage takes the name or ID of an image and exports it to a destination like a tarball. There is also # a booleon option to force compression. It also takes in a string array of tags to be able to save multiple # tags of the same image to a tarball (each tag should be of the form :). Upon completion, the ID # of the image is returned. If the image cannot be found in local storage, an [ImageNotFound](#ImageNotFound) # error will be returned. See also [ImportImage](ImportImage). method ExportImage(name: string, destination: string, compress: bool, tags: []string) -> (image: string) # PullImage pulls an image from a repository to local storage. After the pull is successful, the ID of the image # is returned. # #### Example # ~~~ # $ varlink call -m unix:/run/podman/io.projectatomic.podman/io.projectatomic.podman.PullImage '{"name": "registry.fedoraproject.org/fedora"}' # { # "id": "426866d6fa419873f97e5cbd320eeb22778244c1dfffa01c944db3114f55772e" # } # ~~~ method PullImage(name: string) -> (id: string) # ImageNotFound means the image could not be found by the provided name or ID in local storage. error ImageNotFound (name: string) # ContainerNotFound means the container could not be found by the provided name or ID in local storage. error ContainerNotFound (name: string) # ErrorOccurred is a generic error for an error that occurs during the execution. The actual error message # is includes as part of the error's text. error ErrorOccurred (reason: string) # RuntimeErrors generally means a runtime could not be found or gotten. error RuntimeError (reason: string)