Repository files navigation

This is a gem to pragmatically access yourNetbox instancevia it's API from Ruby. This gem is currently only compatible with Netbox v2.4 or newer.

Add this line to your application's Gemfile:

gem'netbox-client-ruby'

If your application already uses Faraday 0.x or 1.x and you cannot otherwise upgrade to Faraday 2, you must also add this line to your application's Gemfile:

gem'faraday_middleware'# remove when upgrading to Faraday 2+

And then execute:

$ bundle

Or install it manually:

$ gem install netbox-client-ruby

Put this somewhere, where it runs, before any call to anything else of Netbox.If you are using Rails, then this would probably be somewhere underneath /config.

require'netbox-client-ruby'NetboxClientRuby.configuredo |config|config.netbox.auth.token='YOUR_API_TOKEN'config.netbox.api_base_url='http://netbox.local/api/'# these are optional:config.netbox.auth.rsa_private_key.path='~/.ssh/netbox_rsa'config.netbox.auth.rsa_private_key.password=''config.netbox.pagination.default_limit=50config.faraday.adapter=Faraday.default_adapter# https://lostisland.github.io/faraday/#/customization/request-optionsconfig.faraday.request_options={open_timeout:1,timeout:5}# see: https://lostisland.github.io/faraday/#/customization/ssl-optionsconfig.faraday.ssl_options={verify:true}config.faraday.logger=:logger# built-in options: :logger, :detailed_logger; default: nilend

The methods are aligned with the API as it is defined in Netbox.You can explore the API endpoints in your browser by opening the API endpoint. Usually that'shttp://YOUR_NETBOX/api/.

So if the URL is/api/dcim/sites.json, then the corresponding Ruby code would beNetboxClientRuby.dcim.sites.

# configurationNetboxClientRuby.configuredo |c|c.netbox.auth.token='2e35594ec8710e9922d14365a1ea66f27ea69450'c.netbox.api_base_url='http://netbox.local/api/'c.netbox.auth.rsa_private_key.path='~/.ssh/netbox_rsa'end# get all sitessites=NetboxClientRuby.dcim.sitesputs"There are#{sites.total} sites in your Netbox instance."# get the first site of the result setfirst_site=sites.firstputs"The first site is called#{first_site.name}."# filter devices by site# Note that Netbox filters by *slug*devices_of_site=NetboxClientRuby.dcim.devices.filter(site:first_site.slug)puts"#{devices_of_site.total} devices belong to the site.#{devices_of_site}.length devices have been fetched."# Finds a specific deviceNetboxClientRuby.dcim.devices.find_by(name:'my-device',other_field:'other-value')# Finds a specific device with a certain custom fieldNetboxClientRuby.dcim.devices.find_by(cf_custom_url:'https://google.com')# Or a mix of regular and custom fieldsNetboxClientRuby.dcim.devices.find_by(name:'my-device',cf_custom_field:'custom-value')# get a site by ids=NetboxClientRuby.dcim.site(1)# update a sites.update(name:'Zurich',slug:'zrh')# update a site (alternative)s.name='Amsterdam's.slug='ams's.save# create a sitenew_s=NetboxClientRuby::DCIM::Site.newnew_s.name='Berlin'new_s.slug='ber'new_s.save# create a site (alternative)new_s=NetboxClientRuby::DCIM::Site.new(name:'Berlin',slug:'ber').save# delete a sites=NetboxClientRuby.dcim.site(1)s.delete# working with secretssecrets=NetboxClientRuby.secrets.secretsputs"#{secrets.total} secrets are in your Netbox."secrets[0].plaintext# => nil, because you have not yet defined a session_keyNetboxClientRuby.secrets.get_session_key# now get a session_keysecrets=NetboxClientRuby.secrets.secrets# you must reload the data from the serversecrets[0].plaintext# => 'super secret password'# optionally, you can persist the session_key:session_key=NetboxClientRuby.secrets.get_session_key.session_keyFILE_NAME=File.expand_path('~/.netbox_session_key').freezeFile.write(FILE_NAME,session_key)# later on, you can restore the persisted session_key:persisted_session_key=File.read(FILE_NAME)NetboxClientRuby.secrets.session_key=persisted_session_key

Not all objects which the Netbox API exposes are currently implemented. Implementing new objectsis trivial, though.

• Circuits:
  • Circuits:NetboxClientRuby.circuits.circuits
  • Circuit Types:NetboxClientRuby.circuits.circuit_types
  • Circuit Terminations:NetboxClientRuby.circuits.circuit_terminations
  • Providers:NetboxClientRuby.circuits.providers
