Migrating from SSH

Transitioning from traditional SSH key management to Alpacon’s zero-trust architecture provides enhanced security, better auditability, and simplified access management. This guide walks you through the migration process step by step.

Why migrate from SSH?

SSH key management challenges

Traditional SSH presents several operational challenges:

  • Key sprawl: SSH keys proliferate across servers without central tracking
  • No expiration: Keys remain valid indefinitely unless manually rotated
  • Limited audit trail: Difficult to track who accessed what and when
  • Complex key rotation: Manual process prone to errors and service disruption
  • Shared accounts: Multiple users often share the same SSH user account
  • Lost keys: No way to remotely revoke access if a device is compromised

Alpacon advantages

Alpacon addresses these challenges with:

  • Centralized access control: Manage all access from a single dashboard
  • Time-bound tokens: Access automatically expires
  • Complete audit logs: Every command and action is logged
  • Instant revocation: Remove access immediately from the web console
  • Individual accountability: Each user has their own identity
  • No exposed ports: Servers don’t need SSH ports open to the internet

Migration strategy

Running Alpacon alongside SSH initially allows for a smooth, risk-free transition.

  1. Install Alpacon agent on servers while keeping SSH active
  2. Test connectivity through Alpacon web console
  3. Grant access to team members via Alpacon
  4. Monitor usage to ensure all workflows are supported
  5. Gradually reduce SSH key usage
  6. Disable SSH once confident in Alpacon

Phase 2: User migration

Inventory existing access

First, audit your current SSH access:

# List all authorized keys on a server
find /home -name "authorized_keys" -exec ls -la {} \;
 
# Check SSH configuration
cat /etc/ssh/sshd_config | grep -E "^(PermitRootLogin|PasswordAuthentication|PubkeyAuthentication)"
 
# Review sudo permissions
cat /etc/sudoers
getent group sudo

Map users to Alpacon roles

SSH Access PatternAlpacon Configuration
Root access via keyGrant Superuser role in Alpacon
Sudo userGrant Staff role with sudo permissions
Application userGrant User role with specific command ACLs
Read-only accessGrant User role with restricted commands
Service accountsUse API tokens for automation

Phase 3: Workflow migration

Interactive sessions

Before (SSH):

ssh user@server.example.com

After (Alpacon):

alpacon websh connect production-server
# Or use the web console at https://alpacon.io/workspace

File transfers

Before (SCP/SFTP):

scp file.txt user@server:/path/to/destination

After (Alpacon WebFTP):

  • Use the WebFTP interface in the Alpacon console
  • Drag and drop files directly in your browser
  • Or use the CLI: alpacon ftp upload file.txt /path/to/destination

Automation and CI/CD

Before (SSH in GitHub Actions):

- name: Deploy via SSH
  uses: appleboy/ssh-action@v0.1.5
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    key: ${{ secrets.SSH_KEY }}
    script: |
      cd /app
      git pull
      npm install
      pm2 restart app

After (Alpacon in GitHub Actions):

- name: Deploy via Alpacon
  uses: alpacax/alpacon-websh-action@v1.0.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    target: 'production-server'
    script: |
      cd /app
      git pull
      npm install
      pm2 restart app

API integration for third-party tools

For tools that don’t have native Alpacon support, use the REST API:

# Execute commands via REST API
curl -X POST https://your-workspace.us1.alpacon.io/api/events/commands/ \
  -H "Authorization: Bearer $ALPACON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "production-server",
    "command": "systemctl restart nginx",
    "timeout": 300
  }'

See the API Reference for full documentation.

Migration checklist

Use this checklist to track your migration progress:

Preparation phase

  • Back up all SSH keys and configurations
  • Document current users and permissions
  • Create Alpacon workspace
  • Plan migration schedule
  • Identify critical workflows

Implementation phase

  • Install Alpamon on all target servers
  • Register servers in workspace
  • Configure user groups and roles
  • Update CI/CD pipelines
  • Set up monitoring and alerts
  • Test access for all team members

Verification phase

  • Verify all users can access servers
  • Test all CI/CD pipelines
  • Review audit logs
  • Validate performance metrics
  • Document any issues or workarounds

Completion phase

  • Disable SSH ports
  • Remove SSH keys
  • Update documentation
  • Complete team training
  • Schedule post-migration review

Security considerations

Before disabling SSH

Ensure these items are complete before disabling SSH access:

  • All team members have Alpacon access configured
  • Emergency access procedures are documented
  • Backup access method is available (console/IPMI)
  • Monitoring alerts are updated to use Alpacon
  • Automation scripts are migrated to use API tokens
  • Command ACLs are configured for restricted users

Hardening after migration

Once you’ve migrated to Alpacon:

  1. Disable SSH service:
# Disable SSH daemon
sudo systemctl disable sshd
sudo systemctl stop sshd
  1. Close firewall ports:
# Remove SSH port from firewall
sudo ufw delete allow 22/tcp
  1. Remove authorized keys:
# Clean up old SSH keys
find /home -name "authorized_keys" -exec rm {} \;
find /root -name "authorized_keys" -exec rm {} \;

Rollback plan

If you need to re-enable SSH access:

  1. Via Alpacon console:
# Re-enable SSH service
sudo systemctl enable sshd
sudo systemctl start sshd
 
# Open firewall port
sudo ufw allow 22/tcp
 
# Add emergency SSH key
echo "ssh-rsa YOUR_EMERGENCY_KEY" >> ~/.ssh/authorized_keys
  1. Via physical/console access:
  • Use cloud provider’s console access (AWS Systems Manager, GCP Serial Console)
  • Access server via IPMI/iDRAC if available
  • Physical access to on-premise servers

Common migration scenarios

Development servers

Low-risk servers ideal for initial migration:

  1. Install Alpacon agent
  2. Test all development workflows
  3. Gather team feedback
  4. Apply lessons learned to production migration

Production servers

Requires careful planning:

  1. Schedule maintenance window
  2. Notify all stakeholders
  3. Test in staging environment first
  4. Have rollback plan ready
  5. Monitor closely after migration

Legacy systems

Systems that cannot be migrated immediately:

  1. Isolate legacy servers in separate network segment
  2. Use Alpacon jump server as single entry point
  3. Gradually modernize and migrate
  4. Maintain strict audit logs for compliance

Troubleshooting migration issues

”Cannot connect after migration”

Check:

  • Alpacon agent is running: systemctl status alpamon
  • Server is registered in workspace
  • User has appropriate permissions
  • Firewall allows outbound HTTPS (port 443)

“Automation scripts failing”

Verify:

  • API token has necessary permissions
  • Command ACLs allow required commands
  • Environment variables are properly set
  • Script paths are absolute, not relative

”File transfers not working”

Ensure:

  • WebFTP is enabled for the workspace
  • User has file transfer permissions
  • Target directories have appropriate permissions
  • Sufficient disk space available

Next steps

Need help?