Gluesync Control for Linux

Gluesync Control is the program that starts, stops, updates and collects the logs of Gluesync on a Linux server. It is one static file for each CPU (amd64 and arm64) and needs nothing on the server except Docker: no .NET, no libraries and no other file. You use it as the gluesync command, or, when you run gluesync with no arguments in a terminal, as a text screen. It comes with the Linux installers 1.3.6 (released October 18, 2026) and later.

For Windows Server, see Gluesync Control (Windows).

What you need

Docker Engine and Docker Compose, the docker compose plugin (version 2) or docker-compose (version 1). The Linux installers install them.
root, or a user who can reach the Docker daemon (a member of the docker group, or the owner of a rootless socket).
Podman is not supported: with Podman (podman-docker) start, stop and restart stop with GS-CTL-002. status still works.

The same file runs on glibc and musl distributions (Rocky, Red Hat, Debian, Ubuntu, Alpine and others). It takes about 9 MB.

Where it is installed

The Linux installers (docker-installer.sh and docker-installer-linux-offline.sh, version 1.3.6 and later) install it from the kit, in /opt/gluesync, and put it on the PATH:

/opt/gluesync/gluesync is a link to gluesync-linux-amd64 or gluesync-linux-arm64, the file for the CPU of the server;
/usr/local/bin/gluesync is a link to /opt/gluesync/gluesync, so gluesync works from any shell;
on Red Hat family servers (Rocky, AlmaLinux, Oracle Linux), sudo does not look in /usr/local/bin. The installer then also links /usr/bin/gluesync, so that sudo gluesync works. It never replaces a file or a link that is not its own.

The installer prints the version, then asks Turn on the daily automatic update of Gluesync Control? (Y/n). The answer is yes when you press Enter. Set GLUESYNC_CONTROL_AUTO_UPDATE=y or n to answer it in an unattended install. See Automatic updates of Gluesync Control.

If the CPU is not amd64 or arm64, or the kit has no gluesync-linux-<cpu> file (a kit from before installer 1.3.6), the installer prints a warning and the install goes on without Gluesync Control. The kit then keeps its own scripts. The kit’s run.sh starts Gluesync in both cases.

Where Gluesync Control keeps its files:

What Where

What	Where
The Gluesync folder	`/opt/gluesync`. By default the folder of the `gluesync` file, or its parent, when it holds `docker-compose.yaml` or `docker-compose.yml`; else the folder Gluesync Control remembers; else `/opt/gluesync`. To manage an installation in another folder, add `--folder <path>` (the folder, or its compose file) to any command.
State	`/var/lib/gluesync` as root, otherwise `~/.local/state/gluesync`. It holds `backups`, `support`, `pins.json` and the self-update files.
Logs	`/var/log/gluesync` as root, otherwise `~/.local/state/gluesync/logs`: `control.log` (what the program did), `launch-platform.log` (the output of Docker Compose when Gluesync starts), `update.log` and `self-update.log`.

The Gluesync folder

/opt/gluesync. By default the folder of the gluesync file, or its parent, when it holds docker-compose.yaml or docker-compose.yml; else the folder Gluesync Control remembers; else /opt/gluesync. To manage an installation in another folder, add --folder <path> (the folder, or its compose file) to any command.

State

/var/lib/gluesync as root, otherwise ~/.local/state/gluesync. It holds backups, support, pins.json and the self-update files.

Logs

/var/log/gluesync as root, otherwise ~/.local/state/gluesync/logs: control.log (what the program did), launch-platform.log (the output of Docker Compose when Gluesync starts), update.log and self-update.log.

The Linux uninstaller, docker-uninstaller.sh, turns off the daily timer and removes the gluesync links. It removes /usr/local/bin/gluesync and /usr/bin/gluesync only when they are links into /opt/gluesync.

Who can run it

Run gluesync with sudo, as root, or as a user who can use Docker. Anyone else gets GS-CTL-007 and exit code 228, for example gluesync: this command needs root or access to Docker. Run it with sudo, or add your user to the docker group …. gluesync --help, gluesync --version, gluesync update --list, gluesync update --dry-run and gluesync self-update --check work for everyone.

