Cannot restart SSH after adding host entry in sshd_config

Restarting SSH after modifying sshd_config typically fails due to syntax errors or invalid directives introduced during editing. The most effective solution is to validate the configuration file using sshd -t before restarting the service, which identifies specific line numbers and error types allowing for precise corrections.

Understanding the Restart Failure

When you edit the /etc/ssh/sshd_config file, even a single misplaced character, an unknown directive, or an incorrect value can prevent the SSH daemon from starting. Unlike many other services that might ignore bad settings with a warning, OpenSSH is strict. If the configuration parser encounters an issue, it aborts the startup process entirely to maintain security integrity. This results in the service failing to restart, often leaving you without remote access if you are connected via SSH. The error messages provided by the system are usually verbose enough to pinpoint the exact cause, but they require careful reading. Common issues include typos in directive names, such as writing PubkeyAuthenticaton instead of PubkeyAuthentication, or using values outside the accepted range for boolean or integer parameters. Additionally, adding host-specific entries incorrectly can disrupt the global parsing logic. It is crucial to understand that the order of directives matters less than their validity, but certain files like authorized_keys must exist and have correct permissions for key-based authentication to function after a restart.

Validating Configuration Syntax

Before attempting to restart the service again, you must verify that the new configuration is syntactically correct. The standard method for this is using the built-in test mode of the SSH daemon. Run the following command in your terminal:

sudo sshd -t

This command does not start the service; it only parses the configuration files and checks for errors. If the configuration is valid, the command returns silently with no output. If there is an error, it will print a message indicating the file name, line number, and a description of the problem. For example, you might see an output like:

/etc/ssh/sshd_config line 45: Unsupported option "BadDirective"

This output tells you exactly where to look. You should open the configuration file in a text editor, navigate to line 45, and correct the directive. Once corrected, run sshd -t again until it produces no output. This step is essential because it prevents the service from entering a broken state repeatedly.

Common Host Entry Errors

The title mentions adding a "host entry," which often refers to configuring host-specific blocks within the SSH client configuration rather than the server configuration. However, users sometimes confuse ssh_config (client) with sshd_config (server). If you added a block intended for the client into the server configuration, it will fail because the server does not recognize client-side directives like Host or IdentityFile. If you are indeed trying to configure the SSH server, ensure that you are not mixing up global settings with host-specific overrides. In sshd_config, you cannot use the Host keyword to create conditional blocks for different clients in the same way you do in the client config. Instead, you use Match blocks. A common mistake is placing a Match block at the top of the file before any global settings, which can cause unexpected behavior or parsing errors depending on the OpenSSH version. For host-specific server configurations, use the Match directive correctly. For example:

Match User admin
    PermitRootLogin yes
    PasswordAuthentication no

Ensure that the Match block is placed after all global settings. If you place it before, some older versions of OpenSSH may ignore subsequent global settings or fail to parse the file correctly. Always validate these changes with sshd -t to ensure the match conditions are valid.

Checking File Permissions

Another reason for restart failure, though less common with syntax errors, is incorrect file permissions. The sshd_config file itself must be owned by root and have restrictive permissions. If you accidentally changed the ownership or permissions while editing, the daemon may refuse to load the configuration for security reasons. Check the permissions using:

ls -l /etc/ssh/sshd_config

The file should typically show permissions like -rw-r--r-- and be owned by root:root. If the permissions are too open (e.g., writable by group or others), SSH may reject the configuration. Correct the permissions using:

sudo chmod 644 /etc/ssh/sshd_config
sudo chown root:root /etc/ssh/sshd_config

After correcting permissions, test the configuration again with sshd -t and then attempt to restart the service.

Restarting the Service Safely

Once sshd -t confirms the configuration is valid, you can safely restart the SSH service. Use the appropriate command for your Linux distribution. On systemd-based systems like Ubuntu, Debian, or CentOS, use:

sudo systemctl restart sshd

On older SysVinit systems, you might use:

sudo service ssh restart

If the restart fails despite passing the syntax check, check the system logs for more detailed error messages. On systemd systems, view the recent logs with:

journalctl -xeu sshd.service

This log output can reveal issues related to port conflicts, SELinux restrictions, or missing certificates that are not caught by the basic syntax check. If you are unable to reconnect via SSH after a failed restart, ensure you have physical access or a console session available to revert changes if necessary. Always keep a backup of the original sshd_config file before making significant changes.

Frequently Asked Questions

What if sshd -t shows no errors but the service still won't start?

If the syntax check passes but the service fails to start, the issue is likely environmental rather than configurational. Check the system logs using journalctl to identify permission denied errors, port binding failures, or SELinux denials. Ensure that the SSH port is not already in use by another process and that firewall rules allow incoming connections on the specified port.

Can I recover SSH access if I lock myself out?

If you cannot connect via SSH due to a misconfiguration, you must use alternative access methods such as a cloud provider's console, physical keyboard and monitor, or IPMI/iLO interfaces. Once accessed, you can temporarily rename the sshd_config file or restore it from a backup to regain service. Always test configurations in a staging environment or with a secondary connection before applying changes to production servers.

Why does my Match block not apply to specific users?

Match blocks in sshd_config must be placed at the end of the file, after all global settings. If placed earlier, they may not be processed correctly or may override global settings unexpectedly. Ensure the criteria in the Match block, such as User or Address, are spelled correctly and match the actual user or IP connecting to the server.

How do I disable password authentication securely?

To disable password authentication, set PasswordAuthentication no in sshd_config. Ensure that you have configured key-based authentication and tested it successfully before disabling passwords. Also, consider setting PermitEmptyPasswords no and restricting root login to key-based access only to enhance security.

Is it safe to edit sshd_config while connected via SSH?

It is generally safe if you follow best practices, such as validating the configuration with sshd -t before restarting the service. However, always have an alternative means of accessing the server, such as a console session, in case the restart fails and locks you out. Avoid making multiple changes at once so you can isolate the problematic setting if issues arise.