Differences

This shows you the differences between two versions of the page.

--- playground:test [2021/04/18 14:28] – created gall0ws
+++ playground:test [2021/04/18 14:47] (current) – typos and minor stuff gall0ws
@@ Line 1: / Line 1: @@
+====== Receiving and sending emails with 9front ======
+In this tutorial we're going to show how to configure on 9front IMAP
+and SMTP access for your SDF mailbox.
+Note that for using SMTP on SDF you have to be a META, VHOST, VPM or
+DIALUP member.
+In the course of this article we will use some uppercasi variables
+you've got to replace appopriately for your use case:
+	SDF_USER	- username to login to the SDF shell
+	SDF_PASSWORD	- password to login to the SDF shell, it will be used for IMAP auth as well
+	SMTP_SECRET	- you may need to set this one up, it will be used for SMTP auth
+===== 1. Receiving =====
+==== 1.1 Add your password to factotum(4) ====
+In order to access your mailbox, we store the credentials in factotum
+adding the appopriate key:
+	% echo 'key proto=pass server=mx.sdf.org service=imap user=SDF_USER !password=SDF_PASSWORD' \
+		 > /mnt/factotum/ctl
+==== 1.2 upasfs(4) ====
+''upas/fs'' is used to access the remote mailbox and mounting it locally
+as a filesystem.  If you're not running upas yet, you can launch it
+with:
+	% upas/fs -f '/imaps/mx.sdf.org/SDF_USER'
+You'll find the mailbox mounted under /mail/fs/mbox (default mailbox).
+=== 1.2.1 Non-default mailbox ===
+If you're already using ''upasfs(4)'', the command in the previous section
+will most probably fail as you already have another mailbox named ''mbox''.
+Of course you can have many different mailboxes, to create a separate
+one for SDF:
+	% echo open /imaps/mx.sdf.org/SDF_USER sdf > /mail/fs/ctl
+In this scenario the SDF mailbox will be mounted under ''/mail/fs/sdf''
+See ''upasfs(4)'' for more details.
+For the rest of this article we're assuming that the mailbox is
+mounted as the default one, and the programs we're going to use make
+the same assumption, however such programs accept a flag or an
+additional parameter to specify a different mailbox.  Please consult
+the appropriate manual pages for more details.
+=== 1.2.2 IMAP server certificate. ===
+The very first time you try to access mx.sdf.org with upas you'll get
+an error:
+	upas/fs: opening /imaps/mx.sdf.org/SDF_USER: mx.sdf.org/imaps:cert for mx.sdf.org not recognized: sha256=j1iBZLD5iPEcGYJopv9oMBHjZcZAzTsfAzj7bIXA2T4
+That's because the X.509 certificate is unknown to your system; to
+make it trusted for the mailer just add it to the file ''mail'' inside
+''/sys/lib/tls'' (most probably such file doesn't exist yet).
+	% echo 'x509 sha256=j1iBZLD5iPEcGYJopv9oMBHjZcZAzTsfAzj7bIXA2T4' >> /sys/lib/tls/mail
+=== 1.2.3 Namespaces considerations ===
+If you're running ''upasfs(4)'' inside a rio's window you'll quickly find
+out that a fresh new window won't inherith the previously opened mbox.
+That's because it was mounted in a different process group and its
+namespace is not fully shared with every other process.
+To do that, you may want run ''upas/fs'' before starting
+''rio(1)'', so every window created will have ''/mail/fs'' populated.
+Another way to share the mail box is launching ''upas/fs'' with the ''-s'' flag:
+	% upas/fs -s -f '/imaps/mx.sdf.org/SDF_USER'
+From ''upasfs(4)''
+	-s		causes fs to put itself in /srv with a name of
+			the form /srv/upasfs.user.
+That allows you to mount back your mailbox in a separate process group running:
+	% mount /srv/upasfs.$user /mail/fs
+==== 1.3 Read emails ====
+The mbox is exposed as a filesystem where each email is presented as a
+directory, e.g.:
+	% lc /mail/fs/mbox/92
+	bcc		disposition	from		messageid	rawunix		subject
+	body		ffrom		header		mimeheader	references	to
+	cc		fileid		info		raw		replyto		type
+	date		filename	inreplyto	rawbody		sender		unixdate
+	digest		flags		lines		rawheader	size		unixheader
+Every file in such directories contains the relative data about the email.
+This is a great API, because it makes very easy to write your own mail
+client.
+We could also read the email directly from the shell with something
+like:
+	% for (i in from subject body) echo $i: `{cat /mail/fs/mbox/92/$i}
+But that isn't really that great, is it?
+=== 1.3.1 nedmail(1) ===
+	% mail
+when ''mail(1)'' is used in this way it is just a frontend to ''nedmail(1)''.
+//TODO: expand.//
+=== 1.3.2 faces(1) ===
+With ''faces(1)'' we could monitor a mailbox for incoming mails.
+	% faces -i
+{{:playground:faces.jpg?400|faces(1)}}
+It uses the ''plumber(4)'' to receive "notifications" from new emails from
+''upasfs(4)'' and, right-cliking on a message, it plumbs the message so it
+can be displayed by another program.
+=== 1.3.3 acmemail(1) ===
+Mail allows you to manage your mailbox directly inside ''acme(1)''
+All you have to do is launch acme:
+	% acme
+And then run ''Mail''.
+By default it will open a new window ''/mail/fs/mbox'' where you can edit
+and read your mailbox.
+Right-clicking on a message id will open the message in a new window.
+''Put'' in the mailbox context is used to save any changes to ''upasfs(4)'',
+for instance the read status of a message.
+{{:playground:acme_eread.jpg?800|Managing mailbox using acme(1)}}
+See ''acme(1)'' if you're not familiar with it and ''acmemail(1)'' for more
+details.
+===== 2. Sending =====
+As mentioned in the intro, you need a META, VHOST, VPM or
+DIALUP membership to send emails through SDF.
+See https://sdf.org/?faq%3FEMAIL%3F08 for the official details.
+==== 2.1 SDF SMTP configuration from 9front ====
+To setup the SDF SMTP from 9front you can use ''vt(1)'' and ''ssh(1)'':
+	% vt
+	% ssh SDF_USER@tty.sdf.org
+Then on the SDF shell:
+	sdf$ setdialup
+	SETDIALUP Version 3
+	 [p]  Set your DIALUP and SMTP Auth password
+	 [m]  Toggle SDF_USER@tenex.org email address
+	 [n]  Set your connection type to NETWORK PPP (default)
+	 [s]  Set your connection type to SHELL
+	 [t]  Set your connection to TIP
+	 [r]  REMOVE your DIALUP Membership
+	 [q]  QUIT
+	Choice?
+At this prompt you should choose ''[p]'' to set your SMTP secret and then
+''[m]'' to enable the email address.
+==== 2.2 rewrite(6) ====
+''/mail/lib/rewrite'' is used in order to convert a given email
+destination to a command to properly send the email.
+By default rewrite doesn't contain any rules, for our purpose we could
+just use the template provided by ''rewrite.gateway''
+	% cat /mail/lib/rewrite.gateway > /mail/lib/rewrite
+See ''rewrite(6)'' for more details.
+==== 2.3 /mail/lib/remotemail ====
+This script is used by ''/mail/lib/qmail'' do dispose of a remote message.
+We can edit it in order to hardcode ''smtp(8)'' so use SDF SMTP server:
+	#!/bin/rc
+	shift
+	sender=SDF_USER@sdf.org
+	shift
+	addr=tcp!mx.sdf.org!25
+	shift
+	fd=`{/bin/upas/aliasmail -f $sender}
+	switch($fd){
+	case *.*
+		;
+	case *
+		fd=sdf.org
+	}
+	exec /bin/upas/smtp -d -u SDF_USER.tenex.org@sdf.org -a -h $fd $addr $sender $*
+=== 2.3.1 Avoid to overwrite defaults ===
+In a shared system changing ''/mail/lib/*'' files may not be ideal, an
+alternative way to do that is creating a ''$home/lib/mail'' directory and
+make there the changes we described, finally use ''bind(1)'' to replace
+the global one just inside our namespace:
+	% bind -b $user/lib/main /mail/lib
+See ''bind(1)'' for more info.
+==== 2.4 Add your SMTP secret to factotum ====
+Similarly at what we did in 1.1 for IMAP, we're adding our credentials
+in factotum to access SDF SMTP server.
+	% echo 'key proto=cram server=mx.sdf.org user=SDF_USER.tenex.org@sdf.org !password=SMTP_SECRET' \
+		> /mnt/factotum/ctl
+Note that the proto in this case is ''cram'' and the username, as
+mentionened in the SDF FAQ, is sligthly different than usual.
+==== 2.5 SMTP server certificate. ====
+As the SMTP server is mx.sdf.org, we can just copy the cert we
+used for IMAP (see 1.2.2):
+	% cp /sys/lib/tls/mail /sys/lib/tls/smtp
+==== 2.6 Post email ====
+Now we're almost ready to send emails from 9front using SDF!
+=== 2.6.1 Correct From field ===
+With the setup described in this article you're going to send emails
+with ''From'' set to $user@sdf.org.  Unless you're really glenda@sdf.org
+(oh, hi!) or in general $user doesn't match SDF_USER, please be sure
+to have the upasname env variable set to SDF_USER:
+	% upasname=SDF_USER
+You may want to set this inside ''$home/lib/profile'' to prevent any
+error.
+=== 2.6.1 mail(1) ===
+The simplest way to send an email is:
+	% echo 'this is a test' | mail -s test gurdulu@sdf.org
+when ''mail(1)'' is used in this way it is just a frontend to ''marshal(1)''.
+=== 2.6.2 acmemail(1) ===
+''Mail'', already introduced in 1.3.3.  could also be used to compose and
+send emails directly from ''acme(1)''
+You can start composing a new email middle-clicking ''Mail'' in the mailbox
+window: a new window will be opened, fill the email in and finally middle-click Post to send it.
+{{:playground:acme_esend.jpg?800|Composing an email using acme(1)}}
+==== 2.7 Troubleshooting ====
+	% tail -f /sys/log/smtp
+	% tail -f /sys/log/smtp.fail