Belenios 3.3.0

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick Belenios 3.3.0 on Ubuntu 24.04 as the software version and select your Region. Choose Launch through EC2, then select m5.large (or larger for big electorates), your key pair and a security group as described above.

To launch with the AWS CLI instead, replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=belenios}]'

First boot takes about a minute. It generates the certificate and the administrator password, starts Belenios and checks the login before nginx opens port 443.

Version SSH user

Belenios 3.3.0 on Ubuntu 24.04 ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

The message of the day shows your Belenios address and the commands that you need.

systemd runs everything: Docker, the one-time first-boot unit, the Belenios container and nginx. Confirm that the services are active:

systemctl is-active docker belenios-firstboot belenios nginx
sudo ss -Htln | awk '{print $4}' | sort -u sudo docker ps --format 'table {{.Image}}\t{{.Status}}\t{{.Ports}}'

active active active active 0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:8001 127.0.0.53%lo:53 127.0.0.54:53 [::]:22 [::]:443 [::]:80 IMAGE STATUS PORTS sac/belenios:3.3.0 Up 36 seconds 127.0.0.1:8001->8001/tcp

Belenios itself listens only on 127.0.0.1:8001. nginx is the only service on ports 80 and 443.

First boot writes everything you need to a file that only root can read. Show the file without the password line:

sudo grep -v '^belenios.admin.pass=' /root/belenios-credentials.txt

# Belenios 3.3.0 - generated on this instance's first boot by belenios-firstboot.service # The password below is unique to this instance. Keep this file secret (0600 root). # # Open the URL below (self-signed certificate made on first boot), choose "Administer elections", # log in with the local account below, and create your first election. belenios.url=https://ec2-203-0-113-25.compute-1.amazonaws.com/ belenios.admin.user=admin # # Change this password (written back here):
sudo belenios-admin-password
# Add another administrator account:
sudo belenios-admin-password --user <name>
# Serve under your own DNS name (new certificate + Belenios public URL):
sudo belenios-set-hostname <name>
# Election e-mails: kept in /var/lib/belenios/mail/outbox until you configure an SMTP relay (see the guide).
# Elections and accounts: /var/lib/belenios. Licence and source: /usr/share/doc/belenios/ and https://ec2-203-0-113-25.compute-1.amazonaws.com/belenios.tar.gz
# User guide: https://secureanycloud.com/stacks/belenios-3-3-0/

To read the password, run this command on the instance:

sudo grep '^belenios.admin.pass=' /root/belenios-credentials.txt

Open the belenios.url address in your browser. The instance generated its own certificate, so the browser warns until you install a certificate that it trusts (Step 9). The home page is the local login. Enter admin and the password from Step 4.

The first time you log in, Belenios asks you to accept the terms of service and then to give the account an e-mail address. It e-mails a confirmation code to that address. Until you configure an SMTP relay (Step 8), the message stays in the outbox on the instance, so read the code there:

sudo grep -A2 'please use the following code' /var/lib/belenios/mail/outbox | tail -n 1

Enter the code, which is valid for 15 minutes. Belenios confirms the address and returns you to the login page. Log in again to reach the administration page, where your elections are listed. Later logins go straight there.

Choose Create a new election and work through the setup:

• The name and description.
• The questions and their answers.
• The voters, by e-mail address.
• The credential authority, who generates and sends the voting credentials.
• The trustees, who hold the decryption keys.

When everything is ready, open the election. Each election has its own page with a cryptographic fingerprint and a link to its audit data, which anyone can use to verify the result.

Voters open the election link and vote in the booth. They enter their credential and answer the questions, and the browser encrypts their ballot before it is sent.

These read-only checks show HTTPS, the redirect, the dropped unknown host names, the locked-down container and the metadata block:

H=$(sudo sed -n 's/^set \$app_host "\(.*\)";$/\1/p' /etc/nginx/belenios-host.conf)
curl -sk -o /dev/null -w 'https %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/" curl -s -o /dev/null -w 'http %{http_code}\n' --resolve "$H:80:127.0.0.1" "http://$H/" curl -sk -o /dev/null -w 'unknown host %{http_code}\n' --resolve "other.example:443:127.0.0.1" https://other.example/ || true
sudo docker inspect --format 'user={{.Config.User}} readonly={{.HostConfig.ReadonlyRootfs}} capdrop={{.HostConfig.CapDrop}} options={{.HostConfig.SecurityOpt}}' belenios
sudo iptables -S DOCKER-USER | grep -E '169.254.169.254|br-belenios' curl -s -o /dev/null -w 'IMDSv1 %{http_code}\n' http://169.254.169.254/latest/meta-data/ || true

https 200 http 301 unknown host 000 user=10101:10101 readonly=true capdrop=[ALL] options=[no-new-privileges] -A DOCKER-USER ! -i br-belenios -o br-belenios -m conntrack --ctstate NEW -j DROP -A DOCKER-USER -d 169.254.169.254/32 -j DROP IMDSv1 401

