Class: Vault::Sys

Inherits:
Request show all
Defined in:
lib/vault/api/sys.rb,
lib/vault/api/sys/auth.rb,
lib/vault/api/sys/init.rb,
lib/vault/api/sys/seal.rb,
lib/vault/api/sys/audit.rb,
lib/vault/api/sys/lease.rb,
lib/vault/api/sys/mount.rb,
lib/vault/api/sys/quota.rb,
lib/vault/api/sys/health.rb,
lib/vault/api/sys/leader.rb,
lib/vault/api/sys/policy.rb,
lib/vault/api/sys/namespace.rb

Instance Attribute Summary

Attributes inherited from Request

#client

Instance Method Summary collapse

Methods inherited from Request

#initialize, #inspect, #to_s

Methods included from EncodePath

encode_path

Constructor Details

This class inherits a constructor from Vault::Request

Instance Method Details

#audit_hash(path, input) ⇒ String

Generates a HMAC verifier for a given input.

Examples:

Vault.sys.audit_hash("file-audit", "my input") #=> "hmac-sha256:30aa7de18a5e90bbc1063db91e7c387b32b9fa895977eb8c177bbc91e7d7c542"

Parameters:

  • path (String) —

    the path of the audit backend

  • input (String) —

    the input to generate a HMAC for

Returns:

  • (String) 


88
89
90
91
92
 
# File 'lib/vault/api/sys/audit.rb', line 88

def audit_hash(path, input)
  json = client.post("/v1/sys/audit-hash/#{encode_path(path)}", JSON.fast_generate(input: input))
  json = json[:data] if json[:data]
  json[:hash]
end

#audits ⇒ Hash<Symbol, Audit>

List all audits for the vault.

Examples:

Vault.sys.audits #=> { :file => #<Audit> }

Returns:



31
32
33
34
35
36
37
 
# File 'lib/vault/api/sys/audit.rb', line 31

def audits
  json = client.get("/v1/sys/audit")
  json = json[:data] if json[:data]
  return Hash[*json.map do |k,v|
    [k.to_s.chomp("/").to_sym, Audit.decode(v)]
  end.flatten]
end

#auth_tune(path) ⇒ AuthConfig

Read the given auth path’s configuration.

Examples:

Vault.sys.auth_tune("github") #=> #<Vault::AuthConfig "default_lease_ttl"=3600, "max_lease_ttl"=7200>

Parameters:

  • path (String) —

    the path to retrieve configuration for

Returns:

  • (AuthConfig) —

    configuration of the given auth path



92
93
94
95
96
97
98
 
# File 'lib/vault/api/sys/auth.rb', line 92

def auth_tune(path)
  json = client.get("/v1/sys/auth/#{encode_path(path)}/tune")
  return AuthConfig.decode(json)
rescue HTTPError => e
  return nil if e.code == 404
  raise
end

#auths ⇒ Hash<Symbol, Auth>

List all auths in Vault.

Examples:

Vault.sys.auths #=> {:token => #<Vault::Auth type="token", description="token based credentials">}

Returns:

  • (Hash<Symbol, Auth>) 


38
39
40
41
42
43
44
 
# File 'lib/vault/api/sys/auth.rb', line 38

def auths
  json = client.get("/v1/sys/auth")
  json = json[:data] if json[:data]
  return Hash[*json.map do |k,v|
    [k.to_s.chomp("/").to_sym, Auth.decode(v)]
  end.flatten]
end

#create_namespace(namespace) ⇒ true

Create a namespace. Nests the namespace if a namespace header is provided.

Examples:

Vault.sys.create_namespace("foo")

Parameters:

  • namespace (String) —

    the potential path of the namespace, without any parent path provided

Returns:

  • (true) 


49
50
51
52
 
# File 'lib/vault/api/sys/namespace.rb', line 49

def create_namespace(namespace)
  client.put("/v1/sys/namespaces/#{namespace}", {})
  return true
end

#create_quota(type, name, opts = {}) ⇒ Object 



61
62
63
64
65
 
# File 'lib/vault/api/sys/quota.rb', line 61

def create_quota(type, name, opts={})
  path = generate_path(type, name)
  client.post(path, JSON.fast_generate(opts))
  return true
end

#delete_namespace(namespace) ⇒ true

Delete a namespace. Raises an error if the namespace provided is not empty.

Examples:

Vault.sys.delete_namespace("foo")

Parameters:

  • namespace (String) —

    the path of the namespace to be deleted

