Re: Documentation for Cyrus::IMAP::Admin and friends
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 1, > "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 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
Re: Documentation for Cyrus::IMAP::Admin and friends
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 1,
"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 Cyrus::IMAP::Admin and friends
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
