Serial console via USB

OpenWRT users, developers, et alia:

I have several routers (Netgear WNDR3700v2, and some Linksys routers like WRT1900ACS, WRT3200ACM, RT3200, etc...) and they each have an USB port on the back.

Recently my WRT1900ACS got jacked up and I needed to use the serial console. I realied I needed a PH 2.0 6-pin cable (which I ordered) to use with a TTL/Serial level converter I have. Once the 6-pin cable arrives I will be able to use the console.

However, would it not be a wise idea to bake into OpenWRT the ability for OpenWRT to notice if an USB Serial port cable is plugged into the USB port and upon detecting it say, oh, let me use that as my serial console not the internal serial console that requires someone to open the router and plug a special cable with level converter into!?! I imagine I am not the first person to think of this idea, and if not, then can someone refer me to what is required to configure such functionality into the next OpenWRT environment I create so I can do that in the future.

Thanks!

Stuart

Your idea sounds cool, until you realize that it doesn't work - and can't work.

The bootloader is provided by the OEM and never changed/ touched, it does not know about your fancy usb2serial adapter and won't try to direct its output to it, nor accept any input from it. The next problem would be that there are at least half a dozen of different USB2serial chipsets, each needing their own drivers (with that comes the problem, which drivers to include (limited flash size), how the adapters are addressed and what to do if there are suddenly two- (or more) adapters connected concurrently; and there may be users who don't want the router's serial console on their usb2serial adapter (because they need it to control something else)).

The native UART of the SOC is very low-level, it doesn't need much cooperation from the SOC or the kernel - connecting to it is your problem, not the router's. The USB stack however is much, much, higher level, it needs (a whole stack of-) drivers, something that isn't provided by most bootloaders - and even at the kernel level, USB is going to fail much earlier than the native serial console. This is a means of recovery, something you need once in a blue moon, but which needs to be 101% reliable, at all times - not a fair weather technology which won't work when you need it most.

3 Likes

Usb is a driver and software based serial communication system.
A “serial” or more precisely a uart is a direct hardware communication with a hardware uart module on the cpu. If the cpu or soc is actually alive it will start communicate on the serial port once powered on.

Sometimes more modern hardware have started using a usb connectors for console communications but then I guess that there is a converter somewhere inside to make it work.

1 Like

Actually, it is the converter itself... It's just a fancier version of the USB-to-TTL serial adapter that you would use normally. The 'serial UART' side is directly connected to the standard UART port, and the USB side goes to your computer with a full-stack OS that has the drivers to talk to the USB adapter chip.

1 Like

