server

Documentation

Overview

Package server supports a RESTful API for the Libpod library

This documentation describes the Podman v2.x+ RESTful API. It consists of a Docker-compatible API and a Libpod API providing support for Podman’s unique features such as pods.

To start the service and keep it running for 5,000 seconds (-t 0 runs forever):

podman system service -t 5000 &

You can then use cURL on the socket using requests documented below.

NOTE: if you install the package podman-docker, it will create a symbolic link for /run/docker.sock to /run/podman/podman.sock

NOTE: Some fields in the API response JSON are encoded as omitempty, which means that if said field has a zero value, they will not be encoded in the API response. This is a feature to help reduce the size of the JSON responses returned via the API.

NOTE: Due to the limitations of [go-swagger](https://github.com/go-swagger/go-swagger), some field values that have a complex type show up as null in the docs as well as in the API responses. This is because the zero value for the field type is null. The field description in the docs will state what type the field is expected to be for such cases.

See podman-system-service(1) for more information.

Quick Examples:

 'podman info'

    curl --unix-socket /run/podman/podman.sock http://d/v4.0.0/libpod/info

 'podman pull quay.io/containers/podman'

    curl -XPOST --unix-socket /run/podman/podman.sock -v 'http://d/v4.0.0/images/create?fromImage=quay.io%2Fcontainers%2Fpodman'

 'podman list images'

    curl --unix-socket /run/podman/podman.sock -v 'http://d/v4.0.0/libpod/images/json' | jq

Terms Of Service:

https://github.com/containers/podman/blob/913caaa9b1de2b63692c9bae15120208194c9eb3/LICENSE

Schemes: http, https
Host: podman.io
BasePath: /
Version: 4.0.0
License: Apache-2.0 https://opensource.org/licenses/Apache-2.0
Contact: Podman <podman@lists.podman.io> https://podman.io/community/

InfoExtensions:
x-logo:
  - url: https://raw.githubusercontent.com/containers/libpod/main/logo/podman-logo.png
  - altText: "Podman logo"

Produces:
- application/json
- application/octet-stream
- text/plain

Consumes:
- application/json
- application/x-tar

swagger:meta

Index

• Constants
• func ListenUnix(network string, path string) (net.Listener, error)
• func VersionedPath(p string) string
• type APIServer
  • func NewServer(runtime *libpod.Runtime) (*APIServer, error)
  • func NewServerWithSettings(runtime *libpod.Runtime, listener net.Listener, opts entities.ServiceOptions) (*APIServer, error)
  • func (s *APIServer) APIHandler(h http.HandlerFunc) http.HandlerFunc
  • func (s *APIServer) Close() error
  • func (s *APIServer) Serve() error
  • func (s *APIServer) Shutdown(halt bool) error
  • func (s *APIServer) StreamBufferedAPIHandler(h http.HandlerFunc) http.HandlerFunc
• type BufferedResponseWriter
  • func (w *BufferedResponseWriter) Flush()
  • func (w *BufferedResponseWriter) Header() http.Header
  • func (w *BufferedResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)
  • func (w *BufferedResponseWriter) Write(b []byte) (int, error)
  • func (w *BufferedResponseWriter) WriteHeader(statusCode int)

Constants

const (
	DefaultCorsHeaders       = ""
	DefaultServiceDuration   = 300 * time.Second
	UnlimitedServiceDuration = 0 * time.Second
)

Number of seconds to wait for next request, if exceeded shutdown server

Functions

func ListenUnix

func ListenUnix(network string, path string) (net.Listener, error)

ListenUnix follows stdlib net.Listen() API, providing a unix listener for given path

ListenUnix will delete and create files/directories as needed

func VersionedPath

func VersionedPath(p string) string

VersionedPath prepends the version parsing code any handler may override this default when registering URL(s)

Types

type APIServer

type APIServer struct {
	http.Server               // The  HTTP work happens here
	net.Listener              // mux for routing HTTP API calls to libpod routines
	*libpod.Runtime           // Where the real work happens
	*schema.Decoder           // Decoder for Query parameters to structs
	context.CancelFunc        // Stop APIServer
	context.Context           // Context to carry objects to handlers
	CorsHeaders        string // Inject Cross-Origin Resource Sharing (CORS) headers
	PProfAddr          string // Binding network address for pprof profiles
	// contains filtered or unexported fields
}

func NewServer

func NewServer(runtime *libpod.Runtime) (*APIServer, error)

NewServer will create and configure a new API server with all defaults

func NewServerWithSettings

func NewServerWithSettings(runtime *libpod.Runtime, listener net.Listener, opts entities.ServiceOptions) (*APIServer, error)

NewServerWithSettings will create and configure a new API server using provided settings

func (*APIServer) APIHandler

func (s *APIServer) APIHandler(h http.HandlerFunc) http.HandlerFunc

APIHandler is a wrapper to enhance HandlerFunc's and remove redundant code

func (*APIServer) Close

func (s *APIServer) Close() error

Close immediately stops responding to clients and exits

func (*APIServer) Serve

func (s *APIServer) Serve() error

Serve starts responding to HTTP requests.

func (*APIServer) Shutdown

func (s *APIServer) Shutdown(halt bool) error

Shutdown is a clean shutdown waiting on existing clients

func (*APIServer) StreamBufferedAPIHandler

func (s *APIServer) StreamBufferedAPIHandler(h http.HandlerFunc) http.HandlerFunc

An API Handler to help historical clients with broken parsing that expect streaming JSON payloads to be reliably messaged framed (full JSON record always fits in each read())

type BufferedResponseWriter

type BufferedResponseWriter struct {
	// contains filtered or unexported fields
}

func (*BufferedResponseWriter) Flush

func (w *BufferedResponseWriter) Flush()

func (*BufferedResponseWriter) Header

func (w *BufferedResponseWriter) Header() http.Header

func (*BufferedResponseWriter) Hijack

func (w *BufferedResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)

func (*BufferedResponseWriter) Write

func (w *BufferedResponseWriter) Write(b []byte) (int, error)

func (*BufferedResponseWriter) WriteHeader

func (w *BufferedResponseWriter) WriteHeader(statusCode int)