Running the In-Place Upgrade Script to v1.3.1
What: Upgrade a single-instance StorageLink 1.3.0 to 1.3.1 in place
Requirement: The instance must be on 1.3.0. Instances on 1.2.1 or earlier have no license and are refused; move them to a new instance with a backup instead
Command: cd ~ && curl -sS -O https://thorntech-products.s3.amazonaws.com/storagelink/1.003.01/in-place-upgrade-storagelink.sh && sudo bash ./in-place-upgrade-storagelink.sh
Important: Export a backup file first. 1.3.1 is a security hotfix (Apache Tomcat, Jackson and Log4j API updates) with no database changes, so the restart takes about a minute
Overview
This article goes over how to run the in-place upgrade script to upgrade an existing StorageLink 1.3.0 instance to version 1.3.1 (1.003.01). 1.3.1 is a security hotfix off 1.3.0; the Release Notes list what changed. From 1.3.0 the script replaces the application files and nothing else.
Note: The script only applies to instances on 1.3.0. Licensing arrived in 1.3.0, so an instance on 1.2.1 or earlier has no license, and an upgrade in place would leave it unlicensed. The script refuses those instances before changing anything. To upgrade one, deploy a new instance and import a backup, as described in the Upgrade Process article. Contact support@thorntech.com first if the instance has more than 10 users or legacy pricing, so that a license covering them is ready.
Your license carries forward. It is stored in the database, bound to this instance, and the script does not touch it; it prints 1.3.x source: the existing license (database, cluster-bound) carries forward unchanged. at the start of the run.
Important Mentions
Make a new Backup File
Our recommended approach for upgrading is to deploy a new StorageLink instance and import your Users & Settings into it with a Backup file, as described in the Upgrade Process article. You can export a new Backup file under Settings ---> Backup & Recovery ---> Export Backup File.
The script exists for convenience; the safest approach is the one above. Before running it, export a new Backup file. The script also writes its own rollback bundle (a database dump and the files it replaces) to /var/backups/slink-upgrade-<stamp>/.
LetsEncrypt and custom SSL certificates
If you used LetsEncrypt or installed your own certificate, edit the new website.conf after the upgrade: the script installs a new one and keeps yours as website.conf-<stamp> in the same directory. Copy the server_name, ssl_certificate and ssl_certificate_key lines across, then run sudo nginx -t && sudo systemctl restart nginx. The file is located here:
AWS:
/etc/nginx/conf.d/website.conf
Azure and Google Cloud:
/etc/nginx/sites-available/website.conf
Check out the Troubleshooting section of the LetsEncrypt article to see what the file should look like.
Memory Settings
The script sizes the Java heap from the VM's RAM in /opt/swiftgw/swiftgateway-1.3.1.conf. If you resize the VM later, use the Memory Settings article.
Troubleshooting
The script stops with cannot be upgraded in place. The instance is on 1.2.1 or earlier and nothing has been changed. See the note in the Overview.
The script stops with backend did not become healthy in 10 minutes. The service is left running and may still be starting. Check sudo systemctl status swiftgateway and the most recent application log (the date is in the name):
/opt/swiftgw/log/application-2026-11-04.log
If you become stuck at the Please wait while StorageLink finishes setting up loading screen, or need to roll back, contact us at support@thorntech.com and send the script output and that log. The rollback bundle for each run is in /var/backups/slink-upgrade-<stamp>/.
Edge cases
Restricted networks, high availability, load balancers, nginx validation, rolling back
No outbound internet access. The script downloads the 1.3.1 files from https://thorntech-products.s3.amazonaws.com, and installs Java 21 or unzip from your operating system's package repositories only if they are missing. An instance without outbound HTTPS access cannot run it; use the backup-and-restore path in the Upgrade Process article instead.
High-availability deployments. Do not run the script on a high-availability deployment; contact support@thorntech.com for the upgrade path.
Behind a load balancer or reverse proxy. Nothing to do. The trusted-proxy setting (security.client-ip.trusted-proxies) that StorageLink 1.3.0 introduced is already in place on a 1.3.x instance, and the script leaves your existing properties alone.
nginx validation. The script refuses to start if your current nginx configuration fails nginx -t, and tells you so; fix the file it names and run the script again. If the new website.conf fails validation, the script restores your previous one, keeps the new one as website.conf-1.3.1-failed in the same directory, and continues. Send both files to support if that happens.
StorageLink does not start after the upgrade. One known cause: security.max-login-failed-attempts or security.failed-login-timeout-seconds set below 1 in /opt/swiftgw/application.properties. The startup error in the application log names the property; set it to 1 or more and run sudo systemctl restart swiftgateway.
Rolling back. Each run writes /var/backups/slink-upgrade-<stamp>/ with pg_dumpall.sql (the database before the upgrade), opt-swiftgw.tgz (the previous /opt/swiftgw), and the previous swiftgateway.service, website.conf and application.properties. The previous jar also stays in /opt/swiftgw/. Contact support@thorntech.com before rolling back and we will walk through it with you.
Running the Script
SSH into the VM (see SSH into the VM).
Download the script into your home directory:
cd ~
curl -sS -O https://thorntech-products.s3.amazonaws.com/storagelink/1.003.01/in-place-upgrade-storagelink.sh
Run it:
sudo bash ./in-place-upgrade-storagelink.sh
Run it exactly like that, with sudo bash from your home directory: /tmp is mounted noexec on the StorageLink image. The script prints every command it runs. Keep the SSH session open until it finishes. If the script stops partway, run it again. A successful run ends with:
StorageLink 1.3.1 is UP after upgrade.
Upgrade to 1.3.1 complete.
Rollback bundle: /var/backups/slink-upgrade-<stamp>
When you refresh your Web Admin UI you should see the updated UI and version 1.3.1 at the bottom.
After the Upgrade
- Certificates. Re-apply your hostname and certificate lines to the new
website.conf(see above). - Clean up. Remove the rollback bundle and the stamped copies of the previous admin UI,
website.confand service definition once you are satisfied.
Script Contents
in-place-upgrade-storagelink.sh (1.003.01)
#!/bin/bash
#
# StorageLink in-place upgrade script — upgrades an existing 1.3.0 instance to
# v1.3.1. Instances on 1.2.1 or earlier are not upgraded in place: they have no
# license (licensing arrived in 1.3.0) and move to a new instance through a backup.
#
# 1.3.1 is a security hotfix off 1.3.0 (Apache Tomcat, Jackson and Log4j API
# dependency updates). It adds no application properties, applies no database
# migrations and changes no behavior, so from 1.3.0 this is a jar/UI swap.
# The 1.3.x transition steps are kept (idempotent, no-ops on a 1.3.0 source):
# 1. Application files: the 1.3.1 jar and conf, the web admin UI and the nginx
# site config. Spring Boot 4 no longer produces an executable boot jar, so
# the systemd unit is replaced with one that launches `java -jar` with an
# EnvironmentFile (JAVA_OPTS/RUN_ARGS), Type=notify, and
# features.systemd.notify=true in application.properties.
# 2. Application properties: adds the properties 1.3.x requires and sets
# server.forward-headers-strategy=none (1.3.x resolves client addresses
# through security.client-ip.trusted-proxies instead). Every step is
# idempotent, so on a 1.3.0 source these are no-ops.
# 3. Java 21 is installed if it is missing.
#
# PostgreSQL is left as it is. StorageLink 1.3.x enforces no minimum PostgreSQL
# version, so the database already on the instance keeps running unchanged; a
# new 1.3.x instance deployed from the marketplace ships PostgreSQL 18.
#
# Every step can be repeated: if the script stops partway, run it again.
#
# Supported: single-instance StorageLink 1.3.0 on AWS (Amazon Linux 2023), Azure
# and Google Cloud (Ubuntu). Not for high-availability deployments.
#
# QA mode: if ASSETS_TARBALL is set (a .tgz containing swiftgateway-<ver>.jar,
# swiftgateway-<ver>.conf, admin-ui/ and website.conf), it is used instead of the
# public S3 assets.zip — lets the upgrade run against pre-release builds.
#
# How to run:
# cd ~
# curl -sS -O https://thorntech-products.s3.amazonaws.com/storagelink/1.003.01/in-place-upgrade-storagelink.sh
# sudo bash ./in-place-upgrade-storagelink.sh
#
# Run it with "sudo bash" from your home directory: /tmp is mounted noexec on
# the hardened appliance, so "sudo ./in-place-upgrade-storagelink.sh" from /tmp
# fails with "Permission denied".
#
set -xe
if [[ $(whoami) != "root" ]]; then
echo "Usage: sudo bash $0"
exit 1
fi
TARGET_VERSION="${TARGET_VERSION:-1.3.1}"
TARGET_VERBOSE_VERSION="1.003.01"
# One stamp per run: every backup copy and the rollback bundle carry it, so a
# re-run never overwrites the copies taken before the first attempt.
STAMP=$(date +"%m%d%Y-%H%M%S")
APPLICATION_PROPERTIES="/opt/swiftgw/application.properties"
BACKUP_DIR="/var/backups/slink-upgrade-${STAMP}"
# Wait for any other apt/dpkg holder (e.g. unattended-upgrades) instead of
# failing mid-upgrade, and never let a package replace a locally-modified
# config file via a conffile prompt (noninteractive runs die on those).
APT_OPTS=(-o DPkg::Lock::Timeout=600
-o Dpkg::Options::=--force-confdef
-o Dpkg::Options::=--force-confold)
function extractPropValueFromSourceFile {
local prefix="${1}"
local str=`grep "${prefix}" ${2} 2>/dev/null`
echo "${str#$prefix}" | xargs
}
#
# 0. Preflight
#
# Source version: the jar currently installed (the newest one that is not the
# target). Drives the licensing message below and the health-wait hint later.
CURRENT_JAR=$(ls /opt/swiftgw/swiftgateway-*.jar 2>/dev/null | grep -v "swiftgateway-${TARGET_VERSION}.jar" | sort -V | tail -1 || true)
SOURCE_VERSION=$(basename "${CURRENT_JAR:-swiftgateway-unknown.jar}" .jar); SOURCE_VERSION="${SOURCE_VERSION#swiftgateway-}"
echo "Upgrading StorageLink ${SOURCE_VERSION} -> ${TARGET_VERSION}"
# Licensing arrived in 1.3.0. A 1.3.x source keeps its license: it is stored in
# the database, bound to this instance's cluster ID, and nothing here touches
# it. Anything older has no license and would come up unlicensed after an
# in-place upgrade, so stop before changing anything.
if [[ "${SOURCE_VERSION}" != 1.3* ]]; then
echo "ERROR: StorageLink ${SOURCE_VERSION} cannot be upgraded in place (this script needs 1.3.0). Nothing has been changed." >&2
echo "Versions before 1.3.0 have no license, so an in-place upgrade would leave this instance unlicensed." >&2
echo "Move to a new ${TARGET_VERSION} instance with a backup instead; contact support@thorntech.com first if you have more than 10 users or legacy pricing:" >&2
echo " https://help.thorntech.com/storagelink/docs/backup-migration-update/upgrade" >&2
exit 1
fi
echo "1.3.x source: the existing license (database, cluster-bound) carries forward unchanged."
mkdir -p "${BACKUP_DIR}"
# Determine cloud provider (same probe order as prior scripts)
# head -c keeps a wrong-cloud error page (e.g. Google's HTML 404) from
# flooding the trace log — the real values are all short strings.
AWS_DOMAIN=$(curl -s --max-time 2 "http://169.254.169.254/latest/meta-data/services/domain" | head -c 40 || true)
AZURE_DOMAIN=$(curl --noproxy "*" --max-time 2 -s -H 'Metadata: True' "http://169.254.169.254/metadata/instance/compute/azEnvironment?api-version=2019-06-01&format=text" | head -c 40 || true)
GCP_CHECK=$(curl -s --max-time 2 "http://169.254.169.254/computeMetadata/v1/instance/zone" -H "Metadata-Flavor: Google" | head -c 80 || true)
CLOUD_PROVIDER=aws
# GCP's metadata answer contains "zones/..." — other clouds' IMDS return XML/JSON errors here
[[ $GCP_CHECK == *"zones/"* ]] && CLOUD_PROVIDER=gcp
[[ $AWS_DOMAIN == "amazonaws.com" ]] && CLOUD_PROVIDER=aws
[[ $AZURE_DOMAIN == "AzurePublicCloud" ]] && CLOUD_PROVIDER=azure
# Determine OS and nginx layout
if getent passwd www-data > /dev/null 2>&1; then
OS=ubuntu
NGINX_USER=www-data
NGINX_CONF_PATH="/etc/nginx/sites-available"
else
OS=el
NGINX_USER=nginx
NGINX_CONF_PATH="/etc/nginx/conf.d"
fi
# unzip is needed to unpack the assets bundle; not every image ships it.
if ! command -v unzip >/dev/null 2>&1; then
if [ "$OS" == "ubuntu" ]; then
apt-get "${APT_OPTS[@]}" update
DEBIAN_FRONTEND=noninteractive apt-get "${APT_OPTS[@]}" install -y -q unzip
else
yum install -y unzip
fi
fi
# Pre-flight: refuse to start if the CURRENT nginx config already fails
# validation. This upgrade stops the app — never begin that on a box whose
# web tier is already broken.
if ! nginx -t; then
echo "" >&2
echo "ERROR: 'nginx -t' fails on this instance's CURRENT nginx configuration." >&2
echo "The upgrade has NOT started and nothing has been changed." >&2
echo "Fix the nginx configuration (run 'sudo nginx -t' to see the error), then re-run this script." >&2
exit 1
fi
#
# 1. Backups (rollback bundle)
#
# Full logical DB backup — the database itself is not modified by this script.
# 1.3.1 applies no schema changes; a 1.2.x source gets the 1.3.x migrations on
# first start. Either way, keep a copy of the pre-upgrade state.
sudo -u postgres pg_dumpall > "${BACKUP_DIR}/pg_dumpall.sql"
# App + config backups
tar czf "${BACKUP_DIR}/opt-swiftgw.tgz" --exclude='swiftgw/tmp/*' --exclude='swiftgw/log/*' -C /opt swiftgw
cp -a /etc/systemd/system/swiftgateway.service "${BACKUP_DIR}/swiftgateway.service"
cp -a "${NGINX_CONF_PATH}/website.conf" "${BACKUP_DIR}/website.conf" 2>/dev/null || \
cp -a /etc/nginx/sites-enabled/website.conf "${BACKUP_DIR}/website.conf" 2>/dev/null || true
echo "Rollback bundle written to ${BACKUP_DIR}"
#
# 2. Stop the application
#
systemctl stop swiftgateway
#
# 3. Java 21 runtime (1.2.x images already ship it; install if missing)
#
if ! java -version 2>&1 | grep -q 'version "21'; then
if [ "$OS" == "ubuntu" ]; then
apt-get "${APT_OPTS[@]}" update
DEBIAN_FRONTEND=noninteractive apt-get "${APT_OPTS[@]}" install -y -q openjdk-21-jre-headless
update-alternatives --set java /usr/lib/jvm/java-21-openjdk-amd64/bin/java || true
else
yum install -y java-21-amazon-corretto
/usr/sbin/update-alternatives --set java /usr/lib/jvm/java-21-amazon-corretto.x86_64/bin/java
fi
fi
#
# 4. Install StorageLink ${TARGET_VERSION} files
#
cd /tmp
rm -rf /tmp/slink-upgrade-assets && mkdir /tmp/slink-upgrade-assets && cd /tmp/slink-upgrade-assets
if [ -n "${ASSETS_TARBALL}" ] && [ -f "${ASSETS_TARBALL}" ]; then
tar xzf "${ASSETS_TARBALL}"
else
curl -fsSL -o assets.zip "https://thorntech-products.s3.amazonaws.com/storagelink/${TARGET_VERBOSE_VERSION}/assets.zip"
# Normalize the zip's assets/ folder to the same top-level layout the
# ASSETS_TARBALL path produces — later steps (website.conf install) resolve
# files relative to /tmp/slink-upgrade-assets and would miss assets/.
unzip -o assets.zip && mv assets/* . && rmdir assets
fi
# jar + conf
chmod +x swiftgateway-${TARGET_VERSION}.jar
chown swiftgw:swiftgw swiftgateway-${TARGET_VERSION}.jar swiftgateway-${TARGET_VERSION}.conf
mv swiftgateway-${TARGET_VERSION}.jar swiftgateway-${TARGET_VERSION}.conf /opt/swiftgw/
# Heap sizing: the conf ships with values computed for the build VM; recompute
# for this instance like first-boot does (Xms ~15% / Xmx ~48% of MemTotal).
MEM_MB=$(awk '/MemTotal/ {printf "%d", $2/1024}' /proc/meminfo)
XMS=$((MEM_MB * 15 / 100))
XMX=$((MEM_MB * 48 / 100))
sed -i -E "s/-Xms[0-9]+m/-Xms${XMS}m/; s/-Xmx[0-9]+m/-Xmx${XMX}m/" /opt/swiftgw/swiftgateway-${TARGET_VERSION}.conf
# admin UI (previous UI kept as admin-ui-<stamp>)
if [ -d admin-ui ]; then
tar czf /usr/share/nginx/admin-ui.tar.gz admin-ui
else
mv admin-ui.tar.gz /usr/share/nginx
fi
cd /usr/share/nginx
[ -d admin-ui ] && mv admin-ui "admin-ui-${STAMP}"
tar xzvpf admin-ui.tar.gz && rm -f admin-ui.tar.gz
# Drop macOS AppleDouble metadata files (._*) if the bundle was built on a Mac.
find admin-ui -name '._*' -delete
chown -R ${NGINX_USER}:${NGINX_USER} admin-ui
# nginx site config (backup already taken; certs keep their existing paths)
cd /tmp/slink-upgrade-assets
if [ -f website.conf ]; then
cp "${NGINX_CONF_PATH}/website.conf" "${NGINX_CONF_PATH}/website.conf-${STAMP}" 2>/dev/null || true
chown ${NGINX_USER}:${NGINX_USER} website.conf
mv website.conf "${NGINX_CONF_PATH}/website.conf"
# Validate the new config immediately. Don't abort — restore the previous
# (working) config, keep the failing one for inspection, and continue loudly.
if ! nginx -t; then
echo "ERROR: new website.conf fails 'nginx -t' — restoring the previous config." >&2
mv "${NGINX_CONF_PATH}/website.conf" "${NGINX_CONF_PATH}/website.conf-${TARGET_VERSION}-failed"
cp "${BACKUP_DIR}/website.conf" "${NGINX_CONF_PATH}/website.conf"
nginx -t
fi
fi
# webconfig.js — preserve this instance's OAuth client
# The OAuth client values are served publicly in webconfig.js by design, but
# keep them out of this trace log — customers share these logs with support.
{ set +x; } 2>/dev/null
echo "Writing webconfig.js with this instance's OAuth client (values not logged)"
CLIENT_ID=$(extractPropValueFromSourceFile "security.client-id=" ${APPLICATION_PROPERTIES})
CLIENT_SECRET=$(extractPropValueFromSourceFile "security.client-secret=" ${APPLICATION_PROPERTIES})
(
cat <<EOF
window._env_ = {
"clientid": "$CLIENT_ID",
"clientsecret": "$CLIENT_SECRET",
"cloudProvider": "$CLOUD_PROVIDER",
"version": "${TARGET_VERSION%%-*}"
};
EOF
) | tee /usr/share/nginx/admin-ui/webconfig.js >/dev/null
chown ${NGINX_USER}:${NGINX_USER} /usr/share/nginx/admin-ui/webconfig.js
set -x
#
# 5. application.properties — add the 1.3.x-required properties (idempotent; no-ops on a 1.3.0 source)
#
function ensure_prop {
local key="$1" value="$2"
grep -q "^${key}=" "${APPLICATION_PROPERTIES}" || \
echo "${key}=${value}" >> "${APPLICATION_PROPERTIES}"
}
cp -a "${APPLICATION_PROPERTIES}" "${BACKUP_DIR}/application.properties"
# Required for the Type=notify systemd unit — without it the service never
# signals readiness and systemd kills it at TimeoutSec.
ensure_prop "features.systemd.notify" "true"
# 1.3.x resolves the client address itself (security.client-ip.trusted-proxies)
# and rebuilds proxied URLs from security.redirect.base-path, so Spring's own
# forwarded-header handling must be off. 1.2.x set this to "framework"; on
# 1.3.x any value other than "none" is logged as an error at startup and
# bypasses the trusted-proxy resolution, so replace whatever is there.
# Leave the file untouched when it is already correct (1.3.x sources), so a
# re-run or a 1.3.0 -> 1.3.1 upgrade does not reorder application.properties.
if ! grep -q '^server\.forward-headers-strategy=none$' "${APPLICATION_PROPERTIES}"; then
sed -i '/^server\.forward-headers-strategy=/d' "${APPLICATION_PROPERTIES}"
ensure_prop "server.forward-headers-strategy" "none"
fi
ensure_prop "security.redirect.base-path" "backend/"
ensure_prop "server.max-http-request-header-size" "128KB"
# Upload-path rewrite feature flags (ship-default empty ruleset)
ensure_prop "features.api.file-upload-accept-rules" ""
chown swiftgw:swiftgw "${APPLICATION_PROPERTIES}"
#
# 6. systemd unit — Spring Boot 4 launch pattern
#
cp -a /etc/systemd/system/swiftgateway.service "/etc/systemd/system/swiftgateway.service-${STAMP}"
cat > /etc/systemd/system/swiftgateway.service <<EOF
[Unit]
Description=StorageLink
After=syslog.target network.target
Before=nginx.service
[Service]
Type=notify
User=swiftgw
WorkingDirectory=/opt/swiftgw
EnvironmentFile=-/opt/swiftgw/swiftgateway-${TARGET_VERSION}.conf
ExecStart=/usr/bin/java \$JAVA_OPTS -jar /opt/swiftgw/swiftgateway-${TARGET_VERSION}.jar \$RUN_ARGS
SuccessExitStatus=143
AmbientCapabilities=CAP_NET_BIND_SERVICE
NotifyAccess=all
TimeoutSec=900
[Install]
WantedBy=multi-user.target
EOF
# Login banner version
sed -i "s/1\..*/${TARGET_VERSION}/" /etc/profile.d/login-info.sh 2>/dev/null || true
#
# 7. Restart everything and wait for health
#
if nginx -t; then
systemctl restart nginx
else
echo "WARNING: nginx config fails validation — nginx NOT restarted (see errors above)." >&2
fi
systemctl daemon-reload
systemctl start swiftgateway
# From 1.2.x the first start applies the 1.3.x schema migrations, so allow up
# to 10 minutes on small VMs; from 1.3.0 the backend is normally UP in ~1 min.
for i in $(seq 1 120); do
sleep 5
if curl -sk --max-time 5 http://127.0.0.1:8080/actuator/health | grep -q '"UP"'; then
echo "StorageLink ${TARGET_VERSION} is UP after upgrade."
break
fi
if [ "$i" == "120" ]; then
echo "ERROR: backend did not become healthy in 10 minutes"
echo "The service was left running and may still be starting. Check 'systemctl status swiftgateway'"
echo "and 'journalctl -u swiftgateway'. Once the cause is fixed it is safe to run this script again."
journalctl -u swiftgateway --no-pager | tail -40
exit 1
fi
done
echo
echo "Upgrade to ${TARGET_VERSION} complete."
echo "Rollback bundle: ${BACKUP_DIR}"
echo "PostgreSQL was left at its current version; ${TARGET_VERSION} needs no database upgrade."
if [[ "${SOURCE_VERSION}" == 1.3* ]]; then
echo "License: carried forward from ${SOURCE_VERSION} (nothing to do)."
else
echo "Reminder: if this instance has no license, activate one in Settings -> License."
fi
echo "Previous application files are kept for rollback: ${CURRENT_JAR:-<none>} and ${BACKUP_DIR}."
