path: root/cmd/podman/varlink/io.projectatomic.podman.varlink

# 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
)

# BuildResponse is used to describe the responses for building images
type BuildResponse (
    logs: []string,
    id: 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. It will return a [BuildResponse](#BuildResponse) structure
# that contains the build logs and resulting image ID.
method BuildImage(build: BuildInfo) -> (image: BuildResponse)

# 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 <image>:<tag>).  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)