Skip to content

feat(aps): rework troubleshooting #4338

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Feb 5, 2025
Merged

feat(aps): rework troubleshooting #4338

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7d9a441
feat(aps): rework troubleshooting
bene2k1 Jan 31, 2025
4d4cdf5
feat(aps): troubleshooting
bene2k1 Feb 3, 2025
c2ab5aa
Apply suggestions from code review
bene2k1 Feb 3, 2025
2bef2e4
Update pages/apple-silicon/troubleshooting/cant-connect-using-ssh.mdx
bene2k1 Feb 3, 2025
9ce1c82
Apply suggestions from code review
bene2k1 Feb 3, 2025
7ace687
Apply suggestions from code review
bene2k1 Feb 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions menu/navigation.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -931,20 +931,32 @@
{
"items": [
{
"label": "Filevault is preventing system boot",
"label": "Troubleshooting issues related to FileVault preventing system boot",
"slug": "filevault-preventing-system-boot"
},
{
"label": "Troubleshooting inaccessibility issues to Mac minis",
"slug": "mac-mini-inacessible"
},
{
"label": "Troubleshooting Mac mini installation issues",
"slug": "mac-mini-installation-issues"
},
{
"label": "Troubleshooting remote desktop connections to Mac mini servers",
"slug": "cant-connect-using-vnc"
},
{
"label": "I can not connect to my Mac mini through a remote SSH connection",
"label": "Troubleshooting SSH connection issues to Mac mini servers",
"slug": "cant-connect-using-ssh"
},
{
"label": "I can not create a new Apple Account on my Mac mini",
"label": "Troubleshooting Apple account creation for hosted Mac minis",
"slug": "cant-create-apple-account"
},
{
"label": "Troubleshooting deletion issues with Mac minis",
"slug": "cant-delete-mac-mini"
}
],
"label": "Troubleshooting",
Expand Down
63 changes: 44 additions & 19 deletions pages/apple-silicon/troubleshooting/cant-connect-using-ssh.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,63 @@
---
meta:
title: Resolving SSH connection issues to Scaleway Mac mini
title: Troubleshooting SSH connection issues to Scaleway Mac mini servers
description: Learn how to fix SSH connection problems with Scaleway Apple silicon Mac mini by uploading your SSH key and rebooting the device.
content:
h1: Resolving SSH connection issues to Scaleway Mac mini
h1: Troubleshooting SSH connection issues to Scaleway Mac mini servers
paragraph: Learn how to fix SSH connection problems with Scaleway Apple silicon Mac mini by uploading your SSH key and rebooting the device.
tags: ssh ssh-key connection
dates:
validation: 2024-12-19
validation: 2025-01-30
posted: 2024-06-12
categories:
- bare-metal
---

This documentation addresses an issue faced by users who are unable to connect to their Mac Mini via SSH.
This problem typically arises because the user's SSH key has not been uploaded to the Mac Mini.
It can also happen after multiple authentication failures while trying to access the VNC server because of default fail2ban security policies.
This guide provides the necessary steps to resolve this issue by connecting to the Scaleway console and rebooting the Mac Mini from the Apple silicon section.

<Message type="note">
The reboot **must** be carried out via the console, and not via any other method, in order to resolve the problem.
</Message>

<Macro id="requirements" />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- An [SSH key](/organizations-and-projects/how-to/create-ssh-key/)
- A [Mac mini](/apple-silicon/how-to/create-mac-mini/)

1. Click **Apple silicon** in the **Bare Metal** section of the side menu. A list of your Mac minis displays.
2. Click the Mac mini you want to configure. Your Mac mini information page displays.
3. Scroll down to the **Reboot Mac mini** section. Click **Reboot** to reboot the Mac mini.
<Message type="tip">
Ensure you have [generated and uploaded your SSH key](/organizations-and-projects/how-to/create-ssh-key/) before rebooting your Mac mini.
## Problem
You are unable to connect to your Scaleway Mac mini via SSH.

### Symptoms
- SSH connection attempts fail.
- "Permission denied" or "Connection refused" errors appear.
- Timeouts occur when trying to establish an SSH connection.

### Possible causes
- The SSH key was not uploaded during the Mac mini setup.
- Your IP has been blacklisted due to multiple failed authentication attempts.
- The Mac mini requires a reboot to apply SSH key changes.

### Solution

#### Verify your SSH key
Ensure your SSH key is correctly configured before attempting to connect:
- Follow the instructions to [generate and upload an SSH key](/organizations-and-projects/how-to/create-ssh-key/).

#### Check for connection blacklisting
Repeated failed login attempts can trigger Scaleway’s security mechanisms, blocking your connection. To resolve this:
- [Reboot](/apple-silicon/how-to/reboot-mac-mini/) your Mac mini to reset the `fail2ban` security measures.
A reboot ensures your SSH key is applied correctly and clears blacklisted IPs.
1. Log in to the [Scaleway console](https://console.scaleway.com).
2. Click **Apple Silicon** in the **Bare Metal** section of the side menu.
3. Select your Mac mini from the list.
4. Scroll down to the **Reboot Mac mini** section and click **Reboot**.
5. Confirm the reboot.

<Message type="note">
The reboot **must** be carried out via the Scaleway console, and not via any other method, in order to resolve the problem.
</Message>
4. Click **Reboot Mac mini** to confirm. The Mac mini reboots and your SSH key will be uploaded during the boot process. Banned host lists are reset as well.

#### Attempt SSH connection again
After the reboot, attempt to reconnect using:
```sh
ssh -i /path/to/your/private_key user@<server_ip>
```
Replace `/path/to/your/private_key` with your actual private key location and `<server_ip>` with your Mac mini’s IP address.

## Further troubleshooting
If the issue persists, contact [Scaleway's support](https://console.scaleway.com/support) for further troubleshooting.
193 changes: 73 additions & 120 deletions pages/apple-silicon/troubleshooting/cant-connect-using-vnc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,158 +1,111 @@
---
meta:
title: Troubleshooting remote desktop connections to Mac mini servers
description: This page suggests solutions for when you cannot establish a remote desktop connection to your Mac mini
description: This page provides solutions for when you cannot establish a remote desktop connection to your Mac mini.
content:
h1: Troubleshooting remote desktop connections to Mac mini servers
paragraph: This page suggests solutions for when you cannot establish a remote desktop connection to your Mac mini
paragraph: This page provides solutions for when you cannot establish a remote desktop connection to your Mac mini.
tags: remote vnc connection apple-silicon error
dates:
validation: 2024-12-19
validation: 2025-01-30
posted: 2023-04-07
categories:
- bare-metal
---

This documentation provides a structured approach to diagnose and resolve issues when you cannot establish a remote desktop connection to your Mac mini.

<Macro id="requirements" />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- An [SSH key](/organizations-and-projects/how-to/create-ssh-key/)
- A [Mac mini](/apple-silicon/how-to/create-mac-mini/)

## 1. Verify the server status
## Problem
You are unable to establish a remote desktop (VNC) connection to your Scaleway Mac mini.

### Symptoms
- VNC client fails to connect to the Mac mini.
- Authentication errors occur during connection attempts.
- Connection times out or is refused.
- Mac mini appears unreachable.

### Possible causes
- The Mac mini is powered off or unresponsive.
- The VNC port assigned during system setup is incorrect.
- The SSH server is unresponsive.
- Your connection is blacklisted due to failed attempts.
- Incorrect credentials are being used.
- Remote connection client compatibility issues.

### Solution

Execute the following `ping` command in a terminal on your local machine:
#### Verify the server status
Run the following command in a terminal:
```sh
ping -c 5 <server_ip>
```
Expected output:
```
PING X.X.X.X (X.X.X.X): 56 data bytes
64 bytes from X.X.X.X: icmp_seq=0 ttl=64 time=0.182 ms
64 bytes from X.X.X.X: icmp_seq=1 ttl=64 time=0.261 ms
64 bytes from X.X.X.X: icmp_seq=2 ttl=64 time=0.191 ms
64 bytes from X.X.X.X: icmp_seq=3 ttl=64 time=0.200 ms
64 bytes from X.X.X.X: icmp_seq=4 ttl=64 time=0.201 ms
--- X.X.X.X ping statistics ---
5 packets transmitted, 5 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 0.182/0.207/0.261/0.028 ms
```
- If `ping` fails, try [rebooting the server](/apple-silicon/how-to/reboot-mac-mini/).
- If rebooting fails or if the server was forced to shut down, wait 24 hours for automatic restart. See [How to shutdown a Mac mini](/apple-silicon/how-to/shutdown-mac-mini/) for more information.

## 2. Verify the VNC connection

<Message type="important">
The VNC port on Mac mini systems is **randomly assigned** during system installation and may therefore be different from the default VNC port 5900. To connect successfully via VNC, use the specific port shown in the **Overview** section of your Mac mini’s configuration.
For manual connections, ensure that the port from the **Overview** section is correctly entered in your VNC client settings, as this is necessary for a successful connection.
</Message>
If `ping` fails:
- Try [rebooting the server](/apple-silicon/how-to/reboot-mac-mini/).
- If the server was forced to shut down, wait 24 hours for automatic restart.

Execute the following command in a terminal on your local machine:
#### Verify the VNC connection
Run the following command:
```sh
nc -zv <server_ip> <vnc_port>
```
Expected output:
```
Connection to <server_ip> port <vnc_port> [tcp/rfb] succeeded!
```
- If the connection fails, try [rebooting the server](/apple-silicon/how-to/reboot-mac-mini/).
- If necessary, restart screen sharing via SSH. See [Restarting screen sharing via SSH](#restarting-screen-sharing-via-ssh).
If the connection fails:
- Verify the correct VNC port in the **Overview** section of your Scaleway console.
- [Reboot the server](/apple-silicon/how-to/reboot-mac-mini/).
- Restart screen sharing via SSH (see below).

## 3. Verify the SSH server response
Execute the following command:
#### Verify the SSH server response
Run the command:
```sh
nc -zv <server_ip> 22
```
Expected output:
```
Connection to <server_ip> port 22 [tcp/ssh] succeeded!
```
- If the connection fails, try [rebooting the server](/apple-silicon/how-to/reboot-mac-mini/).

## 4. Check for connection blacklisting
If VNC connection attempts repeatedly fail, the connection might be blacklisted, or the Apple screen sharing service might be unresponsive.

- [Reboot the server](/apple-silicon/how-to/reboot-mac-mini/) to clear the `fail2ban` table.

## 5. Verify your connection credentials
If the connection fails, [reboot the server](/apple-silicon/how-to/reboot-mac-mini/).

### Remote desktop (VNC) credentials
- Ensure the correct username and password are used. These can be verified in the console.
- For errors like "Authentication failed," verify credentials and retry.
#### Check for connection blacklisting
If VNC connection attempts fail repeatedly, your connection may be blacklisted. [Rebooting](/apple-silicon/how-to/reboot-mac-mini/) clears the `fail2ban` table.

### SSH keys
- Ensure the SSH key is correctly formatted and configured before installing the Mac.
- SSH keys provided post-installation are not considered.
#### Verify your connection credentials
- VNC: Ensure correct username and password.
- SSH: Ensure your SSH key was provided before installation.

## 6. Verify remote connection client compatibility
Ensure your remote connection client is compatible with macOS. Incompatible remote desktop (VNC) clients can cause failed connection attempts. For recommended VNC clients, see [How to access to the remote desktop of a Mac mini](/apple-silicon/how-to/access-remote-desktop-mac-mini/#comparison-matrix-of-remote-desktop-clients).

## 7. Reinstall the Mac mini

If the previous attempts to resolve connection issues to your Mac mini have been unsuccessful, you may need to reinstall your server from the Scaleway console.

Follow these steps to reinstall macOS on your Mac mini:

1. Log in to your Scaleway console.
2. Navigate to your Mac mini server.
3. Select the option to reinstall a version of macOS.

For detailed instructions, refer to [How to reinstall a Mac mini](/apple-silicon/how-to/reinstall-mac-mini/).
#### Verify remote access client compatibility
Use a compatible VNC client. See [this guide](/apple-silicon/how-to/access-remote-desktop-mac-mini/#comparison-matrix-of-remote-desktop-clients) for recommendations.

#### Reinstall the Mac mini
If all else fails, [reinstall macOS](/apple-silicon/how-to/reinstall-mac-mini/) via the Scaleway console.
<Message type="important">
Reinstalling your Mac mini will erase all data on the disk and reset all configurations to default settings. Ensure you have a backup of your data before proceeding.
Reinstalling your Mac mini will delete all data on it's disk. Ensure you have a backup of your data before launching any reinstallation.
</Message>

## Security and configuration

### Enable and configure pf (Packet Filter)
To restrict macOS Screen Sharing to specific IPs:
1. Connect to your Mac mini via SSH:
```sh
ssh@<your_mac_mini_ip>
```
2. Backup the `pf.conf` file:
```sh
sudo cp /etc/pf.conf /etc/pf.conf.backup
```
3. Edit the `pf.conf` file:
```sh
sudo nano /etc/pf.conf
```
4. Add rules to restrict access:
```sh
## Add these lines to block connections to port 5900 except from your static IP
block in on en0 proto tcp from any to any port 5900
pass in on en0 proto tcp from <static IP> to any port 5900
```
Replace `en0` with your network interface and `<static IP>` with the allowed IP address.
5. Save and close the file.
6. Apply the new configuration:
```sh
sudo pfctl -f /etc/pf.conf
```
7. Test the screen sharing connection from the allowed IP and verify it is blocked from other IPs.

<Message type="tip">
For advanced configuration and further information consult our [fail2ban tutorial](/tutorials/protect-server-fail2ban/).
</Message>
## Advanced configuration and security

### Enabling and configuring Packet Filter (pf)
To restrict access to Screen Sharing:
```sh
sudo nano /etc/pf.conf
```
Add:
```sh
block in on en0 proto tcp from any to any port 5900
pass in on en0 proto tcp from <static IP> to any port 5900
```
Apply:
```sh
sudo pfctl -f /etc/pf.conf
```

### Restarting screen sharing via SSH
If screen sharing is unresponsive, restart it via SSH:
1. Connect to your Mac mini via SSH:
```sh
ssh your_mac_mini_username@<your_mac_mini_ip>
```
- Replace `<your_mac_mini_username>` with your Mac mini username.
- Replace `<your_mac_mini_ip>` with the actual IP address of your Mac mini.
2. Restart the screen sharing daemon:
```sh
sudo killall screensharingd
```
The service will restart automatically upon the next connection attempt.

## Troubleshooting and support
For further assistance, visit our #apple-silicon channel in the [Slack Community](https://slack.scaleway.com/).
1. Connect via SSH:
```sh
ssh your_mac_mini_username@<your_mac_mini_ip>
```
2. Restart screen sharing:
```sh
sudo killall screensharingd
```

## Further troubleshooting
If the issue persists, contact [Scaleway's support](https://console.scaleway.com/support) for further troubleshooting.
Loading