Merge pull request #4896 from chenglch/goconsdoc

Add doc to enable goconserver by default
2026-10-01 08:21:56 +00:00 · 2018-03-09 15:04:20 +08:00
parent b25c4064d1 5efb6e70ca
commit 55270d1fe6
13 changed files with 205 additions and 24 deletions
@@ -18,9 +18,9 @@ Remove Old Provision Environment

    makedhcp -d <noderange>

-#. Remove the nodes from the conserver configuration ::
+#. Remove the nodes from the goconserver configuration ::

-    makeconservercf -d <noderange>
+    makegocons -d <noderange>

 Change Definition
 -----------------
@@ -76,6 +76,6 @@ Update The Provision Environment

    makedhcp -a

-#. Configure the new names in conserver ::
+#. Configure the new names in goconserver ::

-    makeconservercf
+    makegocons
@@ -190,9 +190,9 @@ Then update the following in xCAT:

     "1.4","new_MN_name",,,,,,"trusted",,``

-* Setup up conserver with new credentials ::
+* Setup up goconserver with new credentials ::

-    makeconservercf
+    makegocons

 External DNS Server Changed
 ---------------------------
@@ -262,9 +262,9 @@ If it exists, then use the return name and do the following:

      makedhcp -a

-  - Add the MN to conserver ::
+  - Add the MN to goconserver ::

-      makeconservercf
+      makegocons

 Update the genesis packages
 ---------------------------
@@ -0,0 +1,119 @@
+Configuration
+=============
+
+Location
+--------
+
+The configuration file for ``goconserver`` is located at ``/etc/goconserver/server.conf``.
+When the configuration is changed, reload using: ``systemctl restart goconserver.service``.
+An example for the configuration could be found from
+`Example Conf <https://github.com/xcat2/goconserver/blob/master/etc/goconserver/server.conf>`_.
+
+Tag For xCAT
+------------
+
+xCAT generates a configuration file that includes a identifier on the first
+line. For example:  ::
+
+    #generated by xcat Version 2.13.10 (git commit 7fcd37ffb7cec37c021ab47d4baec151af547ac0, built Thu Jan 25 07:15:36 EST 2018)
+
+``makegocons`` checks for this token and will not make changes to the
+configuration file if it exists.  This gives the user the ability to customize
+the configuration based on their specific site configuration.
+
+
+Multiple Output Plugins
+-----------------------
+
+``goconserver`` support console redirection to multiple targets with ``file``,
+``tcp`` and ``udp`` logger plugins. The entry could be found like below: ::
+
+    console:
+      # the console session port for client(congo) to connect.
+      port: 12430
+
+      logger:
+        # for file logger
+        file:
+          # multiple file loggers could be specified
+          # valid fields: name, logdir
+          - name: default
+            logdir: /var/log/goconserver/nodes/
+          - name: xCAT
+            logdir: /var/log/consoles
+
+        tcp:
+          - name: logstash
+            host: briggs01
+            port: 9653
+            ssl_key_file: /etc/xcat/cert/server-cred.pem
+            ssl_cert_file: /etc/xcat/cert/server-cred.pem
+            ssl_ca_cert_file: /etc/xcat/cert/ca.pem
+
+          - name: rsyslog
+            host: sn02
+            port: 9653
+
+        udp:
+          - name: filebeat
+            host: 192.168.1.5
+            port: 512
+
+With the configuration above, the console log files for each node would be written in
+both ``/var/log/goconserver/nodes/<node>.log`` and ``/var/log/consoles/<node>.log``.
+In addition, console log content will be redirected into remote services
+specified in the tcp and udp sections.
+
+Verification
+------------
+
+To check if ``goconserver`` works correctly, see the log file ``/var/log/goconserver/server.log``.
+
+    #. Check if TCP logger has been activated.
+
+       When starting ``goconserver``, if the log message is like below, it
+       means the TCP configuration has been activated. ::
+
+         {"file":"github.com/xcat2/goconserver/console/logger/tcp.go (122)","level":"info","msg":"Starting TCP publisher: logstash","time":"2018-03-02T21:15:35-05:00"}
+         {"file":"github.com/xcat2/goconserver/console/logger/tcp.go (122)","level":"info","msg":"Starting TCP publisher: sn02","time":"2018-03-02T21:15:35-05:00"}
+
+    #. Debug when encounter error about TCP logger
+
+       If the remote service is not started or the network is unreachable, the
+       log message would be like below. ::
+
+         {"file":"github.com/xcat2/goconserver/console/logger/tcp.go (127)","level":"error","msg":"TCP publisher logstash: dial tcp 10.6.27.1:9653: getsockopt: connection refused","time":"2018-03-07T21:12:58-05:00"}
+
+       Check the service status and the network configuration including the
+       ``selinux`` and ``iptable rules``. When the remote service works
+       correctly, TCP or UDP logger of ``goconserver`` would recover automatically.
+
+Reconnect Interval
+------------------
+
+If console node is defined with ``ondemand=false``, when the console connection
+could not be established, ``goconserver`` would reconnect automatically. The
+interval time could be specified at ::
+
+    console:
+      # retry interval in second if console could not be connected.
+      reconnect_interval: 10
+
+Performance Tuning
+------------------
+
+Adjust the worker numbers to leverage multi-core processor performance based on
+the site configuration. ::
+
+    global:
+      # the max cpu cores for workload
+      worker: 4
+
+Debug
+-----
+
+The log level for ``goconserver`` is defined in ``/etc/goconserver/server.conf`` ::
+
+    global:
+      # debug, info, warn, error, fatal, panic
+      log_level: info
@@ -0,0 +1,14 @@
+Go Conserver
+============
+
+``goconserver`` is a conserver replacement written in `Go <https://golang.org/>`_
+programming language. For more information, see https://github.com/xcat2/goconserver/
+
+.. toctree::
+
+  :maxdepth: 2
+
+  quickstart.rst
+  configuration.rst
+  rest.rst
+
@@ -0,0 +1,20 @@
+Quickstart
+==========
+
+To enable ``goconserver``, execute the following steps:
+
+#. Install the ``goconserver`` RPM: ::
+
+      yum install goconserver
+
+
+#. If upgrading xCAT running ``conserver``, stop it first: ::
+
+      systemctl stop conserver.service
+
+
+#. Start ``goconserver`` and create the console configuration files with a single command ::
+
+      makegocons
+
+   The new console logs will start logging to ``/var/log/consoles/<node>.log``
@@ -0,0 +1,5 @@
+REST API
+========
+
+``goconserver`` provides REST API interface to manage the node sessions. For
+detail, see `REST <https://github.com/xcat2/goconserver/tree/master/api/>`_.
@@ -8,6 +8,7 @@ Advanced Topics
   cluster_maintenance/index.rst
   migration/index.rst
   confluent/index.rst
