3 files changed, 50 insertions, 18 deletions
diff --git a/docs/system/index.rst b/docs/system/index.rst
index e47b06ee..1ce1b405 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -12,6 +12,6 @@ System Configuration
    flow-accounting
    ntp
    proxy
-   serialconsole
+   serial-console
    syslog
    task-scheduler
diff --git a/docs/system/serial-console.rst b/docs/system/serial-console.rst
new file mode 100644
index 00000000..53322f53
--- /dev/null
+++ b/docs/system/serial-console.rst
@@ -0,0 +1,49 @@
+.. _serial-console:
+
+##############
+Serial Console
+##############
+
+For the average user a serial console has no advantage over a console offered
+by a directly attached keyboard and screen. Serial consoles are much slower,
+taking up to a second to fill a 80 column by 24 line screen. Serial consoles
+generally only support non-proportional ASCII text, with limited support for
+languages other than English.
+
+There are some scenarios where serial consoles are useful. System administration
+of remote computers is usually done using :ref:`ssh`, but there are times when
+access to the console is the only way to diagnose and correct software failures.
+Major upgrades to the installed distribution may also require console access.
+
+
+.. cfgcmd:: set system console device '<device>'
+
+   Defines the specified device as a system console. Available console devices
+   can be (see completion helper):
+
+   * ``ttySN`` - Serial device name
+   * ``ttyUSBX`` - USB Serial device name
+   * ``hvc0`` - Xen console
+
+.. cfgcmd:: set system console device '<device>' speed '<speed>'
+
+   The speed (baudrate) of the console device. Supported values are:
+
+   * ``1200`` - 1200 bps
+   * ``2400`` - 2400 bps
+   * ``4800`` - 4800 bps
+   * ``9600`` - 9600 bps
+   * ``19200`` - 19,200 bps
+   * ``38400`` - 38,400 bps (default for Xen console)
+   * ``57600`` - 57,600 bps
+   * ``115200`` - 115,200 bps (default for serial console)
+
+##############
+Network Console
+##############
+
+TBD.
+
+.. cfgcmd:: set system console network '<netconXX>'
+
+   ... and many more commands ...
+\ No newline at end of file
diff --git a/docs/system/serialconsole.rst b/docs/system/serialconsole.rst
deleted file mode 100644
index 730c9da1..00000000
--- a/docs/system/serialconsole.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-.. _serial-console:
-
-Serial console
-==============
-
-
-
-Configuring Console
--------------------
-
-.. code-block:: none
-
-  vyos@vyos# set system console
-  Possible completions:
-  +> device       Serial console device name
-  +> network      Network based console logging
-     powersave    Enable screen blank powersaving on VGA console
-\ No newline at end of file