Merge branch 'fabianfrz-backup_serial'

source/manual/how-tos/serial_access.rst

@@ -2,10 +2,25 @@
 Serial Access
 =============
 
+.. image:: images/serial_bootloader.png
+
 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.
+be accessed at any time, even when OPNsense is not accessible over the network. This makes it especially useful for installing OPNsense,
+for emergency troubleshooting when you accidentally cut off internet access as well as for major system upgrades.
+
+------------
+Requirements
+------------
+
+* OPNsense installation must provide a serial interface (virtual or hardware)
+* Software which can be used to access the serial interface (screen, minicom, PuTTY etc.)
+
+For a bare metal installation, you also need the following (unless provided though a management interface differently,
+please refer your server manual):
+
+* a null modem cable
+* if you don't have an RS232 port on your computer, you need an USB to RS232 converter
 
 --------------------------------
 Connecting to the serial console
@@ -27,15 +42,32 @@ The device name can differ per system and per serial device. Examples of names a
 * /dev/tty.usbmodem1112421 (usb-to-serial, macOS)
 * COM1, COM2, ... (Windows)
 
+.. Note::
+    If you have multiple devices of the same type like shown here:
+    ::
+        ls /dev/ttyUSB*
+        /dev/ttyUSB0  /dev/ttyUSB1
+    
+    You can disconnect one of them to see which one is left or you can read the ``dmesg`` log to get the vendor information
+    for the device node.
+    You can search for a message containing "now attached to ttyUSB1" to find out which device it is. Afterwards you can
+    compare the previous output to the output of a tool like ``lsusb``.
+
 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
+  # or
+  minicom -b 115200 -D /dev/tty.usbmodem1112421
 
-If OPNsense is running, you will now be asked for your username and password. The credentials are the same as those
-used for SSH.
+.. Note::
+    Access to the device is likely to be access restricted. You should run the command as root because running it as
+    a user may lead to an access denied error on Linux / BSD.
+  
+If OPNsense is running, you will now be asked for your username and password if authentication is enabled. Otherwise
+the menu is displayed (at least after pressing enter). 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``,

source/manual/updates.rst

@@ -23,3 +23,23 @@ By navigating to **System->Firmware->Settings**, you can influence the firmware
 * **Firmware Flavour:** OPNsense is available in different flavours. Currently, these flavours influence which cryptographic library to use: OpenSSL (the default) or its drop-in replacement LibreSSL.
 * **Release Type:** With this setting, you can switch between the regular fortnightly schedule of tested releases (Production) or the newest, not fully tested code (Development). **Please leave this setting on "Production", unless you fully understand the implications of switching.**
 
+--------------
+Major Upgrades
+--------------
+
+Major upgrades are recommended to do via VGA display or serial because you can see what is going on.
+
+
+.. Note::
+    You can find some documentation about serial access under :doc:`how-tos/serial_access`
+
+.. Warning::
+    Major updates are installed offline. So no web interface or SSH is running to monitor the upgrade.
+    If something fails, you need a second connection or direct access to revert the VM or repair the installation.
+
+If you choose option 12 on the console menu on latest release, you are asked if you want to upgrade to the newest
+version or to the next major release. Type in the major release number (for example "19.1") and press enter.
+OPNsense will download all release files for an offline upgrade (kernel, packages etc.) and will reboot afterwards.
+
+After a reboot, it will install all updates and when it is done, it will reboot again, then you should be on the
+desired release.