{"id":14986187,"url":"https://github.com/puppet-finland/puppet-librenms","last_synced_at":"2025-04-11T21:31:29.162Z","repository":{"id":25290116,"uuid":"28716142","full_name":"Puppet-Finland/puppet-librenms","owner":"Puppet-Finland","description":"A Puppet module for managing LibreNMS","archived":false,"fork":false,"pushed_at":"2021-08-17T10:56:41.000Z","size":141,"stargazers_count":4,"open_issues_count":0,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-22T01:46:19.650Z","etag":null,"topics":["librenms","puppet","vagrant"],"latest_commit_sha":null,"homepage":"https://www.puppeteers.net/open-source/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Puppet-Finland.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-02T14:53:02.000Z","updated_at":"2021-11-30T19:59:17.000Z","dependencies_parsed_at":"2022-08-23T05:00:50.722Z","dependency_job_id":null,"html_url":"https://github.com/Puppet-Finland/puppet-librenms","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Puppet-Finland%2Fpuppet-librenms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Puppet-Finland%2Fpuppet-librenms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Puppet-Finland%2Fpuppet-librenms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Puppet-Finland%2Fpuppet-librenms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Puppet-Finland","download_url":"https://codeload.github.com/Puppet-Finland/puppet-librenms/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248482954,"owners_count":21111408,"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":["librenms","puppet","vagrant"],"created_at":"2024-09-24T14:12:30.008Z","updated_at":"2025-04-11T21:31:28.774Z","avatar_url":"https://github.com/Puppet-Finland.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# librenms\n\nA Puppet module for managing LibreNMS\n\n# Usage\n\nThe Puppet manifest used by Vagrant\n([vagrant/librenms.pp](vagrant/librenms.pp)) shows how to\n\n* Setup LibreNMS (install, configuration, permissions, ACLs, users, etc.)\n* Use puppetlabs-mysql to configure database, user and grants\n* Setup snmpd and create and SNMPv3 user\n* Add the LibreNMS node to LibreNMS\n\nThe manifest used by Vagrant uses two optional features of this module that\n\n* Install the required php packages\n* Configure Apache to serve LibreNMS on port 80 (http)\n\n## Hints for production\n\nTo import a node into LibreNMS using exported resources:\n\n    class { '::snmpd':\n      allow_address_ipv4 =\u003e '10.0.0.0',\n      allow_netmask_ipv4 =\u003e '8',\n      users              =\u003e { 'monitor' =\u003e { 'pass' =\u003e 'my-password' } },\n    }\n    \n    class { '::librenms::device':\n      proto =\u003e 'v3',\n      user  =\u003e 'monitor',\n      pass  =\u003e 'my_password',\n    }\n\nTo use SNMPv2 instead:\n\n    class { '::librenms::device':\n      proto      =\u003e 'v2',\n      community  =\u003e 'public',\n    }\n\nCreate and remove devices using [LibreNMS v0 API](https://docs.librenms.org/API/Devices/):\n\n    librenms_device { 'snmpv3.example.org':\n      ensure     =\u003e 'present',\n      url        =\u003e 'https://librenms.example.org/api/v0',\n      auth_token =\u003e '0123456789abcde0123456789abcded0',\n      snmpver    =\u003e 'v3',\n      authlevel  =\u003e 'noAuthNoPriv',\n      authname   =\u003e 'snmpuser',\n      authpass   =\u003e 'secret',\n      authalgo   =\u003e 'sha',\n      cryptopass =\u003e 'secret',\n      cryptoalgo =\u003e 'aes',\n    }\n    \n    librenms_device { 'snmpv2.example.org':\n      ensure     =\u003e 'present',\n      url        =\u003e 'https://librenms.example.org/api/v0',\n      auth_token =\u003e '0123456789abcde0123456789abcded0',\n      snmpver    =\u003e 'v2c',\n      community  =\u003e 'public',\n    }\n    \n    # Ensure that a decommissioned node is not present in LibreNMS\n    librenms_device { 'decommissioned.example.org':\n      ensure =\u003e 'absent',\n    }\n\nThe provider uses the \"force_add\" parameter to ensure that nodes that are\n(temporarily) inaccessible (e.g. being provisioned) are added correctly.\n\nYou can also manage services using the [LibreNMS v0 API](https://docs.librenms.org/API/Services/):\n\n    librenms_service { 'http-on-librenms':\n      ensure     =\u003e 'present',\n      url        =\u003e 'http://librenms.example.org/api/v0',\n      auth_token =\u003e '0123456789abcde0123456789abcded0',\n      hostname   =\u003e 'librenms.example.org',\n      type       =\u003e 'http',\n      ip         =\u003e 'librenms.example.org',\n      param      =\u003e 'C 50 --sni -S',\n    }\n\nThere are couple of caveats regarding service management:\n\n* The \"desc\" parameter, which defaults to the resource title, is used as an identifier at the LibreNMS. This is because it is the only property which is purely informational. You can use this to import existing resources to Puppet. If multiple services matching the same \"desc\" on the same device are found then Puppet will bail out and ask you to resolve the situation.\n* No verification is done on any of the parameters at Puppet or LibreNMS end except for basic data type validation. For example you can change \"type\" from \"http\" (valid) to \"https\" (invalid) without any errors or warnings.\n\nTo create CustomOID checks use the librenms_customoid type. Below an example of\nhow to use this with\n[net-snmp-systemd-service-status](https://github.com/Puppet-Finland/net-snmp-systemd-service-status):\n\n    $service = 'sshd'\n    \n    # Convert human-readable (ASCII) name to an OID\n    $oid = librenms::name_to_oid($service)\n    $descr = \"${service} on ${::fqdn}\"\n    \n    @@librenms_customoid { $descr:\n      ensure   =\u003e present,\n      \n      # Database username and password: there's no API support for manipulating\n      # CustomOIDs\n      username =\u003e 'librenms',\n      password =\u003e 'secret',\n      \n      # Bind this CustomOID to hostname that matches value of $::fqdn fact\n      hostname =\u003e $::fqdn,\n      \n      # Alternatively use sysName instead for the mapping\n      # sysName   =\u003e $::hostname,\n       \n      # Turn on alerting for this CustomOID.\n      alert    =\u003e 1,\n      \n      # Human readable description\n      descr    =\u003e $descr,\n      \n      # The OID, which matches the service name converted to ASCII.\n      oid      =\u003e $oid,\n      \n      # Send critical alert if the service is not up. We get 0 if it is up, 1\n      # otherwise.\n      limit    =\u003e 1,\n      \n      # Collect using tags\n      tag      =\u003e 'default'\n    }\n\nThen just realize the exported resources on the LibreNMS server:\n\n    Librenms_customoid \u003c\u003c| tag == 'default' |\u003e\u003e\n\nSee\n[lib/puppet/type/librenms_customoid.rb](lib/puppet/type/librenms_customoid.rb)\nfor documentation of all the available parameters.\n\n# Testing with Vagrant\n\nIf you have Vagrant and virtualbox installed then setting up LibreNMS test\ninstance from scratch should be as easy as:\n\n    $ vagrant up\n\nLibreNMS UI can be reached via\n\n* https://192.168.152.10 (librenms)\n* https://192.168.152.11 (librenms-focal)\n\nUsername is \"admin\" and password is \"vagrant\". The instance adds itself to\nLibreNMS, so you should see one device, \"librenms.vagrant.example.lan\" under\ndevices.\n\nIf you want to use snmpwalk note that the username is \"librenms\" and password\nis \"vagrant123\".\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppet-finland%2Fpuppet-librenms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppet-finland%2Fpuppet-librenms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppet-finland%2Fpuppet-librenms/lists"}