Returns:

  • (true) 


63
64
65
66
 
# File 'lib/vault/api/sys/namespace.rb', line 63

def delete_namespace(namespace)
  client.delete("/v1/sys/namespaces/#{namespace}")
  return true
end

#delete_policy(name) ⇒ Object

Delete the policy with the given name. If a policy does not exist, vault will not return an error.

Examples:

Vault.sys.delete_policy("dev") #=> true

Parameters:

  • name (String) —

    the name of the policy



90
91
92
93
 
# File 'lib/vault/api/sys/policy.rb', line 90

def delete_policy(name)
  client.delete("/v1/sys/policy/#{encode_path(name)}")
  return true
end

#delete_quota(type, name) ⇒ Object 



67
68
69
70
71
 
# File 'lib/vault/api/sys/quota.rb', line 67

def delete_quota(type, name)
  path = generate_path(type, name)
  client.delete(path)
  return true
end

#disable_audit(path) ⇒ true

Disable a particular audit. If an audit does not exist, and error will be raised.

Parameters:

  • path (String) —

    the path of the audit to disable

Returns:

  • (true) 


72
73
74
75
 
# File 'lib/vault/api/sys/audit.rb', line 72

def disable_audit(path)
  client.delete("/v1/sys/audit/#{encode_path(path)}")
  return true
end

#disable_auth(path) ⇒ true

Disable a particular authentication at the given path. If not auth exists at that path, an error will be raised.

Examples:

Vault.sys.disable_auth("github") #=> true

Parameters:

  • path (String) —

    the path to disable

Returns:

  • (true) 


77
78
79
80
 
# File 'lib/vault/api/sys/auth.rb', line 77

def disable_auth(path)
  client.delete("/v1/sys/auth/#{encode_path(path)}")
  return true
end

#enable_audit(path, type, description, options = {}) ⇒ true

Enable a particular audit. Note: the options depend heavily on the type of audit being enabled. Please refer to audit-specific documentation for which need to be enabled.

Examples:

Vault.sys.enable_audit("/file-audit", "file", "File audit", path: "/path/on/disk") #=> true

Parameters:

  • path (String) —

    the path to mount the audit

  • type (String) —

    the type of audit to enable

  • description (String) —

    a human-friendly description of the audit backend

  • options (Hash) (defaults to: {}) —

    audit-specific options

Returns:

  • (true) 


56
57
58
59
60
61
62
63
 
# File 'lib/vault/api/sys/audit.rb', line 56

def enable_audit(path, type, description, options = {})
  client.put("/v1/sys/audit/#{encode_path(path)}", JSON.fast_generate(
    type:        type,
    description: description,
    options:     options,
  ))
  return true
end

#enable_auth(path, type, description = nil) ⇒ true

Enable a particular authentication at the given path.

Examples:

Vault.sys.enable_auth("github", "github") #=> true

Parameters:

  • path (String) —

    the path to mount the auth

  • type (String) —

    the type of authentication

  • description (String) (defaults to: nil) —

    a human-friendly description (optional)

Returns:

  • (true) 


59
60
61
62
63
64
65
 
# File 'lib/vault/api/sys/auth.rb', line 59

def enable_auth(path, type, description = nil)
  payload = { type: type }
  payload[:description] = description if !description.nil?

  client.post("/v1/sys/auth/#{encode_path(path)}", JSON.fast_generate(payload))
  return true
end

#get_mount_tune(path) ⇒ MountTune

Get the mount tunings at a given path.

Examples:

Vault.sys.get_mount_tune("pki") #=> { :pki => #<struct Vault::MountTune default_lease_ttl=2764800> }

Returns:



111
112
113
114
115
 
# File 'lib/vault/api/sys/mount.rb', line 111

def get_mount_tune(path)
  json = client.get("/v1/sys/mounts/#{encode_path(path)}/tune")
  json = json[:data] if json[:data]
  return MountTune.decode(json)
end

#get_namespace(namespace) ⇒ Namespace

Retrieve a namespace by path.

Examples:

Vault.sys.get_namespace("foo")

Parameters:

  • namespace (String) —

    the path of the namespace ot be retrieved

Returns:



77
78
79
80
81
82
83
84
 
# File 'lib/vault/api/sys/namespace.rb', line 77

def get_namespace(namespace)
  json = client.get("/v1/sys/namespaces/#{namespace}")
  if data = json.dig(:data)
    Namespace.decode(data)
  else
    json
  end
