Ports used by xySat

[rfx77]

Whe i install xySat via the generated curl link, the link always goes to port 5522:

curl -s "http://xyops.test.local:5522/api/app/satellite/install?t=fc42627f8b35221cfbc55494684c792cdfe78ec024399eacb7b2f5397d8949cd" | sudo sh

this is fine. i opend ports 5522 on my firewall so that all xysat servers can communicate with xyops.

the problem is, that during install also the BASE_URL is required. This is on Port 80 in my setup.

For security reasons it would be better if the xySat only needs 5522 so that the webinterface can be split from the xySat WS communication.
Can i configure the now or is it required that the Webport is open during this install.

[jhuckaby]

Hi @rfx77, thanks for the question. This is an understandable point of confusion because there are a few different URLs involved, and they have similar names.

The short answer is: your xySat servers do not need access to port 80 if they can reach the conductor directly on port 5522. The generated command using http://xyops.test.local:5522 is correct for the setup you described.

However, there is one important detail about the ports: 5522 is not a dedicated xySat WebSocket port. It is xyOps' built-in HTTP listener, and that same listener handles all of the following:

• The web interface
• The HTTP API
• The xySat installer and package downloads
• WebSocket upgrades from xySat, browsers, and other conductors

In other words, ordinary HTTP and ws:// WebSocket traffic share port 5522. Similarly, when TLS is configured, HTTPS and wss:// WebSocket traffic can share the secure listener, which is normally port 5523.

The different URLs

There are three related concepts here:

Setting or value	Purpose	Example in your setup
base_app_url	The URL that people use to open xyOps. It is also used when xyOps creates clickable links in emails, tickets, alerts, and web hooks.	http://xyops.test.local on port 80
Installer BASE_URL	An internal bootstrap variable containing the conductor endpoint from which the installer downloads xySat, tests connectivity, and fetches its generated configuration.	http://xyops.test.local:5522
xySat connection address	The conductor hostname, port, and protocol used for the persistent WebSocket after xySat starts.	xyops.test.local, port 5522, non-secure

The key point is that base_app_url and the installer's BASE_URL are not the same setting and do not need to use the same port. Your human-facing base_app_url may remain on port 80 while xySat installs and operates through port 5522.

BASE_URL is an internal variable used by the xySat bootstrap process. It is not normally something you should set or edit yourself. xyOps pre-populates it automatically in the downloaded installer, using the hostname, protocol, and port from the initial bootstrap request, meaning the URL containing the temporary t= token. If that initial request is made directly to http://xyops.test.local:5522, the generated installer should receive BASE_URL="http://xyops.test.local:5522" automatically.

How xyOps chooses the conductor hostname

By default, xyOps uses the hostname of the conductor server as the hostname that xySat will use to connect back to it. If the conductor is running in Docker, this means the hostname of the container.

It is therefore important that the conductor hostname is stable, resolves correctly from every worker server, and points to an address those workers can reach. For Docker, you can explicitly set this using the --hostname option or the Compose hostname property. Outside of Docker, or when you need to override the detected hostname, you can set the XYOPS_hostname environment variable.

For example, you can set the container hostname directly with Docker:

docker run \
	--hostname "xyops.test.local" \
	...

Alternatively, you can override the hostname detected by xyOps using the environment:

XYOPS_hostname="xyops.test.local"

Normally you would only need one of these hostname mechanisms. The important result is that xyOps identifies itself using a hostname that all xySat workers can resolve and reach.

There is one explicit override to this behavior: if you set a top-level host property inside the conductor's satellite.config object, that value overrides the normal conductor hostname selection for xySat. This is useful when workers must connect through a dedicated worker-facing hostname, reverse proxy, or other special network route. Because this conductor-side setting is distributed to all workers, it should only be used when you want all of them to use that static host.

What happens during installation

When you run this command:

curl -s "http://xyops.test.local:5522/api/app/satellite/install?t=TOKEN" | sudo sh

the process is approximately:

