“Etherbox is a constellation of collective tools and practices that developed in and around Constant*. Etherbox responds to practical issues when collaborating in physical spaces with digital tools. In parallel, it became a platform to reflect on network technologies, on how to document artistic processes and on processes of collaboration.”
*An organisation for art and media based in Brussels.

“Sharing documents over Etherbox means that they don't travel via the far-away data-center servers of corporations, but remain in a network-setup that is visibly and physically accessible to everyone. Likewise the Terms of Service are negotiated locally, between people often in the same room. They become specific conditions for the use and potential afterlives of the collected material, rather than being thrown together by company lawyers on another continent.”

Etherbox is an assemblage existing "boxes", a collection of Free Software tools. Some have a long history and represent deeply embedded workflows. Others, like etherpad-lite, are relatively newer, with a history that can reflect complex inter-plays of commercial interests with Free Software projects. The current release of Etherbox consists of:

• Apache webserver
• Etherpad-lite browser-based real-time document editor
• Pandoc mutli-format markdown-document converter
• Imagemagick "swiss army knife" image converter

Etherdump publishes etherpad pages to files

Guide to using your Etherbox

Make sure you are connected to the network of the Etherbox

Look at the wireless networks listing, and select etherbox.

Surf to etherbox.local

You should see this interface:

You find 4 folders:

• etherdump: a raw listing of all the pads you made
• images: a drag & drop folder to share images
• include: content related to the graphical design of your etherbox
• pages: this folder can have any name, books/videos/sound; you can delete and add as many folders via ftp (see below)

Some browsers don't like to connect via the local address etherbox.local or etherbox.lan. A solution is to connect to the box typing its IP-address in a browser.

Find out the IP address of the box

Open a terminal

ping etherbox.local

Note that the ".local" domain works using a protocol called zero-configuration networking (aka Rendez-vous). On a Linux system you can install a package called avahi if it isn't installed already. On a Mac, this should already be installed. On Windows, installing software such as CyberDuck includes a separate installed for zero-configuration networking / Rendezvous which you can install.

Create a writing pad and start working!

In the tabs upper left of the interface, you click on 'Etherpad'. This brings you to the following page:

Type a name for your new pad, please don't use spaces or strange characters. Those might complicate the backup and compression of your pages:

Access to existing pads

In the tabs upper left of the interface, you click on 'Etherdump'. This brings you to the index of all the pads:

You have different formats you can use:

• pad: the actual pad, to continue editing
• text: a plain text file generated from your pad
• diffhtml: html-page generated from your pad, showing all the different changes

Once your Etherbox is set up in a place for collective work and exchanges, there are a few practical issues that you will have to deal with as a host. This is a non-exhaustive list, written in a somehow chronogical order.

You need the IP-address to ssh into the box (see above).

ssh to the box

Many of the operations described here require that you use the ssh program to gain access to the server via what is called the shell (ssh stands for secure shell). You do this by using a Terminal software. Most Linux users will be familiar with the Terminal. Mac users can find a Terminal in the "Utilities" folder of their applications. On Windows, you can use a dedicated ssh program such as PuTTY.

ssh pi@ip-address-of-the-box

login: pi

pass: raspberry

You need to ssh in the Etherbox in order to shutdown or reboot it, or reboot parts of the software installed. These are the default login/pass of any Raspberry. You can of course change that, but the idea has been to create a low-threshold to participation, following as many "defaults" as possible, as the Etherbox has typically been used with a group of people physically together with respect for each other and the infrastructure they share, and not made available publically.

Make it easier to login, with an ssh key

Starting from your laptop (open a new Terminal session if you are connected to the pi):

ssh-keygen

Choose the defaults. This generates an "ssh key" pair.

Use the ssh-copy-id utility to send it to the pi.

ssh-copy-id pi@etherbox.local

Shutdown the Etherbox

It is recommended to shutdown the etherbox rather than just unplugging it. There is a (small) chance that the filesystem could get messed up if you don't.

sudo shutdown -h now

Wait a few moments still for the system to come to a halt before unplugging. You should see some blinking lights near the power connection of the pi finally stop changing.

Reboot the Etherbox

sudo reboot

Restart Etherpad (this can help when people start having connection problems to the pads)

sudo service etherpad restart

Move to the home folder