end

#get_quota(type, name) ⇒ Object 



73
74
75
76
77
78
79
 
# File 'lib/vault/api/sys/quota.rb', line 73

def get_quota(type, name)
  path = generate_path(type, name)
  response = client.get(path)
  if data = response[:data]
    type_class(type).decode(data)
  end
end

#get_quota_config ⇒ Object 



81
82
83
 
# File 'lib/vault/api/sys/quota.rb', line 81

def get_quota_config
  client.get("v1/sys/quotas/config")
end

#health_status ⇒ HealthStatus

Show the health status for this vault.

Examples:

Vault.sys.health_status #=> #Vault::HealthStatus @initialized=true, @sealed=false, @standby=false, @replication_performance_mode="disabled", @replication_dr_mode="disabled", @server_time_utc=1519776728, @version="0.9.3", @cluster_name="vault-cluster-997f514e", @cluster_id="c2dad70a-6d88-a06d-69f6-9ae7f5485998">

Returns:



61
62
63
64
 
# File 'lib/vault/api/sys/health.rb', line 61

def health_status
  json = client.get("/v1/sys/health", {:sealedcode => 200, :uninitcode => 200, :standbycode => 200})
  return HealthStatus.decode(json)
end

#init(options = {}) ⇒ InitResponse

Initialize a new vault.

Examples:

Vault.sys.init #=> #<Vault::InitResponse keys=["..."] root_token="...">

Parameters:

  • options (Hash) (defaults to: {}) —

    the list of init options

Options Hash (options):

  • :root_token_pgp_key (String) —

    optional base64-encoded PGP public key used to encrypt the initial root token.

  • :secret_shares (Fixnum) —

    the number of shares

  • :secret_threshold (Fixnum) —

    the number of keys needed to unlock

  • :pgp_keys (Array<String>) —

    an optional Array of base64-encoded PGP public keys to encrypt sharees

  • :stored_shares (Fixnum) —

    the number of shares that should be encrypted by the HSM for auto-unsealing

  • :recovery_shares (Fixnum) —

    the number of shares to split the recovery key into

  • :recovery_threshold (Fixnum) —

    the number of shares required to reconstruct the recovery key

  • :recovery_pgp_keys (Array<String>) —

    an array of PGP public keys used to encrypt the output for the recovery keys

Returns:



72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/vault/api/sys/init.rb', line 72

def init(options = {})
  json = client.put("/v1/sys/init", JSON.fast_generate(
    root_token_pgp_key: options.fetch(:root_token_pgp_key, nil),
    secret_shares:      options.fetch(:secret_shares, options.fetch(:shares, 5)),
    secret_threshold:   options.fetch(:secret_threshold, options.fetch(:threshold, 3)),
    pgp_keys:           options.fetch(:pgp_keys, nil),
    stored_shares:      options.fetch(:stored_shares, nil),
    recovery_shares:    options.fetch(:recovery_shares, nil),
    recovery_threshold: options.fetch(:recovery_threshold, nil),
    recovery_pgp_keys:  options.fetch(:recovery_pgp_keys, nil),
  ))
  return InitResponse.decode(json)
end

#init_status ⇒ InitStatus

Show the initialization status for this vault.

Examples:

Vault.sys.init_status #=> #<Vault::InitStatus initialized=true>

Returns:



38
39
40
41
 
# File 'lib/vault/api/sys/init.rb', line 38

def init_status
  json = client.get("/v1/sys/init")
  return InitStatus.decode(json)
end

#leader ⇒ LeaderStatus

Determine the leader status for this vault.

Examples:

Vault.sys.leader #=> #<Vault::LeaderStatus ha_enabled=false, is_self=false, leader_address="">

Returns:



41
42
43
44
 
# File 'lib/vault/api/sys/leader.rb', line 41

def leader
  json = client.get("/v1/sys/leader")
  return LeaderStatus.decode(json)
end

#mount(path, type, description = nil, options = {}) ⇒ Object

Create a mount at the given path.

Examples:

Vault.sys.mount("pg", "postgresql", "Postgres user management") #=> true

Parameters:

  • path (String) —

    the path to mount at

  • type (String) —

    the type of mount

  • description (String) (defaults to: nil) —

    a human-friendly description (optional)



97
98
99
100
101
102
103
 
# File 'lib/vault/api/sys/mount.rb', line 97