1. The worker connects to the conductor on port 5522 and downloads a small shell installer.
2. The conductor automatically puts the hostname, protocol, and port used for that request into the script as the internal BASE_URL variable. In this case it should be http://xyops.test.local:5522.
3. The installer uses that same URL to call the conductor's ping endpoint.
4. It downloads the correct xySat package for the worker's operating system and CPU architecture.
5. It downloads a generated config.json, containing the worker's server ID, authentication token, conductor hostname, port, and protocol.
6. It installs and starts xySat as a system service.
7. xySat initiates an outbound persistent WebSocket connection to the conductor on port 5522.

So the HTTP requests during installation are expected. Port 5522 carries both the short-lived HTTP bootstrap requests and the long-lived WebSocket connection.

The conductor does not need to initiate a new inbound connection to the worker. From a firewall perspective, the important rule is worker-to-conductor TCP access on the configured xyOps port. DNS for xyops.test.local must also resolve to an address reachable from every worker.

What I would use for your setup

Based on your description, I would configure it like this:

• Administrators and browsers use http://xyops.test.local through your port 80 front end.
• base_app_url remains http://xyops.test.local so links generated for users are correct.
• Worker servers connect directly to xyops.test.local:5522.
• The worker network is allowed outbound TCP access to the conductor on port 5522.
• The worker network does not need access to port 80 merely to install or run xySat.

If the generated install command already contains :5522, you should not need to change anything or set BASE_URL yourself. As a diagnostic, you can confirm what xyOps pre-populated in the generated script without executing it:

curl -fsSL "http://xyops.test.local:5522/api/app/satellite/install?t=NEW_TOKEN" | grep '^BASE_URL='

It should report:

BASE_URL="http://xyops.test.local:5522"

If it unexpectedly reports port 80, that generally means the install request is being routed through a proxy, or the proxy is rewriting the Host header. In that case, make sure the generated :5522 URL resolves directly to the conductor and is not being redirected through the port 80 virtual host.

About separating the web interface from xySat

There are two slightly different security goals here.

If your goal is simply that xySat should not need to connect to port 80, then yes, that is already supported. Use port 5522 for the generated installer and the ongoing xySat connection, as described above.

If your goal is that the worker network must be physically unable to request the web interface at all, while still using port 5522 for xySat, then a port-level firewall rule alone cannot provide that separation. The web interface, HTTP API, bootstrap endpoints, and WebSocket listener all share the same xyOps HTTP listener. A client that can reach port 5522 can technically make an HTTP request to / on that port, even if your users normally enter through port 80.

For stricter isolation, you would need a reverse proxy or other application-aware network control in front of the worker-facing endpoint. For example, you could have:

• xyops.test.local on port 80 for the human-facing interface
• xyops-workers.test.local on a separate internal listener for worker traffic

The worker-facing proxy would need to support WebSocket upgrades as well as the HTTP endpoints xySat uses for installation, configuration, upgrades, packages, and job-related file transfers. I would be careful about allowing only the initial three bootstrap URLs, because that can make the first install succeed while breaking later upgrades or job features.

If you introduce a special worker-facing hostname, you can set a top-level host inside the conductor's satellite.config object so all generated installer commands and worker configurations use it. As noted above, this overrides the conductor's normal hostname entirely for xySat. For a Docker deployment, the relevant overrides would look like this:

environment:
  XYOPS_satellite__config__host: xyops-workers.test.local
  XYOPS_satellite__config__port: "5522"
  XYOPS_satellite__config__secure: "false"

You only need this override if the workers should use a hostname different from the conductor's normal hostname. With your current direct xyops.test.local:5522 arrangement, it should not be necessary.

For an Internet-facing or otherwise untrusted network, I would also strongly recommend using TLS. In a direct setup that normally means secure: true, a reachable TLS listener such as port 5523, and a certificate trusted by the workers. A TLS-terminating reverse proxy can also provide a worker-facing https:// and wss:// endpoint on port 443.

You can find some additional background in the Satellite section of the Self-Hosting guide, especially Overriding the Connect URL, and in Adding Servers.

One final security note: the t= value included in your post is an authentication token for the satellite bootstrap process. The token generated by the Add Server dialog is temporary and expires after 24 hours, but it is best not to publish it. Please edit it out of the discussion and generate a fresh install command before continuing.

