Apache Tika Server 3.3.3

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick Apache Tika Server 3.3.3 on Ubuntu 24.04 as the software version, choose your Region, then choose Launch through EC2. Select your instance type, key pair, subnet and the security group described above.

Or use the AWS CLI to create the security group and launch. Replace the values in angle brackets:

aws ec2 create-security-group --region <region> --vpc-id <your-vpc> \
  --group-name tika --description "Apache Tika: SSH from admins, HTTPS from API clients"
aws ec2 authorize-security-group-ingress --region <region> --group-id <sg-id> --ip-permissions \
  'IpProtocol=tcp,FromPort=22,ToPort=22,IpRanges=[{CidrIp=<your-admin-cidr>}]' \
  'IpProtocol=tcp,FromPort=443,ToPort=443,IpRanges=[{CidrIp=<your-client-cidr>}]'
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 <sg-id> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=apache-tika}]'

To serve your own DNS name from the first boot, add user data that writes it before first boot runs, for example #!/bin/sh followed by mkdir -p /etc/sac && echo tika.example.com > /etc/sac/tika-hostname. Without it, the instance serves its EC2 public DNS name (or its IP address, if it has no public DNS name). You can change the name later (Step 10).

Connect over SSH as the ubuntu user of the Apache Tika Server 3.3.3 on Ubuntu 24.04 image:

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

First boot generates the certificate and the API password. Then Tika and nginx start:

systemctl is-active tika nginx
sudo test -f /var/lib/sac/data/tika-firstboot.done && echo FIRSTBOOT_DONE

active active FIRSTBOOT_DONE

nginx is the only service on the network (port 443, plus SSH). Tika's own port 9998 is bound to 127.0.0.1. The other local listeners are the operating system's DNS stub, time sync and DHCP client:

sudo ss -lntup | awk 'NR>1 {print $1, $5, $7}' | sed -E 's/pid=[0-9]+,fd=[0-9]+/.../g' | sort

tcp 0.0.0.0:22 users:(("sshd",...),("systemd",...)) tcp 0.0.0.0:443 users:(("nginx",...),("nginx",...),("nginx",...)) tcp 127.0.0.53%lo:53 users:(("systemd-resolve",...)) tcp 127.0.0.54:53 users:(("systemd-resolve",...)) tcp [::]:22 users:(("sshd",...),("systemd",...)) tcp [::]:443 users:(("nginx",...),("nginx",...),("nginx",...)) tcp [::ffff:127.0.0.1]:9998 users:(("java",...)) udp 127.0.0.1:323 users:(("chronyd",...)) udp 127.0.0.53%lo:53 users:(("systemd-resolve",...)) udp 127.0.0.54:53 users:(("systemd-resolve",...)) udp 172.31.88.254%ens5:68 users:(("systemd-network",...)) udp [::1]:323 users:(("chronyd",...))

The credentials file is readable by root only. This prints it with the password hidden; sudo cat /root/tika-server-credentials.txt shows it:

sudo sed -E 's/^(TIKA_PASSWORD=).*/\1<hidden>/' /root/tika-server-credentials.txt

# Apache Tika Server 3.3.3 - generated on first boot by tika-firstboot.service
# This password is unique to this instance; none was baked into the image. Keep this file secret. TIKA_URL=https://ec2-100-55-11-151.compute-1.amazonaws.com/ TIKA_USERNAME=admin TIKA_PASSWORD=<hidden>
#
# Every Tika endpoint needs HTTP Basic Auth with TIKA_USERNAME and TIKA_PASSWORD; https://ec2-100-55-11-151.compute-1.amazonaws.com/healthz is the
# only open path. The certificate is self signed (minted on this instance's first boot): pass curl --cacert with # /etc/ssl/tika/tika.crt, or install your own certificate. # Extract text:
curl -u admin -T report.pdf -H 'Accept: text/plain' https://ec2-100-55-11-151.compute-1.amazonaws.com/tika
# Extract metadata:
curl -u admin -T report.docx -H 'Accept: application/json' https://ec2-100-55-11-151.compute-1.amazonaws.com/meta
# New password:
sudo tika-set-password
# Change the name it serves as:
sudo tika-set-hostname <your-dns-name>
# User guide: https://secureanycloud.com/stacks/apache-tika-server-3-3-3/

The values above come from one example instance. Yours are different.