All of these commands have the same effect, that the "current working folder" gets set to the pi user's home.

cd

cd ~

cd /home/pi

Make dump (make static copies of the contents of the etherpads)

From the folder ~/www/etherpad you can use the make command to do many useful things. First you need to get to the right place:

cd

cd www/etherpad

or

cd ~/www/etherpad

And then:

make dump

For more recipes, have a look at the makefile

Compile the contents of several pads with an .index pad

The default makefile has rules to create a single publication from any pad whose name ends ".index". This pad may then contain special "include" lines that cause the contents of other pads to be copy/pasted into the master document at that point. In this way many pads can be compiled into a single publication. Each pad should use markdown encoding. For example, an excerpt of the .index pad used to create this publication:

   <!--  ## Introduction to series ('why networks of ones own'). What could be following threads/releases. -->

    #include http://etherbox.local:9001/p/seriesintroduction

    <!--  ## Introduction to first issue ('why etherbox'). FS -->

    #include http://etherbox.local:9001/p/issueintroduction

    ## Makefile

    ```makefile

    #include http://etherbox.local:9001/p/Makefile

    ```

Note that HTML comments are used ( <!-- --> ) to include reminders that are not processed / visible in the output. Note how markdown "code fencing" is used around the makefile to add syntax coloring to the contents of this pad.

If the pad is named HELLO.index, then (following the rules of the default Makefile), after each dump, the system will attempt to make HELLO.html using the pandoc software.

In addition, it is possible to create a PDF output by typing either:

make HELLO.pdf

make HELLO.booklet.pdf

You can also manually trigger a rebuild of the HTML with: make HELLO.html

Note that "HELLO" could be any name you choose. It's possible to make multiple publications on a single etherbox.

sftp to the box

host: etherbox.local or ip-address-of-the-box

user: pi

password: raspberry

protocol: sftp

sftp is handy when people want to customize the index of the Etherbox on the fly. They will be able to create/delete folders, upload/delete large files etc.

Various sftp clients are available FileZilla for GNU/Linux or Cyberduck for MacOS

Delete a pad

Add the tag __NO@PUBLISH__ (without @) on top of the pad. This causes the dumps to get deleted -- and in any case will remove the page from the index.

Archive the pads

Connect via SSH, and run script:

eb_backup.sh

This will create two files in /home/pi/www/backups. One for the etherpad history (an sql dump) and the other a gzipped snapshot of the "etherdump" folder including any HTML/PDF outputs. This script can also be triggered via the makefile by typing:

make backup

Changing the frequency of the cron

By default, pads are dumped every 30 minutes. You can change the frequency that the pads get dumped, and output documents are made. You do this by editing the "crontab":

crontab -e

When you type this command, it opens up a text file with mostly comments that explain cron. At the bottom of the file is a special line that lists a script to run with numbers that indicate how frequently.

# ┌───────────── minute (0 - 59)

# │ ┌───────────── hour (0 - 23)

# │ │ ┌───────────── day of month (1 - 31)

# │ │ │ ┌───────────── month (1 - 12)

# │ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday;

# │ │ │ │ │                                   7 is also Sunday on some systems)

# │ │ │ │ │

# │ │ │ │ │

# *  *  *  *  * command to execute

# For example, you can run a backup of all your user accounts

# at 5 a.m every week with:

# 0 5 * * 1 tar -zcf /var/backups/home.tgz /home/

#

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/pi/bin

# m h  dom mon dow   command

*/30 * * * * /home/pi/cron.sh 2> /home/pi/www/cron.log.txt

The key part is the last line. The /30 means that the script happens every 30 minutes. You could use /5 to update the outputs every 5 minutes for instance. The downside is that this might make the pads slower when the outputs are being generated. (Note also the added PATH variable so that the scripts run with the same $PATH as the pi user.)

The software utility cron is a time-based job scheduler in Unix-like computer operating systems. https://en.wikipedia.org/wiki/Cron

Resetting a box for future use (delete all pads, etc)

Connect via SSH, and run script:

eb_reset.sh

Placing Etherbox in your network

By default, the Etherbox includes software to create it's own hotspot named "etherbox". For work sessions with more than 20 people, we typically use the Raspberry Pi in conjunction with a small OpenWRT router to provide a more robust hotspot. The following diagrams show different network configurations used over the last years.