Some things need more:

gluesync update needs write access to the compose file of the Gluesync folder (use sudo, or GS-UPD-017 tells you to);
gluesync self-update needs write access to the folder of the gluesync file (/usr/local/bin belongs to root);
gluesync self-update --enable-auto and --disable-auto need root.

With sudo, a user’s own environment is not kept. Set HTTPS_PROXY for the command, for example sudo HTTPS_PROXY=http://proxy:3128 gluesync update, or in the sudoers file.

The command line

gluesync                          in a terminal: the terminal screen; in a script: this help
gluesync tui                      the terminal screen, on purpose
gluesync run | start              start Gluesync
gluesync stop                     stop Gluesync
gluesync restart                  stop, then start
gluesync status [--json]          show what is running
gluesync open                     show the address of Gluesync
gluesync update [options]         update Gluesync
gluesync collect-logs [options]   collect a support bundle
gluesync self-update [options]    update Gluesync Control itself
gluesync --help | --version
         --folder <path>          the Gluesync folder, before or after the command

The commands wait until the work is done, write to the console and return the real exit code, so they work in scripts and in cron: gluesync status && echo up, or $?. Errors go to the error output as [ERROR] GS-CTL-003 CONTROL_START_FAILED: <message> followed by Fix: <what to try>. Press Ctrl+C to stop a running command: the exit code is 130.

Command What it does

Command	What it does
`gluesync run` `gluesync start`	Starts Gluesync with the same steps as the `run.sh` of earlier kits. It creates `.env` with the time zone of the server (`TZ`) when there is none, pulls the images on the first start only (a failed pull goes on with the local images), removes dangling images (`docker image prune -f`), and runs `docker compose up -d --remove-orphans`. Before the `up`, it waits for the platform to settle, as described for Windows in Update Gluesync. A stopped Docker daemon is started first when you are root and the server has systemd (for anyone else, `GS-CTL-002` says `sudo systemctl start docker`). It then waits up to 120 seconds for the services and prints `Gluesync is running: https://<address>;`.
`gluesync stop`	Runs `docker compose down --remove-orphans`. Containers and networks are removed. Volumes and images are never removed, so your data stays. If the Docker daemon is stopped, Gluesync is already stopped.
`gluesync restart`	`stop`, then `start`. A failed stop does not start Gluesync.
`gluesync status`	Shows the state (running, partly running, stopped, Docker not running, not installed), the installed version, the services running out of the expected ones, the address, the Docker daemon and the folder. Exit code `0` when Gluesync is running and `3` when it is not. `--json` prints the same information as one JSON object. The address is the IPv4 address of the interface of the default route.
`gluesync open`	Prints `Gluesync is at https://<address>;`, and opens it in the browser only when the session has a desktop (`DISPLAY` or `WAYLAND_DISPLAY`). Exit code `0` either way.
`gluesync update`	Updates Gluesync. See Update Gluesync.
`gluesync collect-logs`	Collects a support bundle. See Collect logs for support.
`gluesync self-update`	Updates Gluesync Control itself. See Automatic updates of Gluesync Control.

gluesync run
gluesync start

Starts Gluesync with the same steps as the run.sh of earlier kits. It creates .env with the time zone of the server (TZ) when there is none, pulls the images on the first start only (a failed pull goes on with the local images), removes dangling images (docker image prune -f), and runs docker compose up -d --remove-orphans. Before the up, it waits for the platform to settle, as described for Windows in Update Gluesync. A stopped Docker daemon is started first when you are root and the server has systemd (for anyone else, GS-CTL-002 says sudo systemctl start docker). It then waits up to 120 seconds for the services and prints Gluesync is running: https://<address>;.

gluesync stop

Runs docker compose down --remove-orphans. Containers and networks are removed. Volumes and images are never removed, so your data stays. If the Docker daemon is stopped, Gluesync is already stopped.

gluesync restart

stop, then start. A failed stop does not start Gluesync.

gluesync status