• DCIM:
  • Console Connections:NetboxClientRuby.dcim.console_connections
  • Console Ports:NetboxClientRuby.dcim.console_ports
  • Console Server Ports:NetboxClientRuby.dcim.console_server_ports
  • Devices:NetboxClientRuby.dcim.devices
  • Device Roles:NetboxClientRuby.dcim.device_roles
  • Device Types:NetboxClientRuby.dcim.device_types
  • Interfaces:NetboxClientRuby.dcim.interfaces
  • Interface Connections:NetboxClientRuby.dcim.interface_connections
  • Manufacturers:NetboxClientRuby.dcim.manufacturers
  • Platforms:NetboxClientRuby.dcim.platforms
  • Power Connections:NetboxClientRuby.dcim.power_connections
  • Power Outlets:NetboxClientRuby.dcim.power_outlets
  • Power Ports:NetboxClientRuby.dcim.power_ports
  • Racks:NetboxClientRuby.dcim.racks
  • Rack Groups:NetboxClientRuby.dcim.rack_groups
  • Rack Roles:NetboxClientRuby.dcim.rack_roles
  • Rack Reservations:NetboxClientRuby.dcim.rack_reservations
  • Regions:NetboxClientRuby.dcim.regions
  • Sites:NetboxClientRuby.dcim.sites
  • Virtual Chassis:NetboxClientRuby.dcim.virtual_chassis_list(⚠️ Exception: The access is different and the class is calledVirtualChassisList because the plural and singularnames are the same and this poses a conflict.)
• Extras:
  • Config Contexts:NetboxClientRuby.extras.config_contexts
  • Journal Entries:NetboxClientRuby.extras.journal_entries
  • Tags:NetboxClientRuby.extras.tags
• IPAM:
  • Aggregates:NetboxClientRuby.ipam.aggregates
  • IP Addresses:NetboxClientRuby.ipam.ip_addresses
  • IP Ranges:NetboxClientRuby.ipam.ip_ranges
  • Prefixes:NetboxClientRuby.ipam.prefixes
  • RIRs:NetboxClientRuby.ipam.rirs
  • Roles:NetboxClientRuby.ipam.roles
  • Services:NetboxClientRuby.ipam.services
  • VLANs:NetboxClientRuby.ipam.vlans
  • VLAN Groups:NetboxClientRuby.ipam.vlan_groups
  • VRFs:NetboxClientRuby.ipam.vrfs
• Secrets:
  • Secrets:NetboxClientRuby.secrets.secrets
  • Secret Roles:NetboxClientRuby.secrets.secret_roles
  • generate-rsa-key-pair:NetboxClientRuby.secrets.generate_rsa_key_pair
  • get-session-key:NetboxClientRuby.secrets.get_session_key
• Tenancy:
  • Tenant:NetboxClientRuby.tenancy.tenants
  • Tenant Groups:NetboxClientRuby.tenancy.tenant_groups
  • Contact:NetboxClientRuby.tenancy.contacts
  • Contact Groups:NetboxClientRuby.tenancy.contact_groups
• Virtualization:
  • Cluster Types:NetboxClientRuby.virtualization.cluster_types
  • Cluster Groups:NetboxClientRuby.virtualization.cluster_groups
  • Clusters:NetboxClientRuby.virtualization.clusters
  • Virtual Machines:NetboxClientRuby.virtualization.virtual_machines
  • Interfaces:NetboxClientRuby.virtualization.interfaces

If you can't find the object you need, also checkthe source codeif it was added in the meantime without the list above having been updated.

After checking out the repo, runbin/setup to install dependencies.Then, runrake spec to run the tests.

To install this gem onto your local machine, runbundle exec rake install.

To experiment interactively, fire up the Netbox Docker container by runningdocker-compose up -d.Then, runbin/console for an interactive prompt that will allow you to experiment against your local Netbox.

To simplify development, e.g. via thebin/console described above, there is a very complete sample set of Netbox data readily available.You can use it to query almost every object and relation in Netbox.

dockerexec -i netbox-client-ruby_postgres_1 psql -U postgres< dump.sql

Should you want to export the current set of data, use the command below.

docker-composeexec postgres pg_dump -U netbox --exclude-table-data=extras_objectchange -Cc netbox> dump.sql

(Remove--exclude-table-data=extras_objectchange from the command if you want to retain the history!)

Bug reports and pull requests are very welcomeon GitHub.

Before opening a PR, please

• extend the existing specs
• run rspec
• run rubocop and fix your warnings
• check if thisREADME.md file needs adjustments

The gem is available as open source under the terms of theMIT License.

This gem is currently maintained and funded bynine.