Installing Nextlist

Richard Kay rich _at_ copsewood _dot_ net Jan 2024

0. Status of requirement

These are notes on a procedure likely to evolve until the nextlist software is considered stable. When that happens, it’s plausible some of this may be semi automated. Linux or Unix system administration skills and the ability to install server software including web servers e.g. Apache or Nginx and CGI web applications and MTA programs e.g. Sendmail, Postfix are pre-requisite. If that’s outside the skill/knowledge set you have or intend acquiring, you’re advised to pay someone with these skills to do this job. The following steps are likely to be needed.

It’s very likely at the current early stage of Nextlist software development, that some Python programming skills debugging the software will be needed to make it work and obtain enough information from the software to fix installation errors such as permission problems.

1. Obtain and unpack sources.

Maybe there’ll be a Github page in future. Currently installers download a tar archive e.g. nextlist.tgz from the development and test production site http://nextlist.letsystem.org/ .

If you make changes, there’s a program make_tgz.py in the main unpacked source directory which puts source code changes back into a tgz suitable for onward distribution, without any of the temporary configuration files and attachment downloads. I’d like to receive patches, fixes and improvements you make, so I can improve the version I use and distribute.

Typically you’ll create a folder to unpack into e.g. /home/user/nextlist and unpack it there e.g.
with a command like:

tar xzvf nextlist.tgz

giving you another folder called nextlist. There isn’t a working installation program yet. You will need to do most of the rest of the installation as the root user, so get a root shell e.g. using su or su bash .

You’re advised to copy the unpacked folder to become /usr/local/nextlist for now. As root, e.g.

cp -R /home/user/nextlist /usr/local/nextlist

Note in the file /usr/local/nextlist/etc/default_paths.py an importable Python file where all the software works out where other components are installed. If you use paths different from my recommendations, you’ll need to edit default_paths.py so web, email and system management programs and modules can still find each other.

2. Create a user and group to run programs

This assumes you will be running Apache2 with mod-setuid and mod-cgi or nginx configured equivalently, to run the web application as a virtual host. I won’t help you do all that, but you’ll need to setup a DNS subdomain or domain and get Apache to respond to it with a suitable virtual hosts configuration. A suitable example file is in the lists/defaults If you have to run the application as the default www-data Apache user, then you will skip this step, and later need to ensure ownership of data and configurations under the lists folder as user: www-data group: www-data .

Typically

adduser –disabled-login nextlist

Check files /etc/passwd and /etc/group for addition of nextlist user and group entries

3. Install web application files

Move the web folder to the Apache virtualhost folder and grand nextlist ownership e.g.

mv /usr/local/nextlist/web /var/www/nextlist

chown -R nextlist:nextlist /var/www/nextlist

Test that the index.html file is served by putting the web domain URL into a web browser, e.g.

http://nextlist.example.org/

Test also that the basic example CGI program runs using http://nextlist.example.org/whoami.cgi which should show that the web application is running as the configured user e.g. nextlist . If not, you will need to fix your Apache and virtualhosts installation. The main list admin entry point will be http://nextlist.example.org/entry.cgi . You won’t be able to login there yet, until a list has been configured.

4. Installing a testlist

You will need to make /usr/local/nextlist/email programs belong to root and /usr/local/nextlist/lists belong to user nextlist group nextlist .

e.g. chown -R nextlist:nextlist /usr/local/nextlist/lists

chown -R root:root /usr/local/nextlist/email

The list_configure.py program is in the web folder e.g.

cd /var/www/nextlist

python3 list_configure.py

It’s suggested you choose configuration options to create a list called testlist with desired settings. This creates a folder /usr/local/nextlist/lists/testlist and files there list.cfg and mimetypes.txt which can, if desired, be edited by hand.

list_configure.py will suggest a set of list aliases to be added to /etc/aliases . This assumes you have Sendmail or Postfix installed, or similar and can receive and send email from your host. I won’t help you do that. You may need to ask your cloud service provider to allow you to receive and send outgoing email by opening port 25. You will need to add suitable aliases to /etc/aliases by editing it and running the newaliases command afterwards. Assuming you are receiving email for domain example.org, the alias which makes the list functional results in email sent to testlist@example.org email address being piped as standard input to /usr/local/nextlist/email/nextlist.sh . 4 command line parameters are sent using this piped command, the listname, the email domain name, the numeric UID and GID (see /etc/passwd and /etc/group) for nextlist user and group names.

5. Making the wrapper program run nextlist.py as correct user and group

By default, programs run through /etc/aliases pipe mechanism run as user and group nobody and without Apache running mod-setuid web applications run as user and group www-data . The web application will need to read and write data and configurations under /usr/local/lists as will the piped email application. So we’re going to switch the email program nextlist.py into a different user and group and this is done using a minimal wrapper program running setuid.

If you don’t know what this means, complete a Unix or Linux security and access control training program so you do know what this means, as next steps may otherwise result in you creating an insecure system without understanding the security issues.

We don’t make interpreted shell scripts or Python programs setuid directly. We do this using a minimal wrapper program written in ‘C’ and compiled. It’s recommended you study the source code of the wrapper.c program. It is executed by nextlist.sh and wrapper executes nexlist.py You may want to make changes and recompile it, but it’s mostly configured through the /etc/aliases piped command parameters which nextlist.sh passes through to it. But you probably shouldn’t trust the distributed binary as is. Up to you. I would install build-essential (Debian package for a C compiler) and check and compile the source myself ( gcc -o wrapper wrapper.c ). You will need to make the compiled wrapper binary setuid root.

e.g. cd /usr/local/nextlist/email

chown root:root wrapper

chmod ug+s wrapper

running

ls -l wrapper

should now show the following permission modes and ownership:

-rwsr-sr-x 1 root root 16352 Jan 19 18:44 wrapper

Note the setuid and setgid flags and user and group ownership

This should achieve the nextlist.sh program running user+group nobody with the nextlist.py program running user+group nextlist .

6. Testing and debugging your installation

Work out the web app authentication details from the lists/testlist/list.cfg file . This should have a List-id of testlist and obscure_email string prefix used as admin login handle for testlist. Knowing these 2, the web app should be able to email you an admin PIN. This PIN is also in list.cfg as ownerpin field.

When authenticated, you will be taken to the admin form where you can add and remove testlist email addresses. When you’ve successfully added addresses, these should appear in lists/testlist/addresses.pkl which is a Python binary database file.

When you can add and remove addresses, you should be able to send a test email to these from a subscribed or the listowner email address. This should either bounce with an error message returned, or should propagate to the list of addresses.