Getting Started

Installation

Prerequisites

To get up and running, the following must be installed:

  • python 2.7.x
  • python-dev
  • libsasl2-dev
  • libldap2-dev
  • libyaml-dev

pip

From the top-level directory of the cloned repository:

pip install .

Note

This is typically performed with an active python virtual environment.

And for optional document generation with sphinx, install the following python packages as well:

pip install sphinx
pip install pygments
pip install sphinx_rtd_theme
pip install sphinx-argparse
pip install mock

TLS

pudl only communicates with Active Directory over TLS and by default, the remote server must meet strict criteria such as the commonname matching the hostname in the LDAP URL, and the remote server must present a certificate that is signed by a trusted authority.

Adding a trusted CA to a Linux system varies by distribution, but is rather simple with ubuntu:

  1. Copy the CA certificate (.CER format) to /usr/share/ca-certificates/extra/
  2. chown the CA certificate to root.root and chmod it to 444
  3. Run sudo dpkg-reconfigure ca-certificates

If the only requirement is an encrypted channel and not verifying the identity of the remote server, the ADQuery constructor takes a tls_no_verify parameter, and the pudl CLI has a –tls-no-verify argument. Use these options with caution.

Basic Usage

Pull a user object (bhodges) and a few attributes to print out:

#! /usr/bin/env python

import sys
from pudl import *
from pudl.ad_query import ADQuery
from pudl.ad_user import ADUser

BASE_DN = 'OU=Departments,DC=example,DC=com'
LDAP_USER = 'jdupont'
PASSWORD = 'my_secret'

def main():
    """
    """
    adq = ADQuery(user=LDAP_USER, password=PASSWORD)
    adu = ADUser(adq)
    users = adu.users(base_dn=BASE_DN, attributes=['samaccountname', 'cn',
                      'title',], samaccountnames=['bhodges',])

    for user in users:
        print '{0}: {1}, {2}'.format(user.samaccountname, user.cn, user.title)

if __name__ == '__main__':
    sys.exit(main())

For additional usage examples, reviewing the pudl cli source is recommended

Why is this package named pudl?

While pronounced like “puddle”, the name is loosely related to ‘pudl’.replace(‘u’, ‘a’)[::-1].