That's indeed the typical setup (for modern, high-end networking gear; if they don't opt for the Cisco-style rj45 rs232c adapter), a plain SOC UART as usual - and an ordinary USB2serial adapter with micro-USB-A or USB-C permanently mounted inside (maybe dissolved onto the main PCB, but that doesn't change anything about the details).

1 Like

SLH, et alia:

Considering your comments I realize it was not such a great idea. That said, I intend to place one of these 6-pin connectors on each of my Linksys routers and will simply fish the small wires out through one of the holes on the router. Perhaps I will solder some sort of connector (audio jack) onto the wires or maybe I will just solder a female jumper wire onto the end.

The main TTL/Serial adapter I use is a small device that has pins on it to connect breadboard female connectors onto and a USB port on the other end.

Stuart

Sure thing you can do this. But is it really worth the hassle? How often do your really need the UART, unless you're doing development work?

Andyboeh, et alia:

No that much, but enough times that I ordered some PH 2.0 6-pin cables recently to at least externalize the 3 pins I need on the several Linksys routers I have. I will probably take the 3 wires and put them onto a 3-pin female 2.5mm or 3.5mm jack. It seems that screw terminal 2.5mm and 3.5mm male/female jacks are all about Aliexpress and not very expensive.

Stuart

Can't answer for anyone else. But I find console a convenient safety net. Makes me relax a bit more when doing changes to the network configuration, or upgrading to a new major relaese, or just fooling around. And with a simple console server I can log unexpected crashes too.

Not critical, but nice to have. And the cost is small. I usually leave a bluetooth UART module inside all the devices I open, so that I don't have to open them again. This also allows permanent console connections without wires all over the place.

But I do like the idea of adding some default failsafe scripts for devices having USB ports. A USB console can be useful even without bootloader support, like e.g my network config usecase. No need to worry about screwing up ethernet access as long as you can use the USB port for an emergency console.

I think this could even be extended further, to support some rescue use cases without having access to any special equipment. Maybe enter failsafe mode if the system boots with a USB storage device having some magic file? Or extend that to have the system restore config files off a USB storage device if there is some magic secret key file present? Would probably have to be locked down for security, but one could imagine a sysupgrade addon allowing you to backup critical config files with a device specific signature for emergency restores.

So many crazy ideas....Better stop now :slight_smile:

1 Like

bmork, et alia:

Let me clarify what my concerns are specifically as we have quite a bit of thought power rolling here (which I think is great)! :slight_smile:

What BlueTooth UART module do you use and how do you connect to it to gain serial port access, can you speak to that with greater granularity please? I would love to implement this solution for sure on all my OpenWRT based routers. Are you referring to the HC-06 style of devices? I'd be curious how you got them programmed and then how you connected to them if that is what you selected to use for this purpose. It is quite an inexpensive and functional solution if so!

In fact the emergency console scenario you are speaking of (I jacked up configuring my VLANs and some other network parameters) would be exactly what I am facing in the instant case. I own several USB to serial port "dongles" and would be happy to pick one and load drivers for it onto all my routers so I could plug it in whenever I like also. If I had the BlueTooth serial console to the SOC solution, then that would also make the resolution of such scenarios much easier as well for sure. However, plugging in an USB to serial cable and plugging it into my console server would also be most helpful too.

As pointed out previously, It is \a rare occurrence that I need to use the serial console to reload firmware per se, as I am not a developer of OpenWRT.

Thanks,
Stuart

I use these (specifically bought a batch of this item a few months ago):

My reasons for that choice was that I wanted a module with low power consumption, without a 3.3V regulator, operating in client mode by default, and simple enough even for me to solder to the device.

I've already posted pictures of some of mye devices:

There's another one if you follow the link to the NR7101 page from that post.

These adapters are almost as easy to use as the USB adapters. The differences are

  • require a working 3.3V output. This can be a problem on some devices. The 3.3V hole on my Netgear GS108Tv3 turned out not to be connected for example. Fixable, but then it's easier to just do USB instead.
  • must be configured (i.e UART speed) before being connected to the OpenWrt device
  • need some software turning a Bluetooth connection into a tty in the other end. I use rfcomm. Simple, available and easy to use

For example, I have this in the /etc/rc.local of one of my Unifi AP AC Pro access points serving as console server for two other OpenWrt devices nearby:

root@unifiac2:~# cat /etc/rc.local 
# bluetooth for conserver
/usr/bin/hciconfig hci0 up
# nr7101 console
/usr/bin/rfcomm bind 0 46:6E:00:00:F0:0F
# gs1900-10hp console
/usr/bin/rfcomm bind 1 A8:6C:00:00:DE:AD
exit 0

making the respective consoles accessible on /dev/rfcomm0 and /dev/rfcomm1.

rfcomm means using BDR of course. I noticed that the firmware on the latest jdy-31 batch I got (the link above) also supports a simple serial over BLE protocol. I haven't done much testing of that. But it'll probably make it easier to use an Android app for console access. The protocol is very simple: write to a characteristic to transmit and read received data from a notification. There's a description here (different module but same BLE protocol):
https://www.martyncurrey.com/hm-10-bluetooth-4ble-modules/

1 Like

A note about the use of a Bluetooth UART adapter:

Although very much dependent on the implementation of the adapter itself, some of these may not have any credential requirements (or easy to guess passcodes like 0000). This may present a security risk to your router insofar as anyone within range could open up a BT terminal and gain TTY access to your router. Obviously this is a proximity based issue and relatively short range (~10m or so), but keep this in mind. One possible mitigation that could be achieved would be to install a power switch to interrupt the 3.3V supply voltage from the board -- turn it on only when necessary (obviously this isn't helpful if the device is in a hard to reach location).

2 Likes

True. Thanks for adding this important warning.

I set
option ttylogin '1'
on my OpenWrt devices, but that's not protecting against everything. Log messages and bootloader access is completely unprotected. Better trust your neighbours :slight_smile:

2 Likes

For 'normal' uses, I'd rather suggest to mount normal micro-USB-A or USB-C based usb2serial adapter inside the router, more or less the same size than the bluetooth module, no configuration necessary (apart from choosing the baudrate when connecting) plug in the USB cable and off you go; prices ranging up to ~1.50 EUR/ USD per board.

Why this 'less convenient' option over the bluetooth one:

  • you need to be physically at the router to plug in the USB cable, so all the wireless attack vectors are gone
  • they're cheap enough to mount inside and 'forget' about
  • they don't need any configuration/ flashing
  • you can get them for all voltages (1.8V, 2.5V, 3.3V, 5V), they don't pull power from the SOCs Vcc pin
  • no interference from the bluetooth signal, causing distortions to the 2.4 GHz WLAN of your router

There are downsides:

  • some of the boards might not be as cooperative as their full-sized siblings (fewer filtering components on the tiny PCBs)
  • you need more attention to details on the small aspects (supported signal voltages)
  • the 'neck' of the USB port might not stick out enough to pass through the plastic case of your router easily
  • you need to find a way to secure it properly inside the router's case (hot glue) and drill/ file a hole for the USB-C connector
  • you need to be within an arm's length while connecting to the USB2serial adapter (safer, but less convenient)

There are obviously reasons for wanting the bluetooth option (outdoor devices come to mind, but there security of the bluetooth link should be considered) or to maintain in-situ permanent logging.

2 Likes

bmork, et alia:

Let first say that for the price I went and ordered one of the JDY-31 boards. However, I was confused by your conflating of two different types of boards with respect to how I go about implementing its usage. If I can get the JDY-31 working with my Linksys router then I plan to order a few more of them and put them on all my OpenWRT based routers.

I do understand that I will have to solder wires to the board for GND, TX, RX, and 3.3V, no problem. In fact, I ordered some PH 2.0 wires with 6 pin connectors (for the Linksys routers I have) that can plug directly onto the router (I also am going to get some double sided sticky tape to hold the JDY-31 in place in the router). Additionally I have a WNDR3700v2 that I'd deploy one of these into as well and one other router I am trying to work on getting OpenWRT ported over onto as well.

Configuring and using the JDY-31 is where my confusion sets in! :slight_smile:

  1. The Linksys routers use a baud rate of 115200 and I understand these devices are 9600 "out of the box", what must I do to configure the JDY-31 to default to 115200?

  2. I have an old GD-8200 laptop with a BlueTooth board in it that runs Kali Linux (Kali does support the BlueTooth board I have, though I am not sure if it will given this unique application of it, but I am optimistic). What must I do to be able to connect to the router once the JDY-31 is installed and at the correct baud rate to gain terminal access to the router at that point?

I know people were speaking of security concerns, but, that is not really an issue for me as my network is pretty secure and the routers are in places in my home that someone would have to be inside my home to really be close enough to be proximate to them. I do suppose I could put a toggle switch on the router to turn off the 3.3v power if I was really concerned about that factor, but I am not.

Thanks for your input and thoughts, I really like this solution if I can get it to work.

Stuart

This may be more for the sake of future readers than you @stuartbh (since you feel that this is of minimal risk in your environment)

With Bluetooth, the proximity requirement does indeed provide some level of inherent protection, but don't assume it to be absolute. A sensitive directional antenna and a determined attacker could absolutely gain access to your router device without you knowing, even though the BT range is generally quite short. If you live somewhere out in the country and your nearest neighbor would be a 10 minutes (or longer) walk from your home, you'd probably notice if someone pulled up into your driveway (and at that point, honestly what are the chances of that??), but if you live in a normal suburban or city environment, you do run the risk of people being close enough to cause you trouble. Obviously there are some really good reasons to consider a BT based adapter, but it does fall short on the security front. If it has the ability to require a passcode, at least use that.

1 Like

psherman, et alia:

It is not a risk I am concerned about, its way over the top into the range of folks that have 6 months of canned food in their underground bunker waiting for a nuclear attack.

If someone reading this felt it was a risk they wanted to mitigate they could just install a toggle switch inline with the 3.3V pin. But, then, if someone were going to drill into the router case to add a toggle switch why not just add an audio jack for serial output and forego the BlueTooth board entirely.

This is just not an attack vector I am worried about. That said, the attacking entity would still need my 4 digit pin and ostensibly the root password to login to the router. I adjudicate the risk is nominal in my view. In fact, if this was a concerning risk to me I'd forget worrying about the BlueTooth board being vulnerable and just delete the root account and replace it with an 8 random character username for example.

Of course, I could also tape a note to the top of the router too. "Hiya, you have broken into my house and instead of stealing my cash and jewelry, you are trying to get into my router. Wonderful! Here is the username and password, have fun. In fact, feel free to surf the internet or play with my home lab as long as you wish or until the police arrive to arrest you. Ooops, overlooked the alarm system in order to hack the router? Too late!"

Stuart

Understandable, since this is a bit underdocumented. But there is a reason that: It is very simple.

There's sort of a manual here: https://adastra-soft.com/wp-content/uploads/2021/06/JDY-31_manual_2.pdf

The bluetooth module operates in two distinct modes: Transparent when connected to a Bluetooth peer, or AT command mode when Bluetooth is disconnected. So you have to configure it with a wired connection, using e.g a USB UART module.

Connect (GND, 3.3V, RX and TX crossed) the USB module to the Bluetooth module and configure minicom or whatever for 9600 8N1 using the appropriate ttyUSBx device.

Note that the AT interpreter is a bit weird. It doesn't like CR. Queries do not end in "?". New values follow the set command without any space or "=" separator between, even if the similar query result includes "=".

The most important commands are

AT+BAUD (value is a single digit: 4=9600, 5=19200, 6=38400, 7=57600, 8=115200, 9=128000)
AT+NAME
AT+LADDR
AT+RESET
AT+ENLOG (log connections: 0=off, 1=on)
AT+VERSION

To change the BAUD rate to 115200, you'd simply do (this will break the session until you match the USB baud rate of course)

AT+BAUD8
AT+RESET

That's really all you need.

But I like to change a couple of other settings for convenience. A unique name makes it much easier to discover the correct module if you have more than one. And I like to include the configured speed in the name so I don't have to guess or remember.

The modules also tend to all have the same mac address, so change it if you have more than one. Note that they also seem to match only on the last 3(?) bytes. So make those unique.

The modules are completely transparent when connected to a Bluetooth peer, but they will by default print CONNECTING>>CONNECTED to the UART when a connection is established. This usually doesn't matter to the console device. But it can be a problem if the bootloader accepts any key press as a stop signal and the message is printed at the wrong time. Chances of that are actually much higher than youd' think, since the Bluetooth module and console device share power supply. This syncronizes device boot with a Bluetooth connection if you have some console server trying to keep the session up. Luckily the message can be disabled with AT+ENLOG.

So a complete configuration could be like

AT+BAUD8
AT+NAMEmy-console-115k2
AT+LADDRBD6C0000BEEF
AT+ENLOG0
AT+RESET

It is also possible to reconfigure the module after installing it, as long as you have some other way in - like ssh. Just disconnect any Bluetooth peer and echo the AT commands to /dev/console. If you forgot to diable the log messages for example:

echo -ne "AT+ENLOG0\n" >/dev/console 
1 Like

Sure. I have no illusions of security wrt dedicated attackers targetting me or my devices. But keeping a permanent connection from a console server is enough to hide the module. The modules can only support a single session, and they do not show up in scans if already connected. This makes it unlikely than a random passer-by will discover it and try to connect.

This isn't a very solid protection obviously. You can just jam the existing connection if you know it's there. But then again: How do you know that your neighbour didn't install a hidden bluetooth module in your OpenWrt router? It's not significantly harder to do than attacking mine.

Yes, the risk is probably quite small in practical terms, and it seems reasonable that the users currently contributing to this thread have deemed the risk low enough (and the convenience great enough) to justify the use of the BT modules.

To be clear, my security warning was intended to serve two purposes:

  1. inform the current people on the thread about the potential risk, in the event that they were not aware or actively thinking about it.
  2. more importantly, inform future readers about the potential risk, however small, so that they can make their own risk/benefit calculation.

Well, given that it would require physical access to install a BT module into my devices, I'd say it's quite unlikely. I would say it's far less likely than someone connecting to a BT UART adapter that is already installed since physical access is not required -- only proximity. Yes, the risk is still small in your case, but higher than mine.