I hope this helps clarify some things. For the layout you described, port 80 can remain the human-facing entry point, while the xySat machines use port 5522 for both installation and their ongoing connection.

I am working on the documentation and trying to make it more clear. It has evolved over many versions, and is a bit confusing in its current state.

[rfx77]

Excerpt from docker-compose.yaml
`
environment:
XYOPS_xysat_local: "true"
XYOPS_masters: "xxxxxxx.test.local"
XYOPS_WebServer__port: "80"
XYOPS_base_app_url: "http://172.25.100.34"
XYOPS_satellite__config__host: "xxxxxxx.test.local"
XYOPS_satellite__config__port: "5522"
XYOPS_satellite__config__secure: "false"
ports:
- "80:80"
- "5522:80"
- "5523:5523"

`

So BASE_URL is always http://xxxxxxx.test.local in the script that i get with curl. even if the script comes from port 5522

This is what the add-server-dialog shows:

curl -s "http://xxxxxxx.test.local:5522/api/app/satellite/install?t=asasasasasddaff4b4458f058f73658c857df52effb02cec6a349845d30ea5acfb"

So why das the installer use port 80? If you calculate the base-url within the curl-request to the installen than it shoult be 5522.

As you can see below your grep command gives a url to port 80 and not 5522.

psrv34:/opt/docker/xyops # curl -fsSL "http://xxxxxxx.test.local:5522/api/app/satellite/install?t=3cf3817dddaff4b4458f058f73658c857df52effb02cec6a349845d30ea5acfb" | grep "^BASE_URL="
BASE_URL="http://xxxxxxx.test.local"

this is ma xySat.json:

No matter waht i try to do. BASE_URL in the downloaded script is always http port 80

it seems to be that

xyops/lib/api/satellite.js

Line 203 in c4152ed

fetch_satellite_install(args, callback) {

ignores the calculation of the base_url that

xyops/lib/api/satellite.js

Line 14 in c4152ed

api_get_satellite_token(args, callback) {

does

[jhuckaby]

Hi @rfx77,

You are correct, and thank you for digging into the source and providing such a clear reproduction. I also owe you a correction: my previous reply missed the external-to-internal Docker port translation in your Compose setup.

The Add Server dialog calculates its URL from satellite.config, so it correctly shows port 5522. However, the downloaded installer does not reuse that calculated endpoint. fetch_satellite_install() reconstructs BASE_URL using the web server's getSelfURL() helper.

Because xyOps is listening on port 80 inside your container, that helper replaces the incoming external port 5522 with the internal listener port 80. Therefore:

• The initial curl correctly reaches host port 5522.
• Docker forwards that request to container port 80.
• The returned script receives BASE_URL="http://xxxxxxx.test.local".
• Its subsequent requests incorrectly go to host port 80.

So yes, this is a real bug in xyOps. It is not caused by base_app_url, even though the resulting URL happens to look the same. The generated upgrade script uses the same logic and is affected as well.

Your xySat configuration using port 5522 is correct. The problem is specifically the bootstrap and upgrade script URL generation.

Until I can get a fix out, one possible workaround is to keep the conductor's internal listener on 5522 and publish that same container port twice:

environment:
  XYOPS_WebServer__port: "5522"

ports:
  - "80:5522"
  - "5522:5522"
  - "5523:5523"

This keeps the human-facing endpoint on host port 80, while workers use host port 5522. Because the internal listener is also 5522, the generated installer will retain the correct port.

Not sure if this will work for your exact case, but I just wanted to give you something to try while I work on a fix. It should be out later this week.

One clarification from my earlier reply still applies: port 5522 is not a dedicated xySat-only listener. It exposes the same xyOps web interface, API, downloads, and WebSocket endpoints as port 80 in this arrangement.

I will correct the installer and upgrade paths so they consistently use the configured worker-facing endpoint, and add regression coverage for Docker port translation.

Thanks again for the excellent investigation and the precise line references. You found it.

[rfx77]

Thanks for the quick investigation. Currently i dont have a real issue and i can live with it.

[jhuckaby]

Fixed in v1.0.87.