Scenario Executions

Possible usage steps within this page

Here are common ways you might use this page to achieve your goals:

Scenario 1: Successfully connecting to a forwarded port on Mac/Linux

You want to connect a local application on your Mac or Linux machine to a service running on the remote device through port forwarding.

1. Open the "Client connection to the web-to-local port" page.
2. Ensure "Mac / Linux" is selected under "Select your operating system:". If not, click on "Mac / Linux".
3. Click the "Download File" button in "Step 1: Download Client".
4. Open your Terminal application on your Mac/Linux machine.
5. Navigate to your Downloads folder using the cd command (e.g., cd ~/Downloads).
6. Copy and paste the first command from "Step 2: Run Installation" (e.g., chmod +x [YOUR_PREFIX]_client_[PORT].sh) into your Terminal and press Enter. This makes the downloaded script executable.
7. Copy and paste the second command from "Step 2: Run Installation" (e.g., ./[YOUR_PREFIX]_client_[PORT].sh) into your Terminal and press Enter. This will run the client script and establish the secure tunnel.
8. Copy the "Connection Address" (e.g., 127.0.0.1:XXXX) from "Step 3: Configure Connection".
9. Open your local application (e.g., a database client, a web browser for a local server) and configure it to connect to the copied "Connection Address".
10. Your application should now successfully connect to the remote service.

Scenario 2: Successfully connecting to a forwarded port on Windows

You want to connect a local application on your Windows machine to a service running on the remote device through port forwarding.

1. Open the "Client connection to the web-to-local port" page.
2. Select "Windows" under "Select your operating system:".
3. Click the "Download File" button in "Step 1: Download Client".
4. Open your Command Prompt application on your Windows machine. You can find this by searching "cmd" in the Start Menu.
5. Navigate to your Downloads folder using the cd command (e.g., cd C:\Users\YourUsername\Downloads).
6. Copy and paste the command from "Step 2: Run Installation" (e.g., [YOUR_PREFIX]_client_[PORT].bat) into your Command Prompt and press Enter. This will run the client script and establish the secure tunnel.
7. Copy the "Connection Address" (e.g., 127.0.0.1:XXXX) from "Step 3: Configure Connection".
8. Open your local application and configure it to connect to the copied "Connection Address".
9. Your application should now successfully connect to the remote service.

Scenario 3: Stopping an active port forwarding session

You no longer need an active port forwarding connection and want to close it.

1. On the "Client connection to the web-to-local port" page, locate the "Port [PORT] Forwarding Active" status box at the top.
2. Click the 'Stop' icon (a square icon) within this status box.
3. The status will change to "Stopping port [PORT] forwarding..." and the connection will be terminated.

Scenario 4: Sharing connection instructions with another user

You need to provide the connection details to a colleague or another device.

1. On the "Client connection to the web-to-local port" page, locate the "Connect via Local Client" section.
2. Click the 'Share' icon (a circular icon with an arrow pointing upwards) in the top-right corner of this section.
3. A dialog box titled "Share Port [PORT] Connection Instructions" will appear.
4. Review the generated text within the dialog, which contains all the necessary steps and links.
5. Click the "Copy to Clipboard" button.
6. You can now paste these instructions into an email, messenger, or document.

Scenario 5: Troubleshooting a stuck Remote Desktop connection (for Port 3389)

If you are forwarding Port 3389 for RDP and your connection becomes unresponsive, you can attempt to reset it.

1. On the "Client connection to the web-to-local port" page, scroll down to the "Troubleshooting" section (this section only appears if Port 3389 is being forwarded).
2. Click the "Execute these commands now" button.
3. The system will attempt to restart the remote desktop service and then restart the awaBerry Anywhere service. A progress message will be displayed.
4. Once complete, you can try connecting with your RDP client again.

Possible errors which may occur on this page

Understanding potential issues can help you troubleshoot effectively:

Error 1: Download of the client script fails or is blocked

What happens: When you click the "Download File" button, nothing downloads, or your browser displays an error message about a blocked download or an insecure file.

Why it happens: This typically occurs due to network restrictions, firewall settings on your computer, or security software that prevents script downloads from external sources. Occasionally, a temporary issue with the download server might also be the cause.

What to do: Check your internet connection, temporarily disable any strict browser security settings, or try using a different web browser. If the issue persists, ensure your network allows downloads from the awaBerry domain.

Error 2: Client script fails to execute in Terminal/Command Prompt

What happens: After downloading, when you try to run the script (e.g., ./[YOUR_PREFIX]_client_[PORT].sh or [YOUR_PREFIX]_client_[PORT].bat), you see an error message like "Permission denied", "command not found", or other script-related errors.

Why it happens: On Mac/Linux, "Permission denied" means the script doesn't have execution rights; the chmod +x command is crucial for this. "Command not found" usually means you are not in the correct directory where the script was downloaded. On Windows, issues might arise if your antivirus blocks the script or if the file path is incorrect.

What to do: For Mac/Linux, make sure you've run chmod +x for the script. For both operating systems, ensure you've navigated to the exact directory where the script was saved before trying to run it. Temporarily disable antivirus/firewall if you suspect it's interfering.

Error 3: Local client application cannot connect after running the script

What happens: You've successfully run the client script, and it seems to be active, but your local application fails to connect to the 127.0.0.1:XXXX address.

Why it happens: The secure tunnel might not have established correctly, or the remote service you are trying to reach is not running, is misconfigured, or is itself inaccessible on the remote device. Sometimes, a firewall on your local machine might be blocking the connection to the local forwarded port.

What to do: Verify the remote service is active and listening on the expected port. Check for any local firewall rules that might be blocking connections to 127.0.0.1:XXXX. You can also try stopping and restarting the port forwarding session from the awaBerry platform.

Error 4: RDP troubleshooting commands fail to execute (for Port 3389)

What happens: When you click "Execute these commands now" in the Troubleshooting section, an error occurs, or the RDP connection issues are not resolved.

Why it happens: The remote system might not support the systemctl commands (it's a Linux-specific command for system service management), or the user running awaBerry Anywhere does not have the necessary permissions to stop and start system services. The underlying issue with RDP might also be more complex than a simple service restart can fix.

What to do: Ensure the remote device is running a Linux-based operating system that uses systemd for service management. If you are the administrator, verify that awaBerry Anywhere has the correct permissions to execute these commands. For persistent RDP issues, further investigation into the remote device's system logs may be necessary.