verdnatura-mirror
/
node-ldapjs
mirror of https://github.com/ldapjs/node-ldapjs.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

First steps toward updating the docs

This commit is contained in:
Patrick Mooney 2015-10-16 00:25:49 -05:00
parent 9ec1e9022d
commit 622b7486f7
16 changed files with 514 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
Makefile
View File

@ -23,16 +23,8 @@ TAP := ./node_modules/.bin/tap
# #
# Files # Files
# #
DOC_FILES = client.md \ DOC_FILES := $(shell find docs -name '*.md' -printf '%f\n')
dn.md \ RESTDOWN_FLAGS := -b docs/branding/
errors.md \
examples.md \
filters.md \
guide.md \
index.md \
persistent_search.md \
server.md
JS_FILES := $(shell find lib test -name '*.js') $(shell find bin -name 'ldapjs-*') JS_FILES := $(shell find lib test -name '*.js') $(shell find bin -name 'ldapjs-*')
JSL_CONF_NODE = tools/jsl.node.conf JSL_CONF_NODE = tools/jsl.node.conf
JSL_FILES_NODE = $(JS_FILES) JSL_FILES_NODE = $(JS_FILES)

2
deps/restdown vendored

@ -1 +1 @@
Subproject commit 14131f6b33bf45a04b4c66e388d0ce1f3e5b55ef Subproject commit 34a843cfce0ff988bf5073706882722a61036786

80
docs/branding/footer.html.in
View File

@ -1,52 +1,46 @@
<div id="footer">
<p class='copy'>Copyright &copy; 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"> <script type="text/javascript" charset="utf-8">
$(function () { $(function() {
$("#toc").click(function(event) { var headerHeight = $("#header").height();
// This to ensure clicks in the #toc don't make it up to the var offsets = [];
// button handler. var current = -1;
event.stopPropagation();
}); function endpoint(scrollDistance) {
$("#toc a").click(function(event) { if (scrollDistance < offsets[0]) {
$("#tocbutton").click(); return -1;
})
$("#tocbutton").click(function(event) {
var target = $("#toc");
if (target.css("display") !== "block") {
$("body").bind("click.tocCloser", function(event) {
$("#tocbutton").click();
event.stopPropagation();
});
} else { } else {
$("body").unbind("click.tocCloser"); for (var id = offsets.length; id > 0; id--) {
if (scrollDistance > offsets[id - 1]) {
return id - 1;
break;
}
}
} }
target.slideToggle(100); }
event.stopPropagation();
$("h2").each(function(i) {
offsets.push($(this).offset().top - headerHeight)
}); });
$("#api").click(function(event) { $("#content").append('<h2 class="fixed" style="display: none"><span>&nbsp;</span></h2>');
// This to ensure clicks in the #api don't make it up to the var fixed_h2 = $("h2.fixed");
// button handler. var fixed_span = $("h2.fixed span");
event.stopPropagation();
}); $("#content").scroll(function() {
$("#api a").click(function(event) { var scrollDistance = $("#content").attr('scrollTop');
$("#apibutton").click(); var now = endpoint(scrollDistance);
})
$("#apibutton").click(function(event) { if (now !== current) {
var target = $("#api"); $("#sidebar li").removeClass("current");
if (target.css("display") !== "block") { current = now;
$("body").bind("click.apiCloser", function(event) { if (current < 0) {
$("#apibutton").click(); fixed_h2.hide();
event.stopPropagation(); } else if (current >= 0) {
}); var heading = $($("h2 span")[current]).text();
} else { $("#sidebar a[href|=#" + heading.replace(' ', '-') + "]").parent().addClass("current");
$("body").unbind("click.apiCloser"); fixed_span.text(heading);
fixed_h2.show();
}
} }
target.slideToggle(100);
event.stopPropagation();
}); });
}); });
</script> </script>

75
docs/branding/header.html.in
View File