Network configuration Relearn 2014

Network configuration Uncreative Writing

Booklet printing with a makefile

The booklet printing rule defined in the default Makefile is based on the class OSP blog post How to Print A Booklet in 19 Easy steps http://blog.osp.kitchen/live/how-to-print-a-booklet-in-16-steps.html

A straightforward rendering of these steps in single monolithic make rule could look like this:

%.booklet.pdf: %.pdf

       pdftk_utils.py $< pad --multiple 4 --output $*.01.pdf

       pdftops -paper match $*.01.pdf $*.01.ps

       psbook -s`pdftk_utils.py $*.01.pdf count` $*.01.ps $*.02.ps

       psnup -2 -PA4 $*.02.ps $*.03.ps

       ps2pdf $*.03.ps $@

       rm $*.01.pdf $*.01.ps $*.02.ps $*.03.ps

However, the fun of a makefile is the abilty to define incremental transformations, and let make put the sequence of steps together itself! Here are the final set of rules used in the default Makefile:

%.pdf: %.html

    weasyprint $< $@

# PDF to Postscript

%.m4.ps: %.m4.pdf

    pdftops -paper match $< $@

# Postscript to PDF

%.pdf: %.ps

    ps2pdf $< $@

# Ensure a PDF has a multiple of 4 pages

%.m4.pdf: %.pdf

    pdftk_utils.py $< pad --multiple 4 --output $@

%.book.ps: %.m4.ps %.m4.pdf

    psbook -s`pdftk_utils.py $*.m4.pdf count` $< $@

%.booklet.ps: %.book.ps

    psnup -2 -PA4 $< $@

Etherbox was developed out of urgency to accommodate needs of particular small to medium scale art-cultural working/production events using free-libre-open source software, cheap hardware and also to reduce dependencies to and limitations of commercial internet services.

“On a practical level, etherbox was a response to several frustrations: the fragility of online resources, the fact that the labour necessary to maintain resources online after a collective session was often overlooked or simply assumed to continue indefinitely, the limitations of Internet bandwidth when working with many people using etherpad-lite. The goal of the project was thus to present an infrastructure that is both visible and situated. Since it's early beginnings in 2013, many groups have enjoyed the pleasure of writing and documenting together, questioning infrastructure set-ups or simply sharing files effortlessly. Through these multiple experiences, Etherbox has grown up to facilitate discussions and collaborative practices independent from Constant collaborators. Now it is ready to transmutate into other networked imaginations.

As part of its programme, Constant regularly organises situations in which artists, activists, programmers, academics, designers and other researchers collaborate, exchange and reflect. Participants are invited to appropriate physical spaces for the time of the meeting: they share tables, couches, a library, the kitchen and its utensils, the basement or the closet. Etherbox extends this hospitality into digital space. It is the installation of a temporary local platform that foregrounds the sociality of DIWO* infrastructures over the services of often commercially owned spaces in global networks.”
* Do It With Others

Example: BOOK AS A NETWORK @Aleppo, Brussels / June 2015
“A residency of 3 days, with the idea to create a space for presentation, exchange, discussion on new ways of reading and writing. One of the threads, Book as a network, led by Catherine Lenoble and Michael Murtaugh, was the idea of using a local server as a space for collective reading and writing. A first publication was done afterwards with a lot of manual work.” 

From #a-conversation-about-releasing-etherbox

“
RA: The reason to document the history of etherbox, is because we are publishing an image right now that will expand beyond its original group of users in Brussels.
FS: It's a way to remember that Etherbox is an object that grew within a practice, that it is intimately linked to events, groups of people, concerns and practises. If we would not document its geneaology, the code or the object would eclipse other types of input.
...
MM: For me, I've had the opportuntiy to develop the system as part of my role with Constant caring for the infrastructure used during the worksessions Constant hosts twice a year. For me it's ideal, because it gives a situation where I can observe how the system is used, and many of the participants of such sessions are often also involved in similar projects, so there's a lot of exchange of ideas.
”

‍

ETHERBOX should be picked up by every cultural organization that can have a technology informed person (at least part time or based on need) that can understand the setup.

Ideally it should be further developed and documented for non-tech users to be able to operate it with minimum instructional (video) training.

http://CONSTANTvzw.org/ (mostly by Michael Murtaugh)