Archives/opensense-docs
2
0
Fork 0
mirror of https://github.com/opnsense/docs synced 2024-10-30 21:20:20 +00:00
Code Issues Projects Releases Wiki Activity

Write page about serial access (#120)

Browse Source
This commit is contained in:
Michael Steenbeek 2019-01-31 11:09:17 +01:00 committed by Ad Schellevis
parent 609379fcac
commit 69891588ca
3 changed files with 45 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
source/manual/how-tos/serial_access.rst Normal file
View File

@ -0,0 +1,42 @@
=============
Serial Access
=============
Besides the web frontend, SSH and a locally connected monitor (if your device supports it), OPNsense can also be
controlled via serial. Accessing OPNsense via serial is similar to accessing via SSH, but unlike SSH, the system can
be accessed at any time, even when OPNsense is not running. This makes it especially useful for installing OPNsense,
as well as for emergency troubleshooting when you accidentally cut off internet access.
--------------------------------
Connecting to the serial console
--------------------------------
If you already installed OPNsense via a non-serial installer, serial access needs to be turned on. To do this, open
the web interface, navigate to **System->Settings->Administration**, scroll down to 'Console' and set the primary or
secondary console to 'Serial console'. Note: this is **only** necessary if you already installed OPNsense, and did not
use the serial installer to do so. In all other cases (accessing BIOS, running the serial installer, connecting to an
installation that was done via serial), serial access is already available.
On Unix-like systems, you can connect to the serial console using the ``screen`` program, with a baud rate of 115200.
The device name can differ per system and per serial device. Examples of names are:
* /dev/ttyS0 (serial port, Linux)
* /dev/ttyUSB0 (usb-to-serial, Linux)
* /dev/cuau0 (serial port, FreeBSD)
* /dev/cuaU0 (usb-to-serial, FreeBSD)
* /dev/tty.usbmodem1112421 (usb-to-serial, macOS)
* COM1, COM2, ... (Windows)
For example, on the Deciso DEC630, accessed from macOS, the device is named ``/dev/tty.usbmodem1112421``. Entering
the serial console thus involves opening a terminal and executing the following instruction:
::
screen /dev/tty.usbmodem1112421 115200
If OPNsense is running, you will now be asked for your username and password. The credentials are the same as those
used for SSH.
A thing to note is that the screen won't always auto-update. If you connect and see no output, try pressing `Enter`
first before checking the other (more complex) possibilities. Another thing is that, when connecting via ``screen``,
you might not be able to scroll (but you can still pipe the output through a pager like ``more`` or ``less``).

1
source/manual/howtos.rst
View File

@ -7,6 +7,7 @@ How-tos
:titlesonly:
:glob:
how-tos/serial_access
how-tos/accounting
how-tos/bind
how-tos/c-icap

3
source/manual/install.rst
View File

@ -240,7 +240,8 @@ Download the installation image from one of the mirrors listed on the `OPNsense
The easiest method of installation is the USB-memstick installer. If
your target platform has a serial interface choose the "serial image.
64-bit and 32-bit install images are provided. The following examples
apply to both.
apply to both. If you need to know more about using the serial interface,
consult the :doc:`serial access how-to<how-tos/serial_access>`.
Write the image to a USB flash drive (>=1 GB) or an IDE hard disk,
either with dd under FreeBSD or under Windows with physdiskwrite