@ -1,57 +1,32 @@
<!DOCTYPE html> <!DOCTYPE html>
<html lang="en"> <html lang="en">
<head> <head>
<title>%(title)s</title> <title>%(title)s</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="%(mediaroot)s/css/style.css"> <link rel="stylesheet" type="text/css" href="%(mediaroot)s/css/restdown.css">
%(doc_style)s <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="media/js/jquery-1.4.2.min.js"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-25326304-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head> </head>
<body> <body>
<div id="wrapper">
<div id="main">
<div id="fadeout"></div>
<div id="header"> <div id="header">
<span id="logo"> <h1>%(title)s Documentation</h1>
<a id="homelink" href="http://ldapjs.org">ldapjs</a> </div>
</span> <div id="sidebar">
<a class="navbutton" href="guide.html">Guide</a> <div>Sections</div>
<span>
<span id="apibox"> <ul>
<span id="apibutton" class="navbutton">API</span> <li><div><a href="index.html">Home</a></div></li>
<div id="api" class="popup" style="display: none"> <li><div><a href="guide.html">Guide</a></div></li>
<ul> <li><div><a href="examples.html">Examples</a></div></li>
<li><div><a href="server.html">server</a></div></li> <li><div><a href="client.html">Client API</a></div></li>
<li><div><a href="client.html">client</a></div></li> <li><div><a href="server.html">Server API</a></div></li>
<li><div><a href="dn.html">dn</a></div></li> <li><div><a href="dn.html">DN API</a></div></li>
<li><div><a href="filters.html">filters</a></div></li> <li><div><a href="filters.html">Filters API</a></div></li>
<li><div><a href="errors.html">errors</a></div></li> <li><div><a href="errors.html">Error API</a></div></li>
<li><div><a href="examples.html">examples</a></div></li> </ul>
</ul> </span>
</div>
</span> <div>Contents</div>
</span>
<span id="tocbox"> %(toc_html)s
<span id="tocbutton" class="navbutton">Page Contents</span>
<div id="toc" class="popup" style="display: none">
%(toc_html)s
</div>
</span>
<a id="githubfork" href="http://github.com/mcavage/node-ldapjs">
<img src="https://a248.e.akamai.net/assets.github.com/img/abad93f42020b733148435e2cd92ce15c542d320/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677265656e5f3030373230302e706e67"
alt="Fork me on GitHub">
</a>
</div> </div>

325
docs/branding/media/css/restdown.css Normal file
View File

@ -0,0 +1,325 @@
/* ---- general styles */
body {
font: 13px "Lucida Grande", "Lucida Sans Unicode", arial, sans-serif;
line-height: 1.53846; /* 20px */
color: #4a3f2d;
}
:focus {
outline: 0;
}
h1,h2,h3 {
font-weight:normal;
}
h3{
margin-bottom:0;
}
ul, li {
margin:0px;
padding:0px;
}
ul {
margin-left:40px;
}
ul > li {
list-style:disc;
list-style-position:inside;
margin:10px 0px;
}
hr {
border:none;
width:98%;
margin-left:-10px;
border-top:1px solid #CCCCCC;
border-bottom:1px solid #FFFFFF;
}
code,
pre {
border:1px solid #CCCCCC;
background:#F2F0EE;
-webkit-border-radius:2px;
-moz-border-radius:2px;
border-radius:2px;
white-space:pre-wrap;
}
code {
padding: 0 0.2em;
}
pre {
margin: 1em 0;
padding: .75em;
overflow: auto;
padding:10px 1.2em;
margin-top:0;
margin-bottom:20px;
}
pre code {
border: medium none;
padding: 0;
}
a code {
text-decoration: underline;
}
a {
color:#FD6512;
text-decoration:none;
}
h4 {
font-size: 85%;
margin: 0;
padding: 0;
line-height: 1em;
display: inline;
}
/* ---- custom classes */
pre.shell,
pre.shell code {
background:#444;
color:#fff;
border-width:0px;
}
pre.shell code::before {
content: '$ ';
display: inline;
}
/* ---- header and sidebar */
#header {
background:#C3BDB3;
background:#1C313C;
height:66px;
left:0px;
position:absolute;
top:0px;
width:100%;
z-index:1;
font-size:0.7em;
}
#header h1 {
width: 424px;
height: 35px;
display:block;
background: url(../img/logo.svg) no-repeat;
line-height:2.1em;
padding:0;
padding-left:140px;
margin-top:18px;
margin-left:20px;
color:white;
text-transform: uppercase;
}
#sidebar {
background-color:#EDEBEA;
bottom:0px;
left:0px;
overflow:auto;
padding:20px 0px 0px 15px;
position:absolute;
top:66px;
width:265px;
z-index:1;
}
#content {
top:64px;
bottom:0px;
right:0px;
left:290px;
padding:20px 30px 400px;
position:absolute;
overflow:auto;
z-index:0;
}
#sidebar .vertical_divider {
background-color:#FFFFFF;
bottom:0px;
position:absolute;
top:0px;
right:0px;
width:1px;
}
#sidebar h1 {
font-size:1.2em;
padding:0px;
margin-top:15px;
margin-bottom:3px;
}
#sidebar ul {
margin:3px 0 10px 0;
}
#sidebar ul ul {
margin:3px 0 5px 10px;
}
#sidebar li {
margin:0;
padding:0;
font-size:0.9em;
}
#sidebar li,
#sidebar li a {
color:#5C5954;
list-style:none;
padding:1px 0px 1px 2px;
}
#sidebar li span.verb {
color:#aaa;
padding:2px 3px 0px;
width:30px;
display:block;
float:left;
font-size:9px;
font-family:verdana;
-moz-border-radius:3px;
-webkit-border-radius:3px;
margin-left:0px;
margin-right:5px;
}
#sidebar li.current {
background-repeat: no-repeat;
background-position:right;
}
/* ---- intro */
.intro {
color:#29231A;
padding: 22px 25px;
background: #EDEBEA;
-webkit-border-radius: 5px;
-moz-border-radius: 5px;
-o-border-radius: 5px;
border-radius: 5px;
margin-bottom:40px;
}
.intro pre.base {
background:#444;
color:#29231A;
color:#fff;
border-color:#fff;
font-size:1.5em;
}
.intro h1 {
color: #1C313C;
}
.intro h3 {
margin: 5px 0px 3px;
font-size: 100%;
font-weight: bold;
}
.intro ul {
list-style-type:disc;
padding-left:20px;
margin-left:0;
}
.intro ul li{
margin:0;
}
.intro p {
padding-left:20px;
margin: 5px 0px 3px;
}
h2 {
overflow: auto;
margin-top: 60px;
border-top: 2px solid #979592;
z-index: 3;
}
h1 + h2 {
margin-top: 0px;
}
h2.fixed {
position:fixed;
margin-top: 0;
border-top:none;
right:45px;
top:66px;
}
h2 span {
background: #979592;
float:right;
color:#fff;
margin:0;
margin-left:3px;
padding:0.3em 0.7em;
font-size: 0.55em;
word-spacing: 0.8em; /* separate verb from path */
color:#fff;
}
/*---- print media */
@media print {
body { background:white; color:black; margin:0; }
#sidebar {
display: none;
}
#content {
position: relative;
padding: 5px;
left: 0px;
top: 0px;
}
h1, h2, h4 {
page-break-after: avoid;
}
pre {
page-break-inside: avoid;
}
}
/* tables still need cellspacing="0" in the markup */
table {
border-collapse:collapse; border-spacing:0;
margin: 20px 0;
}
th,
td {
border: solid #aaa;
border-width: 1px 0;
line-height: 23px;
padding: 0 12px;
text-align: left;
vertical-align: text-bottom;
}
th {
border-collapse: separate;
}
tbody tr:nth-child(odd) {
background-color: #f2f0ee;
}