The result 000 means nginx closed the connection without answering, which happens for a request for a name that the instance does not serve. The result 401 means the instance metadata service requires IMDSv2 tokens.

Belenios e-mails voters their credentials and notifications. Until you configure a relay, every message is appended to an outbox file on the instance, and nothing leaves the instance:

sudo docker exec belenios printenv BELENIOS_SENDMAIL
sudo test -e /etc/belenios/smtp/msmtprc && echo "SMTP relay configured" || echo "no SMTP relay: e-mails stay in /var/lib/belenios/mail/outbox"

/usr/local/bin/belenios-sendmail no SMTP relay: e-mails stay in /var/lib/belenios/mail/outbox

To send mail, put an msmtp configuration for your SMTP relay at /etc/belenios/smtp/msmtprc and restart Belenios. The directory belongs to the server's account (uid 10101), so write the file as that account, with mode 0600. The following example is for a relay that accepts authenticated submission on port 587:

sudo setpriv --reuid=10101 --regid=10101 --clear-groups sh -c 'umask 077; cat > /etc/belenios/smtp/msmtprc' <<'EOF' account default host smtp.your-domain.example port 587 tls on tls_starttls on auth on user belenios@your-domain.example password <your-smtp-password> from belenios@your-domain.example EOF
sudo install -d -m 0755 /etc/sac echo belenios@your-domain.example | sudo tee /etc/sac/belenios-mail-from
sudo systemctl restart belenios

Messages already in the outbox are not re-sent. Read them with sudo less /var/lib/belenios/mail/outbox.

Election URLs are part of each election's data, so set the name you want to keep before you create real elections. Point a DNS record at the instance, then run:

sudo belenios-set-hostname vote.your-domain.example

The command writes a new certificate for that name, renders the Belenios public URL and restarts the services. To use a certificate that your browsers trust, replace /etc/ssl/belenios/belenios.crt and /etc/ssl/belenios/belenios.key with your own (or one from your certificate authority), then run sudo systemctl reload nginx.

To publish your own terms of service, write their URL to /etc/sac/belenios-tos-uri and restart Belenios:

sudo install -d -m 0755 /etc/sac echo https://your-domain.example/voting-terms | sudo tee /etc/sac/belenios-tos-uri
sudo systemctl restart belenios

sudo belenios-admin-password
# new random password for admin (written to /root/belenios-credentials.txt)
sudo belenios-admin-password --user alice
# add or reset another administrator (password in /root/belenios-user-alice.txt)

Neither command prints the password. Belenios restarts so that the change takes effect at once.

Elections, accounts, the administrator password file and the mail outbox are all under /var/lib/belenios, owned by the server's account (uid 10101, shown as belenios):

sudo ls -la /var/lib/belenios ls /usr/share/doc/belenios
sudo docker images sac/belenios

total 20 drwx------ 8 belenios belenios 200 Nov 9 11:55 . drwxr-xr-x 51 root root 4096 Nov 9 10:04 .. drwx------ 2 belenios belenios 100 Nov 9 11:58 accounts drwx------ 2 belenios belenios 60 Nov 9 11:58 lib drwx------ 2 belenios belenios 100 Nov 9 11:52 log drwx------ 2 belenios belenios 40 Nov 9 11:56 mail -rw------- 1 belenios belenios 12288 Nov 9 11:52 ocsidb -rw------- 1 belenios belenios 95 Nov 9 11:55 password_db.csv drwx------ 2 belenios belenios 60 Nov 9 11:58 spool drwx------ 2 belenios belenios 40 Nov 9 11:52 upload COPYING NOTICE-sac.txt THIRD-PARTY.txt npm-packages-booth.txt opam-licences.txt opam-packages-build.txt trivy-belenios-image.json trivy-booth-npm.json IMAGE ID DISK USAGE CONTENT SIZE EXTRA sac/belenios:3.3.0 5508263abfbe 179MB 0B U

opam-packages-build.txt lists the build environment. THIRD-PARTY.txt lists the libraries linked into the server and their licences. The trivy-*.json files hold the CVE scans that ran at build time.

To back up your elections, snapshot the instance's EBS volume, or copy /var/lib/belenios to other storage on a schedule. For a consistent copy, stop Belenios first: sudo systemctl stop belenios, copy, then sudo systemctl start belenios. The election data holds the cryptographic material of every election, so keep backups private.

• Allow port 22 in the security group from your own networks only, and ports 443 and 80 only to your administrators and voters.
• Set your DNS name and a trusted certificate before the first real election (Step 9).
• Give administrator accounts only to the people who run elections, and rotate passwords that may have leaked (Step 10).
• Configure an SMTP relay that you control before you send voter credentials (Step 8).
• Keep the operating system patched. Unattended security upgrades are on, and sudo apt-get update && sudo apt-get upgrade applies everything else.