USB-to-Serial Access

Skill Level: Moderate (assumes familiarity with SSH sessions)

Goal

To enable serial out-of-band (OOB) access over SSH using the USB port.

Setup

A USB-to-Serial adapter will be required. Configuration varies depending upon the type of adapter -- single serial or a serial splitter.

USB-to-Serial Access

Serial out-of-band (OOB) access can be leveraged over SSH using the USB port.  There are two types of USB-to-serial cables that can be utilized: single USB-to-Serial or a USB-to-Serial splitter.  Purchasing options are available through Accelerated.

For assistance with enabling SSH, please refer to the following documentation:

Setup on firmware 18.8.14.122 or higher

This feature is now listed as an entry in the Serial section of the ACL router's configuration profile.  Open the configuration profile for the ACL router and make the following changes:

  1. Under Serial, type in a name in the Add Serial port entry, then click Add.
  2. Set Type to USB serial port
  3. Set USB port to External
  4. Adjust the baud rage, data bits, and other serial parameters as needed to match those of the console being connected to the serial port.
  5. Under Authentication -> Groups -> serial -> Serial ports, click Add and select the newly created serial entry.
  6. Click Save

After the configuration is applied to the ACL router, an option will be added to the selection menu when a user establishes an SSH session to the device, or accesses the Terminal of the ACL router.  Below is an example SSH session showing the newly created serial entry to access the USB-to-serial adapter.

$ ssh [email protected]
Password:
X11 forwarding request failed on channel 0


Access selection menu:

    a: Admin CLI          
    1: Serial: port1        (9600,8,1,none,none)                    
    2: Serial: usb          (9600,8,1,none,none)                    
    s: Shell              
    q: Quit                

Select access or quit [admin] : 2


Connecting to usb:
Settings: 9600, 8, 1, none, none
Type '~.' to disconnect from port
Type '~?' to list commands
Setup on firmware 18.4.54.41 or lower

This feature is currently supported by shell interactions in an SSH session. With shell access enabled, press 's' after authenticating to the device.

$ ssh [email protected]
$ password
Access selection menu:         
                               
    a: Admin CLI               
    s: Shell                   
    q: Quit                    
                                
Select access or quit [admin] : s
Connecting now, 'exit' to disconnect from shell ...
#
Click to copy

The relevant command(s) for USB-to-Serial access will depend on the type of adapter being used.

Single USB-to-Serial Cable

Refer to the following command to bring up a single serial connection over USB.

tip -l "$(dmesg | grep "FTDI USB Serial Device converter now attached" | grep -m 1 -o "ttyUSB[0-9]")" -c -s 9600
Click to copy

Pressing '~.' followed by ENTER will close the serial connection; note that this does not end the console session on the device being accessed over serial.

USB-to-Serial Splitter

To conveniently access multiple serial connections over SSH using this adapter, enter the following script into router's Custom Script field, setting its Run mode to "On boot." This field is nested under System > Scheduled Tasks > Custom Script.

cat <<EOT > /opt/serial_port_selector
#!/bin/sh
bugout() {
  echo "\$@"
  exit
}
serials="\$(dmesg | grep "FTDI USB Serial Device converter now attached" | grep -o "ttyUSB[0-9]" | sort -u)"
[ "\$serials" ] || bugout 'no serial-to-USB converters found'
serial_count=\$(echo "\$serials" | wc -l)
echo "Found \$serial_count USB-to-serial converters."
for i in \$serials; do
  echo "\$i"
done
echo "Type the number of the USB port you wish to open a console connection to"
echo "(e.g. for ttyUSB2, type '2'), followed by ENTER:"
read port_num
serial_port=\$(echo "\$serials" | grep "\$port_num")
[ "\$serial_port" ] || bugout "Port number \$port_num is not available, please re-run and specify a differnt port."
echo "Opening connection to USB-to-serial port \$serial_port."
echo "Press '~.' followed by ENTER to close connection."
tip -l "\$serial_port" -c -s 9600
EOT
chmod +x /opt/serial_port_selector
Click to copy

With the script enabled, SSH onto the device and enter the following command from the shell to bring up the available serial connections:

/opt/serial_port_selector
Click to copy

This will list all available connections. Enter the number of the USB port to proceed. For example:

Access selection menu:
    a: Admin CLI           
    s: Shell               
    q: Quit                
Select access or quit [admin] : s
Connecting now, 'exit' to disconnect from shell ...
# /opt/serial_port_selector 
Found 4 USB-to-serial converters.
ttyUSB0
ttyUSB1
ttyUSB2
ttyUSB3
Type the number of the USB port you wish to open a console connection to
(e.g. for ttyUSB2, type '2'), followed by ENTER:
3
Opening connection to USB-to-serial port ttyUSB3.
Press '~.' followed by ENTER to close connection.
Connected.
Click to copy