class Rbeapi::Api::Users

The Users class provides configuration of local user resources for an EOS node.

Public Class Methods

new(node) click to toggle source
Calls superclass method Rbeapi::Api::Entity::new
# File lib/rbeapi/api/users.rb, line 44
def initialize(node)
  super(node)
  # The regex used here parses the running configuration to find all
  # username entries. There is extra logic in the regular expression
  # to store the username as 'user' and then creates a back reference
  # to find a following configuration line that might contain the
  # users sshkey.
  @users_re = Regexp.new(/^username\s+(?<user>[^\s]+)\s+
                          privilege\s+(?<priv>\d+)
                          (\s+role\s+(?<role>\S+))?
                          (?:\s+(?<nopassword>(nopassword)))?
                          (\s+secret\s+(?<encryption>0|5|7|sha512)\s+
                          (?<secret>\S+))?.*$\n
                          (username\s+\k<user>\s+
                           sshkey\s+(?<sshkey>.*)$)?/x)

  @encryption_map = { 'cleartext' => '0',
                      'md5' => '5',
                      'sha512' => 'sha512' }
end

Public Instance Methods

create(name, opts = {}) click to toggle source

create will create a new user name resource in the nodes current configuration with the specified user name. Creating users require either a secret (password) or the nopassword keyword to be specified. Optional parameters can be passed in to initialize user name specific settings.

@since eos_version 4.13.7M

Commands

username <name> nopassword privilege <value> role <value>
username <name> secret [0,5,sha512] <secret> ...

@param name [String] The name of the user to create.

@param opts [hash] Optional keyword arguments.

@option opts nopassword [Boolean] Configures the user to be able to

authenticate without a password challenge.

@option opts secret [String] The secret (password) to assign to this

user.

@option opts encryption [String] Specifies how the secret is encoded.

Valid values are "cleartext", "md5", "sha512".  The default is
"cleartext".

@option opts privilege [String] The privilege value to assign to

the user.

@option opts role [String] The role value to assign to the user.

@option opts sshkey [String] The sshkey value to assign to the user.

@return [Boolean] Returns true if the command completed successfully.

# File lib/rbeapi/api/users.rb, line 211
def create(name, opts = {})
  cmd = "username #{name}"
  cmd << " privilege #{opts[:privilege]}" if opts[:privilege]
  cmd << " role #{opts[:role]}" if opts[:role]
  if opts[:nopassword] == :true
    cmd << ' nopassword'
  else
    # Map the encryption value if set, if there is no mapping then
    # just return the value.
    enc = opts.fetch(:encryption, 'cleartext')
    unless @encryption_map[enc]
      raise ArgumentError, "invalid encryption value: #{enc}"
    end
    enc = @encryption_map[enc]

    unless opts[:secret]
      raise ArgumentError,
            'secret must be specified if nopassword is false'
    end
    cmd << " secret #{enc} #{opts[:secret]}"
  end
  cmds = [cmd]
  cmds << "username #{name} sshkey #{opts[:sshkey]}" if opts[:sshkey]
  configure(cmds)
end
default(name) click to toggle source

default will configure the user name using the default keyword. This command has the same effect as deleting the user name from the nodes running configuration.

@since eos_version 4.13.7M

Commands

default username <name>

@param name [String] The user name to default in the nodes

configuration.

@return [Boolean] Returns true if the command complete successfully.

# File lib/rbeapi/api/users.rb, line 268
def default(name)
  configure("default username #{name}")
end
delete(name) click to toggle source

delete will delete an existing user name from the nodes current running configuration. If the delete method is called and the user name does not exist, this method will succeed.

@since eos_version 4.13.7M

Commands

no username <name>

@param name [String] The user name to delete from the node.

@return [Boolean] Returns true if the command completed successfully.

# File lib/rbeapi/api/users.rb, line 250
def delete(name)
  configure("no username #{name}")
end
get(name) click to toggle source

get returns the local user configuration.

@example

{
  name: <string>,
  privilege: <integer>,
  role: <string>,
  nopassword: <boolean>,
  encryption: <'cleartext', 'md5', 'sha512'>
  secret: <string>,
  sshkey: <string>
}

@param name [String] The user name to return a resource for from the

nodes configuration

@return [nil, Hash<Symbol, Object>] Returns the user resource as a

