Admin(3pm)

🎀 NAME 🎀

okay so bestie, we're in the Admin(3pm) page (User Contributed Perl Documentation, she's iconic) and the main character is IMAP::Admin — a Perl module for basic IMAP server administration. no cap. 💅

---

✨ SYNOPSIS ✨

here's how you summon her, fr fr:

use IMAP::Admin;

$imap = IMAP::Admin->new('Server' => 'name.of.server.com',
                         'Login' => 'login_of_imap_administrator',
                         'Password' => 'password_of_imap_adminstrator',
                         'Port' => port# (143 is default),
                         'Separator' => ".", # default is a period
                         'CRAM' => 1, # off by default, can be 0,1,2
                         'SSL' => 1, # off by default
                         # and any of the SSL_ options from IO::Socket::SSL
                         );

$err = $imap->create("user.bob");
if ($err != 0) {
  print "$imap->{'Error'}\n";
}
if ($err != 0) {
  print $imap->error;
}
$err = $imap->create("user.bob", "green");
$err = $imap->delete("user.bob");
$err = $imap->h_delete("user.bob");

$err = $imap->subscribe("user.bob");
$err = $imap->unsubscribe("user.bob");

$err = $imap->rename("bboard", "newbboard");
$err = $imap->rename("bboard", "newbboard", "partition");

@quota = $imap->get_quotaroot("user.bob");
@quota = $imap->get_quota("user.bob");
$err = $imap->set_quota("user.bob", 10000);

@acl = $imap->get_acl("user.bob");
%acl = $imap->get_acl("user.bob");
$err = $imap->set_acl("user.bob", "admin", "lrswipdca", "joe", "lrs");
$err = $imap->delete_acl("user.bob", "joe", "admin");

@list = $imap->list("user.bob");
@list = $imap->list("user.b*");

$imap->{'Capability'} # this contains the Capabilities reply from the IMAP server

$imap->close; # close open imap connection

that's the whole menu bestie. call the methods, check your $err, live your life. 🌸

---

💖 DESCRIPTION 💖

IMAP::Admin gives you basic IMAP server adminstration. she's got functions for creating and deleting mailboxes, plus setting stuff like quotas and access rights. very much the "do my chores for me" energy. 🧚

her interface should, in theory, work with any RFC compliant IMAP server — but the author has currently only tested her against Carnegie Mellon University's Cyrus IMAP and Mirapoint's IMAP servers. she does a CAPABILITY check for specific extensions to see if they're supported. iykyk. 🔍

operationally? she opens a socket connection to the IMAP server and logs in with the login and password you handed over. then you can call any of the functions and they'll do their little associated operation. periodt.

Separator on the new call is the hiearchical separator used by the imap server. default is a period (but "/" might be another popular one, so watch out). 🫶

CRAM on the new call will attempt to use CRAM-MD5 as the login type of choice. 0 means off, 1 means on, 2 means on with fallback to login. *Note* this options requires these perl modules: Digest::MD5, Digest::HMAC, MIME::Base64.

