{"id":23073535,"url":"https://github.com/voxpupuli/puppet-ldapquery","last_synced_at":"2025-12-11T21:42:12.141Z","repository":{"id":32281398,"uuid":"35856151","full_name":"voxpupuli/puppet-ldapquery","owner":"voxpupuli","description":"Query an LDAP server using Puppet.","archived":false,"fork":false,"pushed_at":"2025-03-28T17:26:37.000Z","size":181,"stargazers_count":9,"open_issues_count":1,"forks_count":15,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-04-22T05:20:51.249Z","etag":null,"topics":["hacktoberfest","puppet"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voxpupuli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","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,"zenodo":null},"funding":{"open_collective":"vox-pupuli","github":"voxpupuli"}},"created_at":"2015-05-19T03:06:20.000Z","updated_at":"2025-03-28T17:26:39.000Z","dependencies_parsed_at":"2023-11-09T13:02:42.834Z","dependency_job_id":"ad6fd669-9d1c-43df-a138-695741b0eb6a","html_url":"https://github.com/voxpupuli/puppet-ldapquery","commit_stats":{"total_commits":115,"total_committers":14,"mean_commits":8.214285714285714,"dds":0.6608695652173913,"last_synced_commit":"c94d7b02f81670a0c55eb43ee370196cbdbdbd69"},"previous_names":["xaque208/puppet-ldapquery"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-ldapquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-ldapquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-ldapquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-ldapquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voxpupuli","download_url":"https://codeload.github.com/voxpupuli/puppet-ldapquery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250694153,"owners_count":21472386,"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":["hacktoberfest","puppet"],"created_at":"2024-12-16T08:18:12.043Z","updated_at":"2025-12-11T21:42:12.088Z","avatar_url":"https://github.com/voxpupuli.png","language":"Ruby","funding_links":["https://opencollective.com/vox-pupuli","https://github.com/sponsors/voxpupuli"],"categories":[],"sub_categories":[],"readme":"# Puppet-LDAPquery\n\n[![CI](https://github.com/voxpupuli/puppet-ldapquery/actions/workflows/ci.yml/badge.svg)](https://github.com/voxpupuli/puppet-ldapquery/actions/workflows/ci.yml)\n[![Puppet Forge](https://img.shields.io/puppetforge/v/puppet/ldapquery.svg)](https://forge.puppetlabs.com/puppet/ldapquery)\n[![Puppet Forge - downloads](https://img.shields.io/puppetforge/dt/puppet/ldapquery.svg)](https://forge.puppetlabs.com/puppet/ldapquery)\n[![Puppet Forge - endorsement](https://img.shields.io/puppetforge/e/puppet/ldapquery.svg)](https://forge.puppetlabs.com/puppet/ldapquery)\n[![Puppet Forge - scores](https://img.shields.io/puppetforge/f/puppet/ldapquery.svg)](https://forge.puppetlabs.com/puppet/ldapquery)\n[![Apache-2 License](https://img.shields.io/github/license/voxpupuli/puppet-ldapquery.svg)](LICENSE)\n\nA Puppet function to query LDAP.\n\n## Dependencies\n\nThe Ruby `net-ldap` gem is required to communicate with LDAP. To install this use the following command: `puppetserver gem install net-ldap`.  Version 0.11.0 or newer of `net-ldap` is required.\n\nIn some environments, when `ldapquery::search()` is used on Puppet Server, an error\nlike the following may appear.\n\n    Error while evaluating a Function Call\n\nPlease make sure you have `jruby-openssl` at least `0.10.1` with `puppetserver\ngem install jruby-openssl -v 0.10.1`.\n\n## REFERENCE\n\nFor detailed information on this module's functions, see the [REFERENCE.md](https://github.com/voxpupuli/puppet-ldapquery/blob/master/REFERENCE.md)\n\n## Usage\n\nThis module provides two function variants. ``ldapquery::query`` is the legacy implementation where LDAP connection options are sourced from `puppet.conf` on your Puppetserver.\n\n`ldapquery::search` is the replacement implementation. It provides more flexibility than `ldapquery::query` and doesn't reuse `ldap` related settings from `puppet.conf`. All connection options can be specified in the function call and can be different each time you call the function. For convenience, it is also possible to specify defaults to be used in all functions calls in `/etc/puppetlabs/puppet/ldapquery.yaml`. This can also be useful if you want to manage the credentials used to contact your ldap server separately from the code that calls the function.\n\n### Simple example\n\n```pupppet\nldapquery::search(\n  'dc=acme,dc=example,dc=com', # Search base\n  '(objectClass=dnsDomain)',   # filter\n  ['dc'],                      # attributes\n  {                            # connection arguments\n    host =\u003e 'ldap.example.com',\n    auth =\u003e {\n      method   =\u003e simple,\n      username =\u003e 'ldapuser',\n      password =\u003e 'ldappassword',\n    },\n  },\n)\n\n```\n\nA full set of examples can be found in the [REFERENCE.md](https://github.com/voxpupuli/puppet-ldapquery/blob/master/REFERENCE.md) file.\n\n### LDAP connection arguments\n\nLDAP server connection options either have to be specified when calling the function, (in the 4th argument), or configured as defaults on the puppetserver in `/etc/puppetlabs/puppet/ldapquery.yaml`\n\nEverything that the `net-ldap` library supports should work with this function, (eg. connecting to multiple LDAP servers, using TLS etc.) The REFERENCE.MD file has many examples. The examples that follow have omitted this option for simplicity. It can be assumed they have been configured on the puppetserver.\n\n### Filters and attributes\n\nSimply passing the search base and an `rfc4515` search filter string to `ldapquery::search()` will return\nthe results of the query in list form.  Optionally, a list of attributes of which to return the values may also be passed.\n\nConsider the following manifest. (For simplicity, the declaration of `$ldap_args` has been left off of the following examples).\n\n```Puppet\n$base = 'dc=acme,dc=example,dc=com'\n\n$filter = '(uid=zach)'\n\n$attributes = [\n  'loginshell',\n  'uidnumber',\n  'uid',\n  'homedirectory',\n]\n\n$zach = ldapquery::search($base, $filter, $attributes)\n```\n\nAssuming there is only one LDAP object with the `uid=zach`, then the variable\n`$zach` now holds the following data structure:\n\n```Ruby\n[\n  {\n    'uid'           =\u003e ['zach'],\n    'loginshell'    =\u003e ['/bin/zsh'],\n    'uidnumber'     =\u003e ['123'],\n    'homedirectory' =\u003e ['/var/users/zach'],\n  }\n]\n```\n\n**Note that the key values are an array.**  This should make implementation code simpler, if a bit more verbose, and avoid having to check if the value is an array or a string, because it always is.\n\nHere is a slightly more complicated example that will generate *virtual*\n`ssh_authorized_key` resources for every 'posixAccount' that has a non-empty\n'sshPublicKey' attribute.\n\n```Puppet\n$base = 'dc=acme,dc=example,dc=com'\n\n$attributes = [\n  'uid',\n  'sshPublicKey'\n]\n\n$key_query = '(\u0026(objectClass=ldapPublicKey)(sshPublicKey=*)(objectClass=posixAccount))'\n\n$key_results = ldapquery::search($base, $key_query, $attributes)\n$key_results.each |$u| {\n  any2array($u['sshpublickey']).each |$k| {\n    $keyparts = split($k, ' ')\n\n    # Retrieve the comment portion\n    if $keyparts =~ Array[String, 3] {\n      $comment  = $keyparts[2]\n    } else {\n      $comment  = ''\n    }\n\n    $uid = $u['uid'][0]\n\n    @ssh_authorized_key { \"${uid}_${comment}\":\n      user =\u003e $uid,\n      type =\u003e $keyparts[0],\n      key  =\u003e $keyparts[1],\n      tag  =\u003e 'ldap',\n    }\n  }\n}\n```\n\n\n### The legacy function `ldapquery::query`\n\nThis implementation has been replaced by the more advanced version `ldapquery::search` documented above. It should be considered DEPRECATED and may be removed in a future release.  For completeness, documentation specific to this function is retained in this release and follows.\n\n#### On the Puppetserver\n\nYou must set the necessary variables in `puppet.conf` so the puppetserver can connect\nto your LDAP server. You also have to place the CA certificate (and possible intermediate certificates) of the tls certificate of your ldap server in pem format in a file called ldap_ca.pem in your puppetconf folder.\n\nYou can simply add the static values like so:\n\n```INI\n[master]\nldaptls = true\nldapport = 636\nldapserver = ldap.example.com\nldapbase = dc=example,dc=com\nldapuser = cn=puppet,ou=people,dc=example,dc=com\nldappassword = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\n```\n\nOr, use Puppet to manage the values in `puppet.conf` by adding something like\nthe following to the manifest that manages your master's `puppet.conf`.\n\n```Puppet\n$ldap_base   = hiera('ldap_base') # dc=example,dc=com\n$ldap_user   = hiera('ldap_user') # cn=ldapuser,dc=puppetlabs,dc=com\n$ldap_pass   = hiera('ldap_pass') # ultrasecure\n\npackage { 'net-ldap':\n  ensure   =\u003e present,\n  provider =\u003e 'gem'\n}\n\nfile { '/etc/puppetlabs/puppet/ldap_ca.pem':\n  owner  =\u003e 'root',\n  group  =\u003e '0',\n  mode   =\u003e '0644',\n  source =\u003e /path/to/my/ldap/ca.pem,\n}\n\nIni_setting {\n  ensure  =\u003e present,\n  section =\u003e 'master',\n  path    =\u003e '/etc/puppetlabs/puppet/puppet.conf',\n}\n\nini_setting { 'ldapserver':\n  setting =\u003e 'ldapserver',\n  value   =\u003e 'ldap.example.com',\n}\n\nini_setting { 'ldapport':\n  setting =\u003e 'ldapport',\n  value   =\u003e '636',\n}\n\nini_setting { 'ldapbase':\n  setting =\u003e 'ldapbase',\n  value   =\u003e $ldap_base,\n}\n\nini_setting { 'ldapuser':\n  setting =\u003e 'ldapuser',\n  value   =\u003e $ldap_user,\n}\n\nini_setting { 'ldappassword':\n  setting =\u003e 'ldappassword',\n  value   =\u003e $ldap_pass,\n}\n\nini_setting { 'ldaptls':\n  setting =\u003e 'ldaptls',\n  value   =\u003e true,\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Fpuppet-ldapquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoxpupuli%2Fpuppet-ldapquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Fpuppet-ldapquery/lists"}