.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MUTT_LDAP_QUERY 1" .TH MUTT_LDAP_QUERY 1 "2022-09-18" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" mutt_ldap_query \- Query LDAP server for Mutt mail\-reader .SH "SYNOPSIS" .IX Header "SYNOPSIS" mutt_ldap_query.pl [options] [[] ...] .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-\-config=config_file\fR or \fB\-c config_file\fR" 8 .IX Item "--config=config_file or -c config_file" specify an alternate resource file other than the system ones (\fI/etc/lbdb_ldap.rc\fR or \fI/etc/mutt_ldap_query.rc\fR) or default personal ones (\fI\f(CI$HOME\fI/.lbdb/ldap.rc\fR or \&\fI\f(CI$HOME\fI/.mutt_ldap_query.rc\fR). .IP "\fB\-\-server=ldap_server\fR or \fB\-ls ldap_server\fR" 8 .IX Item "--server=ldap_server or -ls ldap_server" hostname of your ldap server. You can also use an ldap://foo[:port] or ldaps://foo[:port] \s-1URL\s0 here to talk to different ports or \s-1SSL\s0 encrypted servers. Or use ldapi://%2fvar%2flib%2fldap_sock to access an ldap server via a socket (use \f(CW%2f\fR as as replacement for a slash in the file name). .IP "\fB\-\-search_base=ldap_search_base\fR or \fB\-sb ldap_search_base\fR" 8 .IX Item "--search_base=ldap_search_base or -sb ldap_search_base" use as the starting point for the search instead of the default. .IP "\fB\-\-search_fields=ldap_search_fields\fR or \fB\-sf ldap_search_fields\fR" 8 .IX Item "--search_fields=ldap_search_fields or -sf ldap_search_fields" list of the fields on which the query will be performed. .IP "\fB\-\-expected_answers=ldap_expected_answers\fR or \fB\-ea ldap_expected_answers\fR" 8 .IX Item "--expected_answers=ldap_expected_answers or -ea ldap_expected_answers" list of the fields expected as the answer of the ldap server that will be used for composing the output of the script. .IP "\fB\-\-format_email=result_format_email\fR or \fB\-fe result_format_email\fR" 8 .IX Item "--format_email=result_format_email or -fe result_format_email" format to be used for composing the email output result. It has to be based on the expected ldap server answers and can use variable containers of the form ${variable} where variable belongs to the set. .IP "\fB\-\-format_realname=result_format_realname\fR or \fB\-fr result_format_realname\fR" 8 .IX Item "--format_realname=result_format_realname or -fr result_format_realname" format to be used for composing the realname output result. It has to be based on the expected ldap server answers and can use variable containers of the form ${variable} where variable belongs to the set. .IP "\fB\-\-format_comment=result_format_comment\fR or \fB\-fc result_format_comment\fR" 8 .IX Item "--format_comment=result_format_comment or -fc result_format_comment" format to be used for composing the comment output result. It has to be based on the expected ldap server answers and can use variable containers of the form ${variable} where variable belongs to the set. .IP "\fB\-\-bind_dn=bind_distinguished_name\fR or \fB\-bd bind_distinguished_name\fR" 8 .IX Item "--bind_dn=bind_distinguished_name or -bd bind_distinguished_name" the destinguished name of the user who binds to the \s-1LDAP\s0 server. Leave it empty for an anonmyous bind. .IP "\fB\-\-bind_password=secret\fR or \fB\-bp secret\fR" 8 .IX Item "--bind_password=secret or -bp secret" the bind password for binding to the \s-1LDAP\s0 server. Leave it empty for an anonmyous bind. .IP "\fB\-\-tls=1\fR or \fB\-\-tls=0\fR" 8 .IX Item "--tls=1 or --tls=0" enable or disable transport layer security (\s-1TLS\s0). .IP "\fB\-\-sasl_mech=mechanism\fR or \fB\-sm mechanism\fR" 8 .IX Item "--sasl_mech=mechanism or -sm mechanism" the \s-1SASL\s0 mechanism, for example \s-1GSSAPI\s0 (empty string to turn off). .IP "\fB\-\-nickname=ldap_server_nickname\fR or \fB\-n ldap_server_nickname\fR" 8 .IX Item "--nickname=ldap_server_nickname or -n ldap_server_nickname" shortcut for avoiding to use all the previous options by using the script builtin or alternate config file table of common servers and associated options. All the required parameters are then derived by performing a lookup. .IP "\fB\-\-debug\fR or \fB\-d\fR" 8 .IX Item "--debug or -d" turn on debugging messages. .IP "\fB\-\-help\fR or \fB\-?\fR or \fB\-h\fR or \fB\-\-man\fR or \fB\-m\fR" 8 .IX Item "--help or -? or -h or --man or -m" generates this help message. .IP "\fB\-\-ignorant\fR or \fB\-i\fR" 8 .IX Item "--ignorant or -i" ignorant mode: search using wildcard for *name_to_query* (requires a longer processing from \s-1LDAP\s0 server but is quite convenient :). .IP "\fB\-\-lbdb_output\fR or \fB\-l\fR" 8 .IX Item "--lbdb_output or -l" suppress number of matches output (suited for interfacing with little brother database https://www.spinnaker.de/lbdb/) .IP "\fB\-\-version\fR or \fB\-v\fR" 8 .IX Item "--version or -v" show the version. .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBmutt_ldap_query\fR performs ldap queries using either ldapsearch command or the perl-ldap module and it outputs the required formatted data for feeding mutt when using its \*(L"External Address Query\*(R" feature. .PP The output of the script consists in 3 fields separated with tabs: the email address, the name of the person and a comment. .SH "INTERFACING WITH MUTT" .IX Header "INTERFACING WITH MUTT" This perl script can be interfaced with mutt by defining in your .muttrc: .PP .Vb 1 \& set query_command = "mutt_ldap_query.pl %s" .Ve .PP Multiple requests are supported: the \*(L"Q\*(R" command of mutt accepts as argument a list of queries (e.g. \*(L"Gosse de\e Courville\*(R"). .PP Alternatively mutt_ldap_query can be interfaced with the more generic little brother database query program (https://www.spinnaker.de/lbdb/) using: .PP .Vb 1 \& set query_command = "lbdbq %s" .Ve .PP and by specifying in your ~/.lbdb/lbdbrc file another method of query just adding to the \s-1METHODS\s0 variable the m_ldap module e.g.: .PP .Vb 1 \& METHODS=\*(Aqm_inmail m_passwd m_ldap m_muttalias m_finger\*(Aq .Ve .PP and the right path to access m_ldap in \s-1MODULES_PATH,\s0 e.g. if you moved \&\fIm_ldap\fR in \fI~/.lbdb/modules\fR: .PP .Vb 1 \& MODULES_PATH="/usr/local/lib $HOME/.lbdb/modules" .Ve .PP Just make sure to use the correct path for calling mutt_ldap_query in the m_ldap script. .SH "RESOURCE FILE FORMAT" .IX Header "RESOURCE FILE FORMAT" mutt_ldap_query is now fully customizable using an external resource file. By default mutt_ldap_query parses the system definition file located generally at \fI/etc/mutt_ldap_query.rc\fR or \&\fI/usr/local/etc/mutt_ldap_query.rc\fR and also the user one: \&\fI\f(CI$HOME\fI/.mutt_ldap_query.rc\fR. .PP Instead of using command line options, the user can redefine all the variables using the resource file by two manners in order to match his site configuration. A file example is provided below: .PP .Vb 8 \& # The format of each entry of the ldap server database is the following: \& # LDAP_NICKNAME => [\*(AqLDAP_SERVER\*(Aq, \& # \*(AqLDAP_SEARCH_BASE\*(Aq, \& # \*(AqLDAP_SEARCH_FIELDS\*(Aq, \& # \*(AqLDAP_EXPECTED_ANSWERS\*(Aq, \& # \*(AqLDAP_RESULT_EMAIL\*(Aq, \& # \*(AqLDAP_RESULT_REALNAME\*(Aq, \& # \*(AqLDAP_RESULT_COMMENT\*(Aq], \& \& # a practical illustrating example being: \& # debian => [\*(Aqdb.debian.org\*(Aq, \& # \*(Aqou=users,dc=debian,dc=org\*(Aq, \& # \*(Aquid cn sn ircnick\*(Aq, \& # \*(Aquid cn sn ircnick\*(Aq, \& # \*(Aq${uid}@debian.org\*(Aq, \& # \*(Aq${cn} ${sn}\*(Aq, \& # \*(Aq${ircnick}\*(Aq], \& # the output of the query will be then: \& # ${uid}@debian.org\et${cn} ${sn}\et${ircnick} (i.e.: email name comment) \& \& # warning this database will erase default script builtin \& %ldap_server_db = ( \& \*(Aqfour11\*(Aq => [\*(Aqldap.four11.com\*(Aq, \& \*(Aqc=US\*(Aq, \& \*(Aqgivenname sn cn mail\*(Aq, \& \*(Aqgivenname cn sn mail o\*(Aq, \& \*(Aq${mail}\*(Aq, \& \*(Aq${givenname} ${sn}\*(Aq, \& \*(Aq${o}\*(Aq ], \& \*(Aqinfospace\*(Aq => [\*(Aqldap.infospace.com\*(Aq, \& \*(Aqc=US\*(Aq, \& \*(Aqgivenname sn cn mail\*(Aq, \& \*(Aqgivenname cn sn mail o\*(Aq, \& \*(Aq${mail}\*(Aq, \& \*(Aq${givenname} ${sn}\*(Aq, \& \*(Aq${o}\*(Aq ], \& \*(Aqwhowhere\*(Aq => [\*(Aqldap.whowhere.com\*(Aq, \& \*(Aqc=US\*(Aq, \& \*(Aqgivenname sn cn mail\*(Aq, \& \*(Aqgivenname cn sn mail o\*(Aq, \& \*(Aq${mail}\*(Aq, \& \*(Aq${givenname} ${sn}\*(Aq, \& \*(Aq${o}\*(Aq ], \& \*(Aqbigfoot\*(Aq => [\*(Aqldap.bigfoot.com\*(Aq, \& \*(Aqc=US\*(Aq, \& \*(Aqgivenname sn cn mail\*(Aq \& , \*(Aqgivenname cn sn mail o\*(Aq \& , \*(Aq${mail}\*(Aq \& , \*(Aq${givenname} ${sn}\*(Aq, \& \*(Aq${o}\*(Aq ], \& \*(Aqswitchboard\*(Aq => [\*(Aqldap.switchboard.com\*(Aq, \& \*(Aqc=US\*(Aq, \& \*(Aqgivenname sn cn mail\*(Aq \& , \*(Aqgivenname cn sn mail o\*(Aq, \& \*(Aq${mail}\*(Aq, \& \*(Aq${givenname} ${sn}\*(Aq, \& \*(Aq${o}\*(Aq ], \& \*(Aqinfospacebiz\*(Aq => [\*(Aqldapbiz.infospace.com\*(Aq, \& \*(Aqc=US\*(Aq, \& \*(Aqgivenname sn cn mail\*(Aq, \& \*(Aqgivenname cn sn mail o\*(Aq, \& \*(Aq${mail}\*(Aq, \& \*(Aq${givenname} ${sn}\*(Aq, \& \*(Aq${o}\*(Aq ], \& ); \& \& # hostname of your ldap server \& $ldap_server = \*(Aqldap.four11.com\*(Aq; \& # ldap base search \& $search_base = \*(Aqc=US\*(Aq; \& # list of the fields that will be used for the query \& $ldap_search_fields = \*(Aqgivenname sn cn mail\*(Aq; \& # list of the fields that will be used for composing the answer \& $ldap_expected_answers = \*(Aqgivenname sn cn mail o\*(Aq; \& # format of the email result based on the expected answers of the ldap query \& $ldap_result_email = \*(Aq${mail}\*(Aq; \& # format of the realname result based on the expected answers of the ldap query \& $ldap_result_realname = \*(Aq${givenname} ${sn}\*(Aq; \& # format of the comment result based on the expected answers of the ldap query \& $ldap_result_comment = \*(Aq(${o})\*(Aq; .Ve .SH "EXAMPLES OF QUERIES" .IX Header "EXAMPLES OF QUERIES" .Vb 8 \& mutt_ldap_query.pl \-\-ldap_server=\*(Aqldap.mot.com\*(Aq \e \& \-\-search_base=\*(Aqou=employees, o=Motorola,c=US\*(Aq \e \& \-\-ldap_search_fields=\*(AqcommonName gn sn cn uid\*(Aq \e \& \-\-ldap_expected_answers=\*(Aqgn sn preferredRfc822Recipient ou c telephonenumber\*(Aq \e \& \-\-ldap_result_email=\*(Aq${preferredRfc822Recipient}\*(Aq \e \& \-\-ldap_result_realname=\*(Aq${gn} ${sn}\*(Aq \e \& \-\-ldap_result_comment=\*(Aq(${telephonenumber}) ${ou} ${c}\*(Aq \e \& Gosse de\e Courville .Ve .PP performs a query using the ldap server ldap.mot.com using the following searching base 'ou=employees, o=Motorola,c=US' and performing a search on the fields 'commonName gn sn cn uid' for 'Gosse' and then \*(L"de Courville\*(R" looking for the following answers 'gn sn preferredRfc822Recipient ou c telephonenumber'. Based on this answers, mutt_ldap_query will return a list of entries identified of the form: .PP .Vb 1 \& <${preferredRfc822Recipient}>\et${gn} ${sn}\et(${telephonenumber}) ${ou} ${c} .Ve .PP where ${} variables should be considered as containers that are replaced by the results of the query. The previous query can be greatly simplified by using the ldap server mini database feature of the resource file introducing for example a nickname. .PP .Vb 1 \& mutt_ldap_query.pl \-\-ldap_server_nickname=\*(Aqmotorola\*(Aq Gosse de\e Courville .Ve .PP When not sure of the full name (i.e. it should contain Courville) the ignorant mode is useful since the query will be performed using wildcards, i.e. *Courville* in the following case: .PP .Vb 1 \& mutt_ldap_query.pl \-\-ignorant Courville .Ve .SH "WHERE TO GET IT" .IX Header "WHERE TO GET IT" The latest version can be retrieved at ftp://ftp.mutt.org/pub/mutt/contrib or http://www.courville.org/ .PP Note that now the script is integrated in the latest version of the little brother database available at https://www.spinnaker.de/lbdb/. It is thus easier to use through this standard package than to hand customize it to fit your system/distribution needs. .SH "REFERENCES" .IX Header "REFERENCES" .IP "\-" 2 perl-ldap module http://perl\-ldap.sourceforge.net/ .IP "\-" 2 mutt is the ultimate email client http://www.mutt.org/ .IP "\-" 2 historical Brandon Blong's \*(L"External Address Query\*(R" feature patch for mutt http://www.fiction.net/blong/programs/mutt/#query .IP "\-" 2 little brother database is an interface query program for mutt that allow multiple searches for email addresses based on external query scripts just like this one 8\-) https://www.spinnaker.de/lbdb/ .SH "AUTHORS" .IX Header "AUTHORS" Marc de Courville and the various other contributors... that kindly sent their patches. .PP Please report any bugs, or post any suggestions, to . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1998\-2003 Marc de Courville . All rights reserved. This program is free software; you can redistribute it and/or modify it under the \s-1GNU\s0 General Public License (\s-1GPL\s0). See http://www.opensource.org/gpl\-license.html and http://www.opensource.org/.