Guide - How to access your unRAID console via a serial port


Recommended Posts

You can get a full console on your unRAID server through a serial port, without needing a dedicated keyboard and monitor. This can be helpful if the server is running headless, or if you need to see error messages after a crash.
The unRAID side of things really lends itself to automation, it would make a great plugin. Hint. Hint. :) 
Make the physical connection
Note: if your unRAID motherboard doesn't have a serial port you might be able add a cheap DB9 RS232 Serial IO card, although I don't have any experience with this.
Connect the unRAID system to a desktop computer with the appropriate serial cable:
(Note: I have not used these exact products, but these are examples of what could work)
Figure out what COM port is being used by unRAID
Login to unRAID via SSH and type:
dmesg | grep ttyS

On my system I saw this, which showed that unRAID saw a COM port on "ttyS0":

[    7.629239] 00:07: ttyS0 at I/O 0x3f8 (irq = 4, base_baud = 115200) is a 16550A
If yours is not on "ttyS0", then ask for help as all the commands below will need to be tweaked.
BTW, you can use the "setserial" command to further confirm there is a serial port at ttyS0:
setserial -g /dev/ttyS0

/dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4


Perform a test without making permanent changes to unRAID

While connected via SSH, type:

(Note that the line that mentions /etc/securetty is not needed from somewhere around 6.8.3+. It won't hurt anything though)

sed -i -e "s/^#ttyS0/ttyS0/" /etc/securetty
sed -i -e "/^#s1/ i s1:12345:respawn:/sbin/agetty -L ttyS0 115200 vt102" /etc/inittab
init q


On the desktop computer (these instructions are for Windows, but there should be a similar process for Mac)

  • Go to the Device Manager to figure out which COM ports you have, for instance I only have one at COM3. If you have more than one COM port you'll need to try them all until you make a connection. 
  • Install and run Putty
  • In Putty, enable "Serial" communications. In the "Serial line" area, specify your COM port (such as COM3). Set the speed to 115200. Give the session and name and click Save. Then click Open 
  • If all goes well, you should see an unRAID login prompt
  • If something goes horribly wrong you can simply reboot unRAID to start fresh and try your changes again


Make it permanent
  • Once you've got the basic connection working, let's make it permanent
  • Add the following lines to the end of your /boot/config/go script using a good text editor like Notepad ++ (be sure to save the file with unix line endings, not Windows)

    (Note that the line that mentions /etc/securetty is not needed from somewhere around 6.8.3+. It won't hurt anything though)
    # setup serial console
    sed -i -e "s/^#ttyS0/ttyS0/" /etc/securetty
    sed -i -e "/^#s1/ i s1:12345:respawn:/sbin/agetty -L ttyS0 115200 vt102" /etc/inittab
    init q


  • In the unRAID webgui, go to Main -> Boot Device -> Flash -> Syslinux Configuration
  • At the top of the Global Configuration section add:
    SERIAL 0 115200


  • Find the "append" line in the "label unRAID OS" area and add this to the end of the line:

    console=ttyS0,115200 console=tty0


  • The whole section will look something like this (it could be different depending on what other customizations you have made)

    label unRAID OS
      menu default
      kernel /bzimage
      append initrd=/bzroot console=ttyS0,115200 console=tty0


  • When you reboot the system, you should see the entire boot process on both the connected monitor (if there is one) and on the serial connection using Putty. You should be able to login using either the connected keyboard (if there is one) or using Putty.

  • If you want to run headless, disconnect the keyboard and monitor and reboot. Again, you should see the entire boot process (starting with the unRAID boot menu) using Putty. If the system refuses to boot, you'll need to reconnect the keyboard/monitor and poke around in the bios to look for a setting called "Halt on error" and disable it (depending on your specific bios it may be called something else)

The best thing about this... Putty has a "record session" option you can use to record everything that happens during boot up. It should also capture any console messages that happen right before a crash.
A big thanks to @Joe L. and @WeeboTech for this post, without it I would not have been able to figure this out
This documentation was also helpful to fill in the gaps:
  • Like 3
Link to comment
  • 1 year later...
On 7/14/2020 at 5:22 PM, lymbada said:

@ljm42 Thanks for the guide, however I see that now (6.8.3) a message indicating that /etc/login.defs is now used in place of /etc/securetty.

Do you know what modifications are now required for allowing serial access? 

(also my device is /dev/ttyUSB0)

You can just ignore the lines that mention /etc/securetty, they are no longer needed. It won't hurt anything to run them, they just won't have any effect.


I'm afraid I don't have any experience with /dev/ttyUSB0. This guide does still work for a standard serial port on /dev/ttyS0 though.

Edited by ljm42
Link to comment
  • 4 months later...

To update this topic for those using USB serial adapters (which I assume is realistically most of us), so far I have not managed to get kernel boot and shutdown messages to show but you can at least get the ability to login via the USB serial port.


Essentially, you don't need the "SERIAL 0 115200" line, nor the changes to the "append" line" at all to get the ability to login via the USB serial adapter.  Getting the ability to login via the USB to serial adapter only requires the addition to the /boot/config/go file as follows:

sed -i -e "/^#s1/ i s1:12345:respawn:/sbin/agetty -L ttyUSB0 115200 vt102" /etc/inittab

Note that my device is ttyUSB0 and it's set to 115200 baud rate as I'm connecting from a Mikrotik router.


This will allow you to login via serial.  What it won't do is let you see kernel messages via the serial port.  There's a couple of issues with even trying to do this, including the fact that the USB driver loads quite late in the boot order and so you won't see a whole bunch of boot messages anyway.


I am still looking into whether I can get kernel events posted to the USB serial console but for now this should help anyone who would like to restart their unRAID server even if network connectivity gets lost due to a NIC module errors or macvlan callbacks that kill the network stack.  You may ask "what is the point since you can just walk up to the monitor and login via keyboard" but if I'm away from home and my unRAID server barfs, the ability to connect to it via serial through my Mikrotik router using Serial Terminal means I can kick it in the pants even without fancy stuff like an iLO card.  My Mikrotik gear is the most reliable stuff in the house, so it makes sense to use this as the pivot point (I even use this for my VPN rather than a VPN container in unRAID).


It may ultimately be that because USB is loaded so late in the kernel boot process, anything more than just basic login capability is a lost cause.  I haven't given up yet, but it's very possible this is the case.  For those of us that are desperate, I recommend a dedicated serial port as a hardware UART serial port will be loaded very early by the Linux kernel.  There are a bunch of PCI-e serial port cards you can buy for this purpose.

Edited by Kaldek
  • Like 1
Link to comment
  • 4 months later...

Hi everyone,


I successfully follow this guide and I have my serial console running... mostly. I can see most of the boot process, but I can't see any messages from the '/sbin/init' process. As result I also don't see any of the shutdown messages. I suspect, some additional configuration is required to instruct '/sbin/init' to write its messages to the serial console (not only the primary monitor). I wonder if somebody already figured it out.


Thank you.

Link to comment
  • 1 year later...

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Reply to this topic...

×   Pasted as rich text.   Restore formatting

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.