Shows the state (running, partly running, stopped, Docker not running, not installed), the installed version, the services running out of the expected ones, the address, the Docker daemon and the folder. Exit code 0 when Gluesync is running and 3 when it is not. --json prints the same information as one JSON object. The address is the IPv4 address of the interface of the default route.

gluesync open

Prints Gluesync is at https://<address>;, and opens it in the browser only when the session has a desktop (DISPLAY or WAYLAND_DISPLAY). Exit code 0 either way.

gluesync update

Updates Gluesync. See Update Gluesync.

gluesync collect-logs

Collects a support bundle. See Collect logs for support.

gluesync self-update

Updates Gluesync Control itself. See Automatic updates of Gluesync Control.

Old scripts and the new commands

Kits before installer 1.3.6 Now

Kits before installer 1.3.6	Now
`./run.sh`	`gluesync run` (the new `run.sh` only starts `gluesync run`)
`./stop.sh`	`gluesync stop`
`./update.sh`	`gluesync update`
`./collect-logs.sh`	`gluesync collect-logs`
(new)	`gluesync restart`, `gluesync status [--json]`, `gluesync self-update`, the terminal screen

./run.sh

gluesync run (the new run.sh only starts gluesync run)

./stop.sh

gluesync stop

./update.sh

gluesync update

./collect-logs.sh

gluesync collect-logs

(new)

gluesync restart, gluesync status [--json], gluesync self-update, the terminal screen

Update Gluesync

gluesync update --list [--channel ga|beta|alpha]
gluesync update --dry-run [--version <x.y.z.w>|latest] [--channel ga|beta|alpha] [--package <file>]
gluesync update [--version <x.y.z.w>|latest] [--channel ga|beta|alpha] [-y]
gluesync update --package <file> [-y]

The options are the ones of the Windows update: --list shows what you can update to and changes nothing, --dry-run shows the plan and stops, --version picks a version (the newest offered without it), --channel ga|beta|alpha sets the newest version you can reach (--beta and --alpha are short for the channel), --package updates from a file with no network access, and -y does not ask. Beta and alpha ask twice unless you add -y.

The online update offers the Core Hub versions that MOLO17 has released for Linux, newer than the installed one and up to the latest GA of the channel, whose Core Hub image exists on Docker Hub. It only upgrades. It follows the steps of the Windows update: checks, backup, new image tags, pull, restart, verification and, on failure or Ctrl+C, a rollback. On Linux:

The backup of docker-compose.yml and .env is in /var/lib/gluesync/backups/<date-time> as root, otherwise ~/.local/state/gluesync/backups (mode 700, the last five are kept).
Modules (the conductor and Chronos) move to their latest version with no suffix, and the third-party images (Traefik, Prometheus, Grafana and Portainer) to the version that MOLO17 publishes for each.
Old images stay on the disk. docker image prune removes the dangling ones.
The variant of Core Hub is the one that is installed: the plain tag (for example 2.3.0.1), or -debian. A CPU that lacks the x86-64-v3 instructions runs the -debian images, and the update keeps that rule: it switches a plain install on such a CPU to the -debian tag and says so (this CPU lacks x86-64-v3). An install that is already -debian stays -debian, and arm64 is never switched.

Core Hub migrates its database when it starts with a newer version, and that migration is one-way. A rollback restores the images and the configuration files, not the database. Take a configuration backup before you update a production system.

Offline update

For a server with no internet access, download the update package for the CPU of the server, gluesync-update-linux-amd64-<version>.tar.gz or gluesync-update-linux-arm64-<version>.tar.gz, from Get Gluesync – offline downloads on a connected computer, copy it to the server, and run:

sudo gluesync update --package /tmp/gluesync-update-linux-amd64-<version>.tar.gz

Gluesync Control reads the whole package once before it changes anything, loads the images one by one with docker load (nothing is unpacked to disk), then backs up, restarts and checks Gluesync like the online update. The free space is checked on the Docker data folder (twice the size of the package, at least 1 GB). The package is refused (GS-UPD-014, before anything changes) when it is a Windows package, is for the other CPU, or carries only Core Hub of another variant. An older or the same version is refused. An installed image that the package does not carry stays as it is.

Pins and updating one service