1
docs/branding/media/img/logo.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="125" height="34.1" viewBox="0 0 146.25 39.96"><defs><path d="M-2.21-3.96h150v45.93h-150z"/><clipPath><use xlink:href="#a" overflow="visible"/></clipPath><clipPath><use xlink:href="#c-4" overflow="visible"/></clipPath></defs><clipPath><use xlink:href="#a" overflow="visible"/></clipPath><g clip-path="url(#b-8)" fill="#f60"><defs><path d="m-2.21-3.96 150 0 0 45.93-150 0z"/></defs><clipPath><use xlink:href="#c-4" overflow="visible" x="0" y="0" width="100" height="100"/></clipPath><path d="m15.74 31.29c8.61 0 15.6-6.98 15.6-15.59C31.34 7.08 24.35 0.1 15.74 0.1 7.13 0.1 0.14 7.08 0.14 15.7c0 8.61 6.98 15.6 15.6 15.6" style="fill-rule:evenodd;fill:#f60"/><path d="m12.96 7.35c0-0.32 0.26-0.59 0.59-0.59l4.38 0c0.33 0 0.59 0.26 0.59 0.59l0 5.57 5.57 0c0.33 0 0.59 0.26 0.59 0.59l0 4.38c0 0.33-0.26 0.59-0.59 0.59l-5.57 0 0 5.57c0 0.33-0.26 0.59-0.59 0.59l-4.37 0c-0.32 0-0.59-0.26-0.59-0.59l0-5.57-5.57 0c-0.32 0-0.59-0.26-0.59-0.59l0-4.37c0-0.32 0.26-0.59 0.59-0.59l5.57 0z" style="fill-rule:evenodd;fill:#fff"/></g><g clip-path="url(#b)" fill="#fff"><defs><path d="m-2.21-3.96 150 0 0 45.93-150 0z"/></defs><clipPath><use height="100" width="100" y="0" x="0" overflow="visible" xlink:href="#c"/></clipPath><path d="m35.84 25.26c1.22 0.94 2.63 1.81 4.52 1.81 2.87 0 3.62-1.73 3.62-4.01l0-19.96 3.11 0 0 16.27c0 1.42 0 2.95-0.08 4.36-0.16 3.77-2.08 5.97-6.52 5.97-3.06 0-5.31-1.26-6.21-2.24zm29.51-5.7c0-4.72-1.37-8.02-5.19-8.02-3.73 0-5.42 3.14-5.42 7.39 0 3.89 0.79 8.49 5.27 8.49 3.73 0 5.35-3.57 5.35-7.86M60.41 9.14c2.71 0 8.06 0.87 8.06 9.75 0 7.66-3.81 10.89-8.72 10.89-4.99 0-8.06-3.38-8.06-10.45 0-8.13 4.83-10.18 8.72-10.18m26.88 19.3 0-18.74-2.99 0 0 11.71c0 2.71-1.81 4.6-4.79 4.6-4.17 0-4.44-2.28-4.44-5.27l0-11.04-3.06 0 0 11.87c0 4.48 2.16 6.09 5.5 6.45-1.93 1.26-4.32 3.54-4.32 6.72 0 3.03 1.93 4.95 5.93 4.95 4.17 0 6.68-2 7.66-5.82 0.35-1.38 0.51-3.69 0.51-5.42m-7.86 8.88c3.58 0 4.83-3.1 4.83-7.39l0-3.42c-4.72 1.97-8.13 4.09-8.13 7.82 0 1.93 1.14 2.99 3.3 2.99M99.94 9.14c-5.97 0-9.12 4.79-9.12 10.61 0 5.86 2.59 10.02 8.72 10.02 3.14 0 5.42-1.41 6.41-2.24l-1.18-2c-0.75 0.55-2.4 1.81-5.03 1.81-4.16 0-5.74-3.38-5.89-6.6l1.02 0.04c3.81 0 10.81-0.94 10.81-6.76 0-2.91-2.08-4.87-5.74-4.87m-0.16 2.28c-4.2 0-5.82 3.97-5.93 7.07l0.79 0.04c2.67 0 8.17-0.63 8.17-4.17 0-1.85-1.26-2.95-3.03-2.95m13.01 17.8 0-12.81c0-2.36 2.28-4.83 5.31-4.83 3.3 0 3.93 2.36 3.93 5.27l0 12.38 3.07 0 0-13.32c0-4.48-2.2-6.76-6.25-6.76-2.56 0-4.83 1.18-6.33 3.38l-0.35-2.83-2.63 0 0.2 2.95 0 16.58 3.07 0zm16.82-27.31 0 21.97c0 2.87 0.16 5.9 5.38 5.9 1.57 0 3.3-0.51 4.44-1.3l-0.9-2.04c-0.67 0.39-1.65 0.94-2.99 0.94-1.85 0-2.87-0.82-2.87-3.42l0-11.63 5.58 0 0-2.63-5.58 0 0-7.78zm12.22 1.8c0 1.14 0.91 1.99 2 1.99 1.08 0 1.99-0.85 1.99-1.99 0-1.12-0.91-1.97-1.99-1.97-1.09 0-2 0.85-2 1.97m0.36 0c0-0.95 0.71-1.68 1.64-1.68 0.92 0 1.63 0.73 1.63 1.68 0 0.97-0.71 1.7-1.63 1.7-0.93 0-1.64-0.73-1.64-1.7m0.86 1.17 0.36 0 0-1 0.38 0 0.63 1 0.39 0-0.66-1.02c0.35-0.04 0.61-0.21 0.61-0.63 0-0.44-0.26-0.66-0.81-0.66l-0.9 0 0 2.32zm0.36-2.02 0.48 0c0.24 0 0.51 0.05 0.51 0.36 0 0.37-0.29 0.38-0.61 0.38l-0.38 0z" clip-path="url(#d)" style="fill-rule:evenodd;fill:#fff"/></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 3.2 KiB

