Class: Docker::API::System

Inherits:
Collection show all
Defined in:
lib/docker/api/collections/system.rb

Overview

The daemon itself, rather than the things it holds.

Examples:

client.system.info["ServerVersion"] #=> "29.7.2"
client.system.ping?                 #=> true

Instance Attribute Summary

Attributes inherited from Collection

#client

Instance Method Summary collapse

Methods inherited from Collection

#exist?, #find, #initialize, #to_s

Constructor Details

This class inherits a constructor from Docker::API::Collection

Instance Method Details

#api_version ⇒ String?

The Engine API version in use for this client, after negotiation.

Returns:

  • (String, nil) 


27
28
29
 
# File 'lib/docker/api/collections/system.rb', line 27

def api_version
  client.connection.api_version
end

#authenticate(username:, password:, serveraddress: nil) ⇒ Hash

Check credentials against a registry.

Parameters:

  • username (String) —

    the account

  • password (String) —

    its password or token

  • serveraddress (String, nil) (defaults to: nil) —

    the registry, or nil for Docker Hub

Returns:

  • (Hash) —

    the daemon's answer

Raises:



88
89
90
91
92
93
94
95
 
# File 'lib/docker/api/collections/system.rb', line 88

def authenticate(username:, password:, serveraddress: nil)
  operations.system_auth(
    body: {
      "username" => username, "password" => password,
      "serveraddress" => serveraddress || Auth::DOCKER_HUB_KEY
    }.compact
  ).json
end

#data_usage(type: nil, verbose: false) ⇒ Hash

Returns disk usage by images, containers, volumes and cache.

Returns:

  • (Hash) —

    disk usage by images, containers, volumes and cache



39
40
41
 
# File 'lib/docker/api/collections/system.rb', line 39

def data_usage(type: nil, verbose: false)
  operations.system_data_usage(type: type, verbose: verbose).json
end

#events(since: nil, until_time: nil, filters: nil) {|event| ... } ⇒ void

This method returns an undefined value.

Stream events from the daemon as they happen.

Examples:

client.system.events(filters: { "type" => ["container"] }) do |event|
  puts "#{event["Action"]} #{event.dig("Actor", "Attributes", "name")}"
end

Parameters:

  • since (String, Integer, nil) (defaults to: nil) —

    where to start in the past

  • until_time (String, Integer, nil) (defaults to: nil) —

    where to stop

  • filters (Hash, nil) (defaults to: nil) —

    which events to report

Yield Parameters:

  • event (Hash) —

    one event

Raises:

  • (ArgumentError) 


71
72
73
74
75
76
77
78
79
 
# File 'lib/docker/api/collections/system.rb', line 71

def events(since: nil, until_time: nil, filters: nil, &block)
  raise ArgumentError, "events needs a block to yield to" unless block

  stream = Stream::JSONLines.new(&block)
  operations.system_events(
    since: since, until_: until_time, filters: filters
  ) { |chunk| stream << chunk }
  nil
end

#info ⇒ Hash

Returns the daemon's full description of itself.

Returns:

  • (Hash) —

    the daemon's full description of itself



15
16
17
 
# File 'lib/docker/api/collections/system.rb', line 15

def info
  operations.system_info.json
end

#ping? ⇒ Boolean

Returns whether the daemon answered.

Returns:

  • (Boolean) —

    whether the daemon answered



32
33
34
35
36
 
# File 'lib/docker/api/collections/system.rb', line 32

def ping?
  client.connection.ping.success?
rescue Error
  false
end

#podman? ⇒ Boolean

Whether the daemon is Podman wearing Docker's API.

Worth knowing, because Podman implements most of this API and diverges in enough places -- notably around networking and rootless behaviour -- that callers sometimes need to branch on it.

Returns:

  • (Boolean) 


50
51
52
 
# File 'lib/docker/api/collections/system.rb', line 50

def podman?
  Array(version["Components"]).any? { |c| c["Name"].to_s.include?("Podman") }
end

#rootless? ⇒ Boolean

Returns whether the daemon runs without root privileges.

Returns:

  • (Boolean) —

    whether the daemon runs without root privileges



55
56
57
 
# File 'lib/docker/api/collections/system.rb', line 55

def rootless?
  info["Rootless"] == true
end

#version ⇒ Hash

Returns versions of the daemon and its components.

Returns:

  • (Hash) —

    versions of the daemon and its components



20
21
22
 
# File 'lib/docker/api/collections/system.rb', line 20

def version
  operations.system_version.json
end