Your First Connection

Welcome to CtrlOps! Adding your first server connection is the gateway to streamlining your DevOps workflow. This guide walks you through the exact steps to securely connect your machine to your server.

1. Prerequisites: SSH Setup Wizard

Before adding a connection, your local machine needs to be properly configured for SSH. If you haven't done this before, CtrlOps includes a built-in SSH Setup Wizard to make the process effortless.

To access the wizard:

Click the New Connection button on your dashboard.
At the top of the modal, look for the blue "Need help with SSH setup?" alert.
Click Open SSH Setup.

The wizard will guide you through three critical steps:

SSH Installation: Verifies that the OpenSSH client is installed on your OS.
SSH Keys: Checks for existing keys or helps you generate a secure new key (Ed25519 recommended).
Server Setup: Provides exact commands (like ssh-copy-id) to securely copy your public key to your target server.

Already have SSH keys set up? You can skip the wizard and proceed directly to adding your connection!

2. What You Need

Before proceeding, ensure you have the following details from your hosting provider (AWS, DigitalOcean, Hetzner, etc.):

IP Address — Your server's public IP (e.g., 203.0.113.0).
Username — Usually root, ubuntu, ec2-user, or your custom admin account.
Authentication — Either your configured SSH key, a .pem file, or a password.

3. Connecting Step-by-Step

Start a New Connection

From the CtrlOps dashboard, click the New Connection button in the top right corner (or Add First Connection if your dashboard is empty).

Fill in Server Details

Server Name (optional): Give your connection a friendly, recognizable name (e.g., "Production Database").
IP Address: Paste your server's public IP address or hostname.
Username: Enter the exact SSH username.

Choose Authentication Method

Select the tab that matches your security setup:

By default, CtrlOps uses your system's standard SSH keys (like ~/.ssh/id_ed25519).

Using a password instead? Toggle the Use password authentication switch, enter your password, and optionally check Remember password for automatic future connections.

Passwords are convenient but less secure than SSH keys. We highly recommend using the SSH Setup Wizard to transition to key-based authentication.

Perfect for AWS EC2 or other cloud providers that give you a downloaded key file.

Click Select .pem Key File to browse your computer, or manually paste the absolute path to your .pem or .key file.

Double-check your username (it is case-sensitive).
If using a password, ensure it is typed correctly.
If using a .pem file, ensure it has the correct permissions (chmod 400 key.pem).
If using standard SSH keys, ensure your public key was properly added to the server's ~/.ssh/authorized_keys file.

"Cannot reach server" / "Connection Timed Out"

Verify the IP address is correct.
Check that the server is currently powered on in your cloud provider's dashboard.
Ensure port 22 (SSH) is open in your server's firewall/security groups.

"Connection Refused"

The server is online, but the SSH service is not running or is configured to use a non-standard port.

Windows: SSH Agent Not Running

If you are using standard SSH keys on Windows and connections fail, your Windows SSH Agent service might be stopped.

Run these commands in PowerShell (as Administrator):

Set the service to start automatically:

Set-Service -Name ssh-agent -StartupType Automatic

Start the service now:
```
Start-Service ssh-agent
```
Add your private key (replace id_ed25519 with your filename if different):
```
ssh-add $env:USERPROFILE\.ssh\id_ed25519
```

Restart CtrlOps and try connecting again.

Next Steps

Now that you're connected to your server, explore what CtrlOps can do:

Need more help? Join our Discord community or email daxesh@tsttechnology.in