From f685d458b432bb2cfc604eb0cc3b621b9b93676d Mon Sep 17 00:00:00 2001 From: chenglch Date: Tue, 6 Mar 2018 14:58:20 +0800 Subject: [PATCH] Add doc to enable goconserver by default Add the steps in documentation to enable goconserver by default. --- .../advanced/goconserver/configuration.rst | 119 ++++++++++++++++++ docs/source/advanced/goconserver/index.rst | 14 +++ .../advanced/goconserver/quickstart.rst | 20 +++ docs/source/advanced/goconserver/rest.rst | 5 + docs/source/advanced/index.rst | 1 + .../ppc64le/management/basic/rcons.rst | 42 +++++-- 6 files changed, 191 insertions(+), 10 deletions(-) create mode 100644 docs/source/advanced/goconserver/configuration.rst create mode 100644 docs/source/advanced/goconserver/index.rst create mode 100644 docs/source/advanced/goconserver/quickstart.rst create mode 100644 docs/source/advanced/goconserver/rest.rst diff --git a/docs/source/advanced/goconserver/configuration.rst b/docs/source/advanced/goconserver/configuration.rst new file mode 100644 index 000000000..5f6a50d61 --- /dev/null +++ b/docs/source/advanced/goconserver/configuration.rst @@ -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 `_. + +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/.log`` and ``/var/log/consoles/.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 diff --git a/docs/source/advanced/goconserver/index.rst b/docs/source/advanced/goconserver/index.rst new file mode 100644 index 000000000..39f3ff2cc --- /dev/null +++ b/docs/source/advanced/goconserver/index.rst @@ -0,0 +1,14 @@ +Go Conserver +============ + +``goconserver`` is a conserver replacement written in `Go `_ +programming language. For more information, see https://github.com/xcat2/goconserver/ + +.. toctree:: + + :maxdepth: 2 + + quickstart.rst + configuration.rst + rest.rst + diff --git a/docs/source/advanced/goconserver/quickstart.rst b/docs/source/advanced/goconserver/quickstart.rst new file mode 100644 index 000000000..96559668b --- /dev/null +++ b/docs/source/advanced/goconserver/quickstart.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/.log`` \ No newline at end of file diff --git a/docs/source/advanced/goconserver/rest.rst b/docs/source/advanced/goconserver/rest.rst new file mode 100644 index 000000000..81c112786 --- /dev/null +++ b/docs/source/advanced/goconserver/rest.rst @@ -0,0 +1,5 @@ +REST API +======== + +``goconserver`` provides REST API interface to manage the node sessions. For +detail, see `REST `_. diff --git a/docs/source/advanced/index.rst b/docs/source/advanced/index.rst index 820e899d8..b2c45af78 100755 --- a/docs/source/advanced/index.rst +++ b/docs/source/advanced/index.rst @@ -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 diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/basic/rcons.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/basic/rcons.rst index 396880103..1addf7997 100644 --- a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/basic/rcons.rst +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/basic/rcons.rst @@ -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 `_ + - `goconserver `_ + - `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 `_. + +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 []`` to verify if the node has been registered. + + #. Invoke the console again: ``rcons `` + +More details for goconserver, see `goconserver documentation `_. + +**[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 `` - - -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 ``