srv/README

(*) Introduction

LOOP is an NNTP server written in Common Lisp.

(*) Assumptions

We assume

  - you have 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 with a 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

(*) Running LOOP

First, try it out.

$ cd /path/to/loop/home
$ ./loop.exe
200 Welcome! I am LOOP 9575ac2. 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.  So say

  ./loop --create-account you root

to create YOU, your account.  The root account has no special power;
it exists solely because a tree of accounts needs a root.  It's an
account like any other, so you could use it yourself.  In that case,
change its password:

$ ./loop --change-passwd root <secret>
Okay, account root now has password ``<secret>''.

(*) How to expose LOOP to the network

Just 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

(*) 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.