Opendistro
A Ruby wrapper around the Opendistro API.
This library will strive to achieve reliable coverage of the Opendistro API. Please submit an issue if you find a bug and feel free to submit a pull request to contribute fixes or new features.
Initial versions of this gem to not achieve 100% coverage of the Opendistro API. Each release will include more and more endpoint support until there is 100% coverage.
The layout and the code in this library is inspired by https://github.com/NARKOZ/gitlab. NARKOZ does a fantastic job of keeping code simple and achieving API feature parity.
Installation
Install it from rubygems:
gem install opendistro
Or add to a Gemfile:
gem 'opendistro'
# gem 'opendistro', github: 'psyreactor/opendistro'
Mac OS users can install using Homebrew (may not be the latest version):
brew install opendistro-gem
Usage
Configuration example:
Opendistro.configure do |config|
config.endpoint = 'https://example.net:9200'
config.username = 'useradmin'
config.password = 'secretpassword'
# Optional
# config.user_agent = 'Custom User Agent'
# config.verify_ssl = false
# config.ca_cert = '/etc/pki/ca_cert/ca.crt'
end
Usage examples:
# set an API endpoint
Opendistro.endpoint = 'https://example.net:9200'
# => "https://example.net:9200"
# set a user user
Opendistro.username = 'useradmin'
# => "useradmin"
# set a user password
Opendistro.password = 'secretpassword'
# => "secretpassword"
# configure a proxy server
Opendistro.http_proxy('proxyhost', 8888)
# proxy server with basic auth
Opendistro.http_proxy('proxyhost', 8888, 'proxyuser', 'strongpasswordhere')
# set timeout for responses
ENV['OPENDISTRO_API_HTTPARTY_OPTIONS'] = '{read_timeout: 60}'
# list users
Opendistro.users()
# #<Opendistro::ObjectifiedHash:46080 {hash: {"logstash"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["logstash"], "attributes"=>{}, "description"=>"Demo logstash user", "opendistro_security_roles"=>[], "static"=>false}, "snapshotrestore"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["snapshotrestore"], "attributes"=>{}, "description"=>"Demo snapshotrestore user", "opendistro_security_roles"=>[], "static"=>false}, "admin"=>{"hash"=>"", "reserved"=>true, "hidden"=>false, "backend_roles"=>["admin"], "attributes"=>{}, "description"=>"Demo admin user", "opendistro_security_roles"=>[], "static"=>false}, "kibanaserver"=>{"hash"=>"", "reserved"=>true, "hidden"=>false, "backend_roles"=>[], "attributes"=>{}, "description"=>"Demo kibanaserver user", "opendistro_security_roles"=>[], "static"=>false}, "kibanaro"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["kibanauser", "readall"], "attributes"=>{"attribute1"=>"value1", "attribute2"=>"value2", "attribute3"=>"value3"}, "description"=>"Demo kibanaro user", "opendistro_security_roles"=>[], "static"=>false}, "readall"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["readall"], "attributes"=>{}, "description"=>"Demo readall user", "opendistro_security_roles"=>[], "static"=>false}}}
# initialize a new client with custom headers
od = Opendistro.client(
endpoint: 'https://example.com:9200',
username: 'useradmin',
password: 'secretpassword',
httparty: {
headers: { 'Cookie' => 'opendistro_canary=true' }
}
)
# get a users
user = od.users
#<Opendistro::ObjectifiedHash:46080 {hash: {"logstash"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["logstash"], "attributes"=>{}, "description"=>"Demo logstash user", "opendistro_security_roles"=>[], "static"=>false}, "snapshotrestore"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["snapshotrestore"], "attributes"=>{}, "description"=>"Demo snapshotrestore user", "opendistro_security_roles"=>[], "static"=>false}, "admin"=>{"hash"=>"", "reserved"=>true, "hidden"=>false, "backend_roles"=>["admin"], "attributes"=>{}, "description"=>"Demo admin user", "opendistro_security_roles"=>[], "static"=>false}, "kibanaserver"=>{"hash"=>"", "reserved"=>true, "hidden"=>false, "backend_roles"=>[], "attributes"=>{}, "description"=>"Demo kibanaserver user", "opendistro_security_roles"=>[], "static"=>false}, "kibanaro"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["kibanauser", "readall"], "attributes"=>{"attribute1"=>"value1", "attribute2"=>"value2", "attribute3"=>"value3"}, "description"=>"Demo kibanaro user", "opendistro_security_roles"=>[], "static"=>false}, "readall"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["readall"], "attributes"=>{}, "description"=>"Demo readall user", "opendistro_security_roles"=>[], "static"=>false}}}
# get a user's
user = od.user('logstash')
# get user description
user.description
# => 'logstash demo user'
Development
With a dockerized Opendistro instance
docker-compose up -d opendistro # Will start the Opendistro instance in the background (approx. 3 minutes)
After a while, your Opendistro instance will be accessible on http://localhost:9200.
Once you have set your new password admin, you can login with the admin user.
Once you have your token, set the variables to the correct values in the docker.env file.
Then, launch the tool:
docker-compose run app
Opendistro.users
=> #<Opendistro::ObjectifiedHash:46080 {hash: {"logstash"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["logstash"], "attributes"=>{}, "description"=>"Demo logstash user", "opendistro_security_roles"=>[], "static"=>false}, "snapshotrestore"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["snapshotrestore"], "attributes"=>{}, "description"=>"Demo snapshotrestore user", "opendistro_security_roles"=>[], "static"=>false}, "admin"=>{"hash"=>"", "reserved"=>true, "hidden"=>false, "backend_roles"=>["admin"], "attributes"=>{}, "description"=>"Demo admin user", "opendistro_security_roles"=>[], "static"=>false}, "kibanaserver"=>{"hash"=>"", "reserved"=>true, "hidden"=>false, "backend_roles"=>[], "attributes"=>{}, "description"=>"Demo kibanaserver user", "opendistro_security_roles"=>[], "static"=>false}, "kibanaro"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["kibanauser", "readall"], "attributes"=>{"attribute1"=>"value1", "attribute2"=>"value2", "attribute3"=>"value3"}, "description"=>"Demo kibanaro user", "opendistro_security_roles"=>[], "static"=>false}, "readall"=>{"hash"=>"", "reserved"=>false, "hidden"=>false, "backend_roles"=>["readall"], "attributes"=>{}, "description"=>"Demo readall user", "opendistro_security_roles"=>[], "static"=>false}}}
To launch the specs:
docker-compose run app rake spec
With an external Opendistro instance
First, set the variables to the correct values in the docker.env file.
Then, launch the tool:
docker-compose run app
Opendistro.users
To launch the specs,
docker-compose run app rake spec
License
Released under the BSD 2-clause license. See LICENSE.txt for details.