<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>ldapvi User Manual</title>
<link rel="stylesheet" type="text/css" href="manual.css">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<div class="sidebar">
<div class="sidebar-title">
Contents
</div>
<div class="sidebar-main"><ul>
<li><a href="#installing"><b>Installing ldapvi</b></a></li>
<li><a href="#gettingstarted"><b>Getting started</b></a></li>
<li><a href="#interactive"><b>Interactive usage</b></a></li>
<li>
<a href="#arguments"><b>Command line arguments</b></a><ul class="sub" style="margin: 0 0 0 0">
<li><a href="#arguments-connection">Connection parameters</a></li>
<li><a href="#arguments-authentication">Authentication</a></li>
<li><a href="#arguments-search">Search parameters</a></li>
<li><a href="#arguments-handy">Handy parameters</a></li>
<li><a href="#arguments-misc">Miscellaneous options</a></li>
<li><a href="#arguments-tools">Command line tool compatibility</a></li>
</ul>
</li>
<li><a href="#config"><b>Configuration file format</b></a></li>
<li>
<a href="#syntax"><b>ldapvi syntax explained</b></a><ul class="sub" style="margin: 0 0 0 0">
<li><a href="#syntax-basics">Basics</a></li>
<li><a href="#syntax-encodings">Value encodings</a></li>
<li><a href="#syntax-changerecords">Change records</a></li>
<li><a href="#syntax-ldif">Using LDIF syntax</a></li>
</ul>
</li>
<li><a href="#bnf"><b>ldapvi syntax (BNF)</b></a></li>
<li><a href="#bugs"><b>Reporting bugs</b></a></li>
</ul></div>
</div>
<h1>ldapvi User Manual</h1>
<p>
<tt>ldapvi</tt> is an interactive LDAP client for Unix terminals.
Using it, you can update LDAP entries with a text editor.
</p>
<p>
Think of it as <tt>vipw</tt>(1) for LDAP.
</p>
<p>
ldapvi was written by David Lichteblau and is available
at <a href="http://www.lichteblau.com/ldapvi/">http://www.lichteblau.com/ldapvi/</a>.
</p>
<h2>Installing ldapvi<a name="installing"></a>
</h2>
<p>
ldapvi uses autoconf and should be rather easy to install.
</p>
<p>
It used to work on Linux, Solaris, FreeBSD, IRIX, and Cygwin for
me and seems to work on MacOS X and NetBSD for others. Current
versions are only really tested on Linux though, so please
send a bug report if a port is broken.
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code">$ ./configure && make
# make install</pre>
<p><b>Prerequisites.
</b>
<ul>
<li>
Recent OpenLDAP client library (>= 2.2 preferred, 2.1 tolerated)
</li>
<li>glib-2.0</li>
<li>popt</li>
<li>curses</li>
<li>GNU make</li>
<li>
OpenSSL or GnuTLS, choose using
<tt>./configure --with-libcrypto</tt>
</li>
<li>GNU readline</li>
<li>
Build dependency: Cyrus SASL. SASL support is disabled in
ldapvi if Cyrus SASL headers cannot be found at compilation
time. (Whether libldap was compiled with SASL support is only
relevant at run time.)
</li>
</ul>
</p>
<p>
Note that binaries compiled for libldap 2.1 will crash when ran
with libldap 2.2.
</p>
<p>
The choice of GnuTLS over OpenSSL affects only the use of hashing
routines for the <tt>userPassword</tt> convenience encodings md5,
smd5, sha, and ssha. GnuTLS support is offered because, according
to Debian, OpenSSL is not GPL compatible.
</p>
<br><br>
<h2>Getting started<a name="gettingstarted"></a>
</h2>
<p>
The quickest way to try ldapvi is using this:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code">$ ldapvi -d --host HOSTNAME</pre>
<p><b>Explanation.
</b>
This will bind anonymously to <tt>hostname</tt>, read all entries
the server has and open them in the editor.
</p>
<p>
<tt>--host</tt> is the one option you really need to give. It can
be one of:
</p>
<ul>
<li>A domain name.</li>
<li><tt>ldap://hostname[:port]</tt></li>
<li><tt>ldaps://hostname[:port]</tt></li>
</ul>
<p>
<tt>-d</tt> is short for <tt>--discover</tt> and lets ldapvi
search all of the server's naming contexts. Without <tt>-d</tt>,
you would have had to specify the base DN yourself
using <tt>--base</tt>, and you know how inconvenient those LDAP
DNs are to type.
</p>
<p><b>Using a configuration file.
</b>
As easy as that was, you might want to put the hostname and other
search options like the precise base DN to use into a
configuration file.
</p>
<p>
To do that, you might like
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code">$ ldapvi --config --discover --host HOSTNAME</pre>
<p>
This will ask the server for its naming contexts and print
sample contents for <tt>~/.ldaprc</tt>
(or <tt>/etc/ldap.conf</tt>).
</p>
<p>
(Note that ldapvi also has its own <a href="config">configuration
file format</a> which supports multiple configuration profiles and
all of its options.)
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><i># ldap.conf(5)
# edit this as needed and paste into ~/.ldaprc
# server name
# (for parameterless operation, make sure to include at least this line)</i>
<b>HOST localhost</b>
<i># default search base
### multiple namingcontexts found (uncomment one of these lines):</i>
<b>#BASE dc=lichteblau,dc=com
#BASE dc=acme,dc=com</b>
<i># user to bind as</i>
<b>#BINDDN <dn></b>
<i># search parameters (uncomment as needed)</i>
<b>#DEREF never
#SIZELIMIT 0
#TIMELIMIT 0</b></pre>
<p>
Adjust to taste.
</p>
<br><br>
<h2>Interactive usage<a name="interactive"></a>
</h2>
<p>
After quitting from the editor, one of three things can happen:
</p>
<ul>
<li>
If ldapvi detects that nothing in the file has changed, it will
quit.
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code">No changes.</pre>
</li>
<li>
Syntax error: Oops. In this case you only have two options:<br>
You can either re-edit the file and fix the error
(type <tt>e</tt>) or give up and quit (type <tt>Q</tt>). As in
all menus, type <tt>?</tt> for interactive help.
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code">Error: Space at beginning of line.
What now? [eQ?]</pre>
</li>
<li>
Regular usage: ldapvi has compared your changed file with the
original contents and reports on the changes found:
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code"><span style="color: #00ff00">add: 2</span>, <span style="color: #0000ff">rename: 1</span>, modify: 0, <span style="color: #ff0000">delete: 1</span>
Action? [yYqQvVebB*rsf+?] </pre>
</li>
</ul>
<p>
If all is well, you are now in the main loop. Your options are:
</p>
<p><b>Edit - diff - fail.
</b>To continue, type <tt>y</tt>.</p>
<ul>
<li>
<tt>y</tt> -- commit changes<br>
</li>
</ul>
<p>
ldapvi will contact the LDAP server apply all changes. First,
entries are processed in order of the changed file, then all
entries missing from the file are deleted.
</p>
<ul>
<li>
<tt>e</tt> -- open editor again</li>
</ul>
<p>
If any LDAP operation fails while processing the file, ldapvi will
stop, report the error, and wait for your choice. To correct such
an error, go back to the editor. Your will find all previously
processed entries removed from the file, with the failing change
at the top. After changing the file, you will be back at the
prompt.
</p>
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code">Action? [yYqQvVebB*rsf+?] <b>y</b>
ldap_modify: Strong(er) authentication required (8)
additional info: modifications require authentication
Error at: cn=blub4,dc=lichteblau,dc=com
add: 0, rename: 0, <span style="color: #ffff00">modify: 1</span>, delete: 0
Action? [yYqQvVebB*rsf+?] </pre>
<ul>
<li>
<tt>Y</tt> -- commit, ignoring errors<br>
</li>
</ul>
<p>
Apply all changes as if invoked
with <a href="#parameter-continue"><tt>--continue</tt></a>
ignoring all errors without further warning. (Make sure to save
changes to an external file before using this option if they were
important. Invalid changes will be lost otherwise.)
</p>
<p><b>Reviewing changes.
</b>
Before applying the changes, you can inspect them in either LDIF
syntax or ldapvi's special changerecord syntax.
</p>
<ul>
<li>
<tt>v</tt> -- view changes as LDIF change records</li>
</ul>
<ul>
<li>
<tt>V</tt> -- view changes as ldapvi change records</li>
</ul>
<p>
LDIF syntax is useful if you want to copy and paste changes into a
file for later processing with other LDAP tools. ldapvi syntax is
usually easier to read (less Base 64) and can also be entered
directly into the editor.
</p>
<ul>
<li>
<tt>+</tt> -- rewrite file to include schema comments</li>
</ul>
<p>
This will update the file to include schema comments and re-enter
the editor afterwards. This works like
the <a href="#parameter-may"><tt>--may</tt></a> command line
option, but is based on the current contents of the file rather
than the original entries, useful when changing the class of an
entry.
</p>
<p>
Note that this command will rewrite the entire file and wipe out
all comments present before invoking it.
</p>
<p><a name="key-b"></a><b>Logging in.
</b>
One way to bind to the LDAP server is to specify user name and
credentials at startup using command line options or configuration
files. The other is to simply start without authentication and
login later.
</p>
<p>
When relying on binding after editing, keep in mind that some
information will not be returned by the LDAP server unless user
authorization permits it in the first place. For example,
a <tt>userPassword</tt> can usually only be displayed and edited
if you are bound as that user or root upon startup.
</p>
<ul>
<li>
<tt>b</tt> -- show login dialog and rebind</li>
</ul>
<p>
This option will ask for your user name and password (in the case
of simple authentication) or various SASL parameters (as
requested by the SASL library).
</p>
<p>
For simple authentication, the user name can be either an DN or a
search filter. In the latter case, it must be written with
parentheses around it.
</p>
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code">Action? [yYqQvVebB*rsf+?] <b>b</b>
--- Login
Type M-h for help on key bindings.
Filter or DN: <b>(cn=admin)</b>
Password: <b>********</b>
OK, bound as cn=admin,dc=lichteblau,dc=com.</pre>
<p>
Same example with SASL:
</p>
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code">Action? [yYqQvVebB*rsf+?] <b>b</b>
SASL/DIGEST-MD5 authentication started
--- SASL login
Type M-h for help on key bindings.
authorization name:
authentication name: <b>admin</b>
password: <b>********</b>
SASL username: admin
SASL SSF: 128
SASL installing layers
Bound as authzid=, authcid=admin.</pre>
<p>
Note that all non-password values are saved
into <tt>~/.ldapvi_history</tt>, so after entering them once,
"cursor up" or incremental search (<tt>C-r</tt>) will save you
from having to type them again.
</p>
<ul>
<li>
<tt>B</tt> -- toggle SASL</li>
</ul>
<p>
Use this key to switch between simple authentication and SASL at
run time:
</p>
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code">Action? [yYqQvVebB*rsf+?] <b>B</b>
SASL authentication enabled.
SASL mechanism: DIGEST-MD5 (use '*' to change)
Type 'b' to log in.</pre>
<ul>
<li>
<tt>*</tt> -- set SASL mechanism</li>
</ul>
<p>
When the SASL dialog is shown, it is too late to switch the SASL
mechanism. Type <tt>*</tt> to set it at run time.
</p>
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code">Action? [yYqQvVebB*rsf+?] <b>*</b>
SASL mechanism: <b>DIGEST-MD5</b>
Type 'b' to log in.</pre>
<p><b>"Oops".
</b>
You can skip one change to proceed with the rest.
</p>
<ul>
<li>
<tt>s</tt> -- skip one entry</li>
</ul>
<p>
Removes the topmost entry from the data file.
</p>
<ul>
<li>
<tt>f</tt> -- forget all deletions</li>
</ul>
<p>
This is useful if you have deleted entries from the file
accidentally (or intentionally) and still want to commit other
change records in the same file.
</p>
<p>
This option does not affect explicit deletion records.
</p>
<p><b>Bailing out.
</b>There is a gentle way to quit and a hard one.</p>
<ul>
<li>
<tt>q</tt> -- save changes as LDIF and quit</li>
</ul>
<ul>
<li>
<tt>Q</tt> -- discard changes and quit</li>
</ul>
<p>
<tt>q</tt> will save your changes to a new file, print the file
name, and quit only then. This way your changes do not get lost
and you can feed them into ldapmodify at a later time.
</p>
<pre style="background-color: #000000; color: #ffffff; border: 0px;" class="code">Action? [yYqQvVebB*rsf+?] <b>q</b>
Your changes have been saved to ,ldapvi-xenon-20094.ldif.</pre>
<!--
wofuer was das doch gleich da?
<ul>
<li><tt>r</tt> - - reconnect to server</li>
</ul>
-->
<br><br>
<h2>Command line arguments<a name="arguments"></a>
</h2>
<p>
Normal <tt>ldapvi</tt> invocations look similar
to <tt>ldapsearch</tt>(1), taking an optional search filter and
zero or more attribute descriptions as unnamed arguments.
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code">ldapvi [OPTION]... [FILTER] [AD]...</pre>
<p>
In addition, ldapvi can also simulate behaviour of other LDAP
command line tools, e.g. as an interactive substitute for
ldapmodify or even for a simple non-interactive usage. See below
under <a href="#arguments-tools">command line tool compatibility</a>.
</p>
<p><b>Index of options.
</b></p>
<table>
<tr style="">
<td width="20"> </td>
<td><tt>-h</tt></td>
<td> </td>
<td><tt>--host</tt></td>
<td> </td>
<td><a href="#parameter-host">LDAP server to connect to</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--bind</tt></td>
<td> </td>
<td><a href="#parameter-bind">Disable or enable SASL</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--bind-dialog</tt></td>
<td> </td>
<td><a href="#parameter-bind-dialog">Interactive login dialog</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-D</tt></td>
<td> </td>
<td><tt>--user</tt></td>
<td> </td>
<td><a href="#parameter-user">User to bind as (simple bind)</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-w</tt></td>
<td> </td>
<td><tt>--password</tt></td>
<td> </td>
<td><a href="#parameter-password">User's password</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-I</tt></td>
<td> </td>
<td><tt>--sasl-interactive</tt></td>
<td> </td>
<td><a href="#parameter-sasl-interactive">Use SASL Interactive mode</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-Q</tt></td>
<td> </td>
<td><tt>--sasl-quiet</tt></td>
<td> </td>
<td><a href="#parameter-sasl-quiet">Use SASL Quiet mode</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-O</tt></td>
<td> </td>
<td><tt>--sasl-secprops</tt></td>
<td> </td>
<td><a href="#parameter-sasl-secprops">SASL security properties</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-R</tt></td>
<td> </td>
<td><tt>--sasl-realm</tt></td>
<td> </td>
<td><a href="#parameter-sasl-realm">SASL realm</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-U</tt></td>
<td> </td>
<td><tt>--sasl-authcid</tt></td>
<td> </td>
<td><a href="#parameter-sasl-authcid">SASL authentication identity</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-X</tt></td>
<td> </td>
<td><tt>--sasl-authzid</tt></td>
<td> </td>
<td><a href="#parameter-sasl-authzid">SASL authorization identity</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-Y</tt></td>
<td> </td>
<td><tt>--sasl-mech</tt></td>
<td> </td>
<td><a href="#parameter-sasl-mech">SASL mechanism</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-b</tt></td>
<td> </td>
<td><tt>--base</tt></td>
<td> </td>
<td><a href="#parameter-base">Search base</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-s</tt></td>
<td> </td>
<td><tt>--scope</tt></td>
<td> </td>
<td><a href="#parameter-scope">Search scope</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-S</tt></td>
<td> </td>
<td><tt>--sort</tt></td>
<td> </td>
<td><a href="#parameter-sort">Search control</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-d</tt></td>
<td> </td>
<td><tt>--discover</tt></td>
<td> </td>
<td><a href="#parameter-discover">Auto-detect naming contexts</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-o</tt></td>
<td> </td>
<td><tt>--class</tt></td>
<td> </td>
<td><a href="#parameter-class">Class to add</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-m</tt></td>
<td> </td>
<td><tt>--may</tt></td>
<td> </td>
<td><a href="#parameter-may">Show schema comments.</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--add</tt></td>
<td> </td>
<td><a href="#parameter-add">Treat attrval records as new entries to add.</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-A</tt></td>
<td> </td>
<td><tt>--empty</tt></td>
<td> </td>
<td><a href="#parameter-empty">Start with empty file</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-a</tt></td>
<td> </td>
<td><tt>--deref</tt></td>
<td> </td>
<td><a href="#parameter-deref">Alias dereferencing mode</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--config</tt></td>
<td> </td>
<td><a href="#parameter-config">Print parameters in ldap.conf syntax</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-c</tt></td>
<td> </td>
<td><tt>--continue</tt></td>
<td> </td>
<td><a href="#parameter-continue">Ignore LDAP errors and continue</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--encoding</tt></td>
<td> </td>
<td><a href="#parameter-encoding">The encoding to allow</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-M</tt></td>
<td> </td>
<td><tt>--managedsait</tt></td>
<td> </td>
<td><a href="#parameter-managedsait">manageDsaIT control</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-Z</tt></td>
<td> </td>
<td><tt>--starttls</tt></td>
<td> </td>
<td><a href="#parameter-starttls">Require startTLS.</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--tls</tt></td>
<td> </td>
<td><a href="#parameter-tls">Level of TLS strictness</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--read</tt></td>
<td> </td>
<td><a href="#parameter-read">Read this entry</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-v</tt></td>
<td> </td>
<td><tt>--verbose</tt></td>
<td> </td>
<td><a href="#parameter-verbose">Note every update</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td><tt>-H</tt></td>
<td> </td>
<td><tt>--help</tt></td>
<td> </td>
<td><a href="#parameter-help">Print usage information</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--deleteoldrdn</tt></td>
<td> </td>
<td><a href="#parameter-deleteoldrdn">Delete the old RDN</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--ldif</tt></td>
<td> </td>
<td><a href="#parameter-ldif">Use LDIF syntax internally</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--ldapvi</tt></td>
<td> </td>
<td><a href="#parameter-ldapvi">Use ldapvi syntax externally</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--out</tt></td>
<td> </td>
<td><a href="#parameter-out">Print entries</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--in</tt></td>
<td> </td>
<td><a href="#parameter-in">Load change records</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--delete</tt></td>
<td> </td>
<td><a href="#parameter-delete">Edit a delete record</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--rename</tt></td>
<td> </td>
<td><a href="#parameter-rename">Edit a rename record</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--ldapsearch</tt></td>
<td> </td>
<td><a href="#parameter-ldapsearch">Print entries noninteractively</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--ldapmodify</tt></td>
<td> </td>
<td><a href="#parameter-ldapmodify">Apply change records noninteractively</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--ldapdelete</tt></td>
<td> </td>
<td><a href="#parameter-ldapdelete">Delete an entry noninteractively</a></td>
</tr>
<tr style="">
<td width="20"> </td>
<td></td>
<td> </td>
<td><tt>--ldapmoddn</tt></td>
<td> </td>
<td><a href="#parameter-ldapmoddn">Rename an entry noninteractively</a></td>
</tr>
</table>
<h3>Connection parameters<a name="arguments-connection"></a>
</h3>
<p>
The <tt>host</tt> option specifies the LDAP server to connect
to. It is required for startup (unless specified in a
configuration file).
</p>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-host"></a><tt>-h</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--host</tt> <i>hostname</i> </td>
<td style="border-bottom: 1px solid #000000">LDAP server to connect to</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Three styles of host name are recognized.
<ul>
<li>A domain name.</li>
<li><tt>ldap://hostname[:port]</tt></li>
<li><tt>ldaps://hostname[:port]</tt></li>
</ul>
To specify a port number or tunnelling through SSL, the URL form
must be used.
</td>
</tr>
<tr><td> </td></tr>
</table>
<br>
<h3>Authentication<a name="arguments-authentication"></a>
</h3>
<p>
Note that you can also bind to the server interactively after
performing the search using <a href="#key-b">the <tt>b</tt>
command</a>.
</p>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-bind"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--bind</tt> <i>simple|sasl</i> </td>
<td style="border-bottom: 1px solid #000000">Disable or enable SASL</td>
</tr>
<tr>
<td></td>
<td colspan="2">
<p>
Initially, ldapvi defaults to simple authentication. If any
SASL parameter is given, the mode is set to <tt>sasl</tt>.
Conversely, <a href="#parameter-user"><tt>-D</tt></a> sets it
to <tt>simple</tt>.
</p>
<p>This parameter sets it explicitly.</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-bind-dialog"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--bind-dialog</tt> <i>never|auto|always</i> </td>
<td style="border-bottom: 1px solid #000000">Interactive login dialog</td>
</tr>
<tr>
<td></td>
<td colspan="2">
<p>
This option controls whether ldapvi will ask for
authentication parameters interactively.
</p>
<p>
The default is <tt>auto</tt>, which means that simple binds
will be done interactively if a user name is provided but no
password, and similarly for SASL.
</p>
<p>
<tt>always</tt> forces display of a login dialog even if
defaults are known. <tt>never</tt> skips the login dialog
completely.
</p>
<p>
Note that this option has effect only for the initial bind
operation. In the main loop, all binds are done interactively.
</p>
<p>
See also: <a href="#parameter-sasl-quiet"><tt>-Q</tt></a>
and <a href="#parameter-sasl-interactive"><tt>-I</tt></a>.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-user"></a><tt>-D</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--user</tt> <i>dn|filter</i> </td>
<td style="border-bottom: 1px solid #000000">User to bind as (simple bind)</td>
</tr>
<tr>
<td></td>
<td colspan="2">
The user name can be specified as a distinguished name
<pre style="background-color: #eeeeee; color: #000000" class="code">uid=foo,ou=bar,dc=acme,dc=com</pre>
or as a search filter
<pre style="background-color: #eeeeee; color: #000000" class="code">(uid=foo)</pre>
<p>
Note the use of parenthesis, which can be omitted from search
filters usually but are required here. For this searching
bind to work, your client library must be configured with
appropriate default search parameters.
</p>
<p>
Exactly one entry must match.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-password"></a><tt>-w</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--password</tt> <i>secret</i> </td>
<td style="border-bottom: 1px solid #000000">User's password</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Beware that passwords in a simple bind are transmitted in clear
text unless the connection is encrypted through SSL.
<p>
This option is valid for both simple authorization and SASL.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<p><b>SASL authentication.
</b>
If any of the SASL arguments is specified, ldapvi uses SASL
by default.
</p>
<p>
If you are unsure which SASL parameters to try for your server,
start with <tt>-Y DIGEST-MD5 -U <i>username</i></tt>.
</p>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-sasl-interactive"></a><tt>-I</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--sasl-interactive</tt> </td>
<td style="border-bottom: 1px solid #000000">Use SASL Interactive mode</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Always ask for SASL parameters interactively.
<p>
This option is an alias for
<a href="#parameter-bind-dialog"><tt>--bind-dialog always</tt></a>
and
<a href="#parameter-bind"><tt>--bind sasl</tt></a>.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-sasl-quiet"></a><tt>-Q</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--sasl-quiet</tt> </td>
<td style="border-bottom: 1px solid #000000">Use SASL Quiet mode</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Never ask for SASL parameters interactively at all.
<p>
This option is an alias for
<a href="#parameter-bind-dialog"><tt>--bind-dialog never</tt></a>
and
<a href="#parameter-bind"><tt>--bind sasl</tt></a>.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-sasl-secprops"></a><tt>-O</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--sasl-secprops</tt> <i>properties</i> </td>
<td style="border-bottom: 1px solid #000000">SASL security properties</td>
</tr>
<tr>
<td></td>
<td colspan="2">
OpenLDAP's <a href="http://www.lichteblau.com/ldapvi/slapd.conf.5.txt">slapd.conf</a>(5)
manual page has some information on these (search for sasl-secprops).
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-sasl-realm"></a><tt>-R</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--sasl-realm</tt> <i>realm</i> </td>
<td style="border-bottom: 1px solid #000000">SASL realm</td>
</tr>
<tr>
<td></td>
<td colspan="2">
The <a href="http://www.lichteblau.com/ldapvi/cyrus-sasl/sysadmin.html#realms">SASL
realm</a> [Cyrus SASL documentation].
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-sasl-authcid"></a><tt>-U</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--sasl-authcid</tt> <i>username</i> </td>
<td style="border-bottom: 1px solid #000000">SASL authentication identity</td>
</tr>
<tr>
<td></td>
<td colspan="2">
The <a href="http://www.lichteblau.com/ldapvi/cyrus-sasl/sysadmin.html#authid">authentication
ID</a> [Cyrus SASL documentation].
<p>
(Basically, your username.)
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-sasl-authzid"></a><tt>-X</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--sasl-authzid</tt> <i>u:username|dn:dn</i> </td>
<td style="border-bottom: 1px solid #000000">SASL authorization identity</td>
</tr>
<tr>
<td></td>
<td colspan="2">
The <a href="http://www.lichteblau.com/ldapvi/cyrus-sasl/sysadmin.html#authid">authorization
ID</a> [Cyrus SASL documentation].
<p>
(See <a href="http://www.openldap.org/doc/admin/sasl.html#SASL%20Proxy%20Authorization">SASL Proxy Authorization</a>
[openldap.org] in the OpenLDAP Administrator's Guide.)
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-sasl-mech"></a><tt>-Y</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--sasl-mech</tt> <i>mechanism</i> </td>
<td style="border-bottom: 1px solid #000000">SASL mechanism</td>
</tr>
<tr>
<td></td>
<td colspan="2">
<p>
The SASL mechanism to use. Possible values depend on the
server, but <tt>DIGEST-MD5</tt> support is mandated by
RFC 2829 for all servers using passwords.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<br>
<h3>Search parameters<a name="arguments-search"></a>
</h3>
<p>Where and how to look for entries.</p>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-base"></a><tt>-b</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--base</tt> <i>dn</i> </td>
<td style="border-bottom: 1px solid #000000">Search base</td>
</tr>
<tr>
<td></td>
<td colspan="2">
The entry at which to start the search.
<p>
Conflicts with <a href="#parameter-discover"><tt>--discover</tt></a>.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-scope"></a><tt>-s</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--scope</tt> base|one|sub </td>
<td style="border-bottom: 1px solid #000000">Search scope</td>
</tr>
<tr>
<td></td>
<td colspan="2">
<ul>
<li>
<tt>base</tt>: Retrieve at most the entry at <tt>base</tt>.</li>
<li>
<tt>one</tt>: Search for entries exactly one level
below <tt>base</tt>.
</li>
<li>
<tt>sub</tt>: Search the entire subtree starting at <tt>base</tt>.
</li>
</ul>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-sort"></a><tt>-S</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--sort</tt> <i>keys</i> </td>
<td style="border-bottom: 1px solid #000000">Search control</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Use the search control to instruct the server to sort results
on <i>keys</i>. ldapvi will fail if the server does not support
the control. Unfortunately, few servers do.
</td>
</tr>
<tr><td> </td></tr>
</table>
<br>
<h3>Handy parameters<a name="arguments-handy"></a>
</h3>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-discover"></a><tt>-d</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--discover</tt> </td>
<td style="border-bottom: 1px solid #000000">Auto-detect naming contexts</td>
</tr>
<tr>
<td></td>
<td colspan="2">
With this option, ldapvi will first read the root DSE, then repeat
the search for each naming context found and present the
concatenation of all search results.
<p>
Conflicts with <a href="#parameter-base"><tt>--base</tt></a>.
</p>
<p>
With <a href="#parameter-config"><tt>--config</tt></a>, show
a <tt>BASE</tt> configuration line for each context.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-class"></a><tt>-o</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--class</tt> <i>objectClass</i> </td>
<td style="border-bottom: 1px solid #000000">Class to add</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Read the server's schema for the specified objectclass to find out
which attributes an entry of this class must have and can have.
Then open the editor with an entry template containing one line
for each such attribute the user needs to fill out. Optional
attributes are included as comments.
<p>
The option can be repeated to include
additional, <i>auxiliary</i> classes.
</p>
<p>
A distinguished name for the entry template can be specified
using <a href="#parameter-base"><tt>--base</tt></a>.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-may"></a><tt>-m</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--may</tt> </td>
<td style="border-bottom: 1px solid #000000">Show schema comments.</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Show schema comments for existing entries. Specificially, show
optional attributes as comments, if not present.
</td>
</tr>
<tr><td> </td></tr>
</table>
<br>
<h3>Miscellaneous options<a name="arguments-misc"></a>
</h3>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-add"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--add</tt> </td>
<td style="border-bottom: 1px solid #000000">Treat attrval records as new entries to add.</td>
</tr>
<tr>
<td></td>
<td colspan="2">
<p>
This option applies only to
the <a href="#parameter-in"><tt>--in</tt></a>/<a href="#parameter-ldapmodify"><tt>--ldapmodify</tt></a> mode:
</p>
<p>
Add new entries (default would be to replace existing attributes).
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-empty"></a><tt>-A</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--empty</tt> </td>
<td style="border-bottom: 1px solid #000000">Start with empty file</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Do not search, start with an empty file instead.
<p>
This is the little brother of
the <a href="#parameter-class"><tt>--class</tt> parameter</a>,
which is more interesting for the original use case of this
option, adding new entries.
</p>
<p>
However, it is still useful because allows the interactive
entry of <tt>delete</tt>, <tt>modify</tt>, or <tt>rename</tt>
changerecords.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-deref"></a><tt>-a</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--deref</tt> never|searching|finding|always </td>
<td style="border-bottom: 1px solid #000000">Alias dereferencing mode</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Default is <tt>never</tt>.
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-config"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--config</tt> </td>
<td style="border-bottom: 1px solid #000000">Print parameters in ldap.conf syntax</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Print a configuration file in standard <tt>ldap.conf</tt> syntax
which reflects current command line arguments. The file is
written to standard output. Use this option to create an
initial configuration file after experimenting with search
parameters. Useful in conjunction
with <a href="#parameter-discover"><tt>--discover</tt></a>.
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-continue"></a><tt>-c</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--continue</tt> </td>
<td style="border-bottom: 1px solid #000000">Ignore LDAP errors and continue</td>
</tr>
<tr>
<td></td>
<td colspan="2">
When LDAP errors occur while applying changes, print the messages
but continue processing. This mode can also be specified
interactively using the 'Y' key.
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-encoding"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--encoding</tt> ASCII|UTF-8|binary </td>
<td style="border-bottom: 1px solid #000000">The encoding to allow</td>
</tr>
<tr>
<td></td>
<td colspan="2">
This option controls how ldapvi deals with non-ASCII bytes in
attribute values.
<ul>
<li>
<tt>ASCII</tt>: If an attribute value contains any non-ASCII
character, use Base 64 encoding for this value
</li>
<li>
<tt>UTF-8</tt>: Use auto-detection. If an attribute value
parses as correct UTF-8, pass it through to the file or
terminal unchanged. Otherwise, fall back to Base 64. Mark
the file's encoding as UTF-8 for Emacs and VIM.
</li>
<li>
<tt>binary</tt>: Do not inspect attribute values at all, let
arbitrary data through, including zero bytes. Do not use
Base 64.
</li>
</ul>
<p>
The default is <tt>UTF-8</tt>.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-managedsait"></a><tt>-M</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--managedsait</tt> </td>
<td style="border-bottom: 1px solid #000000">manageDsaIT control</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Use this option to edit referral entries.
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-starttls"></a><tt>-Z</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--starttls</tt> </td>
<td style="border-bottom: 1px solid #000000">Require startTLS.</td>
</tr>
<tr>
<td></td>
<td colspan="2">
After opening an unencrypted LDAP connection, use startTLS to
enable SSL. (This is an alternative to LDAP connections
tunnelled through SSL, specified using <tt>ldaps://</tt> URLs.)
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-tls"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--tls</tt> never|allow|try|strict </td>
<td style="border-bottom: 1px solid #000000">Level of TLS strictness</td>
</tr>
<tr>
<td></td>
<td colspan="2">
This option controls the level of certificate checking
strictness. Default is <tt>try</tt>.
<p>
fixme: If anyone has a concise description of what these
values mean rather than the wishy-washy explanations I can
find right now, please tell. Thanks.
</p>
<p>
(Basically, if you want to use SSL but your certificate is
self-signed, you might want to experiment with something less
than <tt>try</tt>.)
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-read"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--read</tt> <i>DN</i> </td>
<td style="border-bottom: 1px solid #000000">Read this entry</td>
</tr>
<tr>
<td></td>
<td colspan="2">
A rather trivial option. It means the same as:
<pre style="background-color: #eeeeee; color: #000000" class="code">-b DN -s base '(objectclass=*)' + *</pre>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-verbose"></a><tt>-v</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--verbose</tt> </td>
<td style="border-bottom: 1px solid #000000">Note every update</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Print the distinguished name of every entry as it is being
processed.
</td>
</tr>
<tr><td> </td></tr>
</table>
<!--
<parameter short="q" long="quiet" brief="Disable progress output">
Make ldapvi shut up a little.
</parameter>
<parameter short="!"
long="noquestions"
brief="Don't ask for confirmation">
documentme
</parameter>
-->
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50">
<a name="parameter-help"></a><tt>-H</tt>
</td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--help</tt> </td>
<td style="border-bottom: 1px solid #000000">Print usage information</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Print help on command line arguments.
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-deleteoldrdn"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--deleteoldrdn</tt> </td>
<td style="border-bottom: 1px solid #000000">Delete the old RDN</td>
</tr>
<tr>
<td></td>
<td colspan="2">
When changing the relative distinguished name to a new attribute
value, delete the old attribute value instead of keeping it.
<p>
This option applies only to
the <a href="#parameter-rename"><tt>--rename</tt></a> mode.
</p>
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-ldif"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--ldif</tt> </td>
<td style="border-bottom: 1px solid #000000">Use LDIF syntax internally</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Use standard LDIF syntax in the editor. The default is to use
ldapvi syntax.
</td>
</tr>
<tr><td> </td></tr>
</table>
<table cellspacing="0" width="90%">
<tr style="">
<td style="font-weight: bold; border-bottom: 1px solid #000000" width="50"><a name="parameter-ldapvi"></a></td>
<td style="border-bottom: 1px solid #000000" width="30%">
<tt style="font-weight: bold">--ldapvi</tt> </td>
<td style="border-bottom: 1px solid #000000">Use ldapvi syntax externally</td>
</tr>
<tr>
<td></td>
<td colspan="2">
Use ldapvi syntax when reading and writing files. The default
is to use LDIF syntax.
</td>
</tr>
<tr><td> </td></tr>
</table>
<br>
<h3>Command line tool compatibility<a name="arguments-tools"></a>
</h3>
<p>
ldapvi invocation modes inspired by LDAP command line tools:
<a name="parameter-out"></a>
<a name="parameter-in"></a>
<a name="parameter-delete"></a>
<a name="parameter-rename"></a>
</p>
<table cellspacing="0">
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt>
ldapvi <b>--out</b> [OPTION]... <b>[FILTER] [AD]...</b>
</tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">Print LDIF, similar to ldapsearch</td>
</tr>
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt>
ldapvi <b>--in</b> [OPTION]... <b>[FILENAME]</b>
</tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">Load LDIF change records, similar to ldapmodify</td>
</tr>
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt>
ldapvi <b>--delete</b> [OPTION]... <b>DN...</b>
</tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">Edit delete records, similar to ldapdelete</td>
</tr>
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt>
ldapvi <b>--rename</b> [OPTION]... <b>DN1 DN2</b><!--<br/>
ldapvi <b>--modrdn</b> [OPTION]... <b>DN RDN</b>-->
</tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">Edit rename records, similar to ldapmodrdn</td>
</tr>
</table>
<p>
All of these are more verbose and interactive than the standard
command line tools. There are additional aliases for closer
compatibility:
<a name="parameter-ldapsearch"></a>
<a name="parameter-ldapmodify"></a>
<a name="parameter-ldapdelete"></a>
<a name="parameter-ldapmoddn"></a>
</p>
<table cellspacing="0">
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt><b>--ldapsearch</b></tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">
Short for
<tt>--quiet --out</tt>
</td>
</tr>
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt><b>--ldapmodify</b></tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">
Short for
<tt>--noninteractive --in</tt>
</td>
</tr>
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt><b>--ldapdelete</b></tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">
Short for
<tt>--noninteractive --delete</tt>
</td>
</tr>
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt><b>--ldapmoddn</b></tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">
Short for
<tt>--noninteractive --rename</tt>
</td>
</tr>
<!--
<mode short="--noninteractive --modrdn"><b>--ldapmodrdn</b></mode>
-->
</table>
<p>
Please keep in mind that all these invocation modes are only
meant to imitate LDAP command line tools <i>as far as
possible</i> while still working within the design of ldapvi.
An option-by-option emulation of the OpenLDAP command line tools
is <i>not</i> a goal, and minor differences in look and feel are
to be expected.
</p>
<p><b>Format conversion.
</b></p>
<table cellspacing="0">
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt>
ldapvi --in | cat
</tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">Convert LDIF on stdin to ldapvi format on stdout</td>
</tr>
<tr>
<td width="20"> </td>
<td style="border-bottom: 1px solid #707070"><tt>
ldapvi --in --ldif --ldapvi | cat
</tt></td>
<td style="border-bottom: 1px solid #707070; border-right: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070">
</td>
<td style="border-bottom: 1px solid #707070" valign="top">Convert ldapvi format on stdin to LDIF on stdout</td>
</tr>
</table>
<br>
<br><br>
<h2>Configuration file format<a name="config"></a>
</h2>
<p>
The are two ways to configure ldapvi. It has its own
configuration files <tt>~/.ldapvirc</tt>
(or <tt>/etc/ldapvi.conf</tt>) which support multiple configuration
profiles and all of its custom options. Alternatively, it can
fall back to <tt>libldap</tt>'s standard configuration
files, <tt>/etc/ldap.conf</tt> and <tt>~/.ldaprc</tt>.
</p>
<p><b>Files and profiles.
</b>
On startup, ldapvi will first look for <tt>~/.ldapvirc</tt>,
or <tt>/etc/ldapvi.conf</tt> if the former does not exist.
</p>
<ul>
<li>
If <tt>--profile</tt> <i>name</i> is specified at the command
line, one of these configuration files must exist and it must
contain the named profile. Otherwise ldapvi quits with an
error.
</li>
<li>
If no <tt>--profile</tt> was given, ldapvi looks for a profile
called <tt>default</tt>. If no such profile can be found or the
files do not exist, ldapvi falls back to <tt>libldap</tt>
configuration files.
</li>
<li>
By default, if a profile is used, it suppresses loading of
the <tt>libldap</tt> configuration files <tt>/etc/ldap.conf</tt>
and <tt>~/.ldaprc</tt>. If you want these files to take effect
anyway, you can set <tt><a href="#parameter-ldaprc">ldaprc</a>:
yes</tt> in the profile.
</li>
</ul>
<p><b>Environment variables.
</b>The choice of text editor is made
using environment variables. <tt>$VISUAL</tt>
and <tt>$EDITOR</tt> are looked up in this order. If neither is
set, ldapvi falls back to <tt>vi</tt>.
</p>
<p><b>Profile syntax.
</b>
The configuration file has <a href="#syntax">ldapvi syntax</a>,
except with header lines of the
form <tt>profile</tt> <i>name</i>.
</p>
<p>
Every configuration file option corresponds to a command line
parameter.
</p>
<p>
For the named command line parameters, the long name is used in
the configuration. For details, refer to the documentation of
each parameter: ➙ <a href="#parameter-host">host</a> ➙ <a href="#parameter-bind">bind</a> ➙ <a href="#parameter-bind-dialog">bind-dialog</a> ➙ <a href="#parameter-user">user</a> ➙ <a href="#parameter-password">password</a> ➙ <a href="#parameter-sasl-interactive">sasl-interactive</a> ➙ <a href="#parameter-sasl-quiet">sasl-quiet</a> ➙ <a href="#parameter-sasl-secprops">sasl-secprops</a> ➙ <a href="#parameter-sasl-realm">sasl-realm</a> ➙ <a href="#parameter-sasl-authcid">sasl-authcid</a> ➙ <a href="#parameter-sasl-authzid">sasl-authzid</a> ➙ <a href="#parameter-sasl-mech">sasl-mech</a> ➙ <a href="#parameter-base">base</a> ➙ <a href="#parameter-scope">scope</a> ➙ <a href="#parameter-sort">sort</a> ➙ <a href="#parameter-discover">discover</a> ➙ <a href="#parameter-class">class</a> ➙ <a href="#parameter-may">may</a> ➙ <a href="#parameter-add">add</a> ➙ <a href="#parameter-empty">empty</a> ➙ <a href="#parameter-deref">deref</a> ➙ <a href="#parameter-continue">continue</a> ➙ <a href="#parameter-encoding">encoding</a> ➙ <a href="#parameter-managedsait">managedsait</a> ➙ <a href="#parameter-starttls">starttls</a> ➙ <a href="#parameter-tls">tls</a> ➙ <a href="#parameter-read">read</a> ➙ <a href="#parameter-verbose">verbose</a> ➙ <a href="#parameter-deleteoldrdn">deleteoldrdn</a> ➙ <a href="#parameter-ldif">ldif</a> ➙ <a href="#parameter-ldapvi">ldapvi</a> ➙ <a href="#parameter-out">out</a> ➙ <a href="#parameter-in">in</a> ➙ <a href="#parameter-delete">delete</a> ➙ <a href="#parameter-rename">rename</a> ➙ <a href="#parameter-ldapsearch">ldapsearch</a> ➙ <a href="#parameter-ldapmodify">ldapmodify</a> ➙ <a href="#parameter-ldapdelete">ldapdelete</a> ➙ <a href="#parameter-ldapmoddn">ldapmoddn</a>
</p>
<p>
The two unnamed kinds of command line arguments are the search
filter and the list of attribute descriptions to be returned. The
former is named ➙ <tt>filter</tt> in the configuration
file. The latter are given as ➙ <tt>ad</tt>, one line
each.
</p>
<p>
For boolean flags, given without a value at the command line,
use <tt>yes</tt> as their value in the configuration
file. (<tt>no</tt> is also allowed and has no effect.)
</p>
<p><b>Example.
</b>
With the following configuration file, ldapvi
ignores <tt>libldap</tt> configuration, because a <tt>default</tt>
profile is given.
</p>
<ul>
<li>
The default profile falls back to <tt>libldap</tt>
configuration, but enables schema comments.
</li>
<li>
<tt>ldapvi -p otherhost</tt> profile reads all entries from
<tt>otherhost</tt>.
</li>
<li>
<tt>ldapvi -p adduser</tt> will open a template for a new user
entry to be filled in.
</li>
<li>
<tt>ldapvi -p root</tt> will retrieve the root DSE with its
operational attributes.
</li>
</ul>
<pre style="background-color: #eeeeee; color: #000000" class="code">profile default
ldaprc: yes
may: yes
profile otherhost
host: ldap://otherhost
discover: yes
profile adduser
host: ldap://localhost
base: uid=FILLMEIN,ou=passwd,dc=lichteblau,dc=com
class: person
class: posixAccount
profile root
host: ldap://localhost
base:
scope: base
filter: (objectclass=*)
ad: +</pre>
<br><br>
<h2>ldapvi syntax explained<a name="syntax"></a>
</h2>
<p>
<i>ldapvi syntax</i> is somewhat LDIF-like, but not the same as
standard LDIF. This chapter includes examples explaining the
difference between the two formats. (A precise, technical
definition of ldapvi syntax is given in the <a href="#bnf">next
section</a>.)
</p>
<p>
➙ In <b>interactive editing</b>, the default is
<b>ldapvi syntax</b>, explained below, unless overridden
using <a href="#parameter-ldif"><tt>--ldif</tt></a>.
</p>
<p>
➙ For external <b>input and output</b>
(see <a href="#parameter-in"><tt>--in</tt></a>, <a href="#parameter-out"><tt>--out</tt></a>), the default
is <b>standard LDIF</b> syntax, unless overridden
using <a href="#parameter-ldapvi"><tt>--ldapvi</tt></a>.
</p>
<h3>Basics<a name="syntax-basics"></a>
</h3>
<p>Comments are lines starting with a sharpsign:</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"># like this</pre>
<p>
They are allowed both between entries and in the middle of entries
(but not in the middle of an attribute value).
</p>
<p>Empty lines are used to separate entries:</p>
<pre style="background-color: #eeeeee; color: #000000" class="code">0 dc=lichteblau,dc=com
<b># don't touch the number!</b>
objectClass: top
objectClass: dcObject
objectClass: organization
o: lichteblau
dc: lichteblau
<b># more than one empty line would be OK here, too</b>
add cn=admin,dc=lichteblau,dc=com
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: admin
description: LDAP administrator</pre>
<p>
So far this looks pretty much like LDIF, except for the
record <i>key</i> that appears instead of the <tt>dn:</tt> LDIF
uses to start an entry.
</p>
<ul>
<li>
Numbers as keys reference entries read from the server. ldapvi
uses them to find the original entry when comparing your changed
file with its unchanged copy.
</li>
<li>
Special key <tt>add</tt> is used for new entries that are to be
added to the tree. Except for not having a number key, its
syntax is the same as for normal entries.
</li>
<li>
In addition, there are special keys for <i>change records</i>:
<tt>rename</tt>, <tt>delete</tt>, and <tt>modify</tt>. Change
records have special syntax and
are <a href="#syntax-changerecords">explained below</a> in
detail.
</li>
</ul>
<p>
First though, more on low-level syntax issues.
</p>
<br>
<h3>Value encodings<a name="syntax-encodings"></a>
</h3>
<p>
All non-empty, non-comment "lines" have the same base syntax: A
left-hand and a right-hand side, separated by an optional
encoding marker and a space. (Depending on the encoding used, a
such a logical line may include newline characters.)
</p>
<p>
The syntax of the right-hand side depends on the encoding marker.
For simple ASCII text without special characters, there are
multiple valid encodings that can be used.
</p>
<p>
This includes the first line of a record with the distinguished
name, its base syntax is the same as for the attribute lines. For
traditional reasons, ldapvi prints this line without a colon, but
that is not a requirement:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># rather than writing this:</b>
add cn=admin,dc=lichteblau,dc=com
<b># we could have included a colon:</b>
add: cn=admin,dc=lichteblau,dc=com
<b># or actually, this:</b>
add:; cn=admin,dc=lichteblau,dc=com</pre>
<p>
Or, vice versa, we could have omitted the colon from those
attribute values. ldapvi prints it only so that entries looks for
familiar to eyes used to LDIF.
</p>
<p>
Value encodings are:
</p>
<ul>
<li>
<tt>ad: value</tt>: LDIF-compatible</li>
<li>
<tt>ad:: value</tt>: Base 64</li>
<li>
<tt>ad value</tt>: backslashed (short form)</li>
<li>
<tt>ad:; value</tt>: backslashed (long form)</li>
<li>
<tt>ad:<i>n</i> value</tt>: binary</li>
<li>
<tt>ad:< value</tt>: input from file</li>
<li>
<tt>ad:crypt value</tt>: userPassword {CRYPT}-hash</li>
<li>
<tt>ad:cryptmd5 value</tt>: userPassword {CRYPT}-hash</li>
<li>
<tt>ad:md5 value</tt>: userPassword {MD5}-hash</li>
<li>
<tt>ad:smd5 value</tt>: userPassword {SMD5}-hash</li>
<li>
<tt>ad:sha value</tt>: userPassword {SHA}-hash</li>
<li>
<tt>ad:ssha value</tt>: userPassword {SSHA}-hash</li>
</ul>
<p><b>LDIF-compatible encoding.
</b>
Lines with just a colon and a space are parsed according to normal
LDIF rules. Values must be ASCII-only and must not contain zero
bytes, LF, or CR. In addition, they must not start with a space,
a colon, or a less-than sign.
</p>
<p>
This encoding allows LDIF-style line folding: If a line ends, and
the first character of the next line, if any, is a space, the
nextline and the space are elided and parsing continues on the
next line.
</p>
<p>
Note: The language for attribute value lines described above is
the common subset of LDIF's attrval-spec and the actual syntax
accepted by ldapvi for this value encoding. ldapvi will only
ever print out values in this encoding if they follow these
rules and hence are valid LDIF, but is more liberal in parsing
them. It accepts space, colon, or less-than sign as the first
character. It can allow them without ambiguity because, in
contrast to LDIF, it does not ignore an arbitrary number of
space characters after the colon.
</p>
<p>
Examples of valid LDIF values:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># normally, one would write:</b>
objectClass: posixAccount
<b># but with line folding, the same value can be broken into two lines:</b>
objectClass: posix
Account
<b># in contrast to ldapvi backslashed format, this encoding does not
# interpret backslashes specially at all:</b>
cn: this is a value containing a backslash\
but no newline
</pre>
<p>
Examples of attribute values not representable in
LDIF-compatible encoding:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># must not start with '<':</b>
<b># [accepted by ldapvi but not LDIF]</b>
<strike>document: <?xml version="1.0" encoding="UTF-8"><foo/></strike>
<b># cannot start with a space:</b>
<b># [LDIF would ignore the space]</b>
<strike>foo: ...</strike>
<b># must not start with a colon:</b>
<b># [accepted by ldapvi but not LDIF]</b>
<strike>foo: ::::::::</strike>
<b># must not contain non-ASCII bytes:</b>
<strike>surname: Müller</strike>
<b># cannot represent newlines:</b>
<strike>mail: From david@lichteblau.com Mon Apr 1 00:11:22 2006
Return-path: <david@lichteblau.com>
Envelope-to: lists@mail.askja.de</strike></pre>
<p><b>Base 64 encoding.
</b>
Base 64 can be used just as in LDIF.
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># This is what the XML from above looks like in strict LDIF:</b>
document:: PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPjxmb28vPg==</pre>
<p><b>ldapvi backslashed encoding.
</b>
This is the format ldapvi falls back to if a value cannot be
represented in LDIF-compatible encoding without resorting to
Base 64. Any character is valid in this encoding, except for
two characters with a special meaning:
</p>
<ul>
<li>newline terminates the value unless escaped with a backslash</li>
<li>backslash escapes the following character</li>
</ul>
<p>
Examples of valid backslashed attributes:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># any funny characters are OK</b>
document:; <?xml version="1.0" encoding="UTF-8">
foo:; ...
foo:; ::::::::
surname:; Müller
<b># backslash escapes newline</b>
mail:; From david@lichteblau.com Mon Apr 1 00:11:22 2006\
Return-path: <david@lichteblau.com>\
Envelope-to: lists@mail.askja.de
<b># No LDIF line folding, however, so this value contains a space:</b>
cn:; David\
Lichteblau
</pre>
<p>
Counter-example:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># Parsable first line, followed by garbage on the second:</b>
<strike>cn:; David
Lichteblau</strike></pre>
<p>
Finally, in most situations <tt>:;</tt> can be omitted, leaving
just a space between the left-hand and right-hand side of the
line. The only exception is a line with an empty left-hand side,
which occurs in <a href="#syntax-changerecords">modify records</a>.
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code">foo:; bar
<b># is the same as:</b>
foo bar</pre>
<p><b>Binary encoding.
</b>
Decimal numbers are valid as encoding markers and specify the
number of bytes to read after the separating space. No special
characters exist in this syntax. This encoding is not meant for
interactive use, but for the sake of completeness, here is an
example:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># This entry has two attributes, givenname and cn:</b>
add cn=admin,ou=passwd,dc=blubba
givenname:5 Davidcn: admin</pre>
<p><b>File inclusion.
</b>
The less-than sign tells LDAP to read the contents of another
file and use them as the attribute value. This is another
LDIF compatibility feature.
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># oops</b>
add cn=haxor,ou=passwd,dc=blubba
comment:< file:///etc/passwd</pre>
<p><b>userPassword encodings.
</b>
The encodings crypt, cryptmd5, md5, smd5, sha, and ssha are
designed for the <tt>userPassword</tt> attribute. ldapvi takes
the right-hand side as the password, hashes it, and
prepends <tt>{ENCODING}</tt> as appropriate.
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code">userPassword:crypt foo
<b># ...could result in:</b>
userPassword: {CRYPT}KgJTUDs14z57Q
<b># ...or:</b>
userPassword: {CRYPT}UoILyHlM1bPYU
<b># cryptmd5 gives $1$ notation</b>
userPassword:cryptmd5 foo
userPassword: {CRYPT}$1$iKeAY9mQ$vmo/m/6EoDqRuVtjSqLPr0
<b># while the other encodings prepend the marker of the same name:</b>
userPassword:md5 foo
userPassword: {MD5}AQ3GmMeoPXozyRU4wsEDXA==</pre>
<br>
<h3>Change records<a name="syntax-changerecords"></a>
</h3>
Aside from the obvious <tt>add</tt> records mentioned above, there
are three change record formats:
<tt>rename</tt>, <tt>modify</tt>, and <tt>delete</tt>.
<p><b>rename records.
</b>
Like every other record, <tt>rename</tt> states the (original)
distinguished name of the name in the header line. Next is one
additional line stating the new distinguished name.
</p>
<p>
The complication is that LDAP's moddn operation needs to be told
what to do with the old relative DN if there is a new one. The
old one can be kept as an additional attribute value or deleted
in favour of the new one.
</p>
<p>
In ldapvi, this choice is made using the left-hand side of the
second line. It is either "add" or "replace".
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># example for "deleteoldrdn" behaviour:</b>
rename: cn=blub4,dc=lichteblau,dc=com
replace: cn=blub3,dc=neu,dc=com
<b># alternatively, the old RDN can be kept:</b>
rename: cn=blub3,dc=lichteblau,dc=com
add: cn=blub4,dc=neu,dc=com</pre>
<p>
In LDIF, the same changes would be written as:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># this is LDIF, not ldapvi syntax!</b>
dn: cn=blub4,dc=lichteblau,dc=com
changetype: modrdn
newrdn: cn=blub3
deleteoldrdn: 1
newsuperior: dc=neu,dc=com
dn: cn=blub3,dc=lichteblau,dc=com
changetype: modrdn
newrdn: cn=blub4
deleteoldrdn: 0
newsuperior: dc=neu,dc=com</pre>
<p><b>modify records.
</b>
These records state changes to attributes, processed in order.
Attributes can be changed by replacing their existing values
with a new set of values, adding those values to the existing
ones, or removing only selected old values.
</p>
<p>
Example:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># Let's add classes, delete a comment and remove cn entirely:</b>
modify: dc=bar,dc=lichteblau,dc=com
add: objectClass
: posixAccount
: specialAccount
delete: comment
: dummy user
replace: cn
</pre>
<p>
In LDIF, this would be:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># this is LDIF, not ldapvi syntax!</b>
dn: dc=bar,dc=lichteblau,dc=com
changetype: modify
add: objectClass
objectClass: posixAccount
objectClass: specialAccount
-
delete: comment
comment: dummy user
-
replace: cn
-</pre>
<p><b>delete records.
</b>
These are rather simple, they consist just of the header line.
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code">delete: dc=acme,dc=com</pre>
<p>
In LDIF, this would be:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"><b># this is LDIF, not ldapvi syntax!</b>
dn: dc=acme,dc=com
changetype: delete</pre>
<br>
<h3>Using LDIF syntax<a name="syntax-ldif"></a>
</h3>
<p>
When invoked
using <a href="#parameter-ldif"><tt>--ldif</tt></a>, ldapvi will
use <a href="http://www.rfc-editor.org/rfc/rfc2849.txt">RFC
2849</a> syntax instead of its own special syntax.
</p>
<p>
However, there is a special marker in each entry:
</p>
<p>
Existing entries are presented for editing with an additional
marker on the second line, just after the <tt>dn:</tt> line.
This line states the (numeric) <em>key</em> that would appear in
the header line if the entry had been printed in ldapvi syntax.
</p>
<p>
(New entries can have the same line, with <tt>add</tt> as their
key, but records with neither <tt>ldapvi-key</tt>
nor <tt>changetype</tt> are automatically assumed to be new
entries to add.)
</p>
<p>Also, <tt>control:</tt> is not supported.</p>
<p>
Examples:
</p>
<pre style="background-color: #eeeeee; color: #000000" class="code"># Existing entry
dn: dc=lichteblau,dc=com
<b>ldapvi-key: 0</b>
objectClass: top
objectClass: dcObject
objectClass: organization
o: lichteblau
dc: lichteblau
# New entry
dn: cn=admin,dc=lichteblau,dc=com
# next line is optional
<i>ldapvi-key: add</i>
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: admin
description: LDAP administrator
# Changerecord (standard LDIF syntax)
dn: cn=blub4,dc=lichteblau,dc=com
<i>changetype: modify</i>
delete: seeAlso
seeAlso: cn=dort
-
</pre>
<br>
<br><br>
<h2>ldapvi syntax (BNF)<a name="bnf"></a>
</h2>
<p>
As explained above, ldapvi has its own, vaguely LDIF-inspired
syntax. For a precise definition, see <tt>ldapvi-file</tt> below.
</p>
<p>
LDIF is defined in
<a href="http://www.rfc-editor.org/rfc/rfc2849.txt">RFC 2849</a>.
</p>
<p>
RFC 2849 modifies the language generated by its BNF grammar with
the "Notes on LDIF Syntax" (2) and (3) presented there. These
notes do not apply to ldapvi syntax as stated: Line folding and
comments can be used, but are allowed specificially by our
modified BNF, not hacked into the rules later. Line folding is
allowed only in LDIF-compatible attribute values and comments.
ldapvi files cannot be read line-by-line without knowing the
encoding of those lines, since newlines are permitted in certain
attribute value representations.
</p>
<p>
The following rules are used as defined in RFC 2849 and not
reproduced here: AttributeDescription, SAFE-STRING, BASE64-STRING,
SPACE.
</p>
<p><b>Changes to the RFC 2849 BNF grammar.
</b></p>
<pre style="background-color: #eeeeee; color: #000000" class="code">ldapvi-file = vspace ldapvi-record
*(vspace SEP vspace ldapvi-record) vspace
ldapvi-record = ldapvi-attrval-record
/ ldapvi-rename-record
/ ldapvi-modify-record
ldapvi-attrval-record = *(comment) dn-spec 1*(*(comment) attrval-spec)
ldapvi-rename-record = *(comment)
"rename" distinguishedName SEP
("add" / "replace") value-spec SEP
ldapvi-modify-record = *(comment)
"modify" distinguishedName SEP
1*(*(comment) mod-spec)
mod-spec = ("delete" / "add" / "replace") ad-value SEP
*(value-enc SEP)
vspace = *(comment / sep)
comment = "#" *(ldif-char) *(SEP " " *(ldif-char)) SEP
dn-spec = key distinguishedName SEP
key = number / "add"
distinguishedName = value-spec ;encoding an RFC 2253 DN
attrval-spec = AttributeDescription value-spec SEP
value-spec = value-simple / value-enc
value-simple = SPACE escaped-string ;escape CR/LF with '\\\\'
value-enc = (":;" SPACE escaped-string / ;ditto
":" SPACE 0*1(SAFE-STRING ;LDIF compatible
*(SEP " " *SAFE-CHAR)) /
"::" SPACE BASE64-STRING / ;ditto
":" number SPACE 0*1(octet) / ;exactly `number' octets
":<" SPACE url / ;only file:// supported
":crypt" SPACE password / ;for userPassword
":cryptmd5" SPACE password /
":md5" SPACE password /
":smd5" SPACE password /
":sha" SPACE password /
":ssha" SPACE password /
;; other encoding markers reserved
)
octet = %x00-ff
number = 1*(%x30-39) ;any decimal number
ldif-char = unescaped-char / %5c ;any except for CR/LF.
unescaped-char = %x00-%x09 / %x0a-%x0c / %x0d-%5b / %x5d-%ff
escaped-string = *(unescaped-char / %x5c %x0a / %x5c %x0d / %x5c %x5c)
password = 0*ldif-char
SEP = LF ;this is a unix program!
ad-value = value-spec ;parsing as an AttributeDescription</pre>
<br><br>
<h2>Reporting bugs<a name="bugs"></a>
</h2>
<p>
Please report bugs to the ldapvi mailing list for archival
purposes.
</p>
<p>
Address: <a href="mailto:ldapvi@lists.askja.de">ldapvi@lists.askja.de</a>
</p>
<br><br>
</body>
</html>