From 1.4.2, gluesync update can pin Core Hub or a service to a version, keep the pin until you remove it, and update one service only. It works as on Windows, and the options, the three confirmations of a Core Hub pin and the data backup of a downgrade are described in Pin versions and update one service. The differences on Linux:

The pins are in /var/lib/gluesync/pins.json as root, otherwise in ~/.local/state/gluesync/pins.json. A user who runs Docker without sudo also reads the pins that were made with sudo.
The data backup of a Core Hub downgrade goes to <state folder>/backups/<date-time>/core-hub-data/.
A tag is a version when it is <n.n[.n[.n]]>[.word], with no suffix (or the -debian family for Core Hub). latest, a beta, a test build and the tags of another family are not.
--services, --versions, --pins, --unpin and --dry-run need no access to Docker. --pin and --service change Gluesync and do.

sudo gluesync update --services
sudo gluesync update --pin core-hub=2.2.11.12 --i-understand-pinning --allow-downgrade
sudo gluesync update --service gluesync-chronos
sudo gluesync update --unpin all

Collect logs for support

gluesync collect-logs [--days N] [--max-mb N] [--tail N] [--out <dir>]
                      [--local-only] [--ticket X --email Y] [--delete-after-upload]

The options and what they do are the ones of Collect logs for support on Windows: --days (default 3), --max-mb (default 1024), --tail (default 50000), --local-only (--no-upload is the same), and --ticket with --email to upload the bundle to MOLO17 support. Both are needed: use the number of your ticket on the support portal and the e-mail address you opened it with. Without them the bundle stays on the server. On Linux:

The bundle, gluesync-support-<date-time>.zip, is written to /var/lib/gluesync/support as root, otherwise ~/.local/state/gluesync/support. --out <dir> writes it elsewhere (--out . writes it to the current folder). The path is printed at the end. The three newest bundles are kept in the default folder.
It collects the Gluesync log files and the installer logs of /var/log/gluesync and /var/lib/gluesync, the configuration files with secrets replaced by ***, a system snapshot (operating system, kernel, CPU, memory, disks, whether the CPU has the x86-64-v3 instructions, the proxy variables with the credentials hidden), the output of ss, ip, df, lsblk, getenforce, firewall-cmd, ufw and journalctl -u docker where those programs exist, Docker diagnostics (version, info, ps, images, docker inspect of every container with secrets hidden) and the log of every container. It also has the state of the self-update timer.
It runs at low priority (nice 10), and it never deletes or changes your files.
The upload goes over HTTPS, then over FTP. It uses the proxy from HTTPS_PROXY, HTTP_PROXY and NO_PROXY.

For example, to collect the last three days and send them with your ticket:

sudo gluesync collect-logs --ticket <ID> --email <you>

If you have no ticket yet, collect with --local-only and attach the file to a new ticket. If you can sign in to the Gluesync Control Plane, you can also send the logs from there. See Exporting and uploading logs to support.

Automatic updates of Gluesync Control

Gluesync Control can update itself. This is different from updating Gluesync: it replaces only the gluesync program. The Gluesync platform, its containers, its configuration and its data are not touched, Gluesync keeps running and nothing restarts.

gluesync self-update [--check] [--quiet] [-y] [--channel ga|beta] [--set-channel ga|beta]
gluesync self-update --enable-auto | --disable-auto

Option Meaning

Option	Meaning
`--check`	Prints the running version and the newest published version, and installs nothing. Exit code `0` when Gluesync Control is up to date and `4` when a newer version exists. It works for any user.
`-y`	Does not ask for confirmation.
`--quiet`	What the daily timer runs: no question and no output unless something fails.
`--enable-auto`	Root only. Sets up the daily check: a systemd timer, `gluesync-control-self-update.timer`, that runs `gluesync self-update --quiet -y` once a day after a random delay of up to 1 hour (`Persistent=true`, so a missed run happens at the next start). It writes the service and the timer in `/etc/systemd/system`.
`--disable-auto`	Root only. Stops and removes the timer and its two unit files.
`--channel ga\|beta`	The channel for this run. `ga` is the default. `beta` installs a pre-release build that MOLO17 publishes for testing, never for production.
`--set-channel ga\|beta`	Saves the channel in `control-settings.json` of the state folder. Use `sudo`, because the daily timer runs as root and reads the file of root.

