{"id":13710855,"url":"https://github.com/ninech/netbox-client-ruby","last_synced_at":"2025-04-04T21:06:08.137Z","repository":{"id":43642396,"uuid":"88061135","full_name":"ninech/netbox-client-ruby","owner":"ninech","description":"A ruby client library for Netbox v2.","archived":false,"fork":false,"pushed_at":"2025-03-21T06:55:16.000Z","size":702,"stargazers_count":27,"open_issues_count":9,"forks_count":23,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-28T20:05:47.517Z","etag":null,"topics":["docker-compose","faraday","netbox","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ninech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-12T14:28:03.000Z","updated_at":"2025-03-21T14:26:30.000Z","dependencies_parsed_at":"2023-01-30T07:01:13.667Z","dependency_job_id":"5d63ad3f-8601-42f8-a55f-8aa3f5766f12","html_url":"https://github.com/ninech/netbox-client-ruby","commit_stats":{"total_commits":205,"total_committers":20,"mean_commits":10.25,"dds":0.3219512195121951,"last_synced_commit":"391586331a16fc278815905c53e69063e27f9873"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninech%2Fnetbox-client-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninech%2Fnetbox-client-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninech%2Fnetbox-client-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninech%2Fnetbox-client-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ninech","download_url":"https://codeload.github.com/ninech/netbox-client-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-compose","faraday","netbox","ruby"],"created_at":"2024-08-02T23:01:01.455Z","updated_at":"2025-04-04T21:06:08.107Z","avatar_url":"https://github.com/ninech.png","language":"Ruby","readme":"# NetboxClientRuby\n\n[![Build Status](https://travis-ci.org/ninech/netbox-client-ruby.svg?branch=master)](https://travis-ci.org/ninech/netbox-client-ruby)\n[![Gem Version](https://badge.fury.io/rb/netbox-client-ruby.svg)](https://badge.fury.io/rb/netbox-client-ruby)\n[![Code Climate](https://codeclimate.com/github/ninech/netbox-client-ruby/badges/gpa.svg)](https://codeclimate.com/github/ninech/netbox-client-ruby)\n\nThis is a gem to pragmatically access your [Netbox instance](https://github.com/digitalocean/netbox)\nvia it's API from Ruby. This gem is currently only compatible with Netbox v2.4 or newer.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'netbox-client-ruby'\n```\n\nIf 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:\n\n```ruby\ngem 'faraday_middleware' # remove when upgrading to Faraday 2+\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it manually:\n\n    $ gem install netbox-client-ruby\n\n## Usage\n\n### Configuration\n\nPut this somewhere, where it runs, before any call to anything else of Netbox.\nIf you are using Rails, then this would probably be somewhere underneath /config.\n\n```ruby\nrequire 'netbox-client-ruby'\nNetboxClientRuby.configure do |config|\n  config.netbox.auth.token = 'YOUR_API_TOKEN'\n  config.netbox.api_base_url = 'http://netbox.local/api/'\n\n  # these are optional:\n  config.netbox.auth.rsa_private_key.path = '~/.ssh/netbox_rsa'\n  config.netbox.auth.rsa_private_key.password = ''\n  config.netbox.pagination.default_limit = 50\n  config.faraday.adapter = Faraday.default_adapter\n  # https://lostisland.github.io/faraday/#/customization/request-options\n  config.faraday.request_options = { open_timeout: 1, timeout: 5 }\n  # see: https://lostisland.github.io/faraday/#/customization/ssl-options\n  config.faraday.ssl_options = { verify: true }\n  config.faraday.logger = :logger # built-in options: :logger, :detailed_logger; default: nil\nend\n```\n\n### Structure\n\nThe methods are aligned with the API as it is defined in Netbox.\nYou can explore the API endpoints in your browser by opening the API endpoint. Usually that's `http://YOUR_NETBOX/api/`.\n\nSo if the URL is `/api/dcim/sites.json`, then the corresponding Ruby code would be `NetboxClientRuby.dcim.sites`.\n\n### Examples\n\n```ruby\n# configuration\nNetboxClientRuby.configure do |c|\n  c.netbox.auth.token = '2e35594ec8710e9922d14365a1ea66f27ea69450'\n  c.netbox.api_base_url = 'http://netbox.local/api/'\n  c.netbox.auth.rsa_private_key.path = '~/.ssh/netbox_rsa'\nend\n\n# get all sites\nsites = NetboxClientRuby.dcim.sites\nputs \"There are #{sites.total} sites in your Netbox instance.\"\n\n# get the first site of the result set\nfirst_site = sites.first\nputs \"The first site is called #{first_site.name}.\"\n\n# filter devices by site\n# Note that Netbox filters by *slug*\ndevices_of_site = NetboxClientRuby.dcim.devices.filter(site: first_site.slug)\nputs \"#{devices_of_site.total} devices belong to the site. #{devices_of_site}.length devices have been fetched.\"\n\n# Finds a specific device\nNetboxClientRuby.dcim.devices.find_by(name: 'my-device', other_field: 'other-value')\n\n# Finds a specific device with a certain custom field\nNetboxClientRuby.dcim.devices.find_by(cf_custom_url: 'https://google.com')\n\n# Or a mix of regular and custom fields\nNetboxClientRuby.dcim.devices.find_by(name: 'my-device', cf_custom_field: 'custom-value')\n\n# get a site by id\ns = NetboxClientRuby.dcim.site(1)\n\n# update a site\ns.update(name: 'Zurich', slug: 'zrh')\n\n# update a site (alternative)\ns.name = 'Amsterdam'\ns.slug = 'ams'\ns.save\n\n# create a site\nnew_s = NetboxClientRuby::DCIM::Site.new\nnew_s.name = 'Berlin'\nnew_s.slug = 'ber'\nnew_s.save\n\n# create a site (alternative)\nnew_s = NetboxClientRuby::DCIM::Site\n          .new(name: 'Berlin', slug: 'ber')\n          .save\n\n# delete a site\ns = NetboxClientRuby.dcim.site(1)\ns.delete\n\n# working with secrets\nsecrets = NetboxClientRuby.secrets.secrets\nputs \"#{secrets.total} secrets are in your Netbox.\"\nsecrets[0].plaintext # =\u003e nil, because you have not yet defined a session_key\nNetboxClientRuby.secrets.get_session_key # now get a session_key\nsecrets = NetboxClientRuby.secrets.secrets # you must reload the data from the server\nsecrets[0].plaintext # =\u003e 'super secret password'\n\n# optionally, you can persist the session_key:\nsession_key = NetboxClientRuby.secrets.get_session_key.session_key\nFILE_NAME = File.expand_path('~/.netbox_session_key').freeze\nFile.write(FILE_NAME, session_key)\n\n# later on, you can restore the persisted session_key:\npersisted_session_key = File.read(FILE_NAME)\nNetboxClientRuby.secrets.session_key = persisted_session_key\n```\n\n## Available Objects\n\nNot all objects which the Netbox API exposes are currently implemented. Implementing new objects\n[is trivial](https://github.com/ninech/netbox-client-ruby/commit/e3cee19d21a8a6ce480d7c03d23d7c3fbc92417a), though.\n\n* Circuits:\n  * Circuits: `NetboxClientRuby.circuits.circuits`\n  * Circuit Types: `NetboxClientRuby.circuits.circuit_types`\n  * Circuit Terminations: `NetboxClientRuby.circuits.circuit_terminations`\n  * Providers: `NetboxClientRuby.circuits.providers`\n* DCIM:\n  * Console Connections: `NetboxClientRuby.dcim.console_connections`\n  * Console Ports: `NetboxClientRuby.dcim.console_ports`\n  * Console Server Ports: `NetboxClientRuby.dcim.console_server_ports`\n  * Devices: `NetboxClientRuby.dcim.devices`\n  * Device Roles: `NetboxClientRuby.dcim.device_roles`\n  * Device Types: `NetboxClientRuby.dcim.device_types`\n  * Interfaces: `NetboxClientRuby.dcim.interfaces`\n  * Interface Connections: `NetboxClientRuby.dcim.interface_connections`\n  * Manufacturers: `NetboxClientRuby.dcim.manufacturers`\n  * Platforms: `NetboxClientRuby.dcim.platforms`\n  * Power Connections: `NetboxClientRuby.dcim.power_connections`\n  * Power Outlets: `NetboxClientRuby.dcim.power_outlets`\n  * Power Ports: `NetboxClientRuby.dcim.power_ports`\n  * Racks: `NetboxClientRuby.dcim.racks`\n  * Rack Groups: `NetboxClientRuby.dcim.rack_groups`\n  * Rack Roles: `NetboxClientRuby.dcim.rack_roles`\n  * Rack Reservations: `NetboxClientRuby.dcim.rack_reservations`\n  * Regions: `NetboxClientRuby.dcim.regions`\n  * Sites: `NetboxClientRuby.dcim.sites`\n  * Virtual Chassis: `NetboxClientRuby.dcim.virtual_chassis_list`\n    (⚠️ Exception: The access is different and the class is called `VirtualChassisList` because the plural and singular\n    names are the same and this poses a conflict.)\n* Extras:\n  * Config Contexts: `NetboxClientRuby.extras.config_contexts`\n  * Journal Entries: `NetboxClientRuby.extras.journal_entries`\n  * Tags: `NetboxClientRuby.extras.tags`\n* IPAM:\n  * Aggregates: `NetboxClientRuby.ipam.aggregates`\n  * IP Addresses: `NetboxClientRuby.ipam.ip_addresses`\n  * IP Ranges: `NetboxClientRuby.ipam.ip_ranges`\n  * Prefixes: `NetboxClientRuby.ipam.prefixes`\n  * RIRs: `NetboxClientRuby.ipam.rirs`\n  * Roles: `NetboxClientRuby.ipam.roles`\n  * Services: `NetboxClientRuby.ipam.services`\n  * VLANs: `NetboxClientRuby.ipam.vlans`\n  * VLAN Groups: `NetboxClientRuby.ipam.vlan_groups`\n  * VRFs: `NetboxClientRuby.ipam.vrfs`\n* Secrets:\n  * Secrets: `NetboxClientRuby.secrets.secrets`\n  * Secret Roles: `NetboxClientRuby.secrets.secret_roles`\n  * generate-rsa-key-pair: `NetboxClientRuby.secrets.generate_rsa_key_pair`\n  * get-session-key: `NetboxClientRuby.secrets.get_session_key`\n* Tenancy:\n  * Tenant: `NetboxClientRuby.tenancy.tenants`\n  * Tenant Groups: `NetboxClientRuby.tenancy.tenant_groups`\n  * Contact: `NetboxClientRuby.tenancy.contacts`\n  * Contact Groups: `NetboxClientRuby.tenancy.contact_groups`\n* Virtualization:\n  * Cluster Types: `NetboxClientRuby.virtualization.cluster_types`\n  * Cluster Groups: `NetboxClientRuby.virtualization.cluster_groups`\n  * Clusters: `NetboxClientRuby.virtualization.clusters`\n  * Virtual Machines: `NetboxClientRuby.virtualization.virtual_machines`\n  * Interfaces: `NetboxClientRuby.virtualization.interfaces`\n\nIf you can't find the object you need, also check\n[the source code](https://github.com/ninech/netbox-client-ruby/tree/master/lib/netbox_client_ruby/api)\nif it was added in the meantime without the list above having been updated.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies.\nThen, run `rake spec` to run the tests.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\nTo experiment interactively, fire up the Netbox Docker container by running `docker-compose up -d`.\nThen, run `bin/console` for an interactive prompt that will allow you to experiment against your local Netbox.\n\n### Load Development Data\n\nTo simplify development, e.g. via the `bin/console` described above, there is a very complete sample set of Netbox data readily available.\nYou can use it to query almost every object and relation in Netbox.\n\n```bash\ndocker exec -i netbox-client-ruby_postgres_1 psql -U postgres \u003c dump.sql\n```\n\n### Dump Development from Database\n\nShould you want to export the current set of data, use the command below.\n\n```bash\ndocker-compose exec postgres pg_dump -U netbox --exclude-table-data=extras_objectchange -Cc netbox \u003e dump.sql\n```\n\n(Remove `--exclude-table-data=extras_objectchange` from the command if you want to retain the history!)\n\n## Contributing\n\nBug reports and pull requests are very welcome [on GitHub](https://github.com/ninech/netbox-client-ruby).\n\nBefore opening a PR, please\n\n* extend the existing specs\n* run rspec\n* run rubocop and fix your warnings\n* check if this `README.md` file needs adjustments\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n## About\n\nThis gem is currently maintained and funded by [nine](https://nine.ch).\n\n[![logo of the company 'nine'](https://logo.apps.at-nine.ch/Dmqied_eSaoBMQwk3vVgn4UIgDo=/trim/500x0/logo_claim.png)](https://www.nine.ch)\n","funding_links":[],"categories":["SDKs"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fninech%2Fnetbox-client-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fninech%2Fnetbox-client-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fninech%2Fnetbox-client-ruby/lists"}