66
docs/client.md
View File

@ -1,15 +1,12 @@
--- ---
title: Client API | ldapjs title: Client API | ldapjs
markdown2extras: wiki-tables markdown2extras: tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
--- ---
# ldapjs Client API # ldapjs Client API
This document covers the ldapjs client API and assumes that you are familiar 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. with LDAP. If you're not, read the [guide](guide.html) first.
# Create a client # Create a client
@ -25,18 +22,22 @@ 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 connection to port 636, as in LDAP v2). The full set of options to create a
client is: client is:
||url|| a valid LDAP url.|| |Attribute |Description |
||socketPath|| If you're running an LDAP server over a Unix Domain Socket, use this.|| |---------------|-----------------------------------------------------------|
||log|| You can optionally pass in a bunyan instance the client will use to acquire a logger. The client logs all messages at the `trace` level.|| |url |A valid LDAP URL (proto/host/port only) |
||timeout||How long the client should let operations live for before timing out. Default is Infinity.|| |socketPath |Socket path if using AF\_UNIX sockets |
||connectTimeout||How long the client should wait before timing out on TCP connections. Default is up to the OS.|| |log |Bunyan logger instance (Default: built-in instance) |
||tlsOptions||Additional [options](http://nodejs.org/api/tls.html#tls_tls_connect_port_host_options_callback) passed to the TLS connection layer when connecting via `ldaps://`|| |timeout |How long the client should let operations live for before timing out (Default: Infinity)|
|connectTimeout |How long the client should wait before timing out on TCP connections (Default: OS default)|
|tlsOptions |Additional options passed to the TLS connection layer when connecting via `ldaps://` (See: The TLS docs for node.js)|
|idleTimeout |Seconds after last activity before client emits idle event|
|strictDN |Force strict DN parsing for client methods (Default is true)|
## Connection management ## Connection management
As LDAP is a stateful protocol (as opposed to HTTP), having connections torn As LDAP is a stateful protocol (as opposed to HTTP), having connections torn
down from underneath you is difficult to deal with. down from underneath you is can be difficult to deal with. Several mechanisms
have been provided to mitigate this trouble.
## Common patterns ## Common patterns
@ -49,8 +50,11 @@ Almost every operation has the callback form of `function(err, res)` where err
will be an instance of an `LDAPError` (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. You probably won't need to check the `res` parameter, but it's there if you do.
# bind # bind
`bind(dn, password, controls,callback)` `bind(dn, password, controls, callback)`
Performs a bind operation against the LDAP server. Performs a bind operation against the LDAP server.
@ -166,7 +170,7 @@ 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. dn to be purged.
* The client code will automagically figure out if the request is a "new * The client code will automatically 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). as opposed to just renaming the leaf).
@ -192,12 +196,14 @@ Like every other operation, `base` is a DN string.
Options can be a string representing a valid LDAP filter or an object Options can be a string representing a valid LDAP filter or an object
containing the following fields: containing the following fields:
||scope||One of `base`, `one`, or `sub`. Defaults to `base`.|| |Attribute |Description |
||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. You can provide a string if you want a single attribute or an array of string for one or many.|| |scope |One of `base`, `one`, or `sub`. Defaults to `base`.|
||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.|| |filter |A string version of an LDAP filter (see below), or a programatically constructed `Filter` object. Defaults to `(objectclass=*)`.|
||sizeLimit||the maximum number of entries to return. Defaults to 0 (unlimited).|| |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. You can provide a string if you want a single attribute or an array of string for one or many.|
||timeLimit||the maximum amount of time the server should take in responding, in seconds. Defaults to 10. Lots of servers will ignore this.|| |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 Responses from the `search` method are an `EventEmitter` where you will get a
notification for each `searchEntry` that comes back from the server. You will notification for each `searchEntry` that comes back from the server. You will
@ -271,6 +277,24 @@ The `not` character is represented as a `!`, the `or` as a single pipe `|`.
It gets a little bit complicated, but it's actually quite powerful, and lets you It gets a little bit complicated, but it's actually quite powerful, and lets you
find almost anything you're looking for. find almost anything you're looking for.
# starttls
`starttls(options, controls, callback)`
Attempt to secure existing LDAP connection via STARTTLS.
Example:
var opts = {
ca: [fs.readFileSync('mycacert.pem')]
};
client.starttls(opts, function(err, res) {
assert.ifError(err);
// Client communication now TLS protected
});
# unbind # unbind
`unbind(callback)` `unbind(callback)`

33
docs/dn.md
View File

@ -1,15 +1,11 @@
--- ---
title: DN API | ldapjs title: DN API | ldapjs
markdown2extras: wiki-tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
--- ---
# ldapjs DN API # ldapjs DN API
This document covers the ldapjs DN API and assumes that you are familiar 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. with LDAP. If you're not, read the [guide](guide.html) first.
DNs are LDAP distinguished names, and are composed of a set of RDNs (relative 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 distinguished names). [RFC2253](http://www.ietf.org/rfc/rfc2253.txt) has the
@ -81,6 +77,33 @@ argument. `dn` can be a string or a DN.
Returns a DN object that is the direct parent of `this`. If there is no parent Returns a DN object that is the direct parent of `this`. If there is no parent
this can return `null` (e.g. `parseDN('o=example').parent()` will return null). this can return `null` (e.g. `parseDN('o=example').parent()` will return null).
## format(options)
Convert a DN object to string according to specified formatting options. These
options are divided into two types. Preservation Options use data recorded
during parsing to preserve details of the original DN. Modification options
alter string formatting defaults. Preservation options _always_ take
precedence over Modification Options.
Preservation Options:
- `keepOrder`: Order of multi-value RDNs.
- `keepQuote`: RDN values which were quoted will remain so.
- `keepSpace`: Leading/trailing spaces will be output.
- `keepCase`: Parsed attribute name will be output instead of lowercased version.
Modification Options:
- `upperName`: RDN names will be uppercased instead of lowercased.
- `skipSpace`: Disable trailing space after RDN separators
## setFormat(options)
Sets the default `options` for string formatting when `toString` is called.
It accepts the same parameters as `format`.
## toString() ## toString()
Returns the string representation of `this`. Returns the string representation of `this`.

6
docs/errors.md
View File

@ -1,15 +1,11 @@
--- ---
title: Errors API | ldapjs title: Errors API | ldapjs
markdown2extras: wiki-tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
--- ---
# ldapjs Errors API # ldapjs Errors API
This document covers the ldapjs errors API and assumes that you are familiar 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. with LDAP. If you're not, read the [guide](guide.html) first.
All errors in the ldapjs framework extend from an abstract error type called 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 `LDAPError`. In addition to the properties listed below, all errors will have

4
docs/examples.md
View File

@ -1,9 +1,5 @@
--- ---
title: Examples | ldapjs title: Examples | ldapjs
markdown2extras: wiki-tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
--- ---
# ldapjs Examples # ldapjs Examples

17
docs/filters.md
View File

@ -1,15 +1,11 @@
--- ---
title: Filters API | ldapjs title: Filters API | ldapjs
markdown2extras: wiki-tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
--- ---
# ldapjs Filters API # ldapjs Filters API
This document covers the ldapjs filters API and assumes that you are familiar 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. with LDAP. If you're not, read the [guide](guide.html) first.
LDAP search filters are really the backbone of LDAP search operations, and 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 ldapjs tries to get you in "easy" with them if your dataset is small, and also
@ -28,17 +24,6 @@ All Filters in the ldapjs framework extend from `Filter`, which wil have the
property `type` available; this will return a string name for the filter, and property `type` available; this will return a string name for the filter, and
will be one of: will be one of:
||equal||an `EqualityFilter`||
||present||a `PresenceFilter`||
||substring||a `SubstringFilter`||
||ge||a `GreaterThanEqualsFilter`||
||le||a `LessThanEqualsFilter`||
||and||an `AndFilter`||
||or||an `OrFilter`||
||not||a `NotFilter`||
||approx||an `ApproximateMatchFilter` (quasi-supported in ldapjs)||
||ext||an `ExtensibleMatchFilter` (not supported in ldapjs)||
# parseFilter(filterString) # parseFilter(filterString)
Parses an [RFC2254](http://www.ietf.org/rfc/rfc2254.txt) filter string into an Parses an [RFC2254](http://www.ietf.org/rfc/rfc2254.txt) filter string into an

27
docs/guide.md
View File

@ -1,9 +1,6 @@
--- ---
title: LDAP Guide | ldapjs title: LDAP Guide | ldapjs
markdown2extras: wiki-tables markdown2extras: tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
--- ---
# LDAP Guide # LDAP Guide
@ -135,7 +132,7 @@ since we haven't added any support in yet, but go ahead and try it anyway:
$ ldapsearch -H ldap://localhost:1389 -x -b "o=myhost" objectclass=* $ ldapsearch -H ldap://localhost:1389 -x -b "o=myhost" objectclass=*
Before we go any further, note that the complete code for the server we are Before we go any further, note that the complete code for the server we are
about to build up is on the [examples](http://ldapjs.org/examples.html) page. about to build up is on the [examples](examples.html) page.
## Bind ## Bind
@ -237,13 +234,15 @@ for a moment to explain an /etc/passwd record.
The sample record above maps to: The sample record above maps to:
||jsmith||user name.|| |Field |Description |
||x||historically this contained the password hash, but that's usually in /etc/shadow now, so you get an 'x'.|| |-------------------|-----------------------------------|
||1001||the unix numeric user id.|| |jsmith |Username |
||1000||the unix numeric group id. (primary).|| |x |Placeholder for password hash |
||'Joe Smith,...'||the "gecos," which is a description, and is usually a comma separated list of contact details.|| |1001 |Numeric UID |
||/home/jsmith||the user's home directory.|| |1000 |Numeric Primary GID |
||/bin/sh||the user's shell.|| |'Joe Smith,...' |DisplayName |
|/home/jsmith |Home directory |
|/bin/sh |Shell |
Let's write some handlers to parse that and transform it into an LDAP search Let's write some handlers to parse that and transform it into an LDAP search
record (note, you'll need to add `var fs = require('fs');` at the top of the record (note, you'll need to add `var fs = require('fs');` at the top of the
@ -629,8 +628,8 @@ And then run the following command:
# Where to go from here # Where to go from here
The complete source code for this example server is available in The complete source code for this example server is available in
[examples](/examples.html). Make sure to read up on the [server](/server.html) [examples](examples.html). Make sure to read up on the [server](server.html)
and [client](/client.html) APIs. If you're looking for a "drop in" solution, and [client](client.html) APIs. If you're looking for a "drop in" solution,
take a look at [ldapjs-riak](https://github.com/mcavage/node-ldapjs-riak). take a look at [ldapjs-riak](https://github.com/mcavage/node-ldapjs-riak).
[Mozilla](https://wiki.mozilla.org/Mozilla_LDAP_SDK_Programmer%27s_Guide/Understanding_LDAP) [Mozilla](https://wiki.mozilla.org/Mozilla_LDAP_SDK_Programmer%27s_Guide/Understanding_LDAP)

32
docs/index.md
View File

@ -1,9 +1,6 @@
--- ---
title: ldapjs title: ldapjs
markdown2extras: wiki-tables markdown2extras: tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
--- ---
<div id="indextagline"> <div id="indextagline">
@ -15,7 +12,7 @@ Reimagining <a href="http://tools.ietf.org/html/rfc4510" id="indextaglink">LDAP<
ldapjs is a pure JavaScript, from-scratch framework for implementing ldapjs is a pure JavaScript, from-scratch framework for implementing
[LDAP](http://tools.ietf.org/html/rfc4510) clients and servers in [LDAP](http://tools.ietf.org/html/rfc4510) clients and servers in
[Node.js](http://nodejs.org). It is intended for developers used to interacting [Node.js](http://nodejs.org). It is intended for developers used to interacting
with HTTP services in node and [express](http://expressjs.com). with HTTP services in node and [restify](http://restify.com).
var ldap = require('ldapjs'); var ldap = require('ldapjs');
@ -57,22 +54,25 @@ that you can build LDAP over anything you want, not just traditional databases.
$ npm install ldapjs $ npm install ldapjs
If you're new to LDAP, check out the [guide](/guide.html). Otherwise, the If you're new to LDAP, check out the [guide](guide.html). Otherwise, the
API documentation is: API documentation is:
||[server](/server.html)||Reference for implementing LDAP servers.||
||[client](/client.html)||Reference for implementing LDAP clients.|| |Section |Content |
||[dn](/dn.html)||API reference for the DN class.|| |---------------------------|-------------------------------------------|
||[filters](/filters.html)||API reference for LDAP search filters.|| |[Server API](server.html) |Reference for implementing LDAP servers. |
||[errors](/errors.html)||Listing of all ldapjs Error objects.|| |[Client API](client.html) |Reference for implementing LDAP clients. |
||[examples](/examples.html)||Collection of sample/getting started code.|| |[DN API](dn.html) |API reference for the DN class. |
|[Filter API](filters.html) |API reference for LDAP search filters. |
|[Error API](errors.html) |Listing of all ldapjs Error objects. |
|[Examples](examples.html) |Collection of sample/getting started code. |
# More information # More information
||License||[MIT](http://opensource.org/licenses/mit-license.php)|| - License:[MIT](http://opensource.org/licenses/mit-license.php)
||Code||[mcavage/node-ldapjs](https://github.com/mcavage/node-ldapjs)|| - Code: [mcavage/node-ldapjs](https://github.com/mcavage/node-ldapjs)
||node.js version||>=0.6|| - node.js version: >=0.8
||Twitter||[@mcavage](http://twitter.com/mcavage)|| - Twitter: [@pfmooney](http://twitter.com/pfmooney)
# What's not in the box? # What's not in the box?

26
docs/server.md
View File

@ -1,15 +1,12 @@
--- ---
title: Server API | ldapjs title: Server API | ldapjs
markdown2extras: wiki-tables markdown2extras: wiki-tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
--- ---
# ldapjs Server API # ldapjs Server API
This document covers the ldapjs server API and assumes that you are familiar 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. with LDAP. If you're not, read the [guide](guide.html) first.
# Create a server # Create a server
@ -47,8 +44,7 @@ Emitted when the server closes.
## Listening for requests ## Listening for requests
The LDAP server API wraps up and mirrors the node The LDAP server API wraps up and mirrors the node.js `server.listen` family of
[listen](http://nodejs.org/docs/v0.4.11/api/net.html#server.listen) family of
APIs. APIs.
After calling `listen`, the property `url` on the server object itself will be After calling `listen`, the property `url` on the server object itself will be
@ -66,7 +62,7 @@ Example:
Begin accepting connections on the specified port and host. If the host is Begin accepting connections on the specified port and host. If the host is
omitted, the server will accept connections directed to any IPv4 address omitted, the server will accept connections directed to any IPv4 address
(INADDR_ANY). (INADDR\_ANY).
This function is asynchronous. The last parameter callback will be called when This function is asynchronous. The last parameter callback will be called when
the server has been bound. the server has been bound.
@ -90,7 +86,7 @@ calls invoked on it. Additionally, it must be set non-blocking; try
# Routes # Routes
The LDAP server API is meant to be the LDAP-equivalent of the express/sinatra The LDAP server API is meant to be the LDAP-equivalent of the express/restify
paradigm of programming. Essentially every method is of the form paradigm of programming. Essentially every method is of the form
`OP(req, res, next)` where OP is one of bind, add, del, etc. You can chain `OP(req, res, next)` where OP is one of bind, add, del, etc. You can chain
handlers together by calling `next()` and ordering your functions in the handlers together by calling `next()` and ordering your functions in the
@ -112,8 +108,8 @@ caching, etc. that need to be placed in an object.
For example [ldapjs-riak](https://github.com/mcavage/node-ldapjs-riak) is a For example [ldapjs-riak](https://github.com/mcavage/node-ldapjs-riak) is a
complete implementation of the LDAP protocol over complete implementation of the LDAP protocol over
[Riak](http://www.basho.com/products_riak_overview.php). Getting an LDAP [Riak](https://github.com/basho/riak). Getting an LDAP server up with riak
server up with riak looks like: looks like:
var ldap = require('ldapjs'); var ldap = require('ldapjs');
var ldapRiak = require('ldapjs-riak'); var ldapRiak = require('ldapjs-riak');
@ -155,7 +151,7 @@ All request objects have the `dn` getter on it, which is "context-sensitive"
and returns the point in the tree that the operation wants to operate on. The and returns the point in the tree that the operation wants to operate on. The
LDAP protocol itself sadly doesn't define operations this way, and has a unique LDAP protocol itself sadly doesn't define operations this way, and has a unique
name for just about every op. So, ldapjs calls it `dn`. The DN object itself name for just about every op. So, ldapjs calls it `dn`. The DN object itself
is documented at [DN](/dn.html). is documented at [DN](dn.html).
All requests have an optional array of `Control` objects. `Control` will have All requests have an optional array of `Control` objects. `Control` will have
the properties `type` (string), `criticality` (boolean), and optionally, a the properties `type` (string), `criticality` (boolean), and optionally, a
@ -175,7 +171,7 @@ identify the request/connection pair in logs (includes the LDAP messageID).
All response objects will have an `end` method on them. By default, calling All response objects will have an `end` method on them. By default, calling
`res.end()` with no arguments will return SUCCESS (0x00) to the client `res.end()` with no arguments will return SUCCESS (0x00) to the client
(with the exception of `compare` which will return COMPARE_TRUE (0x06)). You (with the exception of `compare` which will return COMPARE\_TRUE (0x06)). You
can pass in a status code to the `end()` method to return an alternate status can pass in a status code to the `end()` method to return an alternate status
code. code.
@ -186,8 +182,8 @@ and error message for you.
## Errors ## Errors
ldapjs includes an exception hierarchy that directly corresponds to the RFC list ldapjs includes an exception hierarchy that directly corresponds to the RFC list
of error codes. The complete list is documented in [errors](/errors.html). But of error codes. The complete list is documented in [errors](errors.html). But
the paradigm is something defined like CONSTRAINT_VIOLATION in the RFC would be the paradigm is something defined like CONSTRAINT\_VIOLATION in the RFC would be
`ConstraintViolationError` in ldapjs. Upon calling `next(new LDAPError())`, `ConstraintViolationError` in ldapjs. Upon calling `next(new LDAPError())`,
ldapjs will _stop_ calling your handler chain. For example: ldapjs will _stop_ calling your handler chain. For example:
@ -330,7 +326,7 @@ Whether to return only the names of attributes, and not the values. Defaults to
### filter ### filter
The [filter](/filters.html) object that the client requested. Notably this has The [filter](filters.html) object that the client requested. Notably this has
a `matches()` method on it that you can leverage. For an example of a `matches()` method on it that you can leverage. For an example of
introspecting a filter, take a look at the ldapjs-riak source. introspecting a filter, take a look at the ldapjs-riak source.

2
tools/mk/Makefile.deps
View File

@ -40,5 +40,5 @@ $(JSSTYLE_EXEC): | deps/jsstyle/.git
# restdown # restdown
# #
RESTDOWN_EXEC ?= deps/restdown/bin/restdown RESTDOWN_EXEC ?= deps/restdown/bin/restdown
RESTDOWN ?= python2.6 $(RESTDOWN_EXEC) RESTDOWN ?= python $(RESTDOWN_EXEC)
$(RESTDOWN_EXEC): | deps/restdown/.git $(RESTDOWN_EXEC): | deps/restdown/.git

14
tools/mk/Makefile.targ
View File

@ -239,8 +239,8 @@ DOC_MEDIA_FILES_BUILD := $(DOC_MEDIA_FILES:%=$(DOC_BUILD)/media/%)
# #
.PHONY: docs .PHONY: docs
docs: \ docs: \
$(DOC_FILES:%.restdown=$(DOC_BUILD)/%.html) \ $(DOC_FILES:%.md=$(DOC_BUILD)/%.html) \
$(DOC_FILES:%.restdown=$(DOC_BUILD)/%.json) \ $(DOC_FILES:%.md=$(DOC_BUILD)/%.json) \
$(DOC_MEDIA_FILES_BUILD) $(DOC_MEDIA_FILES_BUILD)
# #
@ -248,16 +248,16 @@ docs: \
# files in DOC_BUILD are up to date. # files in DOC_BUILD are up to date.
# #
.PRECIOUS: \ .PRECIOUS: \
$(DOC_FILES:%.restdown=docs/%.html) \ $(DOC_FILES:%.md=docs/%.html) \
$(DOC_FILES:%.restdown=docs/%json) $(DOC_FILES:%.md=docs/%json)
# #
# We do clean those intermediate files, as well as all of DOC_BUILD. # We do clean those intermediate files, as well as all of DOC_BUILD.
# #
CLEAN_FILES += \ CLEAN_FILES += \
$(DOC_BUILD) \ $(DOC_BUILD) \
$(DOC_FILES:%.restdown=docs/%.html) \ $(DOC_FILES:%.md=docs/%.html) \
$(DOC_FILES:%.restdown=docs/%.json) $(DOC_FILES:%.md=docs/%.json)
# #
# Before installing the files, we must make sure the directories exist. The | # Before installing the files, we must make sure the directories exist. The |
@ -270,7 +270,7 @@ $(DOC_MEDIA_FILES_BUILD): | $(DOC_MEDIA_DIRS_BUILD)
$(DOC_BUILD)/%: docs/% | $(DOC_BUILD) $(DOC_BUILD)/%: docs/% | $(DOC_BUILD)
$(CP) $< $@ $(CP) $< $@
docs/%.json docs/%.html: docs/%.restdown | $(DOC_BUILD) $(RESTDOWN_EXEC) docs/%.json docs/%.html: docs/%.md | $(DOC_BUILD) $(RESTDOWN_EXEC)
$(RESTDOWN) $(RESTDOWN_FLAGS) -m $(DOC_BUILD) $< $(RESTDOWN) $(RESTDOWN_FLAGS) -m $(DOC_BUILD) $<
$(DOC_BUILD): $(DOC_BUILD):