How to use iTerm2 Shell Integration with Amazon EC2

Why use iTerm2 Shell Integration

In this post I will explain you how to configure iTerm2 to easilly upload and download files on a remote Amzon EC2 host with a simple drag-and drop.

iTerm2 is a terminal emulator for macOS that replaces the system Terminal by extending its functions: it’s used to remote login to servers via SSH, and it’s one of the best tool for managing remote sessions.

One of the most useful iTerm2 features, that could save you a lot of time and increase the experience, is Shell Integration. It enables features like saving locations in history, alerting on command completion, assign profiles to usernames, and most important it allows you to download files with one click and drag-and-drop file to upload them via SCP.

How Shell Integration Works, and problems with Amazon EC2

Shell Integration uses SCP protocol to securely transfer files, so to integrate it with your Amazon EC2 Linux it needs to know two things:

The host name to connect to;
The user name and the certificate that need to be used;

To know the remote host name to upload files, SCP uses the hostname command, which unfortunately on Amazon EC2 Linux instances gives you the internal host name and not the public host name.

ip-YYY–YYY–YYY–YYY.eu-south-1.compute.internal

When you try to upload a file, your Mac receives an internal name that could not be resolved by its DNS, and so the upload fails.

The second problem is how to specify to SCP which user and which certificate needs to be used, without providing it every time you upload a file.

So, let’s see step by step how to solve this two problems.

Getting the public hostname

To solve the problem of the host name, on your Amazon EC2 Linux you can set an environment variable called iterm2_hostname that overrides the hostname value with whatever you want.

So you can specify your public host name as a string or use Amazon EC2 Linux meta data to get the public host name:

export TOKEN=`curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`export iterm2_hostname=`curl -s -H "X-aws-ec2-metadata-token: $TOKEN"  http://169.254.169.254/latest/meta-data/public-hostname`

The variable TOKEN containes an auth token needed to query Amazon EC2 Linux meta data and then it’s used to call the meta-data web service that provides the public-hostname.

So if you save the two lines above in your .bashrc file (if you use Bash, or .zshrc for example if you use Zsh) on your Amazon EC2 Linux, each time you connect to your instance from your Mac, will set the variable term2_hostname and iTerm Shell Integration can undersand the public name of the host you are connected to.

Specify username and credentials

Specify username and the certificate to login to the remote host is very simple: of course SCP uses SSH, so you can specify the credentials inside your ~/.ssh/configuration file on your Mac (if you don’t have it, create a new blank one).

Host ec2-XXX-XXX-XXX-XXX.eu-south-1.compute.amazonaws.com
    Hostname ec2-XXX-XXX-XXX-XXX.eu-south-1.compute.amazonaws.com
    User ec2-user
    IdentityFile /path/to/your/identity/file/identityfile.pem

Where:

ec2-XXX-XXX-XXX-XXX.awsregion.compute.amazonaws.com: is the public hostname of your remote machine;
ec2-user: is your username for Amazon EC2 Linux (Note that ec2-user is the default username, you can use it for your first connection and unless you don’t create other users);
/path/to/your/identity/file/identityfile.pem: is the certify you associate to your Amazon EC2 Linux instance when you created it

Now all is set.

Note: you can now ssh in your Amazon EC2 Linux using this simple command:

ssh ec2-XXX-XXX-XXX-XXX.eu-south-1.compute.amazonaws.com

SSH will search the hostname in the configuration file and will use the key and username provided to connect.

Let’s test it!

Now SSH into your remote Amazon EC2 Linux Server:

ssh ec2-XXX-XXX-XXX-XXX.eu-south-1.compute.amazonaws.com

… and drag-and-drop a file on the iTerm window while pressin the ALT key.

You’ll be asked a confirm to scp the file and then the transfer will start.

At the end a notification will be sent via your Notification Center on your Mac and you’ll see the uploaded file marked as Finished in your Uploads menu in iTerm2.

Now you can do the same thing to download a file: if you list (ls) the content of a directory, you can click on a file while pressing the COMMAND key and it will be downloaded to your Mac.

Like for ‘Uploads’ you will see now a Downloads menu in iTerm2 with your file marked as finished

Conclusions

Shell Integration is for me one of the most useful features of iTerm2 available: it not only allows you to drag-and-drop to upload and click to download, but I suggest you to check also all the available features that can smooth your experience working with remote servers.

I can assure you that your experience will increase and working with remote machines will be a breeze!

Gianluca Nieri