How to Change the SSH Port on Flatcar Container Linux
Change the SSH port on Flatcar Container Linux with an sshd.socket drop-in, on running machines and in Butane configs. Fedora CoreOS has no documented method.
This guide moves the SSH service to a different TCP port on Flatcar Container Linux, the maintained fork of CoreOS Container Linux. Flatcar is an immutable, image-based system, so the usual advice (edit /etc/ssh/sshd_config, restart the service) does not apply as written: the port belongs to a systemd socket unit. The sections below show how to change it at provisioning time with a Butane config and on a machine that is already running.
The original CoreOS Container Linux reached end of life on 26 May 2020 and no longer receives security updates. Flatcar keeps the same layout and the core user. If you run an ordinary distribution such as Ubuntu, Debian or AlmaLinux, the procedure is different and simpler than what follows.
Fedora CoreOS, the successor from the Fedora project, is not covered. Its documentation contains no procedure for changing the SSH port; a request for one has been open in the project's issue tracker since 2020. Because there is no officially documented method, this guide covers Flatcar only.
Before you start
- Make sure you can reach the machine through your provider's web console. A mistake in the SSH configuration cannot be fixed over SSH.
- Pick a port above 1024 that nothing else uses. The examples use
2222. - If a cloud firewall or security group sits in front of the server, or you have added packet filter rules on the host, allow the new port there before you switch.
- Keep your current SSH session open the whole time. Test every change with a second, new connection, and close the first session only after the new port has let you in.
Changing the port does not make SSH more secure by itself. It removes most automated scanner noise from the logs; key-only authentication, which Flatcar uses by default, is what protects the service.
Change the port on Flatcar
Flatcar runs OpenSSH through systemd socket activation. The unit sshd.socket listens on port 22 and starts one sshd process per incoming connection, so a Port line in sshd_config has no effect. The unit file lives in /usr/lib/systemd/system/sshd.socket, which is on the read-only /usr partition and is replaced with every OS update. Do not try to edit it. Override it with a drop-in under /etc instead.
On a running machine
Create the drop-in directory and file:
sudo mkdir -p /etc/systemd/system/sshd.socket.d
sudo vi /etc/systemd/system/sshd.socket.d/10-sshd-listen-ports.confAdd these lines:
[Socket]
ListenStream=
ListenStream=2222ListenStream is a list: every line adds a socket. The empty assignment clears the list first; without it the machine would listen on port 22 and on 2222.
Reload systemd and restart the socket. Existing sessions stay connected.
sudo systemctl daemon-reload
sudo systemctl restart sshd.socketConfirm the listening address:
systemctl status sshd.socketThe Listen: line should show [::]:2222 (Stream). From your workstation, open a second session:
ssh -p 2222 core@203.0.113.10If you want a fallback while you test, add ListenStream=22 as a third line so that both ports answer, and remove it once the new port works.
To bind SSH to one address as well, write the address and port together and add FreeBind=true, so the socket can be created before the address is configured at boot:
[Socket]
ListenStream=
ListenStream=203.0.113.10:2222
FreeBind=trueAt provisioning time with Butane
Butane configs are applied by Ignition on the first boot only. To build new machines that listen on the new port from the start, add the same drop-in to the config:
variant: flatcar
version: 1.0.0
systemd:
units:
- name: sshd.socket
dropins:
- name: 10-sshd-port.conf
contents: |
[Socket]
ListenStream=
ListenStream=2222Convert it to Ignition JSON and pass the result as user data when you create the server:
butane --strict config.bu > config.ignWithout socket activation
If you prefer a permanently running daemon, which keeps accepting connections even when systemd is in trouble, mask the socket and start the service:
sudo systemctl mask --now sshd.socket
sudo systemctl restart sshd.serviceThe Butane form of this change, shown in the Flatcar documentation, also enables sshd.service. On a running machine do the same, so that the daemon starts at the next boot now that the socket is masked, and reboot once while you still have console access to confirm it:
sudo systemctl enable sshd.serviceIn this mode the port comes from the Port directive in /etc/ssh/sshd_config. On Flatcar that file is a symlink to a read-only file in /usr; replace the link with a regular copy before editing it:
sudo sed -i '' /etc/ssh/sshd_configIn a Butane config, the equivalent is to enable sshd.service, set mask: true on sshd.socket, and write your own /etc/ssh/sshd_config under storage.files with overwrite: true.
Disable root login (optional)
Flatcar expects you to log in as core with an SSH key and use sudo. To refuse root logins explicitly, replace the sshd_config symlink with a regular file as shown above and add PermitRootLogin no to it. With socket activation there is nothing to restart: the next connection starts a fresh sshd that reads the new file.
Troubleshooting
- Connection refused on the new port: run
systemctl status sshd.socketand check theListen:line. If it still shows port 22, the drop-in is in the wrong directory or you skippeddaemon-reload. - Both ports answer: the empty
ListenStream=line is missing from the drop-in. - Timeout: a cloud firewall or security group is still blocking the new port.
The upstream reference is the Flatcar guide to customizing the SSH daemon.
Frequently asked questions
Will an OS update undo the change?
No. Updates replace the /usr partition; files you created under /etc are kept. That is also why the stock unit file in /usr/lib/systemd/system must not be edited: it is read-only, and it is replaced with every OS update.
Can I apply a changed Butane config to an existing machine?
No. Ignition runs once, on the first boot. For machines that already exist, make the change by hand as shown, or with your configuration management tool, and keep the Butane config in step so that replacement machines come up the same way.
Can I listen on port 22 and the new port during a migration?
Yes. List both ports as separate ListenStream= lines after the empty one. Remove port 22 once every client and script uses the new port.