(*) Introduction

LOOP is an NNTP server written in Common Lisp.

(*) Assumptions

We assume

  - you run SBCL, Quicklisp and git installed
  - you know how to use a TCP server such as 
      https://cr.yp.to/ucspi-tcp.html
  - you know how to manage a daemon witha package such as
      https://cr.yp.to/daemontools.html

(*) How to install it

LOOP is not in the Quicklisp repository, so we'll instruct you to
install it as a local project.  Go to

  ~/quicklisp/local-projects/

and say 

  $ git clone https://git.antartida.xyz/loop/srv loop
  $ cd loop
  $ echo /path/to/loop/home > conf-home
  $ make install

(*) Systems with no installation issues

We installed LOOP just fine on

  FreeBSD 14.1, 14.2 with SBCL 2.4.9.
  Debian GNU/Linux 8.11 codename jessie with SBCL 1.2.4.debian.

(*) Systems with installation issues

We installed LOOP on Ubuntu 24.04 (24.01.1 LTS) codename noble with
SBCL 2.2.9.debian.  We found that CLSQL could not load the shared
object libsqlite3.so because ``apt install libsqlite3'' installs the
library at 

  /usr/lib/x86_64-linux-gnu/libsqlite3.so.0.8.6

with a symbolic link to libsqlite3.so.0, but not to libsqlite3.so.
SBCL is trying to load libsqlite3.so, so a solution is to just tell
your system to

  ln -s libsqlite3.so.0 libsqlite3.so

at /usr/lib/x86_64-linux-gnu.

(*) Running LOOP

First, try it out.

$ cd /path/to/loop/home
$ ./loop
200 Welcome! Say ``help'' for a menu.
quit
205 Good-bye.

It runs.  Whenever you run loop, make sure you're in its home
directory because it will look for the file accounts.lisp always
relatively to the current working directory of the process.  The same
applies if you set up a cron job later on---make sure the job, too,
sets LOOP's home directory as its current working directory.

(*) Create your account

LOOP requires authentication for most things, so you should create an
account for you right away.  Accounts are kept in accounts.lisp in
your installation directory.  Every time you create an account, you
must specify who is inviting this new account into the loop---because
we keep a tree of accounts.  The root account is called anonymous, so
your first account must be invited by the anonymous account.  So you
can say

  ./loop --create-account you anonymous

The anonymous account has no special power; it exists solely because
the graph of accounts needs a root.

(*) How to expose LOOP to the network

Run your TCP server of choice.  For instance, if you're using djb's
tcpserver and would like LOOP to listen on port 1024, tell your shell

--8<-------------------------------------------------------->8---
$ tcpserver -v -HR 0.0.0.0 1024 ./loop -s
tcpserver: status: 0/40
--8<-------------------------------------------------------->8---

Using another terminal, telnet to your host on port 1024:

--8<-------------------------------------------------------->8---
$ telnet localhost 1024
Trying 127.0.0.1...
Connected to antartida.xyz.
Escape character is '^]'.
200 Welcome! Say ``help'' for a menu.
quit
205 Good-bye.
Connection closed by foreign host.
--8<-------------------------------------------------------->8---

Directories daemon/ and daemon-tls/ in LOOP's source code have sample
scripts to use with djb's tcpserver and daemontools.  If you have
never done this, it will be better education if you learn to use
daemontools and ucspi-tcp before going live with a LOOP community.
It's easy and fun.

(*) LOOP's REPL

LOOP is hackable.  If you're remotely connected, you can get total
control over the loop process using the repl command.

$ telnet example.com 119
Trying example.com...
Connected to example.com.
Escape character is '^]'.
200 Welcome! Say ``help'' for a menu.
login you <secret>
200 Welcome, YOU.
repl
LOOP> *client*
#S(CLIENT :GROUP NIL :ARTICLE 1 :USERNAME YOU :AUTH? YES)
LOOP> (list-groups)
(local.control.news local.test)
LOOP> quit
200 Okay, no more REPL hacking.

(*) Cron jobs

If you'd like to remove inactive accounts, we wrote
scripts/cron-remove-inactive-users.lisp.  Here's our crontab:

$ crontab -l
@daily cd /path/to/loop/home && sbcl --script scripts/cron-remove-inactive-users.lisp