Quick Introduction to SSH for Mac Admins

Please consider supporting Scripting OS X by buying one of my books!

What is SSH?

SSH is short for ‘Secure SHell’. It is a protocol that allows you to open a shell (terminal session) on another remote computer over the network. On macOS you will usually initiate an SSH session with the Terminal application, though there are other third party applications for macOS and iOS that support the SSH protocol as well.

On macOS SSH access is sometimes called ‘Remote Login’.

As the name implies, connections over SSH are encrypted and secure. This may not seem unusual today, but it did replace many unsecured protocols such as telnet and rlogin.

SSH is supported on many platforms. You can use SSH to connect to Macs as well as any other computer which supports SSH and has it enabled. Of course, when you SSH to a different system, the environment you get through SSH might be very different (i.e. not bash, different commands, etc.), so be sure you understand the remote system.

Enable SSH access

By default SSH access is disabled on macOS. Before you can connect to a Mac with SSH you need to enable access. In the UI you can do this in System Preferences > Sharing, by enabling the ‘Remote Login’ option. Here you can also control whether all users on the Mac can get SSH access or just some of them.

The Sharing pane will also show the current hostname of this computer:

Computers on your local network can access your computer at:
client.example.com

You can also enable SSH access from the command line with

$ sudo systemsetup -setremotelogin on

and turn it off again with

$ sudo systemsetup -setremotelogin off

Turning SSH off with this command helpfully reminds you that if you are currently connected remotely, you will disconnect with this command and have to login locally to re-enable. To override this helpful notice, you can add the -f option:

$ sudo systemsetup -f -setremotelogin off

And if you want to know which hostname a Mac thinks it is, use the hostname command:

$ hostname
client.example.com

Note: If you want to control which users have access with a script, I have an example in this post. This post was written for Munki but should be fairly easy to adapt to other systems.

Connect with SSH

To connect to a machine from another Mac (the one you are working on) is simple enough. Open Terminal and enter:

$ ssh username@client.example.com

or alternatively (different syntax, same result, which one you prefer is a matter of taste)

$ ssh -l username client.example.com

If you do not give a username, ssh will use the short name you are currently logged in as. That is a useful shortcut if the username is the same on both systems.

When you connect to a remote machine for the first time you will get this prompt:

ssh client.example.com
The authenticity of host 'client.example.com (IP address)' can't be established.
ECDSA key fingerprint is SHA256:abcdefghhijklmonpqrstuvwxyz.
Are you sure you want to continue connecting (yes/no)? 

(Your actual fingerprint will look differently.) This prompt tells you that your ssh does not recognize this host and gives you a chance to not connect. For now, type yes to confirm. This will add the host to the list of known hosts, so the prompt will not return when you connect again. We will discuss keys and security in a later post.

Next ssh will prompt you for the password on the remote computer. Once you enter that you will get the prompt and have a secure shell to the remote computer. Any command you enter now, will be run on the remote computer.

You can connect with ssh when no user is logged in, i.e. the Mac is sitting at the login window. You can even connect with one user, while a different user is logged into the Mac with a UI session. In these cases, commands that interact with the UI, will fail, since the UI is either not running, or running as a different user. Most common examples are open and osascript (AppleScript).

$ open .
LSOpenURLsWithRole() failed with error -10810 for the file /Users/armin.

If you happen to be logged in on the same Mac with the same user, then the command will work, but open will open and display the Finder window on the remote Mac, not the Mac you are working on, which can be confusing.

Ending it

To end the remote session, just use the exit command.

$ exit
logout
Connection to client.example.com closed.

This will return you to the shell on your Mac where you executed the ssh command.

SSH Shortcut Files

If you frequently connect to certain hosts you may want to create an ssh short cut file, which you can then just double click or invoke with spotlight.

Execute Just One Command

Instead of opening a remote shell you can use ssh to just execute just a single command on the remote host:

$ ssh client.example.com sw_vers
Password:
ProductName:    Mac OS X
ProductVersion: 10.12.5
BuildVersion:   16F73

The ssh command will prompt for the password and the print the output of the command from the remote machine. This can be very useful. You can combine multiple commands with ;

$ ssh client.example.com hostname; sw_vers; system_profiler SPHardwareDataType

In some case the command you want to execute remotely can prompt for information, usually a password. You can add the -t option to make ssh use an interactive shell:

$ ssh -t client.example.com sudo installer -pkg ~/Downloads/myinstaller.pkg -tgt / -verbose

This will prompt twice for the password. The first time to establish the remote connection and the second time for sudo on the remote machine.

Sending single commands with ssh can be useful for automating workflows in scripts. However, the requirement to keep entering passwords will be very detrimental to automation. It will also be annoying when you frequently connect to specific remote Macs.

We will discuss how the key security works and how it can replace passwords in the following posts.

Leave a Reply

Your email address will not be published. Required fields are marked *