| ldapsh - Shell for an easy LDAP access and content changes |
ldapsh - Shell for an easy LDAP access and content changes
ldapsh [expression]
For readability reasons, the example can only be viewed on the HTML version of the documentation (use the pod2html command).
bash-prompt> ldapsh>
[LDAP @ ] > ads
Password > ***********
[LDAP @ adsserver] dc=linkvest,dc=com > ls
OU=France
OU=Switzerland
-----
2 entries found
[LDAP @ adsserver] dc=linkvest,dc=com > cd ou=Switzerland,ou=Users
[LDAP @ adsserver] ou=Users,ou=Switzerland,dc=linkvest,dc=com > search 'department=*'
95 entries found
[LDAP @ adsserver] ou=Users,ou=Switzerland,dc=linkvest,dc=com > apply {$_->replace('department', ['New Dept']) if $_->get_value('department') =~ /CCSR/}
[LDAP @ adsserver] ou=Users,ou=Switzerland,dc=linkvest,dc=com > changes
========================================
CN=Test user 1,OU=Users,OU=Switzerland,DC=linkvest,DC=com
>>> Replace attribute 'department' with values: 'New Dept'
========================================
CN=Test user 2,OU=Users,OU=Switzerland,DC=linkvest,DC=com
>>> Replace attribute 'department' with values: 'New Dept'
========================================
CN=Test user 3,OU=Users,OU=Switzerland,DC=linkvest,DC=com
>>> Replace attribute 'department' with values: 'New Dept'
========================================
CN=Test user 4,OU=Users,OU=Switzerland,DC=linkvest,DC=com
>>> Replace attribute 'department' with values: 'New Dept'
========================================
CN=Test user 5,OU=Users,OU=Switzerland,DC=linkvest,DC=com
>>> Replace attribute 'department' with values: 'New Dept'
========================================
CN=Test user 6,OU=Users,OU=Switzerland,DC=linkvest,DC=com
>>> Replace attribute 'department' with values: 'New Dept'
========================================
6 entries to commit
[LDAP @ adsserver] ou=Users,ou=Switzerland,dc=linkvest,dc=com > commit
Changed 6 entries of 95. 0 errors.
[LDAP @ adsserver] ou=Users,ou=Switzerland,dc=linkvest,dc=com > quit
bash-prompt>
ldapsh is a shell that allows you to work in an interactive way with LDAP entries. Usually, system administrators use scripts (shell, perl, python...) to do massive changes or to take a look inside an LDAP directory. With this shell you can navigate through the directory almost as it it were a filesystem. You have a current working directory ($CWD) and you enter ls to list the entries in this ``directory''. You can change the current working directory using cd and display an entry using cat.
If you have to remember only one thing, it is: This shell is simply a set of Perl functions and all you do is to call functions from a prompt.
You can request help typing help [<command>] or, if you use
Term::ReadLine::Gnu, you can type <CTRL-t> after a command
to get help on it.
ldapsh includes a simple command-line interpreter. It can also make use of the optional Psh module for an enhanced user experience. This manual describes both interpreters as indicated by [ldapsh] and [Psh], respectively. Both interpreters facilitate evaluation of Perl expressions and you may use the $G variable to store your own data.
In this manual, command options are shown as '-l', to be compatible with the
Perl eval() function. However, you do not usually need to type the
apostrophes because ldapsh will insert them automatically. If you have
Psh installed, you do not need to use commas, either.
[ldapsh] Whatever you type at the prompt will either be:
system() call (if your entry starts with an exclamation mark).eval()).For convenience, a few commands (such as cd, lcd and help)
automatically quote their arguments. Thus, you can type cd ou=Users
instead of cd "ou=Users".
[Psh] What you type at the prompt will be passed through a number of handlers that facilitate a rich shell-like syntax. The order of precedence is: exclamation mark, brace, ldapsh commands, Perl functions, shell executables, Perl evaluation. Please note the following examples for correct quoting of strings, arrays, and hashes:
$CWD literally: echo '$CWD'$ENV{PATH} literally: echo '$ENV{PATH}'
Almost every function that uses LDAP entries (ls, cat,
ldif, dump, etc...) has three syntaxes. Such functions are
identified in the documentation with a usage like: ls <expansion>
The three syntaxes are:
-r
argument is used, in which case the scope is sub. The base for the search
is the current working directory.
The results of the search are put in the $ENTRIES array reference (composed of Net::LDAP::Entry entries).
(objectclass=*).
If neither -r nor the dot (a.k.a. ``full stop'' or ``period'') is given, the
scope is one. If -r is given, the scope is sub. If the dot is
given, the scope is base (this can be used to match the current working
directory itself).
By default, LDAP results are displayed on the ``standard output'' while diagnostic messages are printed to the ``standard error''.
You may redirect search results using the redir command. This will stay in effect until noredir is called.
[Psh] Psh allows you to use standard shell symbols such as ``|'' (for piping) and ``>'' (for output redirection).
[ldapsh] Alternatively, you can use a special shell syntax which will have only a
temporary effect. The special syntax is appending ``; | ...'' to your command,
where ``...'' is a parameter to the open function.
For example:
ldapsh> redir '|awk "/Smith/{print}"'
ldapsh> cat
cn: Jack Smith
sn: Smith
cn: Jill Smith
sn: Smith
ldapsh> version;|cat
LDAP Shell (ldapsh) by Rafael Corvalan.
ldapsh> cat
cn: Jack Smith
sn: Smith
cn: Jill Smith
sn: Smith
ldapsh> noredir
ldapsh uses the following Perl modules:
ldapsh can benefit from the following Perl modules:
Synopsis: which '<command>'
A synonym for help <command>.
Synopsis: help ['<command>'|'all']
Display help about the given command (or global help, if 'all' is given). If no parameter is given, a summary of commands will be shown.
Display the version of the LDAP Shell you're using.
Synopsis: set ['-a']
Display the names and values of the global variables you can set. The purpose of this function is to help the user to remember the names of the variables he can set. The -a parameter allows read-only values to be seen.
Save the history and quits the shell.
A synonym for exit.
Synopsis: connect [$server]
Connect to an LDAP Server. If no server name is given, one is taken from $CONNPARAMS->{SERVER} (see Variables and the set command).
Synopsis: bind [$binddn]
Bind to the LDAP Server. Connects first, if not connected. If no $binddn is given, the bind command uses $CONNPARAMS->{BINDDN}. If this variable is empty, binding will be anonymous.
Unbind from the LDAP Server. The connection is invalid after an unbind. If you would like to rebind using a new DN, just do a new bind without unbinding.
A synonym for unbind.
Display the DN used to bind. The value is one of:
Synopsis: echo @list
Display each item in the list, appending a carriage return after each item.
Example: echo scalar(@$ENTRIES)
Synopsis: loadrc [<file>]
Load and ``run'' the Perl file <file> using the do Perl function. If no filename is given, ldapsh tries to load ~/.ldapshrc.
Synopsis: source <file>
A synonym for loadrc <file>.
TODO
Synopsis: history
Print out each line of the command-line history, if Term::ReadLine::Gnu is available.
Reset the Term::ReadLine status.
Synopsis: rdn '<DN>'
Return (but do not print) the RDN of the DN that was given as a string argument.
Synopsis: cd ['<RDN>' | '<foo>', '<bar>' | '-']
Change the current working directory to the specified RDN.
You can specify multiple RDNs separated by commas (in the reverse order of the DN, to allow completion).
You can also specify .. to go to the parent DN.
If no RDN is specified, the current working directory is not changed.
If - is specified, $OLDWD is swapped with the current working directory.
If foo and bar are specified, bar will be substituted for foo
in the current working directory and the result will be used to
invoke setdn. If foo was not present in $CWD,
the current working directory is not changed.
See also the acd, setdn, pushd and popd commands.
Synopsis: setdn '<DN>'
Change the current directory to the specified DN. Unlike the cd command, the argument is a DN, not an RDN. This command has a synonym named acd.
Synopsis: acd '<DN>'
A synonym for setdn. (The name is an abbreviaton of ``absolute cd''.)
Synopsis: pushd ['<RDN>' | '<foo>', '<bar>' | '-']
Perform the same action as the cd command. If the action succeeds, the old working directory is stored on a stack (which can be shown using dirs). It can be restored using popd.
If no RDN is given, the current working directory will be pushed onto the stack.
Synopsis: popd
Pop a directory from the directory stack (see pushd) and change the current working directory to the popped directory.
Synopsis: dirs
Show the directory stack (see pushd and popd).
Display the current working directory.
Synopsis: lcd '<localdir>'
Change the local (filesystem) working directory.
Synopsis: lpwd '<localdir>'
Display the name of the local (filesystem) working directory.
Synopsis: usearch '[/BaseDN][?[Attributes][?[Scope][?Filter]]]]'
Search using an LDAP URL. The LDAP URL does not contain Host and Port since you must be connected and bound prior to running this command.
The resulting entries are stored in the $ENTRIES array reference.
Returns a reference to an array containing the Net::LDAP::Entry objects found.
Synopsis: search <expansion>
Search for the entries matched by the expansion (see Expansion). Does not dump the entries themselves, only a summary of the search results.
Returns a reference to an array containing the Net::LDAP::Entry objects found.
Synopsis: ldif <expansion>
Display the entries matched by the expansion (see Expansion) using the LDIF format. See also cat.
Returns a reference to an array containing the Net::LDAP::Entry objects found.
Synopsis: cat <expansion>
A synonym for ldif.
Synopsis: dump <expansion>
Dump the entries matched by the expansion (see Expansion) in a relatively human-readable format.
Synopsis: list ['-a',] ['-dn',] <expansion>
Display the attribute values of the entries matched by the expansion (see Expansion) in a list format (easy to parse).
Arguments:
Synopsis: csv [<options>,] <expansion>
Display the entries matched by the expansion (see Expansion) in a CSV format.
The first argument can be a list of options to tell how to format the file. If it's given, it's a hash reference.
Exemple: csv -fs => "\t", -dn, $ENTRIES
The possible options are:
-fs: Field Separator. Default: ``;''-vs: Value separator (for multi-valued attributes). Default: ``|''-nomv: For multi-valued attributes, show only one attribute value.-dn: Output the DN of the entries.
Synopsis: ls ['-C',|'-m',] ['-l',] <expansion>
List the DNs of the entries matched by the expansion (see Expansion). Entries are displayed in the order received (no sorting is performed), with one entry per line.
The -C argument requests multi-column output (the default is to print only one column per line).
ldapsh uses as many columns as will fit into the character width of the terminal (see $COLUMNS).
If -m is also specified, columns will be separated by $DNSEP (the default string is ``; '').
The separator is omitted from the last entry on each line.
The -m argument requests that all entries be printed on a single line,
with entries separated by the $DNSEP string (the default string is ``; '').
The separator appears after every entry (including the last one).
Synopsis: redir ['<spec>']
Redirect ldapsh's output. spec is used as a parameter to the open
function, so you can specify, for example:
If no argument is given, the current redirection will be displayed.
Synopsis: sink ['<spec>']
A synonym for redir ['<spec>'].
Synopsis: noredir
No longer perform any of the redirections that were previously specified using redir.
Synopsis: nosink
A synonym for noredir].
Synopsis: create ['-d',|'-k',|'-m',|'-n',|'-q',|'-v',] '<RDN|DN>' [,'<objectclass>' ...]
Create a new LDIF file based on the specified distinguished named and object classes. By default, the LDIF file will be populated with attributes to comply with the schema supplied by the LDAP server. A text editor will then be invoked on the LDIF file. In the file is subsequently edited, a new LDAP entry will be created. Upon success, the LDIF file is deleted. Note: you must be sure to create a valid LDIF file from the template that is provided to you. If you do not, an entry cannot be created. If this error occurs, your invalid LDIF file will be preserved for your convenience.
By default, the LDIF file is populated with all attributes specified in the schema
('MUST' and 'MAY'). When the -m parameter is given, only 'MUST' attributes
are included. The -n parameter prevents schema-based population.
The -q parameter suppresses informational comments about each attribute
while -v prints verbose information about each attribute.
The -k parameter prevents deletion of the LDIF file (regardless of success),
while -d forces deletion (regardless of failure).
A synonym for create.
A synonym for create.
Synopsis: remove ['-a',] ['-f',] <expansion>
Remove entries from the directory. Unless the -f parameter is given, the
command will prompt you prior to starting and will stop if an error is
encountered. You may specify -r, too, as a normal part of expansion (see
Expansion). If -a is specified, an attempt will be made to
delete leaf entries before their parent entries. Thus, to delete an entire
subtree, you might try this:
cd 'cn=Old Directory Subtree' remove '-ar' cd '-'
A synonym for remove.
Synopsis: cp '<from-expansion>'|'*' '<to>'
Copy an entry to a new DN or copy a set of entries to new locations in the LDAP tree.
from-expansion will be expanded in the usual way
(see Expansion), with the addition that * corresponds to
the filter (objectclass=*).
If the to parameter is an RDN, a single object will be copied to a new RDN within
the same level of the LDAP tree, and you will get an error if from-expansion
expands to more than one object.
If to is a DN, all the objects from from-expansion will be be copied to
the new location, using to as a base DN and retaining their old RDNs.
This makes it convenient to copy many objects.
TODO: With to being a DN, we may want to copy entire subtrees.
Currently we only copy objects as leaves.
Synopsis: rename '<from-expansion>'|'*' '<to>'
Rename an entry with a new RDN or move a set of entries to new locations in the LDAP tree.
from-expansion will be expanded in the usual way
(see Expansion), with the addition that * corresponds to
the filter (objectclass=*).
If your directory server does not allow subtrees to be moved, you may have to copy entries to a new location and then remove the old subtree (see cp and remove).
A synonym for rename.
Synopsis: vi <expansion>
Show the entries matched by the expansion (see Expansion) in a text editor. Entries are saved to a temporary file for editing in the LDIF format. If the temporary file is modified, it will be re-read as an LDIF file and used to modify the search results. Any changes can be viewed using changes and will need to be committed using commit. BUG (TODO): If you add an attribute to an entry (so, if you add a value to an attribute that hadn't previously a value), it will not be detected. We should do a two-way check.
A synonym for apply.
Synopsis: apply {<your code>} [$entries]
Apply some code to the local copies of the LDAP entries.
You can use the variable $_ in your code (it will refer to an Net::LDAP::Entry object).
If no entries are given, the apply command uses the $ENTRIES global variable.
The entries are merely locally modified! You must commit! You can see the changes using the changes command.
Example: apply {$_->replace('department', ['New Dept']) if $_->get_value('department') =~ /CCSR/}
Synopsis: add '<attribute>', '<value>' ...
Add one or more new attributes to the entries in the $ENTRIES global variable.
The values will be added to the values that already exist for the given attribute.
The entries are locally modified! You must commit! You can see the changes done using the changes command.
Example: add 'givenName', 'Bob', 'Robert'
Synopsis: replace '<attribute>', '<value>' ...
Similar to add, except that the given values will replace any values that already exist for the given attribute.
The entries are merely locally modified! You must commit! You can see the changes using the changes command.
Example: replace 'givenName', 'Bill', 'William'
Synopsis: delete '<attribute>'[, '<value>' ...]
Delete the values of given attribute from the the $ENTRIES global variable. If no values are given, the entire attribute will be deleted.
The entries are locally modified! You must commit! You can see the changes done using the changes command.
Example: delete 'givenName'
Synopsis: changes [$entries]
Show the changes done to the entries given in the $entries array reference (or $ENTRIES, if omitted). You can apply some changes to a set of entries using the apply command, and see the changes using the changes command.
Synopsis: commit [$entries]
Commit local changes to the server. You can modify the a set of entries using the apply command.
Synopsis: nbentries [$entries]
Display the number of entries in $entries (or the global variable $ENTRIES if omitted).
Synopsis: append
The entries found in a search will in future be appended to the $ENTRIES variable instead of replacing any existing values. Returns 0 if the previous mode was ``append'' and 1 if the previous mode was ``noappend''.
Synopsis: append
The entries found in a search will replace the values on the $ENTRIES variable, instead of being appended. Returns 1 if the previous mode was ``append'' and 0 if the previous mode was ``noappend''.
Synopsis: exclude [$entries] '<regexp>'
Remove the entries whose DNs match the given regexp from the $entries list (or the global variable $ENTRIES if omitted).
This is very useful for creating aliases. Here is an example of what you can put on your .ldapshrc:
sub ads {
$CONNPARAMS{SERVER} = 'ads.company.com';
$CONNPARAMS{BINDDN} = '.. blabla ...';
$CWD='dc=linkvest,dc=com';
connect;
bind;
}
So, in your shell you can type ``ads'' and get connected to a specific server.
Additionally, you could invoke ldapsh as ldapsh ads to call the function
straight away.
Remember: you put in this file Perl code. So you can do whatever you want!!!
The width of the output device in characters (decimal string). Its initial value is obtained from the environment or the Term::Size module, with a default of 80 characters.
The name of the server to connect to when the connect function will be called.
The DN to bind with when the bind function will be called.
The port to connect to when the connect function will be called. 389 by default.
The protocol version to use (3 by default).
Set this to 'tls' if you connect to the standard LDAP port and use Transport Layer Security for encryption. Set this to 'ssl' if you want to use SSL to a dedicated port on the server. Any other value, including not setting this at all, will get you an unencrypted connection.
Currently, no certificate verification is done.
The current working directory in the LDAP Directory Tree. You can change the current working directory (relatively with the cd command, or absolutely using this variable).
String used to separate DNs on a line (see ls).
The default editor used when the vi command is called. By default, this is obtained from the environment variable $VISUAL (if set) or $EDITOR (if set) or otherwise ``vi''.
The buffer of entries (Net::LDAP::Entry). It's an array reference. Contains the last entries got with the commands ls, cat, search...
A global variable you can use as you want. As we use the strict module, you cannot declare variables in the shell without using my. And if you use my, the scope of your variable is the line you entered, so your variable will not live until the next command you type.
Using this variable you can store objects, scalars, everything you want.
Example: $G = $ENTRIES
Will save the entries found during the last search, so you can use this later. You only have one global variable for your own use, so if you need more than one, set this variable to a hash:
Example: $G = {ENTRIES = $ENTRIES, PWD => $PWD}; $G->{TIME} = time();>
Contains the Net::LDAP handler. Use it only if you know what you are doing...
The immediate past current working directory, updated by the cd and setdn commands.
The prompt template. It will be ``eval''ed so will do variable substitution. You can use the ${APP} variable to display ``**'' when you are in ``append mode'' (see append and noappend).
Example: $PROMPT = '${APP}\[LDAP @ $CONNPARAMS->{SERVER}] $CWD > '
By chronological contribution:
Please report bugs to the mailing list <ldapsh-devel@lists.sourceforge.net> or through <http://sourceforge.net/tracker/?group_id=54115&atid=472731>.
Send comments and suggestions to the above mailing list.
Post Feature Requests to <http://sourceforge.net/tracker/?group_id=54115&atid=472734>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. If you have some enhancements or bug corrections, I'd appreciate if you send them to me so I can improve the original version.
| ldapsh - Shell for an easy LDAP access and content changes |