--check

Prints the running version and the newest published version, and installs nothing. Exit code 0 when Gluesync Control is up to date and 4 when a newer version exists. It works for any user.

-y

Does not ask for confirmation.

--quiet

What the daily timer runs: no question and no output unless something fails.

--enable-auto

Root only. Sets up the daily check: a systemd timer, gluesync-control-self-update.timer, that runs gluesync self-update --quiet -y once a day after a random delay of up to 1 hour (Persistent=true, so a missed run happens at the next start). It writes the service and the timer in /etc/systemd/system.

--disable-auto

Root only. Stops and removes the timer and its two unit files.

--channel ga|beta

The channel for this run. ga is the default. beta installs a pre-release build that MOLO17 publishes for testing, never for production.

--set-channel ga|beta

Saves the channel in control-settings.json of the state folder. Use sudo, because the daily timer runs as root and reads the file of root.

When a newer version is published, Gluesync Control:

downloads the new gluesync file from MOLO17 over HTTPS (only HTTPS, also across redirects), into the folder of the program;
checks that its size is the size in the MOLO17 catalog, that its SHA-256 is the one in the catalog, and that it runs and reports the version that the catalog announced (--version);
makes it executable, keeps the old file as gluesync.old and replaces the program in one step.

A file that fails a check is deleted and nothing changes. gluesync.old is kept until the next self-update run, and then removed. Only a strictly newer version is installed, never the same one and never an older one. A server that cannot reach the update service, or that is in maintenance, tries again later. If MOLO17 has no update information for the CPU (the catalog has no entry), the command says so and exits with 0.

The result of the last run is in last-result.json of <state folder>/self-update and in self-update.log. If an update fails, the previous version stays and the next run tries again. The codes are in Gluesync Control on Linux.

Turn automatic updates off

Run sudo gluesync self-update --disable-auto, or switch off the daily update in Settings of the terminal screen.
Machine policy: create /etc/gluesync/policy.json with {"disableControlSelfUpdate": true}. It turns off the timer, and gluesync self-update stops with GS-SUP-001 (exit code 101).

A server without systemd has no timer: the installer says so and prints the line to put in cron, once a day:

sudo gluesync self-update --quiet -y

The terminal screen

Run gluesync with no arguments in an interactive terminal (or gluesync tui on purpose) to open a text screen with the same tabs as the Windows window: Overview, Update, Support and Settings. In a script, a pipe, cron or a systemd unit, gluesync with no arguments still prints the help, and gluesync tui stops with GS-CTL-006 (exit code 255). The screen needs a terminal of at least 80 columns by 24 rows. Below 60 by 16 it asks you to make the window larger.

Tab What it does

Tab	What it does
Overview	The state, the version, the address, Docker and the folder, with Start, Stop, Restart (both ask first, with No as the default) and Open. Beside it, or below it in a narrow terminal, the services table: a health dot, the image tag, the state and a pin marker. It is read again every 5 seconds.
Update	Two sub-tabs. Updates: check for updates and choose a version to see its plan, Update all (the plan, a confirmation, the progress and the result with the backup folder) and update from a package file. Advanced options: pin Core Hub (the versions, Other version…, then the same three confirmations as on Windows, each with No as the default), the services (choose one to pin, unpin or update it alone), and the pins (unpin one, or all). There is no `-y` in the screen: nothing skips a confirmation of a pin.
Support	Collect logs, kept on the server or uploaded with a ticket and an e-mail address, with the days and the size limit. The result shows the path of the bundle.
Settings	The version of Gluesync Control, the update channel, a check for an update with Update now, and the daily automatic update (the systemd timer, root only; without systemd it shows the line for cron).

Overview

The state, the version, the address, Docker and the folder, with Start, Stop, Restart (both ask first, with No as the default) and Open. Beside it, or below it in a narrow terminal, the services table: a health dot, the image tag, the state and a pin marker. It is read again every 5 seconds.

