class Vault::Sys
Public Instance Methods
Generates a HMAC verifier for a given input.
@example
Vault.sys.audit_hash("file-audit", "my input") #=> "hmac-sha256:30aa7de18a5e90bbc1063db91e7c387b32b9fa895977eb8c177bbc91e7d7c542"
@param [String] path
the path of the audit backend
@param [String] input
the input to generate a HMAC for
@return [String]
# File lib/vault/api/sys/audit.rb, line 85 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
List all audits for the vault.
@example
Vault.sys.audits #=> { :file => #<Audit> }
@return [Hash<Symbol, Audit>]
# File lib/vault/api/sys/audit.rb, line 28 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
Read the given auth path's configuration.
@example
Vault.sys.auth_tune("github") #=> #<Vault::AuthConfig "default_lease_ttl"=3600, "max_lease_ttl"=7200>
@param [String] path
the path to retrieve configuration for
@return [AuthConfig]
configuration of the given auth path
# File lib/vault/api/sys/auth.rb, line 89 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
List all auths in Vault
.
@example
Vault.sys.auths #=> {:token => #<Vault::Auth type="token", description="token based credentials">}
@return [Hash<Symbol, Auth>]
# File lib/vault/api/sys/auth.rb, line 35 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 a namespace. Nests the namespace if a namespace header is provided.
@example
Vault.sys.create_namespace("foo")
@param [String] namespace
the potential path of the namespace, without any parent path provided
@return [true]
# File lib/vault/api/sys/namespace.rb, line 46 def create_namespace(namespace) client.put("/v1/sys/namespaces/#{namespace}", {}) return true end
# File lib/vault/api/sys/quota.rb, line 58 def create_quota(type, name, opts={}) path = generate_path(type, name) client.post(path, JSON.fast_generate(opts)) return true end
Delete a namespace. Raises an error if the namespace provided is not empty.
@example
Vault.sys.delete_namespace("foo")
@param [String] namespace
the path of the namespace to be deleted
@return [true]
# File lib/vault/api/sys/namespace.rb, line 60 def delete_namespace(namespace) client.delete("/v1/sys/namespaces/#{namespace}") return true end
Delete the policy with the given name. If a policy does not exist, vault will not return an error.
@example
Vault.sys.delete_policy("dev") #=> true
@param [String] name
the name of the policy
# File lib/vault/api/sys/policy.rb, line 87 def delete_policy(name) client.delete("/v1/sys/policy/#{encode_path(name)}") return true end
# File lib/vault/api/sys/quota.rb, line 64 def delete_quota(type, name) path = generate_path(type, name) client.delete(path) return true end
Disable a particular audit. If an audit does not exist, and error will be raised.
@param [String] path
the path of the audit to disable
@return [true]
# File lib/vault/api/sys/audit.rb, line 69 def disable_audit(path) client.delete("/v1/sys/audit/#{encode_path(path)}") return true end
Disable a particular authentication at the given path. If not auth exists at that path, an error will be raised.
@example
Vault.sys.disable_auth("github") #=> true
@param [String] path
the path to disable
@return [true]
# File lib/vault/api/sys/auth.rb, line 74 def disable_auth(path) client.delete("/v1/sys/auth/#{encode_path(path)}") return true end
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.
@example
Vault.sys.enable_audit("/file-audit", "file", "File audit", path: "/path/on/disk") #=> true
@param [String] path
the path to mount the audit
@param [String] type
the type of audit to enable
@param [String] description
a human-friendly description of the audit backend
@param [Hash] options
audit-specific options
@return [true]
# File lib/vault/api/sys/audit.rb, line 53 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 a particular authentication at the given path.
@example
Vault.sys.enable_auth("github", "github") #=> true
@param [String] path
the path to mount the auth
@param [String] type
the type of authentication
@param [String] description
a human-friendly description (optional)
@return [true]
# File lib/vault/api/sys/auth.rb, line 56 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
Retrieve a namespace by path.
@example
Vault.sys.get_namespace("foo")
@param [String] namespace
the path of the namespace ot be retrieved
@return [Namespace]
# File lib/vault/api/sys/namespace.rb, line 74 def get_namespace(namespace) json = client.get("/v1/sys/namespaces/#{namespace}") if data = json.dig(:data) Namespace.decode(data) else json end end
# File lib/vault/api/sys/quota.rb, line 70 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
# File lib/vault/api/sys/quota.rb, line 78 def get_quota_config client.get("v1/sys/quotas/config") end
Show the health status for this vault.
@example
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">
@return [HealthStatus]
# File lib/vault/api/sys/health.rb, line 58 def health_status json = client.get("/v1/sys/health", {:sealedcode => 200, :uninitcode => 200, :standbycode => 200}) return HealthStatus.decode(json) end
Initialize a new vault.
@example
Vault.sys.init #=> #<Vault::InitResponse keys=["..."] root_token="...">
@param [Hash] options
the list of init options
@option options [String] :root_token_pgp_key
optional base64-encoded PGP public key used to encrypt the initial root token.
@option options [Fixnum] :secret_shares
the number of shares
@option options [Fixnum] :secret_threshold
the number of keys needed to unlock
@option options [Array<String>] :pgp_keys
an optional Array of base64-encoded PGP public keys to encrypt sharees
@option options [Fixnum] :stored_shares
the number of shares that should be encrypted by the HSM for auto-unsealing
@option options [Fixnum] :recovery_shares
the number of shares to split the recovery key into
@option options [Fixnum] :recovery_threshold
the number of shares required to reconstruct the recovery key
@option options [Array<String>] :recovery_pgp_keys
an array of PGP public keys used to encrypt the output for the recovery keys
@return [InitResponse]
# File lib/vault/api/sys/init.rb, line 69 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
Show the initialization status for this vault.
@example
Vault.sys.init_status #=> #<Vault::InitStatus initialized=true>
@return [InitStatus]
# File lib/vault/api/sys/init.rb, line 35 def init_status json = client.get("/v1/sys/init") return InitStatus.decode(json) end
Determine the leader status for this vault.
@example
Vault.sys.leader #=> #<Vault::LeaderStatus ha_enabled=false, is_self=false, leader_address="">
@return [LeaderStatus]
# File lib/vault/api/sys/leader.rb, line 38 def leader json = client.get("/v1/sys/leader") return LeaderStatus.decode(json) end
Create a mount at the given path.
@example
Vault.sys.mount("pg", "postgresql", "Postgres user management") #=> true
@param [String] path
the path to mount at
@param [String] type
the type of mount
@param [String] description
a human-friendly description (optional)
# File lib/vault/api/sys/mount.rb, line 52 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
Tune a mount at the given path.
@example
Vault.sys.mount_tune("pki", max_lease_ttl: '87600h') #=> true
@param [String] path
the path to write
@param [Hash] data
the data to write
# File lib/vault/api/sys/mount.rb, line 69 def mount_tune(path, data = {}) json = client.post("/v1/sys/mounts/#{encode_path(path)}/tune", JSON.fast_generate(data)) return true end
List all mounts in the vault.
@example
Vault.sys.mounts #=> { :secret => #<struct Vault::Mount type="generic", description="generic secret storage"> }
@return [Hash<Symbol, Mount>]
# File lib/vault/api/sys/mount.rb, line 33 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
List all namespaces in a given scope. Ignores nested namespaces.
@example
Vault.sys.namespaces #=> { :foo => #<struct Vault::Namespace id="xxxx1", path="foo/" } @return [Hash<Symbol, Namespace>]
# File lib/vault/api/sys/namespace.rb, line 21 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
The list of policies in vault.
@example
Vault.sys.policies #=> ["root"]
@return [Array<String>]
# File lib/vault/api/sys/policy.rb, line 31 def policies client.get("/v1/sys/policy")[:policies] end
Get the policy by the given name. If a policy does not exist by that name, nil
is returned.
@example
Vault.sys.policy("root") #=> #<Vault::Policy rules="">
@return [Policy, nil]
# File lib/vault/api/sys/policy.rb, line 42 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
Write the given auth path's configuration.
@example
Vault.sys.auth_tune("github", "default_lease_ttl" => 600, "max_lease_ttl" => 1200 ) #=> true
@param [String] path
the path to retrieve configuration for
@return [AuthConfig]
configuration of the given auth path
# File lib/vault/api/sys/auth.rb, line 107 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
Create a new policy with the given name and rules.
@example
policy = <<-EOH path "sys" { policy = "deny" } EOH Vault.sys.put_policy("dev", policy) #=> true
It is recommend that you load policy rules from a file:
@example
policy = File.read("/path/to/my/policy.hcl") Vault.sys.put_policy("dev", policy)
@param [String] name
the name of the policy
@param [String] rules
the policy rules
@return [true]
# File lib/vault/api/sys/policy.rb, line 72 def put_policy(name, rules) client.put("/v1/sys/policy/#{encode_path(name)}", JSON.fast_generate( rules: rules, )) return true end
# File lib/vault/api/sys/quota.rb, line 46 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
Change the name of the mount
@example
Vault.sys.remount("pg", "postgres") #=> true
@param [String] from
the origin mount path
@param [String] to
the new mount path
@return [true]
# File lib/vault/api/sys/mount.rb, line 100 def remount(from, to) client.post("/v1/sys/remount", JSON.fast_generate( from: from, to: to, )) return true end
Renew a lease with the given ID.
@example
Vault.sys.renew("aws/username") #=> #<Vault::Secret ...>
@param [String] id
the lease ID
@param [Fixnum] increment
@return [Secret]
# File lib/vault/api/sys/lease.rb, line 13 def renew(id, increment = 0) json = client.put("/v1/sys/renew/#{id}", JSON.fast_generate( increment: increment, )) return Secret.decode(json) end
Revoke the secret at the given id. If the secret does not exist, an error will be raised.
@example
Vault.sys.revoke("aws/username") #=> true
@param [String] id
the lease ID
@return [true]
# File lib/vault/api/sys/lease.rb, line 30 def revoke(id) client.put("/v1/sys/revoke/#{id}", nil) return true end
Revoke all secrets under the given prefix.
@example
Vault.sys.revoke_prefix("aws") #=> true
@param [String] id
the lease ID
@return [true]
# File lib/vault/api/sys/lease.rb, line 44 def revoke_prefix(id) client.put("/v1/sys/revoke-prefix/#{id}", nil) return true end
Seal the vault. Warning: this will seal the vault!
@example
Vault.sys.seal #=> true
@return [true]
# File lib/vault/api/sys/seal.rb, line 60 def seal client.put("/v1/sys/seal", nil) return true end
Get the current seal status.
@example
Vault.sys.seal_status #=> #<Vault::SealStatus sealed=false, t=1, n=1, progress=0>
@return [SealStatus]
# File lib/vault/api/sys/seal.rb, line 49 def seal_status json = client.get("/v1/sys/seal-status") return SealStatus.decode(json) end
# File lib/vault/api/sys/leader.rb, line 43 def step_down client.put("/v1/sys/step-down", nil) return true end
Unmount the thing at the given path. If the mount does not exist, an error will be raised.
@example
Vault.sys.unmount("pg") #=> true
@param [String] path
the path to unmount
@return [true]
# File lib/vault/api/sys/mount.rb, line 84 def unmount(path) client.delete("/v1/sys/mounts/#{encode_path(path)}") return true end
Unseal the vault with the given shard.
@example
Vault.sys.unseal("abcd-1234") #=> #<Vault::SealStatus sealed=true, t=3, n=5, progress=1>
@param [String] shard
the key to use
@return [SealStatus]
# File lib/vault/api/sys/seal.rb, line 74 def unseal(shard) json = client.put("/v1/sys/unseal", JSON.fast_generate( key: shard, )) return SealStatus.decode(json) end
# File lib/vault/api/sys/quota.rb, line 82 def update_quota_config(opts={}) client.post("v1/sys/quotas/config", JSON.fast_generate(opts)) return true end
Private Instance Methods
# File lib/vault/api/sys/quota.rb, line 89 def generate_path(type, name=nil) verify_type(type) path = ["v1", "sys", "quotas", type, name].compact path.join("/") end
# File lib/vault/api/sys/quota.rb, line 100 def type_class(type) case type when "lease-count" then LeaseCountQuota when "rate-limit" then RateLimitQuota end end
# File lib/vault/api/sys/quota.rb, line 95 def verify_type(type) return if ["rate-limit", "lease-count"].include?(type) raise ArgumentError, "type must be one of \"rate-limit\" or \"lease-count\"" end