Documentation for Cyrus::IMAP::Admin and friends

[Binarus]

Dear ellie,

you are really a champion!

On 18.12.2018 00:39, ellie timoney wrote:
> Hi Binarus,
> 
> Looks like the documentation for the authenticate() function is pretty incomplete...
> 
>> Well, this man page "documents" the method by exactly one line 
>> (identically in two places):
>>
>> $client->authenticate;
> 
> From my read of the documentation, this is enough.  It will figure out on its own which SASL options are appropriate, and then prompt you (on the controlling terminal) for the password if/as needed.  This nicely avoids implicitly instructing users to hardcode their credentials in a script, so in this sense it's probably good that it's underdocumented (maybe deliberately so).

This is great, and now I am embarrassed that I did not just try it.
Querying the password at runtime is by far better than hardcoding the
password and the mechanism in the script. Obviously, sometimes I am
trying to read too much or am thinking too complicated instead of just
trying ...

> Looking in the source of Cyrus::IMAP, the accepted arguments are:
> 
>> -mechanism, -service, -authz, -user, -minssf, -maxssf, -password, -tlskey, -notls, -cafile, -capath
> 
> If unspecified, "-service" defaults to "imap", "-maxssf" defaults to 10000, "user" defaults to the current unix user, and the rest default to zero or blank.  

Thank you very much for this insight. This is important and really
interesting ...

> Note that "user" is the user to authenticate as (i.e. whose credentials are to be checked), whereas "authz" is who to authoriZe as (i.e. which identity to assume, once successfully authenticated).  authz only works for SASL mechanisms that allow proxy authentication... the imtest(1) man page says "e.g. PLAIN, DIGEST-MD5", I'm not sure if there are others.

I think I saw something like that during my research. For example,
imapsync provides --proxyauth1 and --proxyauth2 command line parameters.

>> The same applies to CPAN: The modules cannot be found there.
> 
> The Cyrus::* perl modules are tightly coupled at build time to the installed cyrus version, so it doesn't make any sense to distribute them independently via CPAN.

I see. This makes sense.

>> Where can I find reasonable (in the sense: may be short and bad, but 
>> must be *complete*) documentation for Cyrus::IMAP::Admin and Cyrus::IMAP 
>> so that I can write my own helper scripts in the future? Do I really 
>> have to unpack Cyrus imapd's sources and read the module source code to 
>> get some ideas?
> 
> Sorta, but you don't need the Cyrus imapd sources -- if you have the perl module, you have the perl module's source.  Look for the "Cyrus/IMAP.pm" file somewhere on your system (something like "sudo find / -name IMAP.pm" should do the trick) and there it is.

Again, thank you very much. You are right, getting it from the Perl
installation is by far easier. Before actually opening it, I'll copy it
to another place and work with the copy (in case I accidentally alter it
while looking at it).

> Cheers,

I can't tell how grateful I am for your support (and for providing Cyrus
imapd in general). IMHO, this is still the best IMAP server for small
and large installations!

Thank you very much again,

Binarus