Update

Two sub-tabs. Updates: check for updates and choose a version to see its plan, Update all (the plan, a confirmation, the progress and the result with the backup folder) and update from a package file. Advanced options: pin Core Hub (the versions, Other version…, then the same three confirmations as on Windows, each with No as the default), the services (choose one to pin, unpin or update it alone), and the pins (unpin one, or all). There is no -y in the screen: nothing skips a confirmation of a pin.

Support

Collect logs, kept on the server or uploaded with a ticket and an e-mail address, with the days and the size limit. The result shows the path of the bundle.

Settings

The version of Gluesync Control, the update channel, a check for an update with Update now, and the daily automatic update (the systemd timer, root only; without systemd it shows the line for cron).

Press 1 to 4, or Tab, to change tab. Use ↑ and ↓ (or j and k) to move, Enter to choose, Esc to go back, r to read again, ? for help and q to quit. The footer always shows the keys of the screen. While something runs, the screen shows the steps, a progress bar and the output of the engine. Press Ctrl+C to stop it the way the command line stops: an update that already changed Gluesync restores the previous version first. The terminal is given back on every way out.

The screen adapts to the terminal. With true colour or 256 colours and a UTF-8 locale it uses a flat look. On a terminal with 16 colours, on the Linux console, with NO_COLOR set, or in a locale that is not UTF-8, it uses plain borders and ASCII characters. Set GLUESYNC_TUI_CLASSIC=1 to ask for the bordered look anywhere.

Without root or Docker access (GS-CTL-007), or with Podman, the screen is read-only: a banner says why, only what reads works (the update check, the services and pins tables, the check for a new Gluesync Control), and what would change the server is shown dimmed.

Exit codes

Gluesync Control returns the same codes as on Windows. A Linux exit status has one byte, so three of them are different.

Exit code Meaning

Exit code	Meaning
`0`	Done.
`3`	`gluesync status`: Gluesync is not running (stopped, partly running or Docker not running).
`4`	`gluesync self-update --check`: a newer Gluesync Control is published.
`101` to `117`	`gluesync self-update`: `GS-SUP-001` to `GS-SUP-017` (the code minus 200). On Windows they are `301` to `317`, which a Linux shell would show as 45 to 61.
`130`	Stopped with `Ctrl`+`C` (`1223` on Windows).
`201` to `227`, `229`	`gluesync update`: `GS-UPD-001` to `GS-UPD-027` and `GS-UPD-029`. See Update codes (GS-UPD). There is no `GS-UPD-228`.
`228`	`GS-CTL-007`: the command needs root or access to Docker (`740` on Windows).
`230` to `240`	`gluesync collect-logs`: `GS-LOG-001` to `GS-LOG-014`. Warnings `GS-LOG-101` to `GS-LOG-106` do not change the exit code.
`250` to `255`	`GS-CTL-001` to `GS-CTL-006`: no installation found, Docker not available, start failed, nothing running after the start, stop failed, wrong arguments.

0

Done.

3

gluesync status: Gluesync is not running (stopped, partly running or Docker not running).

4

gluesync self-update --check: a newer Gluesync Control is published.

101 to 117

gluesync self-update: GS-SUP-001 to GS-SUP-017 (the code minus 200). On Windows they are 301 to 317, which a Linux shell would show as 45 to 61.

130

Stopped with Ctrl+C (1223 on Windows).

201 to 227, 229

gluesync update: GS-UPD-001 to GS-UPD-027 and GS-UPD-029. See Update codes (GS-UPD). There is no GS-UPD-228.

228

GS-CTL-007: the command needs root or access to Docker (740 on Windows).

230 to 240

gluesync collect-logs: GS-LOG-001 to GS-LOG-014. Warnings GS-LOG-101 to GS-LOG-106 do not change the exit code.

250 to 255

GS-CTL-001 to GS-CTL-006: no installation found, Docker not available, start failed, nothing running after the start, stop failed, wrong arguments.

The text of an error keeps its GS- code, so the code in the message is the one to look up. Every code, its meaning and its fix are on Installer error codes and troubleshooting.