more branding, some doc fixes (client done)
This commit is contained in:
Mark Cavage
parent
d33e7cc26a
commit
cffaab7730
docs
|
|
@ -1,7 +1,8 @@
|
|||
<div id="footer">
|
||||
<p class='copy'>Copyright © 2011 <a href="https://github.com/mcavage">Mark Cavage</a></p>
|
||||
</div>
|
||||
</div> <!-- end of #main -->
|
||||
</div> <!-- end of #wrapper -->
|
||||
|
||||
|
||||
<script type="text/javascript" charset="utf-8">
|
||||
$(function () {
|
||||
$("#toc").click(function(event) {
|
||||
|
|
|
|||
|
|
@ -165,10 +165,13 @@ body {
|
|||
#content {
|
||||
position: relative;
|
||||
top: 200px;
|
||||
height: 100%;
|
||||
overflow: auto;
|
||||
padding-bottom: 200px;
|
||||
}
|
||||
#footer {
|
||||
position: relative;
|
||||
padding-top: 60px;
|
||||
}
|
||||
|
||||
|
||||
/* ---- base styles */
|
||||
|
||||
|
|
@ -297,6 +300,11 @@ pre.shell code::before {
|
|||
display: inline;
|
||||
}
|
||||
|
||||
.copy {
|
||||
font-size: 16px;
|
||||
text-align: center;
|
||||
color: #111;
|
||||
}
|
||||
|
||||
/* ----- top header */
|
||||
a#homelink:link {
|
||||
|
|
@ -366,7 +374,7 @@ a#homelink:hover {
|
|||
margin-left: 24px;
|
||||
}
|
||||
#githubfork {
|
||||
position: absolute;
|
||||
position: fixed;
|
||||
top: 0;
|
||||
left: 552px;
|
||||
right: 0px;
|
||||
}
|
||||
|
|
|
|||
100
docs/client.md
100
docs/client.md
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
title: ldapjs
|
||||
brand: spartan
|
||||
markdown2extras: wiki-tables
|
||||
logo-color: green
|
||||
logo-font-family: google:Aldrich, Verdana, sans-serif
|
||||
|
|
@ -9,8 +8,8 @@ header-font-family: google:Aldrich, Verdana, sans-serif
|
|||
|
||||
# Overview
|
||||
|
||||
This documents the ldapjs client API; this assumes that you are familiar with
|
||||
LDAP, so if you're not, hit the [guide](http://ldapjs.org/guide.html) first.
|
||||
This document covers the ldapjs client API and assumes that you are familiar
|
||||
with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
|
||||
|
||||
# Create a client
|
||||
|
||||
|
|
@ -21,13 +20,14 @@ The code to create a new client looks like:
|
|||
});
|
||||
|
||||
You can use `ldap://` or `ldaps://`; the latter would connect over SSL (note
|
||||
this will not use the LDAP TLS extended operation, but literally an SSL
|
||||
connection to port 636, as in LDAP v2). Full list of options:
|
||||
that this will not use the LDAP TLS extended operation, but literally an SSL
|
||||
connection to port 636, as in LDAP v2). The full set of options to create a
|
||||
client is:
|
||||
|
||||
||url|| a valid LDAP url||
|
||||
||socketPath|| If you're running an LDAP server over a Unix Domain Socket, use this||
|
||||
||log4js|| You can optionally pass in a log4js instance that the client will get a logger from. You'll need to set the level to `TRACE` To get any output from the client||
|
||||
||numConnections||The size of the connection pool. Default is 1||
|
||||
||url|| a valid LDAP url.||
|
||||
||socketPath|| If you're running an LDAP server over a Unix Domain Socket, use this.||
|
||||
||log4js|| You can optionally pass in a log4js instance the client will use to acquire a logger. The client logs all messages at the `Trace` level.||
|
||||
||numConnections||The size of the connection pool. Default is 1.||
|
||||
|
||||
## Connection management
|
||||
|
||||
|
|
@ -35,11 +35,11 @@ If you'll recall, the LDAP protocol is connection-oriented, and completely
|
|||
asynchronous on a connection (meaning you can send as many requests as you want
|
||||
without waiting for responses). However, our friend `bind` is a little
|
||||
different in that you generally want to wait for binds to be completed since
|
||||
subsequent operations assume that level of priviledge.
|
||||
subsequent operations assume that level of privilege.
|
||||
|
||||
The ldapjs client deals with this by maintaing a connection pool, and splaying
|
||||
requests across that connection pool, with the exception of `bind` and `unbind`,
|
||||
which it will apply to all connections in the pool. By default a client will
|
||||
which it will apply to all connections in the pool. By default, a client will
|
||||
have one connection in the pool (since it's async already, you don't always need
|
||||
the complexity of a pool). And after that, the operations in the client are
|
||||
pretty much a mapping of the LDAP C API, but made higher-level, so they make
|
||||
|
|
@ -47,23 +47,25 @@ sense in JS.
|
|||
|
||||
## Common patterns
|
||||
|
||||
The last two parameters in every api are `controls` and `callback`. `controls`
|
||||
can be either a single instance of a `Control` or an array of `Control`. You
|
||||
can, and probably will, omit this option.
|
||||
The last two parameters in every API are `controls` and `callback`. `controls`
|
||||
can be either a single instance of a `Control` or an array of `Control` objects.
|
||||
You can, and probably will, omit this option.
|
||||
|
||||
Almost every operation has the callback form of `function(err, res)` where err
|
||||
will be an instance of an ldapjs Error (you can use `instanceof` to switch).
|
||||
will be an instance of an `LDAPError` (you can use `instanceof` to switch).
|
||||
You probably won't need to check the `res` parameter, but it's there if you do.
|
||||
|
||||
# bind
|
||||
`bind(dn, password, controls,callback)`
|
||||
|
||||
Performs a bind operation against the LDAP server.
|
||||
|
||||
The bind API only allows LDAP 'simple' binds (equivalent to HTTP Basic
|
||||
Authentication) for now. Note that all client APIs can optionally take an array
|
||||
of `Control` objects. You probably don't need them though...
|
||||
|
||||
If you have > 1 connection in the connection pool, you'll be called back after
|
||||
*all* of the connections are bound, not just the first one.
|
||||
If you have more than 1 connection in the connection pool, you will be called
|
||||
back after *all* of the connections are bound, not just the first one.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -74,6 +76,8 @@ Example:
|
|||
# add
|
||||
`add(dn, entry, controls, callback)`
|
||||
|
||||
Performs an add operation against the LDAP server.
|
||||
|
||||
Allows you to add an entry (which is just a plain JS object), and as always,
|
||||
controls are optional.
|
||||
|
||||
|
|
@ -92,8 +96,8 @@ Example:
|
|||
# compare
|
||||
`compare(dn, attribute, value, controls, callback)`
|
||||
|
||||
Performs an LDAP compare with the given attribute and value against the entry
|
||||
referenced by dn.
|
||||
Performs an LDAP compare operation with the given attribute and value against
|
||||
the entry referenced by dn.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -119,8 +123,8 @@ Example:
|
|||
`exop(name, value, controls, callback)`
|
||||
|
||||
Performs an LDAP extended operation against an LDAP server. `name` is typically
|
||||
going to be an OID (well, the RFC says it must be. ldapjs has no such
|
||||
restriction). Value is completely arbitrary, and is whatever the exop says it
|
||||
going to be an OID (well, the RFC says it must be; however, ldapjs has no such
|
||||
restriction). `value` is completely arbitrary, and is whatever the exop says it
|
||||
should be.
|
||||
|
||||
Example (performs an LDAP 'whois' extended op):
|
||||
|
|
@ -135,8 +139,8 @@ Example (performs an LDAP 'whois' extended op):
|
|||
`modify(name, changes, controls, callback)`
|
||||
|
||||
Performs an LDAP modify operation against the LDAP server. This API requires
|
||||
you to pass in a `Change` object, which is described below. Note you can pass
|
||||
in a single `Change` or an array of `Change`.
|
||||
you to pass in a `Change` object, which is described below. Note that you can
|
||||
pass in a single `Change` or an array of `Change` objects.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -153,13 +157,13 @@ Example:
|
|||
|
||||
## Change
|
||||
|
||||
A Change object maps to the LDAP protocol of a modify change, and requires you
|
||||
A `Change` object maps to the LDAP protocol of a modify change, and requires you
|
||||
to set the `operation` and `modification`. The `operation` is a string, and
|
||||
must be one of:
|
||||
|
||||
||replace||Replaces the attribute referenced in `modification`. If the modification has no values, is equivalent to a delete||
|
||||
||add||Adds the attribute value(s) referenced in `modification`. The attribute may or may not already exist||
|
||||
||delete||Deletes all the attribute (and all values) referenced in `modification`||
|
||||
||replace||Replaces the attribute referenced in `modification`. If the modification has no values, it is equivalent to a delete.||
|
||||
||add||Adds the attribute value(s) referenced in `modification`. The attribute may or may not already exist.||
|
||||
||delete||Deletes the attribute (and all values) referenced in `modification`.||
|
||||
|
||||
`modification` is just a plain old JS object with the values you want.
|
||||
|
||||
|
|
@ -169,10 +173,10 @@ must be one of:
|
|||
Performs an LDAP modifyDN (rename) operation against an entry in the LDAP
|
||||
server. A couple points with this client API:
|
||||
|
||||
* There is no ability to set "keep old dn". It's always going to flag the old
|
||||
* There is no ability to set "keep old dn." It's always going to flag the old
|
||||
dn to be purged.
|
||||
* The client code will automagically figure out if the request is a "new
|
||||
superior" request (new superior means move to a different part of the tree,
|
||||
superior" request ("new superior" means move to a different part of the tree,
|
||||
as opposed to just renaming the leaf).
|
||||
|
||||
Example:
|
||||
|
|
@ -184,20 +188,23 @@ Example:
|
|||
# search
|
||||
`search(base, options, controls, callback)`
|
||||
|
||||
The search operation is more complex than the operations, so this one takes
|
||||
an options object for all the parameters. However, ldapjs makes some defaults
|
||||
for you so that if you pass nothing in, it's pretty much equivalent to an HTTP
|
||||
GET operation (i.e., base search against the DN, filter set to always match).
|
||||
Performs a search operation against the LDAP server.
|
||||
|
||||
The search operation is more complex than the other operations, so this one
|
||||
takes an `options` object for all the parameters. However, ldapjs makes some
|
||||
defaults for you so that if you pass nothing in, it's pretty much equivalent
|
||||
to an HTTP GET operation (i.e., base search against the DN, filter set to
|
||||
always match).
|
||||
|
||||
Like every other operation, `base` is a DN string. Options has the following
|
||||
fields:
|
||||
|
||||
||scope||One of `base`, `one`, or `sub`. Defaults to `base`||
|
||||
||filter||A string version of an LDAP filter (see below), or a programatically constructed `Filter` object. Defaults to `(objectclass=*)`||
|
||||
||attributes||attributes to select and return (if these are set, the server will return *only* these attributes). Defaults to the empty set, which means all attributes||
|
||||
||attrsOnly||boolean on whether you want the server to only return the names of the attributes, and not their values. Borderline useless. Defaults to false||
|
||||
||sizeLimit||the maximum number of entries to return. Defaults to 0 (unlimited)||
|
||||
||timeLimit||the maximum amount of time the server should take in responding, in seconds. Defaults to 10. Lots of servers will ignore this||
|
||||
||scope||One of `base`, `one`, or `sub`. Defaults to `base`.||
|
||||
||filter||A string version of an LDAP filter (see below), or a programatically constructed `Filter` object. Defaults to `(objectclass=*)`.||
|
||||
||attributes||attributes to select and return (if these are set, the server will return *only* these attributes). Defaults to the empty set, which means all attributes.||
|
||||
||attrsOnly||boolean on whether you want the server to only return the names of the attributes, and not their values. Borderline useless. Defaults to false.||
|
||||
||sizeLimit||the maximum number of entries to return. Defaults to 0 (unlimited).||
|
||||
||timeLimit||the maximum amount of time the server should take in responding, in seconds. Defaults to 10. Lots of servers will ignore this.||
|
||||
|
||||
Responses from the `search` method are an `EventEmitter` where you will get a
|
||||
notification for each search entry that comes back from the server. You will
|
||||
|
|
@ -205,7 +212,7 @@ additionally be able to listen for an `error` and `end` event. Note that the
|
|||
`error` event will only be for client/TCP errors, not LDAP error codes like the
|
||||
other APIs. You'll want to check the LDAP status code (likely for `0`) on the
|
||||
`end` event to assert success. LDAP search results can give you a lot of status
|
||||
codes, such as time or size exceeded, busy, inappropriate matching, etc., etc.,
|
||||
codes, such as time or size exceeded, busy, inappropriate matching, etc.,
|
||||
which is why this method doesn't try to wrap up the code matching.
|
||||
|
||||
Example:
|
||||
|
|
@ -232,7 +239,7 @@ Example:
|
|||
## Filter Strings
|
||||
|
||||
The easiest way to write search filters is to write them compliant with RFC2254,
|
||||
which is the "The string representation of LDAP search filters". Note that
|
||||
which is "The string representation of LDAP search filters." Note that
|
||||
ldapjs doesn't support extensible matching, since it's one of those features
|
||||
that almost nobody actually uses in practice.
|
||||
|
||||
|
|
@ -244,14 +251,13 @@ for an attribute `email` with a value of `foo@bar.com`. The syntax would be:
|
|||
|
||||
(email=foo@bar.com)
|
||||
|
||||
Note that ldapjs requires all filters to be surrounded by '()' blocks. Ok, that
|
||||
was easy. Let's now assume you want to find all records where the email is
|
||||
actually just anything in the @bar.com domain, and the location attribute is set
|
||||
to Seattle:
|
||||
ldapjs requires all filters to be surrounded by '()' blocks. Ok, that was easy.
|
||||
Let's now assume you want to find all records where the email is actually just
|
||||
anything in the "@bar.com" domain, and the location attribute is set to Seattle:
|
||||
|
||||
(&(email=*@bar.com)(l=Seattle))
|
||||
|
||||
Ok, so now our filter is actually three LDAP filters. We have an `and` filter,
|
||||
Now our filter is actually three LDAP filters. We have an `and` filter,
|
||||
an `equality` filter (the l=Seattle), and a `substring` filter. Substrings are
|
||||
wildcard filters. Now, let's say we want to also set our filter to include a
|
||||
specification that either the employeeType *not* be a manager or a secretary:
|
||||
|
|
@ -264,6 +270,8 @@ find almost anything you're looking for.
|
|||
# unbind
|
||||
`unbind(callback)`
|
||||
|
||||
Performs an unbind operation against the LDAP server.
|
||||
|
||||
The unbind operation takes no parameters other than a callback, and will unbind
|
||||
(and disconnect) *all* of the connections in the pool.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@ header-font-family: google:Aldrich, Verdana, sans-serif
|
|||
|
||||
# Overview
|
||||
|
||||
This documents the ldapjs DN API; this assumes that you are familiar with
|
||||
LDAP, so if you're not, hit the [guide](http://ldapjs.org/guide.html) first.
|
||||
This document covers the ldapjs DN API and assumes that you are familiar
|
||||
with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
|
||||
|
||||
DNs are LDAP distinguished names, and are composed of a set of RDNs (relative
|
||||
distinguished names). [RFC2253](http://www.ietf.org/rfc/rfc2253.txt) has the
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@ header-font-family: google:Aldrich, Verdana, sans-serif
|
|||
|
||||
# Overview
|
||||
|
||||
This documents the ldapjs Errors API; this assumes that you are familiar with
|
||||
LDAP, so if you're not, hit the [guide](http://ldapjs.org/guide.html) first.
|
||||
This document covers the ldapjs errors API and assumes that you are familiar
|
||||
with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
|
||||
|
||||
All errors in the ldapjs framework extend from an abstract error type called
|
||||
`LDAPError`. In addition to the properties listed below, all errors will have
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@ header-font-family: google:Aldrich, Verdana, sans-serif
|
|||
|
||||
# Overview
|
||||
|
||||
This documents the ldapjs server API; this assumes that you are familiar with
|
||||
LDAP, so if you're not, hit the [guide](http://ldapjs.org/guide.html) first.
|
||||
This document covers the ldapjs filters API and assumes that you are familiar
|
||||
with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
|
||||
|
||||
LDAP search filters are really the backbone of LDAP search operations, and
|
||||
ldapjs tries to get you in "easy" with them if your dataset is small, and also
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@ header-font-family: google:Aldrich, Verdana, sans-serif
|
|||
|
||||
# Overview
|
||||
|
||||
This documents the ldapjs server API; this assumes that you are familiar with
|
||||
LDAP, so if you're not, hit the [guide](http://ldapjs.org/guide.html) first.
|
||||
This document covers the ldapjs server API and assumes that you are familiar
|
||||
with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
|
||||
|
||||
# Create a server
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue