diff --git a/docs/source/advanced/restapi/restapi_setup/restapi_setup.rst b/docs/source/advanced/restapi/restapi_setup/restapi_setup.rst index ab212e8a9..02581dd30 100644 --- a/docs/source/advanced/restapi/restapi_setup/restapi_setup.rst +++ b/docs/source/advanced/restapi/restapi_setup/restapi_setup.rst @@ -1,7 +1,7 @@ -Enable the HTTPS service for REST API +Enable the HTTPS protocol for REST API ===================================== -To improve the security between the REST API client and server, enabling the HTTPS service on the xCAT MN is recommended. And the REST API client should use the 'https' to access web server instead of the 'http'. +To improve the security between the REST API clients and server, enabling the secure transfer protocol (https) is the default configuration. * **[RHEL6/7/8 (x86_64/ppc64/ppc64le) and RHEL5 (x86_64)]** :: @@ -37,7 +37,7 @@ To improve the security between the REST API client and server, enabling the HTT sudo apache2ctl -t -D DUMP_MODULES | grep ssl apt-get install libjson-perl -.. note:: If use of HTTP service is needed, edit `/etc/httpd/conf.d/xcat-ws.conf` for RHEL or `/etc/apache2/conf.d/xcat-ws.conf` for others and change `RewriteEngine On` to `RewriteEngine Off`, then restart httpd or apache. +.. note:: If use of non-secure HTTP protocol is required, edit ``/etc/httpd/conf.d/xcat-ws.conf`` for RHEL or ``/etc/apache2/conf.d/xcat-ws.conf`` for others and change `RewriteEngine On` to `RewriteEngine Off`, then restart httpd or apache. Enable the Certificate of HTTPs Server (Optional) ================================================= @@ -48,7 +48,7 @@ The certificate for xcatd has already been generated when installing xCAT, it ca Typically the hostname of the xCAT MN is initially set to the NIC which faces to the cluster (usually an internal/private NIC). If you want to enable the REST API for public client, set the hostname of xCAT MN to one of the public NIC. -To change the hostname, edit /etc/sysconfig/network (RHEL) or /etc/HOSTNAME (SLES) and run: :: +To change the hostname, edit ``/etc/sysconfig/network`` (RHEL) or ``/etc/HOSTNAME`` (SLES) and run: :: hostname @@ -56,7 +56,7 @@ After changing the hostname, run the xcat command ``xcatconfig`` to generate a n xcatconfig -c -``Notes:`` If you had previously generated a certificate for non-root userids to use xCAT, you must regenerate them using: /opt/xcat/share/xcat/scripts/setup-local-client.sh +.. note:: If you had previously generated a certificate for non-root userids to use xCAT, you must regenerate them using ``/opt/xcat/share/xcat/scripts/setup-local-client.sh `` The steps to configure the certificate for https server: :: @@ -79,17 +79,7 @@ When accessing the REST API, the certificate CA must be specified and the FQDN o curl -X GET --cacert /root/ca-cert.pem 'https:///xcatws/nodes?userName=root&userPW=' -Extend the Timeout of Web Server -================================ - -Some operations like 'create osimage' (copycds) need a long time (longer than 3 minutes sometimes) to complete. It would fail with a ``timeout error`` (504 Gateway Time-out) if the timeout setting in the web server is not extended: :: - - For [RHEL] - Edit "/etc/httpd/conf/httpd.conf" and change existing or add new entry: "Timeout 600" - service httpd restart - For [SLES] - Edit "/etc/apache2/httpd.conf" and change existing or add new entry: "Timeout 600" - service apache2 restart +.. attention:: Some operations like 'create osimage' (i.e. copycds) may require a longer time to complete and may result in a "504 Gateway Timeout" error. To avoid this, modify the ``httpd.conf`` file and extend the timeout to a larger value: ``Timeout: 600`` Set Up an Account for Web Service Access ======================================== @@ -156,5 +146,5 @@ You should see some output that includes your list of nodes. If errors returned, check `/var/log/httpd/ssl_error_log` on xCAT MN. -``Note:`` if passwords need to be changed in the future, make sure to update the xCAT passwd table. xCAT REST API uses passwords stored in that table to authenticate users. +.. note:: If passwords need to be changed in the future, make sure to update the xCAT passwd table. xCAT REST API uses passwords stored in that table to authenticate users.