def mount(path, type, description = nil, options = {})
  payload = options.merge type: type
  payload[:description] = description if !description.nil?

  client.post("/v1/sys/mounts/#{encode_path(path)}", JSON.fast_generate(payload))
  return true
end

#mount_tune(path, data = {}) ⇒ Object

Tune a mount at the given path.

Examples:

Vault.sys.mount_tune("pki", max_lease_ttl: '87600h') #=> true

Parameters:

  • path (String) —

    the path to write

  • data (Hash) (defaults to: {}) —

    the data to write



126
127
128
129
 
# File 'lib/vault/api/sys/mount.rb', line 126

def mount_tune(path, data = {})
  json = client.post("/v1/sys/mounts/#{encode_path(path)}/tune", JSON.fast_generate(data))
  return true
end

#mounts ⇒ Hash<Symbol, Mount>

List all mounts in the vault.

Examples:

Vault.sys.mounts #=> { :secret => #<struct Vault::Mount type="generic", description="generic secret storage"> }

Returns:



78
79
80
81
82
83
84
 
# File 'lib/vault/api/sys/mount.rb', line 78

def mounts
  json = client.get("/v1/sys/mounts")
  json = json[:data] if json[:data]
  return Hash[*json.map do |k,v|
    [k.to_s.chomp("/").to_sym, Mount.decode(v)]
  end.flatten]
end

#namespaces(scoped = nil) ⇒ Object

List all namespaces in a given scope. Ignores nested namespaces.

Examples:

Vault.sys.namespaces #=> { :foo => #<struct Vault::Namespace id="xxxx1", path="foo/" }

@return [Hash<Symbol, Namespace>]


24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/vault/api/sys/namespace.rb', line 24

def namespaces(scoped=nil)
  path = ["v1", scoped, "sys", "namespaces"].compact
  json = client.list(path.join("/"))
  json = json[:data] if json[:data]
  if json[:key_info]
    json = json[:key_info]
    hash = {}
    json.each do |k,v|
      hash[k.to_s.chomp("/").to_sym] = Namespace.decode(v)
    end
    hash
  else
    json
  end
end

#policies ⇒ Array<String>

The list of policies in vault.

Examples:

Vault.sys.policies #=> ["root"]

Returns:

  • (Array<String>) 


34
35
36
 
# File 'lib/vault/api/sys/policy.rb', line 34

def policies
  client.get("/v1/sys/policy")[:policies]
end

#policy(name) ⇒ Policy?

Get the policy by the given name. If a policy does not exist by that name, nil is returned.

Examples:

Vault.sys.policy("root") #=> #<Vault::Policy rules="">

Returns:



45
46
47
48
49
50
51
 
# File 'lib/vault/api/sys/policy.rb', line 45

def policy(name)
  json = client.get("/v1/sys/policy/#{encode_path(name)}")
  return Policy.decode(json)
rescue HTTPError => e
  return nil if e.code == 404
  raise
end

#put_auth_tune(path, config = {}) ⇒ AuthConfig

Write the given auth path’s configuration.

Examples:

Vault.sys.auth_tune("github", "default_lease_ttl" => 600, "max_lease_ttl" => 1200 ) #=>  true

Parameters:

  • path (String) —

    the path to retrieve configuration for

Returns:

  • (AuthConfig) —

    configuration of the given auth path



110
111
112
113
114
115
116
117
 
# File 'lib/vault/api/sys/auth.rb', line 110

def put_auth_tune(path, config = {})
  json = client.put("/v1/sys/auth/#{encode_path(path)}/tune", JSON.fast_generate(config))
  if json.nil?
    return true
  else
    return Secret.decode(json)
  end
end

#put_policy(name, rules) ⇒ true

Create a new policy with the given name and rules.

It is recommend that you load policy rules from a file:

Examples:

policy = <<-EOH
  path "sys" {
    policy = "deny"
  }
EOH
Vault.sys.put_policy("dev", policy) #=> true
policy = File.read("/path/to/my/policy.hcl")
Vault.sys.put_policy("dev", policy)

Parameters:

  • name (String) —

    the name of the policy

  • rules (String) —

    the policy rules

Returns:

  • (true) 


75
76
77
78
79
80
 
# File 'lib/vault/api/sys/policy.rb', line 75

def put_policy(name, rules)
  client.put("/v1/sys/policy/#{encode_path(name)}", JSON.fast_generate(
    rules: rules,
  ))
  return true
end

#quotas(type) ⇒ Object 