Clients verify the instance's own certificate, /etc/ssl/tika/tika.crt. The certificate is public, and its key is readable by root only. Copy the certificate to every host that calls Tika, as shown here into your home directory, and check that it names this instance. Inside the VPC the public DNS name resolves to the private address, so the commands below also work on the instance itself:

sudo install -m 0644 /etc/ssl/tika/tika.crt ~/tika-ca.crt openssl x509 -in ~/tika-ca.crt -noout -subject -enddate -ext subjectAltName
H=$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' /root/tika-server-credentials.txt)
curl -s --cacert ~/tika-ca.crt "https://$H/healthz"

subject=CN = ec2-100-55-11-151.compute-1.amazonaws.com, O = sac notAfter=Jan 22 04:28:04 2029 GMT X509v3 Subject Alternative Name: DNS:ec2-100-55-11-151.compute-1.amazonaws.com, IP Address:100.55.11.151, IP Address:172.31.88.254, IP Address:127.0.0.1, DNS:localhost ok

Without the password, every Tika endpoint is refused:

H=$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' /root/tika-server-credentials.txt)
curl -s --cacert ~/tika-ca.crt -o /dev/null -w 'no password: HTTP %{http_code}\n' "https://$H/version"
curl -s --cacert ~/tika-ca.crt -o /dev/null -w 'no password, upload: HTTP %{http_code}\n' -T /opt/tika/samples/sac-sample.pdf "https://$H/tika"

no password: HTTP 401 no password, upload: HTTP 401

Keep the password out of your shell history and process list. Put it in a netrc file that only you can read, and give curl --netrc-file. Interactively, curl -u admin also works, and curl then asks for the password.

C=/root/tika-server-credentials.txt
H=$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' $C);
P=$(sudo sed -n 's/^TIKA_PASSWORD=//p' $C) ( umask 077; printf 'machine %s login admin password %s\n' "$H" "$P" > ~/.tika-netrc ) ls -l ~/.tika-netrc | awk '{print $1, $NF}' curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt "https://$H/version"; echo

-rw------- /root/.tika-netrc Apache Tika 3.3.3

Upload a document with PUT (curl -T) to /tika and ask for text/plain. The image includes two small sample documents in /opt/tika/samples, a PDF and a Word (DOCX) file. Use your own files the same way:

H=$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' /root/tika-server-credentials.txt)
curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -T /opt/tika/samples/sac-sample.pdf -H 'Accept: text/plain' "https://$H/tika" | sed '/^[[:space:]]*$/d'
curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -T /opt/tika/samples/sac-sample.docx -H 'Accept: text/plain' "https://$H/tika" | sed '/^[[:space:]]*$/d'

SacTikaProbe Apache Tika on sac extracts text and metadata from this document. SacTikaProbe Apache Tika on sac extracts text and metadata from this document.

Ask /tika for text/html instead to get the document as XHTML with its structure (headings, paragraphs, tables).

/meta returns the document's metadata as JSON: its media type, title, author, page count and so on, and which parser read it:

H=$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' /root/tika-server-credentials.txt)
curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -T /opt/tika/samples/sac-sample.docx -H 'Accept: application/json' "https://$H/meta" | jq '{"Content-Type", "dc:title", "dc:creator", "X-TIKA:Parsed-By"}'