+   goconserver/index.rst
   docker/index.rst
   domain_name_resolution/index.rst
   gpu/index.rst
@@ -161,7 +161,7 @@ When the VM has been created and powered on, choose one of the following methods
 * Use **rcons/wcons** on xCAT management node to open text console: ::

   chdef vm1 cons=kvm
-   makeconservercf vm1
+   makegocons vm1
   rcons vm1

 * Connect to virtual machine through vnc console
@@ -126,7 +126,7 @@ The BMC IP address is obtained by the open range dhcp server and the plan in thi

   Configure the conserver for the **discovered** node to watch the discovery process using ``rcons``::

-       makeconservercf node-8247-22l-10112ca
+       makegocons node-8247-22l-10112ca

   In another terminal window, open the remote console: ::

@@ -99,9 +99,9 @@ The BMC IP address is obtained by the open range dhcp server and the plan is to

 #. **[Optional]**  Monitor the node discovery process using rcons

-   Configure the conserver for the **predefined** node to watch the discovery process using ``rcons``::
+   Configure the goconserver for the **predefined** node to watch the discovery process using ``rcons``::

-       makeconservercf cn01
+       makegocons cn01

   In another terminal window, open the remote console: ::

@@ -34,5 +34,5 @@ To start discovery process, just need to power on the PBMC node remotely with th
 **[Optional]** If you'd like to monitor the discovery process, you can use::

  chdef Server-8247-22L-SN10112CA cons=ipmi
-  makeconservercf
+  makegocons
  rcons Server-8247-22L-SN10112CA
@@ -25,5 +25,5 @@ To start discovery process, just need to power on the PBMC node remotely with th

 **[Optional]** If you'd like to monitor the discovery process, you can use::

-  makeconservercf node-8247-42l-10112ca
+  makegocons node-8247-42l-10112ca
  rcons node-8247-42l-10112ca
@@ -28,7 +28,37 @@ Troubleshooting
 General
 ```````

-The xCAT ``rcons`` command relies on conserver (http://www.conserver.com/).  The ``conserver`` package should have been installed with xCAT as it's part of the xCAT dependency package.  If you are having problems seeing the console, try the following. 
+``xCAT`` has been integrated with 3 kinds of console server service, they are
+
+    - `conserver <http://www.conserver.com/>`_
+    - `goconserver <https://github.com/xcat2/goconserver/>`_
+    - `confluent <https://github.com/xcat2/confluent/>`_
+
+``rcons`` command relies on one of them. The ``conserver`` and ``goconserver``
+packages should have been installed with xCAT as they are part of the xCAT
+dependency packages. If you hope to try ``confluent``,
+see `confluent </advanced/confluent/>`_.
+
+For systemd based systems, ``goconserver`` is used by default. If you are
+having problems seeing the console, try the following.
+
+   #. Make sure ``goconserver`` is configured by running ``makegocons``.
+
+   #. Check if ``goconserver`` is up and running ::
+
+      systemctl status goconserver.service
+
+   #. If ``goconserver`` is not running, start the service using: ::
+
+      systemctl start goconserver.service
+
+   #. Try ``makegocons -q [<node>]`` to verify if the node has been registered.
+
+   #. Invoke the console again: ``rcons <node>``
+
+More details for goconserver, see `goconserver documentation </advanced/goconserver/>`_.
+
+**[Deprecated]** If ``conserver`` is used, try the following.

   #. Make sure ``conserver`` is configured by running ``makeconservercf``.

@@ -42,12 +72,4 @@ The xCAT ``rcons`` command relies on conserver (http://www.conserver.com/).  The
         [sysvinit] service conserver start 
         [systemd] systemctl start conserver.service

-   #. After this, try invoking the console again:  ``rcons <node>``
-
-
-OpenBMC Specific
-````````````````
-
-   #. For OpenBMC managed servers, the root user must be able to ssh passwordless to the BMC for the ``rcons`` function to work.  
-
-      Copy the ``/root/.ssh/id_rsa.pub`` public key to the BMC's ``~/.ssh/authorized_keys`` file.
+   #. Invoke the console again: ``rcons <node>``