Hash. If the specified user name is not found in the nodes current
configuration a nil object is returned.
# File lib/rbeapi/api/users.rb, line 85
def get(name)
  # The regex used here parses the running configuration to find one
  # username entry.
  user_re = Regexp.new(/^username\s+(?<user>#{name})\s+
                        privilege\s+(?<priv>\d+)
                        (\s+role\s+(?<role>\S+))?
                        (?:\s+(?<nopassword>(nopassword)))?
                        (\s+secret\s+(?<encryption>0|5|7|sha512)\s+
                        (?<secret>\S+))?.*$\n
                        (username\s+#{name}\s+
                         sshkey\s+(?<sshkey>.*)$)?/x)
  user = config.scan(user_re)
  return nil unless user && user[0]
  parse_user_entry(user[0])
end
getall() click to toggle source

getall returns a collection of user resource hashes from the nodes running configuration. The user resource collection hash is keyed by the unique user name.

@example

[
  <username>: {
    name: <string>,
    privilege: <integer>,
    role: <string>,
    nopassword: <boolean>,
    encryption: <'cleartext', 'md5', 'sha512'>
    secret: <string>,
    sshkey: <string>
  },
  <username>: {
    name: <string>,
    privilege: <integer>,
    role: <string>,
    nopassword: <boolean>,
    encryption: <'cleartext', 'md5', 'sha512'>
    secret: <string>,
    sshkey: <string>
  },
  ...
]

@return [Hash<Symbol, Object>] Returns a hash that represents the

entire user collection from the nodes running configuration.  If
there are no user names configured, this method will return an empty
 hash.
# File lib/rbeapi/api/users.rb, line 133
def getall
  entries = config.scan(@users_re)
  response = {}
  entries.each do |user|
    response[user[0]] = parse_user_entry(user)
  end
  response
end
set_privilege(name, opts = {}) click to toggle source

set_privilege configures the user privilege value for the specified user name in the nodes running configuration. If enable is false in the opts keyword Hash then the name value is negated using the no keyword. If the default keyword is set to true, then the privilege value is defaulted using the default keyword. The default keyword takes precedence over the enable keyword

@since eos_version 4.13.7M

Commands

username <name> privilege <value>
no username <name> privilege <value>
default username <name> privilege <value>

@param name [String] The user name to default in the nodes

configuration.

@param opts [Hash] Optional keyword arguments.

@option opts value [String] The privilege value to assign to the user.

@option opts enable [Boolean] If false then the command is

negated. Default is true.

@option opts default [Boolean] Configure the user privilege value

using the default keyword.

@return [Boolean] Returns true if the command completed successfully.

# File lib/rbeapi/api/users.rb, line 301
def set_privilege(name, opts = {})
  configure(command_builder("username #{name} privilege", opts))
end
set_role(name, opts = {}) click to toggle source

set_role configures the user role value for the specified user name in the nodes running configuration. If enable is false in the opts keyword Hash then the name value is negated using the no keyword. If the default keyword is set to true, then the role value is defaulted using the default keyword. The default keyword takes precedence over the enable keyword

@since eos_version 4.13.7M

Commands

username <name> role <value>
no username <name> role <value>
default username <name> role <value>

@param name [String] The user name to default in the nodes

configuration.

@param opts [Hash] Optional keyword arguments.

@option opts value [String] The role value to assign to the user.

@option opts enable [Boolean] If false then the command is

negated. Default is true.

@option opts default [Boolean] Configure the user role value

using the default keyword.

@return [Boolean] Returns true if the command completed successfully.

# File lib/rbeapi/api/users.rb, line 334
def set_role(name, opts = {})
  configure(command_builder("username #{name} role", opts))
end
set_sshkey(name, opts = {}) click to toggle source

set_sshkey configures the user sshkey value for the specified user name in the nodes running configuration. If enable is false in the opts keyword Hash then the name value is negated using the no keyword. If the default keyword is set to true, then the sshkey value is defaulted using the default keyword. The default keyword takes precedence over the enable keyword.

@since eos_version 4.13.7M

Commands

username <name> sshkey <value>
no username <name> sshkey <value>
default username <name> sshkey <value>

@param name [String] The user name to default in the nodes

configuration.

@param opts [Hash] Optional keyword arguments

@option opts value [String] The sshkey value to assign to the user

@option opts enable [Boolean] If false then the command is

negated. Default is true.

@option opts default [Boolean] Configure the user sshkey value

using the default keyword.

@return [Boolean] Returns true if the command completed successfully.

# File lib/rbeapi/api/users.rb, line 367
def set_sshkey(name, opts = {})
  configure(command_builder("username #{name} sshkey", opts))
end

Private Instance Methods

parse_user_entry(user) click to toggle source

parse_user_entry maps the tokens find to the hash entries.

@api private

@param user [Array] An array of values returned from the regular

expression scan of the nodes configuration.

@return [Hash<Symbol, Object>] Returns the resource hash attribute.

# File lib/rbeapi/api/users.rb, line 151
def parse_user_entry(user)
  raise ArgumentError, 'user must be an Array' unless user.is_a?(Array)

  hsh = {}
  hsh[:name] = user[0]
  hsh[:privilege] = user[1].to_i
  hsh[:role] = user[2]
  hsh[:nopassword] = user[3] ? true : false
  # Map the encryption value if set, if there is no mapping then
  # just return the value.
  if user[4]
    @encryption_map.each do |key, value|
      if value == user[4]
        user[4] = key
        break
      end
    end
  end
  hsh[:encryption] = user[4]
  hsh[:secret] = user[5]
  hsh[:sshkey] = user[6]
  hsh
end