Documentation for Cyrus::IMAP::Admin and friends

[ellie timoney]

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).

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.  

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.

> 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.

> 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.

Cheers,

ellie

On Sun, Dec 16, 2018, at 9:55 PM, Binarus wrote:
> Dear all,
> 
> as described in my previous messages, I recently had a hard time 
> relocating (i.e. moving) mailboxes and the public namespace from 2.4.16 
> to a new server running 2.5.10. I would have happily written a Perl 
> script which surely had solved much of my problems, but I couldn't do 
> that due to the lack of documentation for the respective Perl modules.
> 
> This is best explained by example:
> 
> I have found a Perl script on the 'net which looks trustworthy at the 
> first sight and which contains (among others) the following lines of 
> code:
> 
> use Cyrus::IMAP::Admin;
> 
> # Connect to Cyrus
> $imap = Cyrus::IMAP::Admin->new("my_server") || die "Unable to connect 
> to my_server";
> 
> $imap->authenticate(-user => "foo", 
> 		-mechanism => "LOGIN",
> 		-password => "password",
> 		);
> 
> I wanted to understand exactly what the script does and thus tried to 
> find Cyrus::IMAP::Admin's documentation. So I issued
> 
> man Cyrus::IMAP::Admin
> 
> and found that some methods are documented, but not the authenticate() 
> method which is needed first and one of the most important ones. 
> However, the man page states (in the section about the "new()" method):
> 
> "Instantiates a cyradm object.  This is in fact an Cyrus::IMAP object 
> with a few additional methods, so all Cyrus::IMAP methods are available 
> if needed.  (In particular, you will always want to use the 
> "authenticate" method.)"
> 
> This tricked me into believing that the "authenticate" method would be 
> part of Cyrus::IMAP and would be explained in that module's 
> documentation, so I issued
> 
> man Cyrus::IMAP
> 
> Well, this man page "documents" the method by exactly one line 
> (identically in two places):
> 
> $client->authenticate;
> 
> It does not explain anything about it; notably, it does not mention any 
> parameters. But from the example script mentioned above, I knew that 
> there was more to it. So I read the rest of that man page and found:
> 
> "The Cyrus::IMAP module provides an interface to the Cyrus imclient library."
> 
> So I installed the development files for Cyrus imapd and issued
> 
> man imclient
> 
> Now, finally, this is a man page a C programmer probably can live with. 
> But when looking more thoroughly into it, I saw that there is no 
> "password" parameter to the authenticate() function although the Perl 
> module's authenticate() method has one:
> 
> int imclient_authenticate (struct imclient *imclient, struct sasl_client 
> **availmech, const char *service, const char *user, int protallowed);
> 
> Plus, I could not find any hints regarding the relationship between the 
> parameters of the C functions and those of the Perl module methods.
> 
> I then headed over to cyrusimap.org and tried to find documentation for 
> the Perl modules. Surprisingly, I couldn't. Not a single word. They 
> don't seem to exist. The tools and helper programs are documented, but 
> the Perl modules are not even mentioned.
> 
> The same applies to CPAN: The modules cannot be found there.
> 
> To make a long story short:
> 
> 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?
> 
> Thank you very much in advance,
> 
> Binarus
> ----
> Cyrus Home Page: http://www.cyrusimap.org/
> List Archives/Info: http://lists.andrew.cmu.edu/pipermail/info-cyrus/
> To Unsubscribe:
> https://lists.andrew.cmu.edu/mailman/listinfo/info-cyrus