49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/vault/api/sys/quota.rb', line 49

def quotas(type)
  path = generate_path(type)
  json = client.list(path)
  if data = json.dig(:data, :key_info)
    data.map do |item|
      type_class(type).decode(item)
    end
  else
    json
  end
end

#remount(from, to) ⇒ true

Change the name of the mount

Examples:

Vault.sys.remount("pg", "postgres") #=> true

Parameters:

  • from (String) —

    the origin mount path

  • to (String) —

    the new mount path

Returns:

  • (true) 


157
158
159
160
161
162
163
 
# File 'lib/vault/api/sys/mount.rb', line 157

def remount(from, to)
  client.post("/v1/sys/remount", JSON.fast_generate(
    from: from,
    to:   to,
  ))
  return true
end

#renew(id, increment = 0) ⇒ Secret

Renew a lease with the given ID.

Examples:

Vault.sys.renew("aws/username") #=> #<Vault::Secret ...>

Parameters:

  • id (String) —

    the lease ID

  • increment (Fixnum) (defaults to: 0)

Returns:



16
17
18
19
20
21
 
# File 'lib/vault/api/sys/lease.rb', line 16

def renew(id, increment = 0)
  json = client.put("/v1/sys/renew/#{id}", JSON.fast_generate(
    increment: increment,
  ))
  return Secret.decode(json)
end

#revoke(id) ⇒ true

Revoke the secret at the given id. If the secret does not exist, an error will be raised.

Examples:

Vault.sys.revoke("aws/username") #=> true

Parameters:

  • id (String) —

    the lease ID

Returns:

  • (true) 


33
34
35
36
 
# File 'lib/vault/api/sys/lease.rb', line 33

def revoke(id)
  client.put("/v1/sys/revoke/#{id}", nil)
  return true
end

#revoke_prefix(id) ⇒ true

Revoke all secrets under the given prefix.

Examples:

Vault.sys.revoke_prefix("aws") #=> true

Parameters:

  • id (String) —

    the lease ID

Returns:

  • (true) 


47
48
49
50
 
# File 'lib/vault/api/sys/lease.rb', line 47

def revoke_prefix(id)
  client.put("/v1/sys/revoke-prefix/#{id}", nil)
  return true
end

#seal ⇒ true

Seal the vault. Warning: this will seal the vault!

Examples:

Vault.sys.seal #=> true

Returns:

  • (true) 


63
64
65
66
 
# File 'lib/vault/api/sys/seal.rb', line 63

def seal
  client.put("/v1/sys/seal", nil)
  return true
end

#seal_status ⇒ SealStatus

Get the current seal status.

Examples:

Vault.sys.seal_status #=> #<Vault::SealStatus sealed=false, t=1, n=1, progress=0>

Returns:



52
53
54
55
 
# File 'lib/vault/api/sys/seal.rb', line 52

def seal_status
  json = client.get("/v1/sys/seal-status")
  return SealStatus.decode(json)
end

#step_down ⇒ Object 



46
47
48
49
 
# File 'lib/vault/api/sys/leader.rb', line 46

def step_down
  client.put("/v1/sys/step-down", nil)
  return true
end

#unmount(path) ⇒ true

Unmount the thing at the given path. If the mount does not exist, an error will be raised.

Examples:

Vault.sys.unmount("pg") #=> true

Parameters:

  • path (String) —

    the path to unmount

Returns:

  • (true) 


141
142
143
144
 
# File 'lib/vault/api/sys/mount.rb', line 141

def unmount(path)
  client.delete("/v1/sys/mounts/#{encode_path(path)}")
  return true
end

#unseal(shard) ⇒ SealStatus

Unseal the vault with the given shard.

Examples:

Vault.sys.unseal("abcd-1234") #=> #<Vault::SealStatus sealed=true, t=3, n=5, progress=1>

Parameters:

  • shard (String) —

    the key to use

Returns:



77
78
79
80
81
82
 
# File 'lib/vault/api/sys/seal.rb', line 77

def unseal(shard)
  json = client.put("/v1/sys/unseal", JSON.fast_generate(
    key: shard,
  ))
  return SealStatus.decode(json)
end

#update_quota_config(opts = {}) ⇒ Object 



85
86
87
88
 
# File 'lib/vault/api/sys/quota.rb', line 85

def update_quota_config(opts={})
  client.post("v1/sys/quotas/config", JSON.fast_generate(opts))
  return true
end