Apache JSPWiki 2.12.5 on AWS User Guide

Overview

This guide covers launching and using the Apache JSPWiki 2.12.5 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg BookStack, CMS, Blogs and Wikis listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

Apache JSPWiki is a mature, open source, general purpose wiki engine built on standard Java servlet technology. Authors create and cross link pages with a compact wiki markup, attach files, and rely on built in page versioning, so every change is kept and any earlier revision can be compared or restored. This image runs the official Apache JSPWiki 2.12.5 web application on Apache Tomcat 9.0.123 and OpenJDK 17, with pages and attachments stored as files on the instance.

The cloudimg image adds:

• HTTPS from the first boot. nginx serves the wiki on port 443 with a certificate generated on your instance's first boot. Port 80 redirects to HTTPS.
• An administrator password unique to your instance. First boot creates the JSPWiki user admin, generates its password and stores only a salted hash in JSPWiki's user database; the password itself is written to /root/jspwiki-credentials.txt. No password is baked into the image.
• A safe default for a public wiki. Anyone can read pages; only the administrator can create, edit, upload, rename or delete them, and visitors cannot register their own accounts, so a new wiki is not an open target for spam. Step 10 shows how to open editing up.
• Fail closed. Tomcat refuses to start until first boot has written the administrator, and nginx refuses to start until first boot has finished.
• Tomcat on loopback only. Tomcat listens on 127.0.0.1:8080 behind nginx, with no shutdown port, no AJP connector, none of Tomcat's sample or manager applications, and error pages that do not reveal versions. JSPWiki's first run setup page (Install.jsp) is removed. The only open ports are 22, 80 and 443.
• Hardened defaults. Tomcat runs as its own unprivileged user in a systemd sandbox that can write only the wiki data, its work directory and its logs; the web application and its configuration belong to root. Tomcat and nginx are blocked from the instance metadata service; the AMI requires IMDSv2. The wiki's address comes from your configuration, never from a request, and requests for a host name the instance does not serve are dropped.
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on (they also keep OpenJDK patched).

What is on the image: Apache JSPWiki 2.12.5 (the official JSPWiki.war, checksum verified), Apache Tomcat 9.0.123 (checksum verified), OpenJDK 17 from Ubuntu, nginx, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. The wiki starts with a small set of starter pages (Main, About and SandBox).

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
• A security group that allows TCP 22 (SSH), TCP 443 (the wiki) and TCP 80 (redirects to HTTPS) from your own networks only.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick Apache JSPWiki 2.12.5 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large, your key pair and a security group as above. The wiki lives under /var/lib/jspwiki on the root volume.

With the AWS CLI (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=jspwiki}]'

Step 2: Connect to your instance

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

Step 3: Check the services

First boot takes a few seconds, and Tomcat needs about half a minute more to start JSPWiki. Then the three units are active:

systemctl is-active jspwiki-firstboot tomcat nginx

active
active
active

Tomcat (the java process) listens on loopback only; nginx serves ports 80 and 443:

sudo ss -tlnp | awk 'NR==1 || /java|nginx|sshd/' | awk '{print $1, $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g'

State Local Peer
LISTEN 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx"))
LISTEN 0.0.0.0:22 users:(("sshd"),("systemd"))
LISTEN 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx"))
LISTEN 127.0.0.1:8080 users:(("java"))
LISTEN [::]:443 users:(("nginx"),("nginx"),("nginx"))
LISTEN [::]:22 users:(("sshd"),("systemd"))
LISTEN [::]:80 users:(("nginx"),("nginx"),("nginx"))

The versions on the image:

sudo ls /opt/tomcat/webapps/ROOT/WEB-INF/lib/ | grep '^jspwiki-main'
sudo java -cp /opt/tomcat/lib/catalina.jar org.apache.catalina.util.ServerInfo | grep -E 'Server number|JVM Version'

jspwiki-main-2.12.5.jar
Server number:  9.0.123.0
JVM Version:    17.0.20.1+1-1-24.04-Ubuntu

Step 4: Get your URL and password

sudo cat /root/jspwiki-credentials.txt