SSL on the new call will attempt to make an SSL connection to the imap server. heads up: it does not fallback to a regular connection if it fails. it is off by default. IO::Socket::SSL requires a ca certificate, a client certificate, and a client private key. by default these live in current_directory/certs, respectively named ca-cert.pem, client-cert.pem, and client-key.pem. the location of this can be overridden by setting SSL_ca_file, SSL_cert_file, and SSL_key_file (you'll probably want to also set SSL_ca_path). ✨

lowkey important: if you start the name of the server with a / instead of using tcp/ip, it'll attempt to use a unix socket. no tcp bestie, just vibes down a socket file. 🦋

---

🔐 the SSL setup saga (cert glow-up) 🔐

the author generated the ca cert and ca key with openssl, like so:

openssl req -x509 -newkey rsa:1024 -keyout ca-key.pem -out ca-cert.pem

and the client key and cert with openssl:

openssl req -new -newkey rsa:1024 -keyout client-key.pem -out req.pem -nodes
openssl x509 -CA ca-cert.pem -CAkey ca-key.pem -req -in req.pem -out client-cert.pem -addtrust clientAuth -days 600

---

🌈 Setting up SSL Cyrus IMAP v 2.x 🌈

(completely unofficial, but it worked for the author, and that's what matters 💜)

add these to your /etc/imapd.conf — and remember to change /usr/local/cyrus/tls to wherever yours is:

tls_ca_path: /usr/local/cyrus/tls
tls_ca_file: /usr/local/cyrus/tls/ca-cert.pem
tls_key_file: /usr/local/cyrus/tls/serv-key.pem
tls_cert_file: /usr/local/cyrus/tls/serv-cert.pem

for the server key, a self signed certificate was used:

openssl req -x509 -newkey rsa:1024 -keyout serv-key.pem -out serv-cert.pem -nodes -extensions usr_cert

(in openssl.cnf the author has nsCertType set to server)

they also added this to /etc/cyrus.conf — it shouldn't strictly be necessary, since clients that are RFC2595 compliant can issue a STARTTLS to initiate the secure layer, but currently IMAP::Admin doesn't issue this command (this goes in the SERVICES section):

imap2  cmd="imapd -s" listen="simap" prefork=0

where simap in /etc/services is:

simap  993/tcp   # IMAP over SSL

---

📬 MAILBOX FUNCTIONS 📬

RFC2060 commands. these should work with any RFC2060 compliant IMAP mail servers. slay.

• create — makes new mailboxes. Cyrus IMAP, for normal mailboxes, has the user. prefix. create returns a 0 on success or a 1 on failure. an error message is placed in the object->{'Error'} variable on failure. create takes an optional second argument that is the partition to create the mailbox in (the author doesn't know if partition is rfc or not, but it is supported by Cyrus IMAP and Mirapoint). 🔥
• delete — destroys mailboxes. the action delete takes varies from server to server depending on it's implementation. on some servers this is a hierarchical delete, and on others this will delete only the mailbox specified and only if it has no subfolders that are marked \Noselect. if you wish to insure a hierarchical delete, use the h_delete command, because it deletes starting with the subfolders and backs up to the specified mailbox. delete returns a 0 on success or a 1 on failure. an error message is placed in the object->{'Error'} variable on failure.
• h_delete — hierarchical delete (the author doesn't believe this is RFC anything, bestie). deletes a mailbox and all sub-mailboxes/subfolders that belong to it. it basically gets a subfolder list and does multiple delete calls. returns 0 on sucess or a 1 on failure, with the error message from delete being put into the object->{'Error'} variable. don't forget to set your Separator if it's not a period. 🙈
• list — lists mailboxes. list accepts wildcard matching.
• subscribe/unsubscribe — does this action on the given mailbox. simple as.
• rename — renames a mailbox. IMAP servers seem to be peculiar about how they implement this, so don't necessarily expect it to do what you think it should. the Cyrus IMAP server will move a renamed mailbox to the default partition unless a partition is given. you can optionally supply a partition name as an extra argument to this function. 💀
• select — selects a mailbox to work on. you need the 'r' acl to select a mailbox. this command selects a mailbox that mailbox related commands will be performed on. this is not a recursive command, so sub-mailboxes/folders will not be affected unless for some bizarre reason the IMAP server has it implemented as recursive. it returns an error or an array that contains information about the mailbox. for example:

FLAGS (\Answered \Flagged \Draft \Deleted \Seen $Forwarded $MDNSent NonJunk Junk $Label7) OK [PERMANENTFLAGS (\Deleted)] 2285 EXISTS 2285 RECENT OK [UNSEEN 1] OK [UIDVALIDITY 1019141395] OK [UIDNEXT 293665] OK [READ-WRITE] Completed

• expunge — permanently removes messages flagged with \Deleted out of the current selected mailbox. it returns a list of message sequence numbers that it deleted. you need to select a mailbox before you expunge. you need to read section 7.4.1 of RFC2060 to interpret the output. essentially, each time a message is deleted the sequence numbers all get decremented, so you can see the same message sequence number several times in the list of deleted messages. in the following example (taken from the RFC) messages 3, 4, 7, and 11 were deleted:

* 3 EXPUNGE * 3 EXPUNGE * 5 EXPUNGE * 8 EXPUNGE . OK EXPUNGE completed

---

💾 QUOTA FUNCTIONS 💾

RFC2087 imap extensions. these are supported by Cyrus IMAP and Mirapoint.

• get_quotaroot and get_quota — retrieve quota information. they return an array on success and undef on failure. in the event of a failure the error is place in the object->{'Error'} variable. the array has three elements for each item in the quota:
  • $quota[0] <- mailbox name
  • $quota[1] <- quota amount used in kbytes
  • $quota[2] <- quota in kbytes
• set_quota — sets the quota. the number is in kilobytes, so 10000 is approximately 10Meg. set_quota returns a 0 on success or a 1 on failure. an error message is placed in the object->{'Error'} variable on failure. 🍓

to delete a quota do a set_quota($mailbox, "none"); — yes, literally the string "none". iconic honestly.

---

🔑 ACCESS CONTROL FUNCTIONS 🔑

RFC2086 imap extensions. these are supported by Cyrus IMAP, Mirapoint and probably many others.

• get_acl — retrieves acl information. it returns an array on success and undef on failure. in the event of a failure the error is placed in the object->{'Error'} variable. the array contains a pair for each person who has an acl on this mailbox:
  • $acl[0] user who has acl information
  • $acl[1] acl information
  • $acl[2] next user ...

you could also treat the return from get_acl as a hash, in which case the user is the key and the acl information is the value. ✨

• set_acl — set acl information for a single mailbox. you can specify more the one user's rights on the same set call. it returns a 0 on success or a 1 on failure. an error message is placed in the object->{'Error'} variable on failure.
• delete_acl — removes acl information on a single mailbox for the given users. you can specify more the one users rights to be removed in the same delete_acl call. it returns a 0 on success or a 1 on failure. an error message is placed int the object->{'Error'} variable on failure.

👑 standard rights (rfc2086) 👑

• l - lookup (mailbox is visible to LIST/LSUB commands)
• r - read (SELECT the mailbox, perform CHECK, FETCH, PARTIAL, SEARCH, and COPY)
• s - keep seen/unseen information across sessions (STORE SEEN flag)
• w - write (STORE flags other then SEEN and DELETED)
• i - insert (perform APPEND and COPY into mailbox)
• p - post (send mail to submission address for mailbox)
• c - create (CREATE new sub-mailboxes) (*note* allows for delete of sub mailboxes as well)
• d - delete (STORE DELETED flag, perform EXPUNGE)
• a - administer (perform SETACL)

🌟 the access control information is from Cyrus IMAP 🌟

• read = "lrs"
• post = "lrsp"
• append = "lrsip"
• write = "lrswipcd"
• all = "lrswipcda"

---

💀 KNOWN BUGS 💀

currently all the of the socket traffic is handled via prints and _read. this means that some of the calls could hang if the socket connection is broken. 😭 eventually the will be properly selected and timed. (yes, that's the actual sentence, we're all just living in it.)

---

💖 LICENSE 💖

okay so legal stuff but make it cute: this whole thing is licensed under the Artistic license (same as perl, bestie, they're matching 🎀). A copy of that license is literally included in this package — the file is called Artistic, so if you ever need to vibe check the fine print, that's where it lives.

And listen, if you use this in a product or distribution, drop me a line 'cause he is always curious about that... 👀 fr fr, he just wants to know where his baby ended up.

---

🌈 AUTHOR 🌈

Eric Estabrooks, eric@urbanrage.com — the main character who wrote all of this 💅👑

---

✨ SEE ALSO ✨

• perl(1) — yes bestie, go read the big one 🐪

---

and that's a wrap on Admin(3pm)!! 💖 this page came to you from perl v5.36.0, dated 2022-10-15, and honestly? iconic. go forth and slay your admin tasks, you absolute legend 🫶✨