{ "Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "dc:title": "sac Tika sample", "dc:creator": "sac", "X-TIKA:Parsed-By": [ "org.apache.tika.parser.DefaultParser", "org.apache.tika.parser.microsoft.ooxml.OOXMLParser", "org.apache.tika.parser.microsoft.ooxml.xwpf.XWPFEventBasedWordExtractor" ] }

/rmeta/text returns metadata and text together, one JSON object per document, including every document embedded in it (attachments of an e-mail, files in a ZIP, images in a Word file). /detect/stream names the media type and /language/string guesses the language of a text:

H=$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' /root/tika-server-credentials.txt)
curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -T /opt/tika/samples/sac-sample.pdf "https://$H/rmeta/text" | jq '.[0] | {"Content-Type", "xmpTPg:NPages", "pdf:PDFVersion", content: (."X-TIKA:content" | gsub("\\s+"; " ") | ltrimstr(" "))}'
curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -T /opt/tika/samples/sac-sample.docx "https://$H/detect/stream"; echo printf 'Apache Tika detects the language of this sentence.' | curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -T - "https://$H/language/string"; echo

{ "Content-Type": "application/pdf", "xmpTPg:NPages": "1", "pdf:PDFVersion": "1.4", "content": "SacTikaProbe Apache Tika on sac extracts text and metadata from this document. " } application/vnd.openxmlformats-officedocument.wordprocessingml.document en

The other endpoints are /unpack (the embedded files of a document, as a ZIP), /parsers, /detectors and /mime-types (what this Tika supports) and /version. The Tika Server documentation describes each endpoint and the request headers that tune parsing.

A wrong password is refused like a missing one, a request for any host name other than the instance's own is dropped, and nothing listens on port 80:

H=$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' /root/tika-server-credentials.txt) printf 'machine %s login admin password %s\n' "$H" "wrong-$(openssl rand -hex 8)" | \
  curl -s --netrc-file /dev/stdin --cacert ~/tika-ca.crt -o /dev/null -w 'wrong password: HTTP %{http_code}\n' "https://$H/version" curl -sk -o /dev/null -w 'unknown host name: HTTP %{http_code} (000 = connection closed)\n' --resolve evil.example:443:127.0.0.1 https://evil.example/version || true curl -s -o /dev/null -w 'port 80: HTTP %{http_code} (000 = nothing listening)\n' http://127.0.0.1/ || true

wrong password: HTTP 401 unknown host name: HTTP 000 (000 = connection closed) port 80: HTTP 000 (000 = nothing listening)

Tika's configuration is /etc/tika/tika-config.xml. It binds Tika to localhost, keeps the unsecure features off and loads only the extraction endpoints. Asked directly on its local port, Tika refuses a fetch request for a local file (422, nothing fetched) and has no /pipes or /async endpoint:

grep -oE '<(host|port|enableUnsecureFeatures|endpoint)>[^<]*' /etc/tika/tika-config.xml | sed 's/^<//; s/>/=/' | paste -sd' ' - curl -s -o /dev/null -w 'fetcher request for /etc/passwd: HTTP %{http_code}\n' -X PUT -H 'fetcherName: fsf' -H 'fetchKey: /etc/passwd' http://127.0.0.1:9998/tika for p in pipes async; do curl -s -o /dev/null -w "POST /$p: HTTP %{http_code}\n" -X POST -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:9998/$p; done

host=127.0.0.1 port=9998 enableUnsecureFeatures=false endpoint=tika endpoint=rmeta endpoint=meta endpoint=detect endpoint=language endpoint=unpack endpoint=mime endpoint=detectors endpoint=parsers endpoint=version fetcher request for /etc/passwd: HTTP 422 POST /pipes: HTTP 404 POST /async: HTTP 404

Port 9998 answers without a password, but only on the instance itself. Anyone who can run commands there is already an administrator. Never open 9998 in a security group or bind Tika to another address. Go through nginx on 443.

An uploaded XML document that tries to include a local file through an external entity gets nothing back:

X=$(mktemp) printf '<?xml version="1.0"?>\n<!DOCTYPE r [<!ENTITY x SYSTEM "file:///etc/passwd">]>\n<r>external entity test: &x;</r>\n' > "$X" curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -T "$X" -H 'Content-Type: application/xml' -H 'Accept: text/plain' \
  "https://$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' /root/tika-server-credentials.txt)/tika" | sed '/^[[:space:]]*$/d' rm -f "$X"

external entity test:

Tika may talk to localhost only (every other address is denied), and nginx and the first boot service are denied the instance metadata addresses:

systemctl show -p IPAddressAllow -p IPAddressDeny tika.service nginx.service tika-firstboot.service | sed '/^$/d'

IPAddressAllow=::1/128 127.0.0.0/8 IPAddressDeny=::/0 0.0.0.0/0 IPAddressAllow= IPAddressDeny=168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128 IPAddressAllow= IPAddressDeny=168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128

Tika runs as the unprivileged tika user. Its watchdog process starts the parsing process with a heap of half the instance memory and restarts it if a document exhausts that memory:

for p in $(pgrep -u tika java); do printf '%s pid %s: %s\n' "$(ps -o user= -p "$p")" "$p" "$(tr '\0' ' ' < /proc/$p/cmdline | grep -oE '(-Xmx[^ ]+|-XX:MaxRAMPercentage=[^ ]+|-XX:\+ExitOnOutOfMemoryError|TikaServerProcess -h [^ ]+ -p [^ ]+|-jar [^ ]+ -c [^ ]+)' | paste -sd' ' -)"; done

tika pid 1035: -Xmx128m -jar /opt/tika/tika-server.jar -c /etc/tika/tika-config.xml tika pid 1353: -XX:MaxRAMPercentage=50 -XX:+ExitOnOutOfMemoryError TikaServerProcess -h 127.0.0.1 -p 9998

Uploads larger than 100 MiB are refused before they reach Tika, and every response carries security headers (Tika's HTML output repeats document content, so browsers are told never to run anything in it):

H=$(sudo sed -n 's#^TIKA_URL=https://\(.*\)/$#\1#p' /root/tika-server-credentials.txt) head -c 110000000 /dev/zero | curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -o /dev/null \
  -w 'a 110 MB upload: HTTP %{http_code}\n' -X PUT -H 'Content-Type: application/octet-stream' --data-binary @- "https://$H/tika" curl -s --netrc-file ~/.tika-netrc --cacert ~/tika-ca.crt -D - -o /dev/null "https://$H/version" | grep -iE '^(strict|x-content|x-frame|content-security|cache-control|server)' | tr -d '\r'

a 110 MB upload: HTTP 413 server: nginx strict-transport-security: max-age=31536000 x-content-type-options: nosniff x-frame-options: DENY content-security-policy: default-src 'none'; frame-ancestors 'none'; sandbox cache-control: no-store

Copy ~/tika-ca.crt to the host that calls Tika and use the URL from the credentials file, or the instance's public IP address (both are in the certificate). From your workstation, with the security group allowing your address on 443:

curl --cacert tika-ca.crt -u admin -T report.pdf -H 'Accept: text/plain' https://<public-ip>/tika

Client libraries that call a Tika Server, for example the Python tika package (set TIKA_SERVER_ENDPOINT to the HTTPS URL), need the same four settings: the URL, the user admin, the password and the CA certificate.

Your own DNS name and certificate. Point a DNS record at the instance (an Elastic IP is recommended), then make nginx serve that name with a new certificate:

sudo tika-set-hostname tika.example.com

The name is kept in /etc/sac/tika-hostname. To use a certificate from a public or private certificate authority instead, replace /etc/ssl/tika/tika.crt and /etc/ssl/tika/tika.key (key mode 0600, owner root) and run sudo systemctl reload nginx, or put an Application Load Balancer with an AWS Certificate Manager certificate in front of port 443.

Generate a new random password, which is written to /root/tika-server-credentials.txt. Or set your own from standard input so it never appears on a command line. nginx reads the password hash on every request, so no restart is needed:

sudo tika-set-password read -rs NEWPW && printf '%s\n' "$NEWPW" | sudo tika-set-password --stdin; unset NEWPW

• Larger uploads. Raise client_max_body_size 100m; in /etc/nginx/sites-available/sac-tika, then sudo nginx -t && sudo systemctl reload nginx. Make sure the instance has the memory and disk for the documents you allow.
• Memory. The parsing process uses half the instance memory (-XX:MaxRAMPercentage=50 under forkedJvmArgs in /etc/tika/tika-config.xml). The simplest way to give Tika more memory is a larger instance type. To change the share instead, edit the value and run sudo systemctl restart tika.
• Time limit. A single parse may take up to 5 minutes (taskTimeoutMillis in the same file) before Tika restarts its parsing process. nginx waits slightly longer.

Keep enableUnsecureFeatures set to false. Turning it on lets anyone who knows the password make Tika read files and fetch URLs through fetchers. If you need Tika's pipes for batch work, run them on a private instance with no internet access.

• Allow TCP 443 only from the hosts that call Tika, and TCP 22 only from your administrators.
• Keep the password in a secret store (for example AWS Secrets Manager) and rotate it with tika-set-password.
• Unattended security upgrades stay on for Ubuntu, OpenJDK and nginx. Tika is the official JAR in /opt/tika. Watch the Apache Tika news page for new releases and security announcements. To upgrade, download the new tika-server-standard JAR from Maven Central and check its checksum. Then point the /opt/tika/tika-server.jar link at it and run sudo systemctl restart tika.