The file holds the address the wiki is served as (your instance's public DNS name by default), the administrator user and the password generated on this instance:

JSPWIKI_URL=https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/
JSPWIKI_ADMIN_USER=admin
JSPWIKI_ADMIN_PASSWORD=<24 letters and digits>

Step 5: Sign in from your browser

Open JSPWIKI_URL in your browser. The certificate is self signed (generated on your instance), so accept the browser warning once, or install your own certificate (Step 9). Anyone who can reach the instance can read the wiki. To edit, open the user menu (the person icon at the top right), choose Log in, and sign in with admin and the password from Step 4.

The login form keeps JSPWiki's Join JSPWiki now! link, but on this image a visitor who follows it cannot create an account: the registration form is not offered and a registration request is refused. Step 10 explains how to add users.

Signed in, the front page shows the starter content, the left hand menu, and the Recent changes list, and the user menu greets you as Administrator (authenticated):

Step 6: Create and edit pages

Signed in as the administrator, click Edit on any page. The editor shows the wiki markup on the left and a live preview on the right; click Save when you are done. To create a page, link to it from an existing page (for example [TeamNotes]) and follow the new link, or type its name into the search box and choose to create it.

Step 7: Review page history

Every save is a new version. Open Info on a page to see its revision history with the author and date of every version, compare any two versions, rename the page or delete it:

Step 8: Security checks

Port 80 sends browsers to HTTPS, the wiki answers over HTTPS, JSPWiki's setup page is gone, and nginx closes the connection for a host name the instance does not serve (000 means no answer):

H=$(sudo sed -n 's#^JSPWIKI_URL=https://\([^/]*\)/.*#\1#p' /root/jspwiki-credentials.txt)
curl -s -o /dev/null -w 'port 80: %{http_code} -> %{redirect_url}\n' --resolve "$H:80:127.0.0.1" "http://$H/"
curl -sk -o /dev/null -w 'wiki front page: %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/Wiki.jsp?page=Main"
curl -sk -o /dev/null -w 'Install.jsp: %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/Install.jsp"
curl -s -o /dev/null -w 'unknown host name: %{http_code}\n' -H 'Host: example.com' http://127.0.0.1/ || true

port 80: 301 -> https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/
wiki front page: 200
Install.jsp: 404
unknown host name: 000

The administrator can sign in from the command line too. JSPWiki protects its forms with an anti forgery token that must be read from the login page and sent back; the password is passed to curl from a file, so it never appears on a command line:

H=$(sudo sed -n 's#^JSPWIKI_URL=https://\([^/]*\)/.*#\1#p' /root/jspwiki-credentials.txt)
PWF=$(mktemp); JAR=$(mktemp)
sudo sed -n 's/^JSPWIKI_ADMIN_PASSWORD=//p' /root/jspwiki-credentials.txt | tr -d '\n' > "$PWF"
T=$(curl -sk --resolve "$H:443:127.0.0.1" -c "$JAR" -b "$JAR" "https://$H/Login.jsp" | grep -oE 'name="X-XSRF-TOKEN"[^>]*value="[^"]*"' | head -1 | sed -E 's/.*value="([^"]*)".*/\1/')
curl -sk --resolve "$H:443:127.0.0.1" -o /dev/null -c "$JAR" -b "$JAR" --data-urlencode j_username=admin --data-urlencode "j_password@$PWF" --data-urlencode "X-XSRF-TOKEN=$T" --data 'submitlogin=Login&redirect=Main' "https://$H/Login.jsp"
curl -sk --resolve "$H:443:127.0.0.1" -b "$JAR" "https://$H/Wiki.jsp?page=Main" | grep -oE 'day, [A-Za-z]+ \(authenticated\)' | head -1 | sed 's/^day, /signed in as: /'
rm -f "$PWF" "$JAR"

signed in as: Administrator (authenticated)

The certificate was generated on this instance and names its own addresses:

H=$(sudo sed -n 's#^JSPWIKI_URL=https://\([^/]*\)/.*#\1#p' /root/jspwiki-credentials.txt)
echo | openssl s_client -connect 127.0.0.1:443 -servername "$H" 2>/dev/null | openssl x509 -noout -subject -ext subjectAltName

subject=CN = ec2-<public-ip-dashed>.<region>.compute.amazonaws.com, O = cloudimg
X509v3 Subject Alternative Name:
    DNS:ec2-<public-ip-dashed>.<region>.compute.amazonaws.com, IP Address:<public-ip>, IP Address:<private-ip>, IP Address:127.0.0.1, DNS:localhost

Tomcat runs unprivileged in a sandbox, and neither Tomcat nor nginx can reach the instance metadata service:

systemctl show tomcat -p User -p ProtectSystem -p NoNewPrivileges -p IPAddressDeny
systemctl show nginx -p IPAddressDeny

IPAddressDeny=fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32
User=tomcat
ProtectSystem=strict
NoNewPrivileges=yes
IPAddressDeny=fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32

Tomcat has no shutdown port, listens on loopback only, takes the wiki's public name from its configuration (so links and redirects never use a host name a client made up) and trusts forwarded client addresses from nginx on 127.0.0.1 only. nginx passes Tomcat a fixed host name and the real client address from the connection:

sudo grep -oE '<Server port="[^"]*"|address="[^"]*" port="[^"]*"|internalProxies="[^"]*"' /opt/tomcat/conf/server.xml
sudo grep '^cloudimg.jspwiki.host=' /opt/tomcat/conf/catalina.properties
grep -E 'proxy_set_header (Host|X-Forwarded-For|X-Real-IP)' /etc/nginx/sites-available/cloudimg-jspwiki

<Server port="-1"
address="127.0.0.1" port="8080"
internalProxies="127\.0\.0\.1"
cloudimg.jspwiki.host=ec2-<public-ip-dashed>.<region>.compute.amazonaws.com
        proxy_set_header Host 127.0.0.1:8080;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;

Step 9: Your own DNS name and certificate

Point a DNS record at the instance, then set the name the wiki is served as. This mints a new self signed certificate for the name, updates nginx, Tomcat and the URL in /root/jspwiki-credentials.txt, restarts Tomcat, and keeps the name across reboots:

sudo jspwiki-set-hostname <your-domain>

To use a certificate from your own certificate authority instead, copy it over the generated pair and reload nginx (running jspwiki-set-hostname again replaces it with a self signed one):

sudo install -m 0644 <your-domain>.crt /etc/nginx/ssl/jspwiki.crt
sudo install -m 0600 <your-domain>.key /etc/nginx/ssl/jspwiki.key
sudo nginx -t && sudo systemctl reload nginx

Step 10: Users, editing rights and the administrator password

The administrator password. jspwiki-set-password sets a new password for admin in JSPWiki's user database (only a salted hash is stored), records it in /root/jspwiki-credentials.txt and restarts Tomcat. Run it without arguments for a new random password, or pass your own (24 to 64 letters and digits) on stdin. You can also change it in the browser from the user menu, User Preferences, Profile.

sudo jspwiki-set-password
printf '%s\n' '<your-new-password>' | sudo jspwiki-set-password --stdin

Who can do what is set by JSPWiki's access policy, /opt/tomcat/webapps/ROOT/WEB-INF/jspwiki.policy. The image ships it as public read, administrator write, no self registration:

sudo sed -n '/Role "All" {/,/};/p' /opt/tomcat/webapps/ROOT/WEB-INF/jspwiki.policy

grant principal org.apache.wiki.auth.authorize.Role "All" {
    permission org.apache.wiki.auth.permissions.PagePermission "*:*", "view";
    permission org.apache.wiki.auth.permissions.WikiPermission "*", "editPreferences";
    permission org.apache.wiki.auth.permissions.WikiPermission "*", "login";
};

Edit the file with sudo nano and run sudo systemctl restart tomcat after a change. The comments at the top of the file list the lines for each change:

• Let people register their own accounts: add permission org.apache.wiki.auth.permissions.WikiPermission "*", "editProfile"; to the All block. Visitors can then use Join JSPWiki now! on the login page. To add a few named users only, enable it, let them register, then remove the line again.
• Let every signed in user edit: add permission org.apache.wiki.auth.permissions.PagePermission "*:*", "modify,rename"; and permission org.apache.wiki.auth.permissions.WikiPermission "*", "createPages"; to the Authenticated block.
• Make a user an administrator: signed in as admin, open the user menu, Groups, then the Admin group's edit page (EditGroup.jsp?group=Admin), add the user's wiki name to the members list and save.
• Require sign in even to read: remove the PagePermission "*:*", "view" lines from the All, Anonymous and Asserted blocks.

Step 11: Your wiki data and backups

Pages are plain text files, with earlier versions under OLD; attachments, the search index and the user and group database live alongside:

sudo ls /var/lib/jspwiki /var/lib/jspwiki/pages

/var/lib/jspwiki:
attachments
etc
pages
work

/var/lib/jspwiki/pages:
About.txt
LeftMenu.txt
LeftMenuFooter.txt
Main.txt
OLD
SandBox.txt

Back up /var/lib/jspwiki (or snapshot the root volume) to keep your pages, their history, attachments and accounts. JSPWiki's own settings for this image are in /opt/tomcat/webapps/ROOT/WEB-INF/classes/jspwiki-custom.properties.

The image ships the JSPWiki and Tomcat versions named in the listing. Ubuntu's unattended upgrades keep the operating system, nginx and OpenJDK patched; to move to a newer JSPWiki or Tomcat release later, snapshot the instance first and follow the Apache upgrade notes, keeping /var/lib/jspwiki and the two files named above.

Step 12: Server components

Step 13: Security recommendations

• Allow ports 22, 80 and 443 in the security group from your own networks only.
• Keep the default access policy (public read, administrator write) unless you need open editing, and leave self registration off on an internet facing wiki.
• Keep the administrator password secret, and rotate it if it may have been shared (Step 10).
• Use your own DNS name and a certificate your browsers trust (Step 9).
• Keep the operating system patched; unattended security upgrades are on, and sudo apt-get update && sudo apt-get upgrade applies everything else.
• Back up /var/lib/jspwiki regularly (Step 11).

Support and licensing

Apache JSPWiki and Apache Tomcat are open source under the Apache License 2.0 (JSPWiki's licence and notice are at /usr/share/doc/jspwiki/, Tomcat's at /opt/tomcat/); there is no per user or per CPU licence fee. The AMI price covers cloudimg's hardening, first boot setup and support.

• Email: support@cloudimg.co.uk
• Website: https://www.cloudimg.co.uk
• Support: 24/7, with a 24 hour response SLA