Configure Web Services¶
The following steps describe how to setup the Web Service to use the REST API
Enable the HTTPS service for REST API¶
To improve the security between the REST API client and server, enabling the HTTPS service on the xCAT management is recommended. And the REST API client should use the ‘https’ to access web server instead of the ‘http’.
[RHEL 6 (x86_64/ppc64)] and [RHEL 5 (x86_64)]
yum install mod_ssl service httpd restart yum install perl-JSON
[RHEL 5 (ppc64)]
Uninstall httpd.ppc64 and install httpd.ppc:
rpm -e --nodeps httpd.ppc64 rpm -i httpd.ppc mod_ssl.ppc
[SLES 10/11 (x86_64/ppc64)]
a2enmod ssl a2enflag SSL /usr/bin/gensslcert cp /etc/apache2/vhosts.d/vhost-ssl.template /etc/apache2/vhosts.d/vhost-ssl.conf Insert line 'NameVirtualHost *:443' before the line '## SSL Virtual Host Context' /etc/init.d/apache2 restart zypper install perl-JSON
[Ubuntu]
sudo a2enmod ssl ln -s ../sites-available/default-ssl.conf /etc/apache2/sites-enabled/ssl.conf sudo service apache2 restart
Verify it is loaded:
sudo apache2ctl -t -D DUMP_MODULES | grep ssl apt-get install libjson-perl
Enable the Certificate of HTTPs Server (Optional)¶
Enabling the certificate functionality of https server is useful for the Rest API client to authenticate the server.
Since a certificate for xcatd has already been generated when installing xCAT, it can be reused by the https server. To enable the server certificate authentication, the hostname of xCAT MN must be a fully qualified domain name (FQDN) that the REST API client must use when accessing the https server. If the hostname of the xCAT MN is not a FQDN, you need to change the hostname. Also, typically the hostname of the xCAT MN is initially set to correspond to the NIC that faces the cluster, which is usually an internal/private NIC. If you want to be able to use the REST API from a remote client, you should make the xCAT MN hostname correspond to the public NIC. To change the hostname, edit /etc/sysconfig/network (RHEL) or /etc/HOSTNAME (SLES) and run:
hostname <newFQDN>
Rerun xcatconfig to generate a new server certificate with the correct hostname.
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<username>
The steps to configure the certificate for https server:
export sslcfgfile=/etc/httpd/conf.d/ssl.conf # rhel
export sslcfgfile=/etc/apache2/vhosts.d/vhost-ssl.conf # sles
export sslcfgfile=/etc/apache2/sites-enabled/ssl.conf # ubuntu
sed -i 's/^\(\s*\)SSLCertificateFile.*$/\1SSLCertificateFile \/etc\/xcat\/cert\/server-cred.pem/' $sslcfgfile
sed -i 's/^\(\s*\)SSLCertificateKeyFile.*$/\1SSLCertificateKeyFile \/etc\/xcat\/cert\/server-cred.pem/' $sslcfgfile
service httpd restart # rhel
service apache2 restart # sles/ubuntu
The REST API client needs to download the xCAT certificate CA from the xCAT http server to authenticate the certificate of the server.
cd /root
wget http://<xcat MN>/install/postscripts/ca/ca-cert.pem
When accessing using the REST API, the certificate CA must be specified and the FQDN of the https server hostname must be used. For example:
curl -X GET --cacert /root/ca-cert.pem 'https://<FQDN of xCAT MN>/xcatws/nodes?userName=root& \
userPW=cluster'
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 (504 Gateway Time-out) if the timeout setting in the web server is not extended:
For rhel
sed -i 's/^Timeout.*/Timeout 600/' /etc/httpd/conf/httpd.conf
service htttd restart
For sles
echo "Timeout 600" >> /etc/apache2/httpd.conf
service apache2 restart
Set Up an Account for Web Service Access¶
The REST API calls need to provide a username and password. When this request is passed to xcatd, it will first verify that this user/pw is in the xCAT TODO:passwd table, and then xcatd will look in the TODO:policy table to see if that user is allowed to do the requested operation.
The account which key is xcat will be used for the REST API authentication. The username and password should be passed in with the attirbutes: userName: Pass the username of the account userPW: Pass the password of the account (xCAT 2.10) password: Pass the password of the account (xCAT earlier than 2.10)
You can use the root userid for your API calls, but we recommend you create a new userid (for example wsuser) for the API calls and give it the specific privileges you want it to have.
Use root Account¶
Since the certificate and ssh keys for root account has been created during the install of xCAT. And the public ssh key has been uploaded to computer node so that xCAT MN can ssh to CN without password. Then the only thing needs to do is to add the password for the root in the passwd table.
tabch key=xcat,username=root passwd.password=<root-pw>
Use non-root Account¶
Create new user and setup the password and policy rules.
useradd wsuser
passwd wsuser # set the password
tabch key=xcat,username=wsuser passwd.password=cluster
mkdef -t policy 6 name=wsuser rule=allow
Note: in the tabch command above you can put the salted password (from /etc/shadow) in the xCAT passwd table instead of the clear text password, if you prefer.
Create the SSL certificate under that users home directory so that user can be authenticated to xCAT. This is done by running the following command on the Management node as root:
/opt/xcat/share/xcat/scripts/setup-local-client.sh <username>
When running this command you’ll see SSL certificates created. Enter “y” where prompted and take the defaults.
To enable the POST method of resources like nodeshell,nodecopy,updating,filesyncing for the non-root user, you need to enable the ssh communication between xCAT MN and CN without password. Log in as <username> and run following command:
xdsh <noderange> -K
Refer to the doc to TODO:[Granting_Users_xCAT_privileges] for details.
Run a test request to see if everything is working:
curl -X GET --cacert /root/ca-cert.pem \
'https://<xcat-mn-host>/xcatws/nodes?userName=<user>&userPW=<password>'
or if you did not set up the certificate:
curl -X GET -k 'https://<xcat-mn-host>/xcatws/nodes?userName=<user>&userPW=<password>'
You should see some output that includes your list of nodes.