Telestra App Note
Logging into Telestra Systems using SSH (#99)
For sites with many systems, or geographically dispersed networks, it is often useful to write scripts to remotely control ASTi Telestra systems. This document provides a step-by-step example of how to securely achieve basic remote control capability.
The Secure Shell (SSH) is a protocol that provides transparent encrypted communication channels over a network. SSH has a client-server architecture and requires a server (typically SSHD), as well as a client (typically SSH) that will connect to the server. The client and server work together to ensure that data being passed over the network is encrypted using modern, secure algorithms, but those complexities are largely hidden from the end user. An SSH server (SSHD) is installed on the Telestra Target and Studio platforms. In order to use SSHD you'll need a system with a SSH installed. Most UNIX-like OS's include these tools by default.
Note to Windows® users, you must first download a UNIX-like environment and command line interface such as Cygwin. For more information see www.cygwin.com. This environment will allow the user to SSH into Telestra systems as described below.
How to use SSH to connect to Telestra? Establishing Remote Terminal Sessions Using Secure Shell
To SSH into a Telestra system you must first establish a remote terminal session. The Telestra is preconfigured with an admin user SSH log in. In the example below, the computer is called 'book' with the username "markh" and it is on the same network as the Telestra system (10.2.140.50). The 'ls /var' command displays the files found in the '/var' directory.
book:~ markh$ ssh firstname.lastname@example.org email@example.com's password: Last login: Wed Oct 20 14:03:11 2010 from book.local [admin@telestra-96-76-F3 ~]$ ls /var account cache db games local log mail opt racoon spool www asti crash empty lib lock lost+found nis preserve run tmp yp [admin@telestra-96-76-F3 ~]$ exit logout Connection to 10.2.140.50 closed. book:~ markh$
Most SSH clients provide a way to specify a command to execute on the same command line where the user@host is provided. In the example below, SSH will connect using the supplied credentials, execute the supplied command line, and disconnect/exit. This example is slightly more succinct than the one above.
book:~ markh$ ssh firstname.lastname@example.org ls /var email@example.com's password: account asti cache crash db empty games lib local lock log lost+found mail nis opt preserve racoon run spool tmp www yp book:~ markh$
Using this technique, it is possible to script many management tasks, so that they can be performed remotely and for any number of Telestra systems. For the configuration thus far, SSH interactively prompts the user for a password. SSH can, however, be configured to use private/public key pairs to perform authentication in place of interactive prompts.
How to Setup Cryptographic Keys and Login Without a Password
To set up SSH to use private/public key pairs to do authentication, you must first generate the keys. Most systems have a utility called ssh-keygen that will generate suitable keys and put them in the correct location on your system. Key pairs generated for use in this manner with SSH are specific to the system user and are usually stored in ~/.ssh. For example, with user 'markh' on 'book' the generated key pairs are saved in '/Users/markh/.ssh/id_rsa.pub.' The pass phrase is optional, however not specifying a pass phrase will allow SSH to connect without an interactive prompt.
Note 1: Some but not all SSH installations include the "ssh-copy-id" command which simplifies copying the public key to the remote server. The "ssh-copy-id" command appends the key to the authorized_keys file and ensures the permissions are correct.
Usage: book:~ markh$ ssh-copy-id -i ~/.ssh/id_rsa firstname.lastname@example.org
Note 2: Accept the default values when prompted.
book:~ markh$ ssh-keygen Generating public/private rsa key pair. Enter file in which to save the key (/Users/markh/.ssh/id_rsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /Users/markh/.ssh/id_rsa. Your public key has been saved in /Users/markh/.ssh/id_rsa.pub. The key fingerprint is: 10:57:b2:c9:e2:20:dd:9a:c4:48:73:ca:3f:96:8b:f7 email@example.com The key's randomart image is: +--[ RSA 2048]----+ | o . . o.. | | o B . + + | | = = + + | | + * o | | B . S | | o o | | . o | | . . | | E | +-----------------+ book:~
Generating the key pair and putting the keys in place on 'book' takes care of the client side of the configuration. As always, the private key should be kept safe. The public key must be distributed to the Telestra systems that the user wants to connect to. Distributing the public key is a matter of adding it to the right place so that the SSH server can find it when the user tries to connect as the admin. To distribute the keys use SCP, a file transfer utility that works over SSH to move the file over an encrypted channel between the main computer and the remote Telestra systems. Place the public key on the Telestra in the .ssh/authorized_keys folder in the user's home directory.
Note that you have to create the directory and set its permissions before you can do the file transfer. Setting permissions on the .ssh directory is important because the SSH server won't trust keys that aren't protected with the appropriate permissions. In the example below the command "mkdir ~/.ssh" makes the directory and the command "chmod 744 ~/.ssh" sets the permissions. The "scp ~/.ssh/id_rsa.pub firstname.lastname@example.org:~/.ssh/authorized_keys" command places the key in the "authorized_keys" directory that was created.
book:~ markh$ ssh email@example.com "mkdir ~/.ssh ; chmod 744 ~/.ssh" firstname.lastname@example.org's password: book:~ markh$ book:~ markh$ cat ~/.ssh/id_rsa.pub | ssh email@example.com
"test – d ~/.ssh || mkdir ~/.ssh ; cat >> .ssh/authorized_keys" firstname.lastname@example.org's password: book:~ markh$
Logging into the Telestra again via SSH you will see that SSH has performed authentication using the private/public key pair instead of an interactive password prompt. Take note of the file permissions in place on the ~admin/.ssh directory and its contents. The file permissions are highlighted below.
book:~ markh$ ssh email@example.com Last login: Wed Oct 20 13:44:21 2010 from book.local [admin@telestra-96-76-F3 ~]$ [admin@telestra-96-76-F3 ~]$ ls -lsa ~/.ssh/ total 16 4 drwxr--r-- 2 admin admin 4096 Oct 20 08:00 . 8 drwx------ 3 admin admin 4096 Oct 20 07:51 .. 4 -rw-r--r-- 1 admin admin 625 Oct 20 11:14 authorized_keys [admin@telestra-96-76-F3 ~]$
Remote Control Scripts
Now that SSH is set up to authenticate remote terminal session requests via the private/public key pairs, it's possible to write a script control for the Telestra. Some cases where scripting control might be useful include checking the status/health of a running model, installing a layout, or shutting down the Telestra. Below is an example of installing (the Project name is "sample" the Layout name is "main") using SSH to connect to the Telestra:
book:~ markh$ ssh firstname.lastname@example.org "ace-user install-layout sample main" Layout installed on localhost book:~ markh$
For a slightly more complicated example, the script below is used to remotely shut down three Telestra systems.
Script Example: Shutting Down the Telestra
#!/bin/bash HOSTS='10.2.140.50 10.2.140.51 10.2.140.52' for HOST in $HOSTS do if [ `ping -c 1 $HOST > /dev/null ; echo $?` != 0 ]; then echo $HOST is not reachable. else echo -ne Shutting down $HOST if [ `ssh admin@$HOST "ace-user shutdown > /dev/null" ; echo $?` != 0 ]; then echo OK else echo FAILED fi fi done
The script below is used to check the Telestra's health and if the check shows problems it will re-install the layout.
Script Example: Checking the Telestra's Health
#!/bin/bash HOSTS='10.2.140.50 10.2.140.51 10.2.140.52' MODEL=CommPanel8Stereo LAYOUT=main for HOST in $HOSTS do if [ `ping -c 1 $HOST > /dev/null ; echo $?` != 0 ]; then echo $HOST is not reachable. else if [ `ssh admin@$HOST "ace-user health > /dev/null" ; echo $?` != 0 ]; then echo -ne $MODEL/$LAYOUT on $HOST restarting... if [ `ssh admin@$HOST "ace-user install-layout $MODEL $LAYOUT > /dev/null ; echo $?"` == 0 ]; then echo OK else echo FAILED fi else echo $MODEL/$LAYOUT on $HOST is OK fi fi done
See Application Note 88 for more commands using the command line interface.
Additional configuration is required to control the Telestra using scripts over the network if the Telestra security package is installed. The SSH server on the Telestra supports TCP wrapper, which provides access control to UNIX services through configuration in /etc/hosts.deny and /etc/hosts.allow. Installation of the ASTi security package will change the /etc/hosts.deny file by disallowing connections to any service from any host. See the example below:
# hosts.deny This file describes the names of the hosts which are # *not* allowed to use the local INET services, as decided # by the '/usr/sbin/tcpd' server. # # The portmap line is redundant, but it is left to remind you that # the new secure portmap uses hosts.deny and hosts.allow. In particular # you should know that NFS uses portmap! ALL:ALL
Host access controls for TCP wrapped services (like SSHD) are actually specified in the '/etc/hosts.deny' and '/etc/hosts.allow' files. When '/etc/hosts.deny' contains ALL:ALL, TCP wrappers will disallow connections to all services from all hosts, but /etc/hosts.allow specifies exceptions to that policy. Changing the configuration to allow SSH connections from a specific host (book, or 10.2.140.2 in this case), requires the user to modify /etc/hosts.all to look like this:
# hosts.allow This file describes the names of the hosts which are # allowed to use the local INET services, as decided # by the '/usr/sbin/tcpd' server. # sshd : 10.2.140.2 : allow